MAKER框架
通过SPRT投票、红旗和微代理编排实现零误差远程LLM执行
> ## ⚠️ 实验性-不用于生产
>
> 这是一个研究实验,而不是生产软件。
>
> - 目的:验证和探索研究论文中的主张 零错误解决百万步LLM任务 (Meyerson等人,2025)
> - 目标:实施MAKER算法,发现替代方法,测试零误差LLM执行的边界
> - 状态:积极研究-可能永远无法达到生产准备状态
> - 使用风险自负:API将发生变化,结果是实验性的,不适合关键应用
MAKER(具有K-margin Error Reduction的大规模分解代理过程)是一个Rust实现,探索LLM代理中基于数学的纠错。它通过基于SPRT的投票、红旗验证和m=1微代理分解来测试零错误执行。
基于: 零错误解决百万步LLM任务 (Meyerson等人,2025)
问题
即使每步准确率为99%,1000步任务的成功率也只有0.004%。MAKER算法旨在通过对数成本缩放将其转化为95%以上的可靠性。
此实现探讨了该主张在实践中是否成立。
| 任务长度 | 初始成功率 | MAKER成功率 | MAKER成本扩展 |
|---|---|---|---|
| 7个步骤 | 93% | 99%+ | 21个样本 |
| 1023步 | 0% | 95%+ | ~6138个样本 |
| 1M步 | 0% | 95%+ | Θ(s ln s) |
快速开始
作为Rust库```rust
use maker::core::{calculate_kmin, MockLlmClient, VoteConfig, vote_with_margin};
// Calculate required k-margin for your task
let k = calculate_kmin(
0.85, // p: per-step success probability
0.95, // t: target task reliability
1_023, // s: total steps (10-disk Hanoi)
1, // m: steps per agent (must be 1)
).unwrap();
// Run error-corrected voting
let client = MockLlmClient::constant("correct_answer");
let config = VoteConfig::default();
let result = vote_with_margin("What is 2+2?", k, &client, config).unwrap();
println!("Winner: {} ({} samples)", result.winner, result.total_samples);
### 作为MCP服务器```bash
# Build and run
cargo build --release
cargo run --bin maker-mcp
添加到您的Claude Code MCP配置中:```json
{
"mcpServers": {
"maker": {
"command": "/path/to/maker-mcp",
"args": [],
"env": {
"OPENAI_API_KEY": "your-key",
"ANTHROPIC_API_KEY": "your-key"
}
}
}
}
### 运行Demos
看 验证演示 下面是详细的文档和结果。
## 验证演示
这些演示验证了MAKER针对不同任务类型的纠错能力。
### 河内演示(`examples/hanoi_demo.rs`)
**目的**:验证MAKER在需要算法思维的多步骤推理任务中的表现。```bash
# 3-disk Hanoi (7 steps) with OpenAI
cargo run --example hanoi_demo -- --disks 3 --provider openai
# 5-disk Hanoi (31 steps) with strict mode (halt on first error)
cargo run --example hanoi_demo -- --disks 5 --provider openai --strict
# With ensemble (multiple providers)
cargo run --example hanoi_demo -- --disks 3 --provider openai --ensemble
# Mock mode for CI/testing
MAKER_USE_MOCK=1 cargo run --example hanoi_demo -- --disks 10 --accuracy 0.85
关键标志:
| 标志 | 描述 |
|---|---|
--disks N |
磁盘数量(1-20) |
--provider |
LLM提供者: ollama, openai, anthropic |
--model |
模型名称覆盖 |
--strict |
在第一个错误时停止(真零错误模式) |
--ensemble |
启用多提供商集成 |
结果 (gpt-5-mini):
- 31/31步骤(5盘) 0个错误 使用少镜头+思维链提示
- 每步平均约2.7个样本
- p_hat收敛到0.950(目标可靠性)
关键发现:原始提示在步骤2失败(系统推理错误)。很少有镜头示例+思维链提示将系统性错误转化为投票可以纠正的随机错误。
算术演示(examples/arithmetic_demo.rs)
目的:在具有真正随机错误(计算错误)的任务上验证MAKER。```bash
20 problems with OpenAI
cargo run --example arithmetic_demo -- --problems 20 --provider openai
50 problems with higher difficulty
cargo run --example arithmetic_demo -- --problems 50 --provider openai --difficulty 3
Strict mode with reproducible seed
cargo run --example arithmetic_demo -- --problems 50 --provider openai --strict --seed 42
Mock mode for CI/testing
MAKER_USE_MOCK=1 cargo run --example arithmetic_demo -- --problems 100 --accuracy 0.90
**关键标志**:
|标志|描述|
|------|-------------|
| `--problems N` |要解决的问题数量|
| `--difficulty 1-5` |数字大小(10^难度)|
| `--provider` |LLM提供者|
| `--strict` |第一次出错时停止|
| `--seed N` |可再现的问题生成|
**结果** (gpt-5-mini):
- 50/50的问题通过以下方式纠正 **0个错误**
- 平均每个问题2.7个样本
- 处理加法、减法、乘法
**关键发现**:随机计算错误可通过投票有效纠正。这验证了MAKER的核心前提——投票纠正随机错误。
______________________________________________________________________
## 研究发现
我们的验证实验揭示了关于MAKER适用性的重要见解:
### 制造商可以纠正什么
错误类型 · 示例 · 是否可纠正? · 为什么
**随机误差** · LLM偶尔会误算73-38✅ 是 · 独立错误通过投票取消
**迅速推理** · 河内,枪击案很少 · ✅ 是 · 将系统误差转换为随机误差
### MAKER无法更正的内容
错误类型 · 示例 · 是否可纠正? · 为什么
**系统误差** · 法学硕士无法解释河内的原因❌ 否 · 所有样本均以相同的方式失败
**知识缺口** · LLM不知道算法 · ❌ 否 · 投票就错误答案达成共识
### 关键洞察
> **MAKER纠正随机错误,而不是系统推理失败。**
>
> 如果法学硕士在某项任务中一直失败,投票将就错误的答案达成共识。及时的工程设计(少数镜头示例,思维链)对于将系统故障转化为投票可以纠正的随机错误至关重要。
### 观测精度
|任务|模型|每步精度|样本/步|
|------|-------|-------------------|--------------|
|算术(难度3)|gpt-5-mini|~95%|2.7|
|河内(少量射击+CoT)|gpt-5-mini|~95%|2.7|
|河内(原始提示)|gpt-5-mini|\<50%|N/A(失败)|
______________________________________________________________________
## 研究验证
`maker-rs` 探讨了学术研究与实际实施之间的界限。以下是这个实验与 原始论文:
### 记分卡(自我评估)
|标准|分数|评估|
|-----------|-------|------------|
| **算法保真度** |A+|精确k_min公式,SPRT投票,严格m=1强制执行|
| **实验覆盖率** |A|Tokio并发、事件源、MCP集成|
| **完整性** |A-|LLM驱动的分解、域分解器、全递归编排|
| **验证状态** |B+|演示验证核心声明;边缘情况需要更多的测试|
### 什么实施得好
- **严格m=1分解**:微代理在最小的上下文中只执行一个步骤,这与论文的核心断言相匹配,即“尽可能小的子任务”可以实现扩展
- **基于SPRT的投票**:使用实际的序列概率比测试和赌徒的破产逻辑——而不是启发式的“三分之一最佳”
- **动态k_min计算**:根据目标可靠性(t)和任务长度(s),根据论文的对数公式计算边距
- **红旗原始**:将验证视为解相关错误的统计必要性,丢弃(从不修复)格式错误的输出
### 实现细节
除了论文的理论模型(实验补充):
|增强|目的|
|-------------|---------|
| **东京 运行 时间** |大规模I/O并发性,实现跨数千步的并行投票采样|
| **事件溯源** |实时可观测性将理论概率与实际调试联系起来|
| **MCP集成** |将抽象状态机转换为Claude Code和其他客户端的可消费工具|
| **指数退避** |利用抖动和断路器处理API速率限制(429s)|
### 已知限制
公认的差距与论文的完整愿景:
- **语义匹配**:MVP默认为精确字符串匹配;基于嵌入和基于AST的匹配器可用,但较少经过实战测试
- **分解测试**:实现了LLM驱动的分解,但需要在不同的任务类型中进行更多的实际验证
### 实际妥协
|论文假设|实施现实|
|------------------|----------------------|
|理想采样|退避、断路器、实际API约束的重试预算|
|红色标志用于装饰|兼作安全护栏,防止迅速注射|
|无限并行性|可配置的并发限制,以遵守提供者配额|
跑 `cargo test --test monte_carlo` 实证验证统计保证。
## 建筑```
src/
├── core/ # Core MAKER algorithms
│ ├── kmin.rs # k_min = ⌈ln(1 - t^(m/s)) / ln((1-p)/p)⌉
│ ├── voting.rs # VoteRace: first-to-ahead-by-k (thread-safe)
│ ├── redflag.rs # RedFlagValidator: discard-don't-repair
│ ├── executor.rs # vote_with_margin() + vote_with_margin_adaptive()
│ ├── adaptive.rs # KEstimator: EMA-based dynamic k adjustment
│ ├── matcher.rs # CandidateMatcher trait + ExactMatcher
│ ├── matchers/ # Pluggable matcher implementations
│ │ ├── embedding.rs # EmbeddingMatcher (cosine similarity)
│ │ ├── ollama_embedding.rs # Ollama embedding client
│ │ ├── openai_embedding.rs # OpenAI embedding client
│ │ └── code.rs # CodeMatcher (tree-sitter AST, optional)
│ ├── decomposition/ # Recursive task decomposition (Section 7)
│ │ ├── llm_agent.rs # LLM-driven "Insight Agent" for task discovery
│ │ ├── discriminator.rs # Vote on decomposition proposals
│ │ ├── orchestrator.rs # Recursive decomposition coordinator
│ │ ├── solver.rs # Leaf node executor with voting
│ │ ├── aggregator.rs # Solution composition
│ │ └── domains/ # Domain-specific decomposers (coding, data, ML)
│ └── orchestration.rs# TaskOrchestrator with m=1 constraint
├── llm/ # Multi-provider LLM abstraction
│ ├── ollama.rs # Local inference
│ ├── openai.rs # OpenAI API
│ ├── anthropic.rs # Anthropic API
│ ├── ensemble.rs # Multi-model ensemble configuration
│ ├── retry.rs # Exponential backoff with jitter
│ └── sampler.rs # Temperature-diverse parallel sampling
├── mcp/ # MCP server (rmcp v0.13)
│ ├── server.rs # MakerServer with #[tool_router]
│ └── tools/ # maker/vote, validate, calibrate, configure, decompose
└── events/ # Event-driven observability
├── bus.rs # Tokio broadcast channel
└── observers/ # Logging (tracing) + Metrics
MCP工具
maker/vote -错误更正投票
请求:```json
{ "prompt": "...", "k_margin": 3, "max_samples": 20, "matcher": "embedding" }
答复:```json
{
"winner": "answer", "vote_counts": {"answer": 5}, "total_samples": 7,
"k_used": 3, "p_hat": 0.87, "matcher_type": "exact", "candidate_groups": 2
}
maker/validate -红旗检查
请求:```json
{ "response": "...", "token_limit": 700, "schema": {"required": ["move"]} }
答复:```json
{ "valid": false, "red_flags": [{"flag_type": "TokenLengthExceeded", "details": "..."}] }
maker/calibrate -成功率估算
请求:```json
{ "samples": [{"prompt": "...", "ground_truth": "..."}] }
答复:```json
{ "p_estimate": 0.87, "confidence_interval": [0.82, 0.92], "recommended_k": 4 }
maker/configure -运行时配置
请求:```json
{
"k_default": 3, "temperature_diversity": 0.1, "token_limit": 700,
"adaptive_k": true, "ema_alpha": 0.1, "k_bounds": [2, 10],
"matcher": { "type": "embedding", "threshold": 0.92, "provider": "ollama" }
}
答复:```json
{ "applied": true, "current_config": {} }
maker/decompose -LLM驱动的任务分解
请求:```json
{
"task": "Build a web scraper that extracts product data",
"depth_limit": 10,
"provider": "openai"
}
答复:```json
{
"task_id": "root-task",
"subtasks": [
{"id": "1", "description": "Parse HTML structure", "is_leaf": true},
{"id": "2", "description": "Extract product fields", "is_leaf": true}
],
"composition": "sequential",
"depth": 1
}
成本缩放
MAKER的成本标度为Θ(s ln s),而单纯重试的成本则为指数:
| 方法 | 7步 | 1023步 | 1M步 |
|---|---|---|---|
| 制造者 | 21个样本 | ~6K个样本 | ~20M个样本 |
| 天真的重试 | 7次尝试 | 不可能 | 不可能 |
MAKER与Naive Retry(蒙特卡洛验证,p=0.85,t=0.95)
| 步骤 | 制造商成本 | 初次重试成本 | 节省 |
|---|---|---|---|
| 20 | 80 | 1,520 | 94.7% |
| 50 | 200 | 506,400 | 99.96% |
| 100 | 500 | 34亿 | ~100% |
在任何步骤失败时,必须重新运行整个任务。当p=0.85时,无误差完成100步的概率为0.85^100≈7×10⁻⁸,需要数十亿次重试。MAKER的每一步投票使成本保持对数。
跑 cargo test --test monte_carlo -- --nocapture 以再现这些结果。
自适应K-Margin
MAKER根据观察到的精度动态调整k-margin,在模型运行良好时减少API调用:```rust
use maker::core::{KEstimator, vote_with_margin_adaptive, MockLlmClient, VoteConfig};
let client = MockLlmClient::constant("answer");
let config = VoteConfig::default();
let mut estimator = KEstimator::new(0.85, 0.95, 100);
// k starts high, decreases as accuracy is confirmed
let result = vote_with_margin_adaptive("prompt", &client, config, &mut estimator).unwrap();
println!("Used k={}, estimated p={:.2}", result.k_used, estimator.p_hat());
通过MCP配置: `{"adaptive_k": true, "ema_alpha": 0.1, "k_bounds": [2, 10]}`
## 语义匹配
对于非确定性任务(代码生成、自然语言),MAKER支持可插入的匹配器,将等效响应分组:
|匹配器|用例|方法|
|---------|----------|--------|
| `ExactMatcher` (默认)|确定性任务|空白归一化字符串相等|
| `EmbeddingMatcher` |自然语言|嵌入的余弦相似度(阈值:0.92)|
| `CodeMatcher` |代码生成|树型AST与alpha重命名的比较|
```rust
use maker::core::matcher::ExactMatcher;
use maker::core::matchers::embedding::{EmbeddingMatcher, MockEmbeddingClient};
// Embedding matcher groups semantically similar responses
let matcher = EmbeddingMatcher::new(Box::new(MockEmbeddingClient::default()), 0.92);
assert!(matcher.are_equivalent("The answer is 42", "The answer is 42."));
这 CodeMatcher 需要 code-matcher 特征标志:```bash
cargo build --features code-matcher
cargo test --features code-matcher
## 多模式集合
MAKER支持在异构LLM模型之间进行投票,以根据模型架构而不仅仅是采样温度来解相关误差:
|策略|行为|用例|
|----------|----------|----------|
| `RoundRobin` |在模型之间均匀分布样本|最大限度地提高多样性|
| `CostAware` |首先是廉价型号,在意见分歧时升级|将成本降至最低|
| `ReliabilityWeighted` |来自更高可靠性模型的更多样本|优化准确性|
通过MCP配置:```json
{
"ensemble": {
"models": [
{ "provider": "ollama", "model": "llama3", "cost_tier": "cheap" },
{ "provider": "anthropic", "model": "claude-haiku", "cost_tier": "medium" }
],
"strategy": "cost_aware"
}
}
与单一昂贵型号相比,具有成本意识的集成节省了87.5%以上。看 基准.md 为了获得完整的结果。
基准测试
MAKER包括涵盖编码任务、数学/逻辑和数据分析的特定领域基准:```bash
cargo bench --bench coding_tasks # 10 coding tasks (trivial to complex)
cargo bench --bench math_logic # Arithmetic, symbolic, logic, Hanoi
cargo bench --bench data_analysis # CSV, statistics, SQL, data cleaning
cargo bench --bench cost_scaling # Θ(s ln s) cost validation
cargo bench --bench ensemble_comparison # Single-model vs ensemble comparison
看 基准.md 详细的结果和验收标准。
## 发展```bash
cargo build # Build
cargo test # All tests (unit + integration + property)
cargo test --features code-matcher # Include tree-sitter code matcher tests
cargo test --example hanoi # Hanoi example tests (21 tests)
cargo test --test properties # Property-based tests (proptest, 21 tests)
cargo test --test mcp_integration # MCP integration tests (35 tests)
cargo test --test semantic_matching # Semantic matching tests (16/25 tests)
cargo test --test monte_carlo # Monte Carlo cost validation
cargo bench --bench cost_scaling # Cost scaling benchmark
cargo bench --bench coding_tasks # Coding task benchmark
cargo bench --bench math_logic # Math & logic benchmark
cargo bench --bench data_analysis # Data analysis benchmark
cargo bench --bench ensemble_comparison # Ensemble comparison
cargo clippy # Lint
cargo fmt --check # Format check
cargo doc --no-deps --open # API documentation
安全
MAKER为MCP工具安全实施深度防御:
- 架构实施:
#[serde(deny_unknown_fields)]在所有输入上 - 红旗过滤:丢弃格式错误的LLM输出,从未修复
- 提示限制:最多10000个字符
- 微量试剂分离:步骤之间没有历史泄漏(m=1)
- 状态哈希验证:在国家转移之前检测到腐败
看 安全.md 用于漏洞报告。
引用此项目
如果您在研究或项目中使用MAKER,请使用GitHub的 “引用此存储库” 按钮,或使用以下BibTeX:bibtex
@software{allen_maker_2026,
author = {Allen, Robert},
title = {{MAKER Framework}},
version = {0.3.0},
date = {2026-02-27},
url = {https://github.com/zircote/maker-rs},
license = {MIT}
}
看 CITATION.cff 获取完整的引用元数据。
致谢
MAKER是Rust实现的算法和理论框架,如:
> Meyerson,E.,Qiu,X.,&Lehman,J.(2025)。 零错误解决百万步LLM任务. arXiv:2511.09030
参考文献
- Meyerson,E.等人(2025)。 零错误解决百万步LLM任务. arXiv:2511.09030
- 人类学。 (2024). 引入模型上下文协议. anthropic.com
- 瓦尔德,A.(1945)。 序列分析(SPRT基础工作)
许可证
麻省理工学院-见 许可证
