ChimeraForge

Chimeraforge

一款本地优先、模型无关的大模型部署规划工具。 它能快速回答“选择哪种模型、量化方式、GPU 和后端？需要多少个？能否运行？能否达到我的 SLO？成本是多少？”并提供明确的依据和假设，可通过 Shell、Python 或 AI 助手使用。

uvx chimeraforge plan --model-size 8b --hardware "RTX 4090 24GB"

信任原则

每个数字都标记为 measured、extrapolated、derived、estimated 或 unknown，工具绝不会伪造它无法担保的数字。 VRAM 和 KV-cache 属于 derived——依据模型真实架构进行精确计算，而非测量值。吞吐量仅在测量该数据集时所用的设备上通过实测查表；在其他 GPU 上，该行数据会按内存带宽缩放，并标记为 extrapolated，同时注明其来源行、测量所用设备以及应用的比率，因为 17.8 倍的带宽外推（RTX 4080 Laptop 432 GB/s -> B200 7700 GB/s）并不代表对你的显卡进行了测量。若无法做到这一点，则明确给出屋顶线 estimate——绝不会把它说成它并非的数据。低于内置数据集覆盖范围的质量结果会报告为 unknown，而不是编造分数。若计划结果为 0，会指出拒绝每个候选项的具体门槛，而不是笼统地说“未找到结果”。无遥测，不会回传数据，可在隔离网络环境中运行。

提供一个模型——尺寸类别、Hugging Face 仓库、Ollama 标签，或尚未发布模型的手动覆盖参数——它就会针对 VRAM、质量、延迟、成本、能耗和可选的安全门槛，搜索（模型 x 量化 x 后端 x GPU 数量 x 张量/流水线并行）空间，然后返回满足你的 SLO 的最低成本配置。

28 条命令，一个工具： plan - check - bundle - study - deploy - deploy-verify - suggest - measure - workload - monitor - monitor-fleet - validate - doctor - contribute - catalog - safety - bench - trace - trace-campaign - trace-envelope - score - gate - eval - compare - refit - report - mcp - serve。此清单对应 Chimeraforge 0.76.0。

实证数据集可追溯至技术报告 TR108-TR137（在消费级 GPU 上进行的约 204,000 次真实测量）。完整功能历史请参阅 CHANGELOG。

规划器实际读取的数据。 约 204,000 次测量是整个研究计划在各报告中的总量。plan 查找数据的表要小得多：

表	大小	内容
解码吞吐量	23 行	仅 FP16；7 个模型，最大的是 3.21B 的 llama3.2-3b；服务引擎上有 9 行（ollama 3、tgi 3、vllm 3），transformers 研究测试框架上有 14 行；每行均在一张 GPU 上测量，即 RTX 4080 Laptop 12GB（192-bit GDDR6，432 GB/s）
量化加速比	7 个倍率	应用于 FP16 行；量化后的吞吐量绝不是对该量化方式的实测值
质量	35 个模型 x 量化单元格	每项 n=20（TR125）
安全性	40 个模型 x 量化单元格	拒答率（TR134/TR142）
延迟服务时间	9	模型 x 后端
第三方审计	17 张 GPU 上的 42 个评分单元格	已发布的基准测试（评分卡）；另有 26 项已发布，但说明不够充分，无法评分

这些行以外的任何数据都属于 extrapolated（根据参考 GPU 的内存带宽缩放）、derived（精确计算）或 estimated（屋顶线估算），计划中的每个数字都会注明其类型。数据本身也记录了自身的局限：

• 每行吞吐量数据均为 FP16。量化后的吞吐量是 FP16 行数据乘以量化倍率，并非该量化方式的实测值。
• 每行数据均在一张 GPU 上测得。其他硬件上的数据按带宽外推，并标记为 'extrapolated'，而非 'measured'。
• 已测量的最大模型为 3.21B；对更大模型的预测会外推幂律关系。
• 没有 SGLang 数据行；该后端会回退到 fp16/幂律路径。

---

安装

无需安装即可试用：

uvx chimeraforge plan --model-size 8b --hardware "RTX 4090 24GB"
pipx run chimeraforge plan --model-size 8b --hardware "RTX 4090 24GB"

正式安装：

pip install chimeraforge            # planner + model resolution (HF/Ollama) + suggest/measure/safety/bench
pip install "chimeraforge[bench]"     # + GPU environment metadata for benchmarks (pynvml)
pip install "chimeraforge[mcp]"       # + MCP server so Claude/GPT/Cursor can call the planner
pip install "chimeraforge[eval]"      # + quality evaluation (ROUGE-L; BERTScore additionally needs `bert-score` + torch)
pip install "chimeraforge[refit]"     # + coefficient refitting (numpy, scipy)
pip install "chimeraforge[all]"       # everything

Python 3.10+。核心安装包含规划器和面向网络的命令（httpx 是核心依赖）。注册表规划和本地目录可离线使用；解析或发现 HF/Ollama 需要明确的网络访问权限。bench / measure / safety 需要正在运行的后端（Ollama、vLLM、TGI 或 SGLang；safety 仅支持 Ollama）。支持 Windows / macOS / Linux。

发布范围（2026-10-24）。 Chimeraforge 0.76.0 增加了被动式已声明集群监控。以下工作流在此版本中可用。原生协议观察结果和托管 CPU 验收均不能证明 GPU 执行能力或实际服务性能。

pip install "chimeraforge[mcp]==0.76.0"

快速入门

# Plan a registry size class on your GPU
chimeraforge plan --model-size 8b --hardware "RTX 4090 24GB" --request-rate 2.0

# Plan ANY model -- a Hugging Face repo or an Ollama tag
chimeraforge plan --model Qwen/Qwen2.5-7B-Instruct --hardware "RTX 4090 24GB"
chimeraforge plan --model ollama:qwen3:14b --ollama-url http://localhost:11434

# Split a model too big for one GPU across several (tensor parallelism)
chimeraforge plan --model Qwen/Qwen2.5-72B-Instruct --hardware "H100 80GB" --tp 4

# Shrink the KV-cache, print the cost/latency/quality trade-off menu
chimeraforge plan --model-size 8b --hardware "RTX 4080 12GB" --kv-quant q8 --pareto

# Benchmark a live model and plan on the MEASURED numbers
chimeraforge plan --model qwen3:14b --measure

# Discover + rank what fits your GPU and budget
chimeraforge suggest --source ollama --hardware "RTX 4090 24GB" --budget 500

# Save and recheck an offline plan
chimeraforge plan --model-size 3b --hardware "RTX 4090 24GB" --no-network --save offline-plan.json
chimeraforge check offline-plan.json --json

在规划和导出过程中保持使用同一个 Hub 检查点

# Metadata/config only: no model weights are downloaded by the planner
chimeraforge plan --model HuggingFaceTB/SmolLM2-135M-Instruct \
  --revision 12fd25f77366fa6b3b4b768ec3050bf629380bac \
  --hardware "RTX 4080 12GB" --platform linux --request-rate 0.01 \
  --quality-target 0 --budget 100000 --save checkpoint-plan.json --json
chimeraforge check checkpoint-plan.json --json           # offline
chimeraforge check checkpoint-plan.json --network --json # explicit Hub inspection

也接受分支和标签；解析过程会先确定一个不可变提交，然后读取该提交的配置和已声明的文件元数据。规划多个 HF 模型时，请重复使用 --revision MODEL=REF。缓存的可变引用是带日期的生成时观察结果，并不能证明其当前状态。

在进行部署导出之前，请选择一个受支持的已保存候选项。vLLM、TGI 和 SGLang 命令会携带解析出的提交对应的 --revision；Ollama 转换无法保留此固定版本，因此会被拒绝。回执会对实际读取的配置字节计算哈希，并记录已声明的权重元数据。它不会验证下载的权重或 tokenizer 字节，也不会标识正在运行的服务。旧版计划仍会按其原有的身份信息缺失情况加载。请参阅 Python 检查点循环。

---

根据实际流量而非猜测进行规划

chimeraforge workload --from-log requests.jsonl --out workload.json
chimeraforge plan --model-size 8b --hardware "RTX 4090 24GB" --workload-profile workload.json

根据请求日志或运行中的 vLLM/SGLang /metrics 端点，推导请求速率、提示词和输出长度、流量方差以及前缀缓存命中率。其中方差最为重要：否则 plan 会将其设为四种预设值之一，而它会影响整个排队延迟尾部。

指标名称因引擎而异，且需明确指定——vLLM 在不同版本之间更改过其中两个指标的名称，而静默回退到过期名称的采集器会报告伪造的测量值。未知引擎会导致错误；数据源未提供的字段会保持缺失，而不会被赋予默认值。

决策简报

chimeraforge plan --model-size 8b --hardware "RTX 4090 24GB" --request-rate 2 --report brief.md

写入一份记录决策的 Markdown 文档，其中包含建议、作为输入而非结论列出的每项假设、备选方案表、规划器的原始警告，以及可重新生成该文档的确切命令。每个数字都会在正文中标记为 measured / extrapolated / derived / estimated / unknown，而不只是用符号标注。

如果价格快照已过期，它会拒绝生成文档并以非零状态退出，而不是换一种更好看的字体打印旧价格——格式化文档看起来比终端输出更可靠，读者也不会重新推导其中的计算过程。

MCP 服务 —— 为 Claude / GPT / Cursor 提供相同的数据

GPU 规格规划正是助手容易出错的地方：硬件价格和规格可能已超出训练数据的截止日期，而 KV 缓存和批处理的计算也容易在凭记忆完成时出错。chimeraforge mcp 会运行一个 stdio MCP 服务，让助手调用基于实测数据的真实规划器，而不是凭空猜测。

pip install "chimeraforge[mcp]"

Claude Code：

claude mcp add --transport stdio chimeraforge -- uvx --from "chimeraforge[mcp]" chimeraforge mcp

Claude Desktop / Cursor（添加到 MCP 配置文件中）：

{
  "mcpServers": {
    "chimeraforge": {
      "command": "uvx",
      "args": ["--from", "chimeraforge[mcp]", "chimeraforge", "mcp"]
    }
  }
}

--from "chimeraforge[mcp]" 会引入 MCP SDK；uvx 会在独立环境中运行该服务。如果你已经将 chimeraforge[mcp] 安装到客户端启动时使用的环境中，也可以改用 "command": "chimeraforge", "args": ["mcp"]。

对于支持 HTTP 的 MCP 客户端，请启动原生 Streamable HTTP 传输：

chimeraforge mcp --transport streamable-http --port 8766
# Connect the client to http://127.0.0.1:8766/mcp

HTTP 绑定到回环地址，默认离线解析模型。只有服务操作者可以通过 --allow-network 启用 Hugging Face 查询和发现；HTTP 工具调用方无法提供本地文件路径、端点 URL 或网络覆盖选项。Ollama 端点解析和发现仍仅支持 stdio。SDK 会拒绝浏览器 Origin、外部 Host，以及超过 64 KiB 的请求体（包括分块上传）。原生会话上限为 32 个，空闲 300 秒后过期。这些设置以及固定的双工作线程容量均可通过 mcp --help 配置。HTTP Hugging Face 发现会在执行网络操作前将每次调用的模型数量限制为 16 个；stdio 保留现有的发现选项。

HTTP 工具在协议事件循环之外运行。响应会在 30 秒后超时；超时或取消的同步任务会继续占用工作线程，直到实际完成。容量已满时，后续调用会收到繁忙错误，而协议 ping / 发现仍能保持响应。Python 线程不会被强制停止：服务关闭时会等待其管理的任务完成，因此可能需要等待较慢的底层解析器。该传输使用受支持的 MCP 1.x SDK（>=1.30,<2），并采用其原生 Streamable HTTP 会话和请求防护机制。

提供五种工具：chimeraforge_plan（完整的门控搜索）、chimeraforge_suggest（反向排序，找出实际适配指定 GPU 的方案）、chimeraforge_compare_api（自托管与托管 API 的成本及盈亏平衡用量比较）、chimeraforge_resolve_model（根据真实参数和架构确定模型 ID），以及 chimeraforge_list_hardware。每个结果都带有与 CLI 相同的 measured / extrapolated / estimated / unknown 来源标记，工具描述也会告诉模型优先使用这些结果，而非自身知识。chimeraforge_plan 还会返回一个 launch 字段，即推荐配置的服务命令；这样助手就能回答“那该如何运行”，而不必编造标志。chimeraforge_compare_api 会依据带有日期的快照计算价格并报告快照的时效，因此助手引用价格时会同时给出采集日期，而不会把过时数据说成当前价格。

---

命令

plan —— 预测性容量规划器

chimeraforge plan --model-size 8b --hardware "RTX 4090 24GB" --request-rate 2.0
chimeraforge plan --model Qwen/Qwen2.5-7B-Instruct --hardware "RTX 4090 24GB"   # any HF repo
chimeraforge plan --model ollama:qwen3:14b --ollama-url http://localhost:11434  # any Ollama tag
chimeraforge plan --model Qwen/Qwen2.5-72B-Instruct --hardware "H100 80GB" --tp 4   # multi-GPU
chimeraforge plan --model-size 3b --kv-quant q4 --pareto                       # smaller KV cache, trade-off menu
chimeraforge plan --model-size 8b --hardware "RTX 4090 24GB" --launch          # + the serve command to actually run it
chimeraforge plan --model-size 3b --workload agent --safety-target 0.85 --json

• 规划任意模型：注册表规模等级、HF 仓库（org/name）、Ollama 标签，或手动覆盖项（--params-b/--n-layers/...）。
• 通过 5 道关卡流程搜索（模型 × 量化 × 后端 × N 个副本 × 批次/GPU）：显存 -> 质量 -> 安全（选择启用）-> 延迟 -> 预算。
• 模拟真实的服务物理特性：连续批处理（vLLM/TGI）、预填充/解码拆分（TTFT + TPOT）、受 KV 缓存限制的并发，以及考虑方差的排队（--workload）。
• 可适配单张 GPU 无法容纳的模型：--tensor-parallel/--tp {N|auto} 会将权重和 KV 分片到 N 张 GPU 上（类似 Megatron，并对通信进行建模）；--pipeline-parallel/--pp {N|auto} 则会将层拆分到 N 个阶段上（慢速互连下成本更低，但需要批处理才能填满流水线）。目前两者不能组合使用。
• **只提供后端实际支持的选项：**Ollama 提供 GGUF 量化版本；vLLM/TGI 提供 FP16 和 FP8（仅限配备 FP8 张量核心的 GPU——Ada/Hopper/Blackwell/CDNA3）。规划器不再推荐在 vLLM 上使用 GGUF 检查点并按 llama.cpp 的速度优势定价。
• **仅在引擎支持的平台上运行（--platform linux|windows|wsl2|macos；默认值为 linux，或在使用 --hardware auto 时采用本机操作系统）：**仅在引擎自身文档声明支持的操作系统和 GPU 上提供该引擎。只有文档明确说明不支持时才会拒绝，并且每次拒绝都会引用相应文档：
  • 在原生 Windows 上使用 vLLM；
  • 在消费级 Radeon 显卡上使用 SGLang 或 TGI，因为它们的 ROCm 文档仅支持 Instinct；
  • 在 AMD 上使用 vLLM AWQ/GPTQ，或在 Intel 上使用 FP8；
  • 在 ROCm 上使用 TGI AWQ。 如果某个引擎的文档未作说明，方案会警示该配置未经验证，而不是拒绝该配置；并且始终会注明 TGI 处于维护模式。
• KV 缓存量化（--kv-quant {fp16,q8,q4}）可缩小缓存并提高最大并发量——在长上下文场景下收益最大。
• 异构 GPU 集群（--fleet "H100 80GB,A100 80GB,L4 24GB"）：为不同类型的 GPU 混合配置，而不是复制 N 份同一类型的 GPU，因为在宽松的 SLO 和小请求场景下，低价 GPU 可能更划算；而在严格的 SLO 和长请求场景下，高价 GPU 则可能更合适。对于 8B 模型、250 req/s 的负载，配置为 3x H100 + 1x L4，费用为 $5,760/月，相比 6x A100 的 $6,912 低 16.7%；这是因为，与再添一块大 GPU 相比，用小 GPU 承担最后几 req/s 的成本更低（plan --model-size 8b --request-rate 250 --fleet "H100 80GB,A100 80GB,L4 24GB" --budget 100000）。混合配置的前提是使用具备能力感知功能的路由器，但目前没有任何推理引擎自带这种路由器，因此每个混合方案都会明确说明这一点；报告的来源可信度按所用 GPU 类型中最差的一种计算，而不是按最好的一种计算。
• 成本真实度（--duty-cycle、--gpu-price-multiplier）：标注的 $/1M-token 价格按集群满负荷计算。你还需要为预留的冗余容量和每个空闲小时付费，因此，8B 模型在 H100 上以 2 req/s 运行时，实际价格为 $2.71/1M（满负荷）和 $9.04/1M（利用率 30%），而满载时为 $0.71（plan --model-size 8b --request-rate 2 --hardware "H100 80GB" --budget 100000 --duty-cycle 0.3）。Spot 和预留实例的价格由你提供，而不是使用捆绑的估算值。
• 超大规模云服务商按需价格（--cloud aws|azure）：捆绑的数据中心价格为市场价格，约比 AWS 和 Azure 的按需收费低 4-5 倍。--cloud 根据各云服务商公开标价的带日期快照，为集群定价：AWS 使用 us-east-1 的 EC2 价格表，Azure 使用 eastus 的 Azure Retail Prices API。价格适用于 Linux、按需实例和共享租户。
  • 整台实例： TP/PP 组必须能装入一台实例，而部分未使用的实例也会按其中的所有 GPU 计费。
  • 示例： 同样是 8B 模型，使用一块 H100 时，按市场价格为 $1,800/月，在 AWS 上为 $4,954（一台 1-GPU p5.4xlarge），在 Azure 上为 $70,790。Azure 只在 8-GPU VM 中提供 H100，方案会注明其中 7 块 GPU 处于空闲状态（plan --model-size 8b --request-rate 2 --hardware "H100 80GB" --budget 100000 --cloud azure）。
  • 数据来源： 每种实例提供的 GPU 型号均取自云服务商自己的实例或 VM 系列页面；GPU 数量和显存则根据硬件数据库进行核验。名称相似但并非同一型号的显卡会被排除，并说明原因，例如 Azure 的 H100 NVL 和 A100 PCIe VM。快照由 scripts/build_cloud_prices.py 重新生成，并在 90 天后标记为过期。
• 批处理模式（--mode batch）：适用于离线待处理任务（例如夜间摘要任务、Embedding 回填或评估轮次），无需等待即时结果。此模式会取消延迟门槛和 70% 利用率冗余。每块 GPU 都以能最大化吞吐量的方式运行批处理；集群规模设为能以满利用率处理完 --request-rate 的最小规模；结果按 $/1M tokens 排序，而不是按月账单排序。
  • 示例：8B 模型在 H100 上以 2 req/s 运行时，价格从 $0.66/1M（在线模式中最便宜的选择 Ollama Q2_K）降至 $0.065/1M（批大小为 267 的 vLLM AWQ），使用的 GPU 数量不变，仍为一块，费用为 $1,800/月（plan --model-size 8b --request-rate 2 --hardware "H100 80GB" --budget 100000 --mode batch）。该吞吐量是屋顶线估算，输出会对此作出说明。
  • 批处理模式下若设置延迟目标（--latency-slo、--ttft-slo、--tpot-slo），会报错，而不会忽略这些目标。报告的请求时间仅为服务时间，不包括排队等待时间，因为待处理任务的等待时间取决于其大小。--pareto 用于权衡每 1M tokens 的价格与质量。
• 自托管与 API 的成本平衡点（--compare-api）：根据你的工作负载，将成本与托管 API 进行比较，并报告自托管开始更划算时的月请求量。价格是带日期的快照，每家服务商都附有来源 URL，超过 90 天会标记为过期——绝不会说成实时报价；而前沿 API 会标记为不同质量等级，不会冒充同等条件的比较。
• 解聚建议：不对 Prefill/Decode 解聚建模。Prefill:Decode 比例不存在封闭形式的计算方法，而且 vLLM 自己的文档指出，这项功能“不会提高吞吐量”。规划器采取的做法是：标记出处于已发布资料所述值得考虑的范围内的候选配置，引用这些资料，但不作任何预测。
  • 何时显示： 方案必须同时设置 --ttft-slo 和 --tpot-slo，处于在线服务模式，使用多块 GPU，并且引擎（vLLM 或 SGLang）的文档中说明了这项功能。每个条件都对应 DistServe（OSDI 2024）或引擎文档中的一句说明，文档版本固定为规划器所锁定的标签。
  • 报告内容： 本方案中 Prefill 占建模请求服务时间的比例（启用驻留时使用受会话容量限制的 TTFT），以及 GPU 的互连信息，因为 KV 交接需要高速链路。
• 前缀缓存（--prefix-cache-hit-rate）：聊天机器人和 Agent 流量会重复使用较长的系统提示词，因此大部分 Prefill 已经缓存。对于 4k 提示词和 90% 的命中率，H100 上的 8B 模型 TTFT 会从 166ms 降至 17ms（plan --model-size 8b --prompt-tokens 4096 --hardware "H100 80GB" --budget 100000 --prefix-cache-hit-rate 0.9）；同一查询在参考显卡 RTX 4080 上则会从 2051ms 降至 205ms。默认值为 0，且绝不推断；为避免 KV 容量不足导致“能装下”变成 OOM，特意不扣除共享前缀所节省的 KV 容量。
• 多轮会话驻留（--think-time SECONDS --session-turns T）：只有当用户思考时间内 KV 未被清除时，对话的下一轮才能命中前缀缓存。轮次之间，对话处于空闲状态（不会进行解码，也不计入并发上限），但其前缀仍需保留在 KV 池中。
  • 计算方式： 根据 Little 定律，集群同时承载的空闲对话数为 rate x (T-1)/T x think time。规划器会计算每种配置（副本数 x 批大小）的可用 KV 能容纳多少个对话前缀，并将报告的命中率限制在这一比例。TTFT 会在搜索过程中根据受限后的命中率计算，因此增加副本数确实会带来帮助。
  • 示例： 8B 模型以 2 req/s 运行，提示词为 4k，轮次间隔 60 s，则会有 108 个空闲对话。单块 RTX 4090 的可用 KV 能容纳其中 19 个，因此标称 90% 的命中率会降至 16%，TTFT 则会从 100ms 升至 837ms（plan --model-size 8b --hardware "RTX 4090 24GB" --request-rate 2 --prompt-tokens 4096 --context-length 8192 --prefix-cache-hit-rate 0.9 --think-time 60 --session-turns 10）。
  • 输出中说明的假设： 使用会话亲和路由，确保后续轮次到达保存其前缀的副本；并假设淘汰过程与用户返回时间随机无关。Ollama 每个副本槽位只保留一个对话。只有同时提供两个标志时才会启用。
• 推理模型（--reasoning-tokens N）：隐藏的思考 tokens 由 GPU 解码，并保存在 KV 中，尽管调用方看不到它们。仅计算可见输出会按推理比例低估解码量——1000 个隐藏 tokens 会使 H100 上 8B 方案的 p95 从 193ms 增至 3664ms（plan --model-size 8b --hardware "H100 80GB" --budget 100000 --reasoning-tokens 1000）。默认值为 0，且绝不推断：该比例取决于你的工作负载，而不是模型权重。
• 感知注意力结构的 KV 计算： MLA（DeepSeek-V2/V3）缓存的是压缩后的潜在表示，而不是每个注意力头的 K/V；如果按 GQA 计算，DeepSeek-V3 的缓存容量会被高估 57x。滑动窗口模型的缓存增长也会在达到窗口大小后停止。对于未声明窗口层模式的模型，不会应用此规则，以免 KV 容量不足导致“能装下”变成 OOM。
• 感知混合专家模型： 显存容量按总参数计算（所有专家始终驻留），吞吐量和 TTFT 则按激活参数计算（每个 token 只会读取路由到的专家）。将 MoE 模型当作稠密模型，会低估 Mixtral-8x7B 的吞吐量 3.6 倍、低估 DeepSeek-V3 的吞吐量约 18 倍。激活参数量根据模型真实的专家结构推导，并与已发布的数据相符。
• 能耗（--electricity-rate）：报告月度 kWh 成本、$/1M-tok (+energy) 和每瓦 tok/s，并将其与预算门槛并列报告，而不计入预算门槛。
• 运营碳排放（--grid-region USA|DEU|France|... 或 --carbon-intensity G）：计算每 1M tokens 的 gCO2e 和每月 kg，方法是将同一能耗值乘以电网碳强度。H100 上的 8B 模型以 2 req/s 运行时，每 1M tokens 在美国电网上产生 60 gCO2e，在法国电网上产生 6.5 gCO2e（plan --model-size 8b --request-rate 2 --hardware "H100 80GB" --budget 100000 --grid-region USA）。
  • 碳强度采用 Ember 按国家统计的年度平均生命周期排放值，数据来自 Our World in Data，并固定到某个 OWID commit；数据由 scripts/build_carbon_data.py 重新生成。每个数值都会附带年份，超过 2 年的数值会标记为过期。
  • 这仅计算 SCI 的运营项（O = E x I）。不对隐含排放建模，因此不是完整的 SCI 分数。
  • E 为 GPU 板卡功耗，不包含主机功耗或数据中心 PUE，因此该数值是下限。若 TDP 未知，碳排放也会标为未知，绝不会视为零。
• 导出启动命令（--launch）：为胜出配置生成 vllm serve / ollama run / TGI docker run 命令，并填入方案自身的上下文长度、TP/PP 度数、批大小和 KV dtype——这些标志最容易在手动计算时出错。无法推导的内容不会凭空编造：GGUF 量化等级会作为说明，提示使用原生等效检查点，而不是捏造 --quantization 标志。
• 提供每项预测的来源可信度（measured / extrapolated / derived / estimated / unknown）；没有配置符合条件时，说明起约束作用的门槛。
• 已通过注册表数据验证：VRAM R^2=0.968、吞吐量 R^2=0.859、质量 RMSE=0.062、延迟 MAPE=1.05%（比解析式 M/D/1 高 20.4 倍，TR133）。无 ML——采用实证查找表和第一性原理插值（注册表外模型使用屋顶线估算）。

check——离线重新检查已保存的计划

chimeraforge plan --model-size 3b --no-network --save plan.json
chimeraforge check plan.json --json

比较已使用的输入、本地定价、可行性、候选项顺序和建模差异，不修改已保存的文件。新快照会绑定完整的模型几何信息、GPU/平台和输入回执；旧版快照会将缺失的绑定报告为未经验证。检查不会启用已保存权限中的网络访问，也不会为 auto 计划探测新主机。退出码 0 表示所需建模组件未发生变化，1 表示所需证据已变化、过期或未经验证，2 表示输入格式错误。建模建议稳定并不能证明服务性能，也无法识别不可变的模型权重。请参阅 API 契约。

bundle——可移植的已保存计划交接

适用于已发布的 0.61.0 CLI。

**测试框架文件可能包含私密提示词或其他数据。分享捆绑包前，请检查确切的输入。**创建时只会复制原始计划及其绑定的系数/质量文件；原始字节、路径和指纹均保持不变。

chimeraforge bundle create plan.json --out handoff
# Move the whole handoff directory to the receiving machine.
chimeraforge bundle verify handoff --json
chimeraforge bundle check handoff --json

即使原始文件已被移除，重新检查也会离线使用经过验证的输入字节。JSON 会分别显示原始来源位置和本地来源位置。当前工具、策略、硬件以及适用的价格/云服务变更仍可采取相应措施；验证通过本身并不代表计划检查通过。对于已验证的内容，verify 退出码为 0；对于未变化的必需事实，check 退出码为 0，对于已变化、过期或必需但未经验证的事实，退出码为 1；格式错误或不受支持的捆绑包退出码为 2。没有字节绑定且贡献依赖非空的旧版计划会在写入前被拒绝。完整性验证不能认证来源，也无法证明实际提供的权重或性能。请参阅可移植工作流。

contribute gate——可信的签名原生对比（自 0.71.0 起）

chimeraforge contribute gate --baseline before.signed.json --candidate after.signed.json --trusted-key receiver.pub --policy gate-policy.json --out decision.json --json

只有在完成精确的签名/制品验证并明确获得接收方信任后，才能比较公开的原生事实。重复标志会保留声明的群体；复制、残缺或不兼容的证据均无法满足条件。api.gate_signed_contributions 会返回防篡改的决策回执。退出码：0 表示有条件通过，1 表示认证失败或可比回退，2 表示格式错误/输出失败，3 表示不可用或无法得出结论。签名不能认证测量结果的真实性、硬件、权重或执行独立性。有关策略、匹配规则、字节限制和公开投影的局限，请参阅签名原生门控。

bundle prediction-*——私密预测证据（自 0.70.0 起）

保留计划及其绑定输入、显式评分策略和所有原始基准回执，以便离线交接：

chimeraforge bundle prediction-create plan.json --policy score-policy.json --benchmark first.json --benchmark second.json --out private-evidence --json
chimeraforge bundle prediction-verify private-evidence --json
chimeraforge bundle prediction-score private-evidence --out scorecard.json --json

**私密交接：**原始基准文件和测试框架文件可能包含提示词、选项、提供方诊断信息或路径。分享前请检查这些文件。元数据和评分卡会公开摘要回执和受限结果；目录会保留原始文件。不会进行上传。封闭式捆绑包契约会在 32 MiB 的传输预算内（包括两份清单）保留确切的回执顺序、字节、哈希以及负面/重复证据。收到的群体为空属于有效的缺失证据。对于有效内容，创建/验证操作退出码为 0；对于无效输入，退出码为 2；评分沿用现有退出码：0 表示在范围内，1 表示可比结果超限，2 表示无效，3 表示不完整。完整性验证不能使 GPU 证据满足资格，也不能认证测量结果。

study——冻结模型工作负载、硬件与成本敏感性

可在已发布的 0.61.0 CLI 中使用。 将明确的假设与一个已保存的计划或可移植捆绑包进行离线比较：

[
  {"name": "twice-the-load", "changes": {"request_rate": 2}},
  {"name": "half-duty", "changes": {"duty_cycle": 0.5}},
  {"name": "no-budget", "changes": {"budget": 0}}
]

将该列表保存为 cases.json，然后运行：

chimeraforge study plan.json --cases cases.json --out study.json --json
# A portable bundle works even with the producer's input files absent.
chimeraforge study handoff --cases cases.json --json

常规搜索会对每个案例使用相同的绑定模型几何信息和经过验证的系数／质量字节。当前引擎支持情况、适用的云价格、电网强度、隔离记录及其时间观测值只会采集一次。报告会将这些当前事实与生成方收据区分开来，保留带有门控原因的不可行案例，并以原生单位比较配置和估算值。策略身份发生变化时，研究会中止。

最多可为 16 个绑定模型目标提供 1–16 个唯一案例。工作负载、上下文、SLO、质量／安全目标、预算、占空比和成本假设可以变化；模型和平台保持固定。未明确指定硬件替代方案的案例也会保持物理硬件不变。 gpu_cost_per_hour 是 运维方的价格假设；对于云实例定价，系统会拒绝此参数；设为零则保留原生的价格未知行为。输出不能覆盖已知输入。退出码 0 表示建模研究已完成，包括不可行案例；输入无效或不可用时退出码为 2。不会下载权重或生成服务流量。完整性和建模差异无法验证输入真实性，也无法证明性能达标。 请参阅Python 和案例约定。

硬件替代方案（自 0.72.0 起）。 通过同一 CLI 或 Python API 比较 GPU 注册表中的完整规格，而无需更改已保存的计划：

[
  {"name": "larger-gpu", "changes": {"hardware": "RTX 4090 24GB"}},
  {"name": "ampere", "changes": {"hardware": "RTX 3090 24GB"}},
  {"name": "explicit-price", "changes": {"hardware": "H100 80GB", "gpu_cost_per_hour": 2}}
]

保存为 hardware-cases.json，然后运行 chimeraforge study plan.json --cases hardware-cases.json --out hardware-study.json --json。 使用 chimeraforge plan --list-hardware 列出的一个不区分大小写的精确规范名称；部分名称、存在歧义的条目和 auto 都会在搜索开始前被拒绝。对于包含云实例定价或 gpu_overrides 的来源，系统会拒绝显式硬件案例，包括显式选择同名硬件的情况；不包含 hardware 的情景会保留已保存的设置。 现有的统一内存占比会保持不变，并遵循原生兼容性规则。

每个替代方案都会绑定来自同一份已固定注册表的完整原始／有效 GPU 规格，包括 VRAM、带宽、算力、FP8、互连和价格来源。基础几何信息会继续绑定到来源。策略变更会导致中止；物理配置身份不包括价格和来源元数据。未知价格和不可行案例都会明确保留。非参考时序会保留原生外推标签，同时有效的模型质量证据仍标记为实测。这些是建模替代方案，不会探测此主机、运行推理，也不会认证硬件／权重。

deploy -- 导出服务配置

同构 Compose 机群（自 0.74.0 起）。 选择一个原始的在线 Linux CUDA vLLM/SGLang 候选项，且 N>1。每个副本都重复指定一次 --replica-devices 7,3 --replica-port 9001，提供互不重叠且有序的 TP x PP ID 组，以及不同的环回主机端口。对于三副本、TP=2 的候选项，直接 API 接受 replica_gpu_devices=[["7", "3"], ["9", "2"], ["8", "4"]] 和 replica_host_ports=[9001, 9002, 9003]。不要将这些选项与单数设备/端口选项混用。每个 inference-1..N 服务 都会保留已保存的模型/修订版本和各副本的批次大小；请手动指定每个端口。 没有路由器、扩缩容器或经过验证的物理容量。请参阅 完整 CLI/API 示例和限制。

显式部署设备（自 0.73.0 起）： 对已保存的每个 TP x PP GPU 重复指定 --gpu-device， 并可选设置 Compose --host-port。对于下面选择的单 GPU vLLM， 追加 --gpu-device 7 --host-port 9001。双 GPU 选择示例： --gpu-device 7 --gpu-device 3。也支持完整 GPU UUID。Compose 会输出 device_ids，而不是 count；其列表顺序表示请求的声明顺序，不代表观测到的 CUDA rank 映射。systemd 使用有序的 CUDA_VISIBLE_DEVICES 选择器。 API 接受 gpu_devices=["7", "3"] 和 host_port=9001；请参阅 完整选项、API 示例和拒绝条件。 省略这些选项时，默认导出的 GPU 数量和端口保持不变。 导出的准入上限为每个副本 64 个 GPU；不会验证设备、拓扑或性能。

将一个已保存的候选项导出为 Compose、systemd 用户服务、Ollama macOS LaunchAgent 或 Modelfile。不会安装、启动或部署任何引擎。

mkdir deployment
chimeraforge plan --model Qwen/Qwen2.5-1.5B-Instruct --hardware "RTX 4090 24GB" --ttft-slo 500 --tpot-slo 50 --save plan.json
# Bash: select a single-replica, resident vLLM FP16 candidate from this artifact.
CANDIDATE_INDEX=$(python -c "import json; p=json.load(open('plan.json')); print(next(i for i,c in enumerate(p['result']['candidates']) if c['backend']=='vllm' and c['quant']=='FP16' and c['n_agents']==1 and c['offload_fraction']==0))")
chimeraforge deploy --plan plan.json --candidate-index "$CANDIDATE_INDEX" --format compose --image vllm/vllm-openai:v0.30.0 --out deployment/compose.yaml

在 PowerShell 中，使用 $CANDIDATE_INDEX = python -c "..." 赋值相同的 Python 选择结果。 导出前请检查已保存的候选项；如果没有匹配项，选择将失败。 第一个候选项不一定是 vLLM，也不一定采用检查点的原生精度。 镜像标签只是一个明确的示例，并不表示该镜像已实际运行；请使用经过验证的引擎镜像，或使用摘要固定镜像内容。输出文件必须是新文件。 选择与显式镜像后端匹配的候选项。不支持的机群、 卸载、未解析的适配器路径，以及检查点/KV 不匹配都会明确报错。 Ollama 会输出守护进程设置和一个附带的 Modelfile，其中包含必需的配置步骤。 原生单元要求提供明确的已安装可执行文件路径。请参阅 支持的模板和配置验证。配置被接受不代表 GPU 已执行，也不代表预测准确。

deploy-verify —— 检查离线声明是否存在偏差

离线部署验证（自 0.75.0 起）。 将原始保存的计划、候选索引和完整渲染意图独立于待检查文件保存。对于上面的单副本导出：

chimeraforge deploy-verify --plan plan.json --candidate-index "$CANDIDATE_INDEX" \
  --config deployment/compose.yaml --image vllm/vllm-openai:v0.30.0 --json

如有需要，请提供相同的 --model，以及相同的单个 --gpu-device / --host-port；对于集群，请重复提供所有 --replica-devices / --replica-port 组。默认值表示请求渲染器默认值；不会根据实际文件推断选项。此命令会读取生成的 JSON Compose（不论扩展名是什么），以及预期的 Ollama 同级 Modelfile。不会解析 YAML、进行插值、读取 .env / 实际挂载、调用 Docker 或写入文件。

退出码 0 表示与此安装版本的渲染器一致；5 表示已准入的 JSON 或必需配套文件存在偏差；1 表示输入无效、不安全、不可用或超出限制。原生 CLI 用法错误仍返回 2。JSON 对象的顺序和空白无关紧要；标量类型、数组顺序及配套文件字节则会影响结果。固定的预期路径 / 类别不会包含实际值和未知键名。这不能证明源文件真实性、镜像 / 注册表准确性、正在运行的权重、原子快照或 GPU 执行情况。参阅完整的 API / 集群示例、限制和回执语义。

suggest —— 发现并为模型排序

chimeraforge suggest --source ollama --hardware "RTX 4090 24GB" --budget 500
chimeraforge suggest --source hf --hf-limit 8 --hardware "RTX 4080 12GB"
chimeraforge suggest --source catalog --hardware "RTX 4080 12GB"   # offline, after `catalog --build`

从实时 Ollama（/api/tags）、HF Hub（文本生成排名靠前的模型）和 / 或本地目录获取候选项；将每个候选项解析为实际参数 / 架构，运行相同的门控搜索，并展示每个模型的最佳配置。

measure —— 基准测试实时模型，依据实测数据进行规划

chimeraforge measure --model qwen3:14b --ollama-url http://localhost:11434
chimeraforge plan --model qwen3:14b --measure   # measure then plan in one step

对实时模型进行基准测试（真实 N=1 吞吐量、服务时间、并发扩展），并将结果纳入本地数据集。plan / suggest 随后会自动优先采用实测数据（来源会切换为 measured）。

SGLang 没有任何实测数据行，规划器会明确说明这一点，而不会借用 vLLM 的数据。请自行测量：chimeraforge measure --backend sglang --model <served-model-name> --base-url http://localhost:30000。vLLM、TGI 和 SGLang 适配器会流式处理并计时首个和最后一个 token，因此记录的是规划器预测的 解码速率，而不是包含预填充过程的整体耗时 token 速率。TTFT 会单独报告。token 数量取自服务端（usage 块，或 TGI 最终响应中的 generated_tokens）。没有 token 数量的响应会被丢弃，不会进行估算。

workload —— 根据真实流量推导计划输入

chimeraforge workload --from-log requests.jsonl --out workload.json
chimeraforge workload --from-metrics http://localhost:8000/metrics --engine vllm --out workload.json
chimeraforge workload --from-metrics http://localhost:8000/metrics --interval 60 --engine vllm --hardware "H100 80GB"
chimeraforge plan --model-size 8b --hardware "RTX 4090 24GB" --workload-profile workload.json

从 JSONL 请求日志或实时 vLLM/SGLang /metrics 端点读取请求速率、提示词/输出长度、流量方差和前缀缓存命中率，让 plan 不再依赖手动输入的猜测值。其中方差最重要——它决定整个排队尾部，而测得的 CV^2 并非四种预设值之一。

• 时间窗口（--interval 60）会抓取两次并计时实际间隔。也可以使用 --interval 配合两份已保存的抓取结果，输出会将该间隔标记为已声明，而非实测。时间窗口会将计数器转换为实测请求速率，均值、方差和缓存命中率描述的是该窗口，而非引擎的运行全程。如果两次抓取之间计数器重置（引擎重启），就会报错。
• KV 缓存压力读取自 vLLM 的 kv_cache_usage_perc 和 SGLang 的 token_usage，以及非零时的 SWA 和 Mamba 内存池。所有值都是 0-1 之间的分数，并标记为瞬时值。
• MFU 和 MBU根据每个引擎在一个时间窗口内的 FLOP 和字节计数器计算，并与 --hardware 指定的显卡的稠密 FP16 峰值和内存带宽进行比较。它们会标记为 estimated，因为计数来自引擎自身的分析模型，而非硬件计数器。只有服务器使用 --enable-mfu-metrics 运行时才会提供这些计数器；缺少时，配置档案会注明这一点。
• 指标名称取自 vLLM v0.30.0 和 SGLang v0.5.20 的源代码。测试夹具是这些声明生成的真实 prometheus_client 输出（scripts/make_engine_metrics_fixtures.py）。手工输入的夹具曾掩盖了 vLLM 前缀缓存计数器带有 _total 后缀这一事实，因此此前一直无法从真实端点读取该命中率。

指标名称按引擎明确区分；未知的 --engine 会报错，将错误的引擎指向某个端点也会直接报错，因为静默回退到改名后的指标会导致抓取器报告虚构的测量值。日志会提供 measured 均值和方差；Prometheus 直方图会提供精确均值，但方差是按桶近似的，并标记为 estimated。单次抓取无法得出速率，因此 request_rate 会保持缺失，而不会用未经测量的运行时间进行除法；数据源未提供的任何字段仍是 plan 的必填输入，不会设为默认值。显式标志始终优先于配置档案。

validate —— 根据实测数据审计预测

chimeraforge validate --matrix matrix.json --measurements captured.json

按来源类别评估规划器自身的预测，让“估算”有数据支撑，而不只是凭感觉。配置矩阵会以指纹形式纳入审计（SHA-256，与顺序无关）。将该哈希通过 --expect-fingerprint <hash> 传回；除非矩阵的哈希仍与之匹配，否则命令会失败。这样，在看到结果后编辑矩阵，就不能冒充已注册的矩阵——这是预先注册，而非事后挑选。若不使用此标志，系统会根据已加载的矩阵重新计算指纹并仅将其打印出来；这本身不能证明任何事情。所有单元格都会公开；汇总时会保留最差结果，而不是将其平均掉；样本数过少的类别会标记为统计效力不足，而不会被作为比率引用。

测量数据是有来源记录的，而非孤立的数字。每个单元格都会注明：

• 测量者：own-rig-measured 或 third-party-measured。两者分别列入评分卡，绝不混合平均；
• 数据来源：source_url，或在自有设备运行时记录的基准测试环境；
• captured_at 日期；
• 来源是否省略了服务配置（underspecified）；此类单元格不会纳入主要行，但仍会公开；
• 每个数字代表的量：decode_tps_single_stream、e2e_tps_single_stream、prefill_tps（根据单元格的提示词长度换算为 TTFT）、ttft_ms、e2e_latency_ms（单个请求、批量大小为 1，并与规划器的服务时间进行比较）、e2e_latency_p95_ms 或 aggregate_tps_at_concurrency。

端到端或聚合速率会保留在原始输出中，但绝不会用于评估规划器的解码预测；ambiguous 不会被加载。引用规划器拟合所用 TR 语料库的第三方单元格会被拒绝。v1 格式 {cell: {metric: value}} 因缺少来源信息而被拒绝。

{"schema_version": 2, "hardware": "RTX 4090 24GB", "cells": {
  "<model|quant|backend|c..|p..|o..|b1>": {
    "evidence": "third-party-measured", "source_url": "https://...", "captured_at": "2026-09-25",
    "underspecified": false, "config_quote": "llama-bench -ngl 99 -fa 1",
    "metrics": [{"definition": "decode_tps_single_stream", "value": "<tok/s>", "quote": "tg128 | ..."}]}}}

评分卡会报告带内通过率（依据矩阵中预先注册的 bands 容差；若未设置则为 n/a）、绝对误差中位数、GMFE（几何平均折叠误差，因此 2 倍高估和 2 倍低估的得分相同）、有符号偏差，以及最差单元格。容差范围、查询过的来源列表，以及每个单元格的 spec（用于离线预测的固定架构）都属于指纹内容。除非指定 --models-path，否则预测始终来自随附语料库，因此已发布的审计不依赖 measure 留在缓存中的内容。批处理单元格会被跳过，而不会与单流预测进行比较。

已发布的审计。 corpora/SCORECARD.md 根据 8 个已发布的第三方基准测试来源、涵盖 17 款 GPU 的 42 个单元格，对规划器进行评估。原始 JSON、每项排除及其规则，以及预先注册的来源列表均已提交；说明文档为 TR147。所有经过审计的预测都是屋顶线估算。

在配置完整的单元格中，解码预测仅有 13% 的情况落在 ±25% 以内，绝对误差中位数为 35.9%（n=15）。不同显存类型的误差方向相反：

• HBM 数据中心 GPU：解码速度中位数被高估 +58%，在 B200 上最高达 +206%。llama.cpp 在 A100/H100/H200/B200/MI300X 上测得的速度为 200-308 tok/s，而屋顶线估算则随带宽增长。
• GDDR 消费级显卡：解码速度中位数被低估 -36%。

对于 HBM GPU，将屋顶线解码数值视为上限。使用 python scripts/build_validation_corpus.py --write --audit 重新生成审计。如果已发布的审计过期或误差范围扩大，测试就会失败。

monitor-fleet —— 观测所有声明的已保存副本

被动监测已声明的副本集群（自 0.76.0 起）。 保留原始的原生三副本候选项，并直接定位现有端点：

chimeraforge monitor-fleet --from-plan fleet-plan.json --candidate-index "$FLEET_INDEX" \
  --endpoint replica-1=http://127.0.0.1:9001 \
  --endpoint replica-2=http://127.0.0.1:9002/metrics \
  --endpoint replica-3=http://127.0.0.1:9003/metrics \
  --ttft-slo 500 --interval 30 --windows 1 --observation-seconds 60 \
  --cleanup-seconds 2 --max-requests 256 --max-body-bytes 8388608 \
  --concurrency 4 --json --prometheus fleet-monitor.prom

原始候选项提供模型／后端和副本数。除非明确覆盖，否则沿用已保存的 TTFT／TPOT 目标。有序槽位保留完整／错误／已取消／未启动状态、原生直方图窗口和元数据前缀。所有已声明的槽位都必须完成并符合要求，才能通过（退出码 0）；已知绑定不匹配（5）、已知原生指标超标（3）和未知／未完成（4）仍分别处理；输入无效时退出码为 1，原生命令行用法错误时退出码为 2。共享的请求／正文／期限限制适用于每个指标和元数据路由；清理有单独的时限，并会等待完成。即使已保存的候选项包含多个副本，现有的 monitor 仍只监测端点。 参见完整的 API／CLI 示例、限制、取消和证明范围。 此功能不提供负载生成、GPU／拓扑／权重认证、汇总百分位数或容量／物理独立性声明。

monitor —— 观测明确指定的延迟 SLO

chimeraforge monitor --backend vllm --url http://localhost:8000 --model YOUR_SERVED_MODEL \
  --ttft-slo 500 --tpot-slo 50 --interval 30 --windows 1 --json
# After starting the selected candidate and generating traffic, bind its saved targets.
chimeraforge monitor --from-plan plan.json --candidate-index "$CANDIDATE_INDEX" \
  --backend vllm --url http://localhost:8000 --model Qwen/Qwen2.5-1.5B-Instruct --windows 1 --json

通过两个抓取周期的直方图窗口观测现有流量。将 P95 桶界与明确指定的毫秒目标进行比较，并报告 pass（退出码 0）、breach（3）或 unknown（4）；操作错误时退出码为 1。数据缺失、没有流量、计数器重置以及跨越目标值的桶都无法通过。支持 SGLang TTFT；其 ITL 直方图无法确定单个请求的 TPOT。--from-plan plan.json --candidate-index 0 会将已保存的候选项及目标来源绑定到被动服务元数据。已知的身份／配置不一致会单独以退出码 5 报告，与原生 SLO 结果区分；必需的端点身份不可用时退出码为 4。GPU 几何信息、集群拓扑、工作负载和不可变权重在无法获取时，仍明确标记为未经验证。独立的计划绑定和原生 SLO Prometheus 指标在监控指南中有说明。此功能不声称能校准预测偏差，也不会生成流量。

doctor——检查这台机器（只读）

chimeraforge doctor            # detected GPUs, what the planner can do with each, local engines
chimeraforge doctor --json     # the same report as JSON

此命令使用各供应商自有的工具检测本地平台，不会更改任何内容。每次探测都会注明所用工具；缺少工具会作为一项发现报告，而不是错误。

• **NVIDIA：**使用 nvidia-smi 获取设备信息，使用 pynvml 获取 CUDA 版本。
• **Linux 上的 AMD：**使用 amd-smi 或已弃用的 rocm-smi。如果数据库中没有该显卡，则使用显卡自行报告的带宽填入 --gpu-bandwidth-gbps。
• **Apple Silicon：**使用 system_profiler，并将结果报告为统一内存。
• **Intel：**使用 xpu-smi。绝不会将其 PCI-ID 设备名称猜测为某个产品。
• **Windows，任意供应商：**使用 CIM 和显示类注册表。Win32_VideoController.AdapterRAM 是 uint32，最大只能表示 4 GB，因此会改为读取驱动程序的 qwMemorySize。集成 GPU 的数值会标为共享内存地址空间，而非 VRAM。
• **WSL：**通过内核版本字符串中的 WSL 检测。Microsoft 指出，非 WSL 内核中也会单独出现“microsoft”。

不会信任退出代码，因为 rocm-smi 即使没有任何报告内容，退出代码也为 0。解析器会使用真实捕获的数据进行黄金测试，每个数据源及其许可证均列于 tests/fixtures/doctor/SOURCES.md。

每个设备都会获得一个规划状态：

• matched：已找到数据库条目，并附带用于规划该设备的标志。
• supply-figures：数据库中没有该设备，因此会列出所需的 --gpu-* 标志。只有在工具报告专用 VRAM 时才会填入数值。

本地服务引擎会使用与 bench 相同的默认 URL 进行探测。只有引擎通过其版本端点表明自身身份时，才会被视为正在运行。如果通用 Web 应用在 :8000 上响应 /health，报告会显示“有响应，但未表明自身是 vllm”，而不会将其视为 vLLM。（check 专用于检测计划偏差。）

doctor 还会显示与检测到的平台对应的引擎支持矩阵一行。各行分别为 linux-cuda、linux-rocm、linux-xpu、windows-native、windows-wsl2、macos-apple-silicon 和 cpu。

每个单元格都依据引擎自身文档中的固定版本信息生成：vLLM v0.30.0、SGLang v0.5.20、TGI v3.3.7 和 Ollama v0.34.4。每项声明都附有原文引述和 /blob/<tag>/ URL；文档未提及的内容会标为 not documented，而不会自行推测。

矩阵内容如下：

• vLLM 无法在 Windows 上原生运行；它可以在 WSL2 下运行。
• 在 ROCm 上，vLLM 列出了面向消费者的 Radeon 显卡（RDNA3/4），而 SGLang 和 TGI 仅支持 Instinct。
• Ollama 是唯一注明支持原生 Windows AMD 的引擎。
• TGI 的代码库已归档，并处于维护模式。

scripts/build_engine_support.py 会重建并验证该矩阵。矩阵超过 90 天未更新时，doctor 会发出警告。

contribute——分享基准测试结果，隔离其他结果

# Serve the FP16 checkpoint first; --quant records its precision.
chimeraforge bench --model llama3.2-3b --backend vllm --quant FP16 --runs 5 --output-dir results/
chimeraforge contribute export results/bench_*.json --out contributions/   # one file per result
chimeraforge contribute verify contributions/*.json              # schema + content hash
chimeraforge contribute import theirs.contribution.json          # into the local quarantine
chimeraforge contribute list
chimeraforge contribute review theirs.contribution.json --decision retain --reason "Replay needed" --json
chimeraforge contribute replay theirs.contribution.json --prompt "Explain KV caching briefly." --output-tokens 128 --runs 3 --base-url http://localhost:8000 --out replay.json --json
chimeraforge plan --model-size 3b --hardware "RTX 4090 24GB" --contributions

无签名的 v1 工作流是建立共享实测语料库的第一步。

• **贡献内容：**一项 bench 结果及其完整环境指纹（GPU、内存、驱动程序、CUDA、OS、引擎及版本、chimeraforge 版本）、每次运行的解码和 TTFT 数据，以及 SHA-256 内容 ID。
• **导出会拒绝的内容：**GPU 名称缺失、运行次数少于 3 次、后端默认精度未知，或未实际应用的量化扫描标签。--quant 声明所服务检查点的精度；它不会更改服务器已加载的模型。无效的指纹、时间戳、样本和不一致的派生统计数据也会被拒绝。解码 CV 超过 5% 时会标记为不稳定，但仍会保留。
• ID 可证明的内容：这些 v1 文件未经签名。ID 表明文件自导出后未被篡改，但不能证明是谁运行的，也不能证明数据真实。因此，导入的内容会进入本地隔离区，其中的任何内容都不会进入随附语料库或 measure 语料库。
• **plan --contributions 的使用方式：**仅在模型、引擎、量化方式和 GPU 完全匹配时使用，并取匹配贡献的中位数。该数值标记为 contributed（*），其等级低于 extrapolated，同时列出贡献 ID 及其来源的引擎／驱动程序集群。在参考设备上测得的本项目数据仍优先。

review 会记录无签名的 pending／retain／reject 处置结果及原因，并将其绑定到原始完整内容 ID 和封装摘要。它可读取文件或完整的隔离区 ID，并保留来源、隔离区和语料库。处置回执不会认证数据提供方，也不会更改规划器的资格判定。

replay 会针对明确联系的端点运行现有基准测试运行器，并要求提供提示词和输出令牌上限。它会记录已应用的工作负载、实际令牌数、所有请求／成功／失败计数、原生样本，以及服务元数据的前后状态。已知的 CPU、引擎、量化方式、模型或配置不一致情况，会与证据不可用的情况分别记录。GPU 名称会根据观测到的内存进行规范化；客户端的 NVML GPU 无法证明执行发生在远程端。

当前的 contribution v1 不包含原始提示词／选项／并发信息，也不包含不可变模型和远程配置绑定。因此，原生解码／TTFT 差异仍仅为算术结果，无法验证重放等效性。退出码为 0 表示审核或重放操作已完成，且未发现已知不匹配，并不表示复现通过。重放遇到已知不匹配、执行失败／不完整时以 1 退出；输入／选项格式错误或回执输出错误时以 2 退出。新回执不能覆盖 contribution 输入，也不能写入隔离区；其端点 URL 不包含凭据／查询参数。

已签名的 v2 contributions 和私密重放（自 0.65.0 起）

安装可选的签名扩展：pip install "chimeraforge[sign]==0.76.0"。 使用当前保存的 PlanBenchmark 回执和你的 Ed25519 密钥文件：

chimeraforge contribute sign plan-benchmark.json --private-key producer.key --out signed.json --json
chimeraforge contribute verify signed.json --format v2 --trusted-key producer.pub --out verified.json --json
chimeraforge contribute replay signed.json --format v2 --trusted-key producer.pub --private-workload private-workload.json --base-url http://localhost:11434 --out replay-v2.json --json

私密文件会准确提供原始提示词和记录的适配器选项；联系端点前必须确认它们的哈希值匹配。公开的已签名制品包含原生总体数据、声明的控制项和承诺值，不包含提示词、补全内容或原始选项。签名有效与接收方信任是两个独立事项。重放会报告当前记录配置的比较结果、已知不匹配项和不可用信息；原始线缆默认值和实际生成的泊松调度仍未经验证。v2 文件不会进入 v1 隔离区或规划器聚合。请参阅密钥设置、API、协议和退出约定。

catalog——本地模型目录

chimeraforge catalog --build         # resolve a curated seed (+ --with-ollama) and cache specs
chimeraforge catalog                 # list the cached catalog

持久化已解析的规格，以便 suggest --source catalog 完全离线地对已知良好的集合进行排序。

safety——实时拒绝检测

chimeraforge safety --model llama3.2-3b --prompts harmful.txt --quant Q4_K_M --safety-target 0.85

plan --safety-target 根据捆绑的 TR134/TR142 数据作出决策，而 safety 则进行测量：它会将你的探测提示词发送给实时模型，判定拒绝情况（基于规则——采用 TR134 正则表达式基线），报告测得的拒绝率与捆绑门槛数据的对比（预期值、偏差、RTSI 风险等级），并在低于 --safety-target 时以状态码 1 退出。提示词由你提供（--prompts，每行一条）——软件包不附带攻击语料；请指定 HarmBench / AdvBench / 你自己的集合。需要运行中的 Ollama。

bench——实时推理基准测试

chimeraforge bench --model llama3.2-3b --runs 5
chimeraforge bench --model llama3.2-3b --all-quants --context 512,1024,2048,4096 --json
chimeraforge bench --model llama3.2-3b --backend vllm --base-url http://localhost:8000
# Requires the selected vLLM candidate from the deploy example to be running.
chimeraforge bench --plan plan.json --candidate-index "$CANDIDATE_INDEX" --model Qwen/Qwen2.5-1.5B-Instruct --base-url http://localhost:8000 --prompt "Explain KV caching briefly." --runs 5 --json

bench --plan 会将不可变的已保存候选项与实际服务观测结果及已应用的工作负载关联起来。它会记录建模值与实测原生值、算术差异、配置不匹配项和不可用的证据；提供的量化 / TP 标签无法验证端点。部分请求和不同的计时基准无法通过建模 SLO。有关回执、适配器限制和退出码，请参阅规划 API 指南。托管 CPU 检查会测试此路径，但不声称能准确预测 GPU 性能。

三种工作负载配置文件（单次 / 批量 / 服务器泊松）；测量吞吐量、TTFT 和延迟的 p50/p90/p95/p99；提供基于 CV 的稳定性警告；输出 JSON。

在发送第一个请求前，bench（以及 measure）会确认该 URL 上的服务就是你指定的引擎：vLLM 通过 /version、TGI 通过 /info、SGLang 通过 /server_info，Ollama 则通过其根路径横幅识别。若某个端口能响应 /health，却无法表明自身身份，则会拒绝使用，因此其他 Web 应用的数据绝不会被记录为 vLLM 数据。

gate——明确的实测回归策略

保存包含非空原生指标规则、精确数量的有序重复测试，以及实测对照组 / 处理组的策略。每条规则都必须在每一对测试中通过；所有声明的回执及其原始样本聚合数据都会经过验证。

{"rules":{"completed_token_rate_tps":0.05,"ttft_ms":0.10},"expected_replicates":2,"fixed_controls":{"device":"cpu","backend":"ollama"},"require_cache_evidence":true}

chimeraforge gate --baseline baseline-1.json --baseline baseline-2.json --candidate candidate-1.json --candidate candidate-2.json --policy policy.json --out gate.json --json

使用实际的 bench --plan 回执文件。退出码 0 表示有条件的工程验证通过，1 表示回归，2 表示输入 / 输出格式错误，3 表示结论不确定。Ollama 服务端原生的预填充 / 解码 / 总耗时与 SSE 客户端计时不同；完整令牌数 / 客户端墙钟时间规则可以比较明确变更的后端。必需但未知的对照组、失败的请求、实测长度不同以及复制的执行载荷均无法通过。缓存证据依据实测的原生计数和配置；缺少必需事实或存在已知变更时，结果为 3。显式预先声明 require_cache_evidence:false 仅豁免缺少证据的情况，仍保留缓存未受控的适用范围，并维持对已知偏差的拒绝。任何决策都无法验证权重，也无法证明独立冷启动、置信度、GPU 准确性或包含排队时间的 SLO 已达成。请参阅完整的策略 / API 合约。基准测试门控功能自 0.61.0 起提供。

trace——真实计划请求与联合目标有效吞吐量

创建一个包含明确计划和输出上限的私有 workload.json：

[
  {"request_id": "first", "prompt": "Explain KV caching briefly.", "max_output_tokens": 32, "arrival_offset_s": 0},
  {"request_id": "second", "prompt": "List three primary colors.", "max_output_tokens": 16, "arrival_offset_s": 0.1}
]

# Requires this model to be running on the named endpoint. Prompts are sent there.
chimeraforge trace workload.json --model llama3.2-3b --backend ollama --concurrency 1 --latency-slo 2000 --first-output-slo 500 --tpot-slo 50 --out trace.json --json

trace 会记录每个计划请求，包括失败、部分完成、已取消和未启动的请求。客户端实际到达、排队、首次输出和终止时间可用于区分调度延迟与服务延迟。联合目标有效吞吐量使用完整的计划/观测时段；所需时间未知的请求不能计入。Ollama 流式传输会直接观测首次输出，而其原生预填充时间则单独记录。平均解码时间会标明计算依据，但不能证明满足逐个 token 的目标。其他不具备首次输出观测能力的适配器会将其报告为未知。输出上限是请求值，实际 token 数会另行记录。

自 0.62.0 起： --backend vllm、sglang 或 tgi 会通过原生流式传输观测可见的首次输出。原生 token ID 包含 EOS/控制步骤，必须与最终服务端计数相符；超出请求上限时会拒绝完成。客户端平均解码时间要求 token ID 完整、首次到达时只有一个 token，且首次与最后一次到达时间不同。有效的单 token 或缓冲式完成会保留计数和首次输出，但解码时间不可用。缺失的 ID/缓存计数仍为未知。这些客户端时间与服务端预填充时间及 Ollama 的服务端解码计算依据相互独立。

回执只包含提示词哈希，不包含提示词或补全内容。退出码 0 表示执行完成，包括违反 SLO 的情况；1 表示执行不完整/失败；2 表示输入格式错误。未设置目标时，不进行 SLO 资格判定。此功能衡量的是已联系的端点和客户端工作负载；GPU 几何结构、独立冷启动运行和已服务文件的身份验证仍未验证。Python API、限制、取消和时间计算依据，请参阅trace 合约。

trace --from-plan——保留冻结的候选项（自 0.68.0 起）

自 Chimeraforge 0.68.0 起可用。选择一个后端与现有端点匹配的候选项，并确保每个工作负载输出上限都等于其保存的 decode_tokens_per_req：

chimeraforge trace workload.json --from-plan plan.json --candidate-index 0 --model YOUR_SERVED_MODEL --concurrency 1 --out plan-trace.json --json

此包装器会保留所选计划、原始工作负载承诺和未更改的原生 trace。它仅从已保存的 SLO 输入中推导明确值，保留到达偏移量，并记录实际服务的别名。拒绝显式后端/SLO 覆盖。输出上限会生效；保存的上下文、并行度、批处理和集群设置仍为建模/未验证。执行前后的绑定矛盾以及实际 token 长度不匹配仍会清晰显示。退出码 0 表示执行完整且无已知绑定不匹配；1 表示不完整/不匹配；2 表示无效；原生 SLO 结果另行处理。关于 API、捆绑包保护和证据限制，请参阅计划绑定请求 trace。

gate --kind trace——包含排队时间的回归判定（自 0.63.0 起）

使用 Chimeraforge 0.63.0 或更高版本，将预先声明的 trace 策略保存为 trace-policy.json：

{
  "rules": {"goodput_rps": 0.05, "latency_p95_ms": 0.10},
  "expected_replicates": 1,
  "fixed_controls": {"device": "cpu"},
  "require_cache_evidence": true
}

chimeraforge gate --kind trace --baseline baseline-trace.json --candidate candidate-trace.json --policy trace-policy.json --out trace-gate.json --json

对每组有序重复运行（每个组 1–16 次）分别重复指定 --baseline 和 --candidate。此 gate 会验证已保存的回执，并重建请求时间、SLO 状态、原生算术结果和有效吞吐量。完整总体的 p95 包含排队延迟；tpot_p95_ms 汇总的是每个请求的 平均 TPOT，而非单个 token。所需行存在未知值、执行失败、控制项/长度不匹配、已知缓存漂移以及复制的执行都会导致判定为无法得出结论。所有声明的输入（包括未配对的回执）都会保留。退出码 0 表示有条件地通过策略；1 表示回归；2 表示输入/输出格式错误；3 表示无法得出结论。基准测试 gate 仍是默认的 --kind benchmark。关于零基线、证据限制和输出保护，请参阅 trace 策略/API 合约。物理来源身份验证、独立冷启动执行和 GPU 资格验证仍未验证。

trace-campaign —— 冻结的串行重放总体（自 0.64.0 起）

使用 Chimeraforge 0.64.0 或更高版本，以及一个已运行的模型：

chimeraforge trace-campaign workload.json --model llama3.2-3b --backend ollama --replicates 3 --campaign-timeout 1800 --concurrency 1 --request-timeout 300 --trace-timeout 600 --latency-slo 2000 --first-output-slo 500 --tpot-slo 50 --out campaign.json --json

工作负载只读取一次，并在联系端点之前冻结哈希清单、按序排列的描述符、控制项和总体。副本按串行方式运行，不重试，也不预热。首次执行不完整后，后续副本仍标记为 not_started；失败的原生回执会保留所有计划请求。子级原始哈希会如实保留为 null，因为它们使用冻结的类型化请求。清单会单独绑定原始输入字节。SLO 违规和未知目标会保留在原生回执中，不会导致完整执行变为不完整。

--campaign-timeout 覆盖准入、预检、元数据和计划重放。它会发出原生停止信号，并阻止后续副本准入；排空操作采用协作方式，可能没有时间上限。SIGINT 会生成停止回执；外部异步任务取消会在清理自有任务后继续传播。退出码 0 表示所有声明的副本均已完成，1 表示总体不完整或已停止，2 表示输入格式错误或输出失败。串行运行无法证明独立性或缓存处于冷态。请参阅活动 API 和生命周期契约。

trace-envelope —— 已观测的有限负载点（自 0.69.0 起）

按声明的统一到达速率评估完整的已保存活动，不进行推断：

chimeraforge trace-envelope --cases cases.json --policy envelope-policy.json --campaign slow=slow-campaign.json --campaign fast=fast-campaign.json --out envelope.json --json

封闭的用例和策略声明会固定请求承诺、副本数、并发数、超时和明确的 SLO 目标。每个副本中的每个请求都必须通过，该单元格才符合条件。报告只列出最高的已观测通过的名义速率；不会插值或估算服务容量。缺失较高单元格时，仍可保留较低的已观测点。整体退出码为 3。已知的控制项、缓存、实际令牌长度或计时依据矛盾，以及复制的原生证据，都会阻止排名。退出码：0 表示有条件通过且执行完整，1 表示已知 SLO 违规，2 表示输入或输出无效，3 表示证据不完整或不兼容。失败和未启动的时隙以及所有已知违规都会保留在结果中。

gate --kind trace-campaign —— 全总体判定（自 0.67.0 起）

自 Chimeraforge 0.67.0 起可用。在离线环境中比较两个完整的已保存活动。在 TraceGatePolicy JSON 文件中声明预期副本数，然后为每个组提供一个完整活动：

chimeraforge gate --kind trace-campaign --baseline baseline-campaign.json --candidate candidate-campaign.json --policy campaign-policy.json --out campaign-gate.json --json

门控会验证清单、每个已声明时隙以及未经修改的原生子级。失败、不完整和未启动的副本都会保留在结果中。控制项变更、观测缺失或复制的执行记录无法产生有条件通过；即使整体结果无法确定，已知违规仍会保留。执行是否完成与 SLO 是否成功是分开的。退出码：0 表示有条件通过，1 表示回归，2 表示输入或输出格式错误，3 表示无法确定。有关总体、字节限制、输出保护以及未经验证的独立性和硬件边界，请参阅策略和 Python API 契约。

score —— 冻结的预测评分卡（自 0.66.0 起）

使用 Chimeraforge 0.66.0 或更高版本。在 score-policy.json 中声明与计划绑定的总体和相对误差范围，然后离线为已保存的证据评分：

chimeraforge score --plan plan.json --policy score-policy.json --benchmark plan-benchmark.json --out scorecard.json --json

评分器读取已保存的候选预测，不会重新规划或替换其系数。它会重新计算原生总体、速率和服务绑定；不会信任生成方的审计声明。只有符合条件的单流 Ollama 服务解码速率才会参与评分，误差按 (prediction - measured) / measured 计算。缺失、多余、不匹配、不可用和重复的证据都会明确显示。完整总体的误差处于包含边界的范围内时，退出码为 0；即使存在其他不完整行，只要有可比较的超限项，退出码仍为 1；输入格式错误时退出码为 2，证据不完整时退出码为 3。实际 CPU 或不完整的硬件元数据无法让建模的 GPU 预测符合条件。这是有条件的算术计算，不涉及物理认证或校准 GO。参阅策略设置、API 和资格限制。

eval —— 质量评估

chimeraforge eval --task general_knowledge --json
chimeraforge eval --predictions preds.txt --references refs.txt --model llama3.2-3b

指标：精确匹配、ROUGE-L（回退到 LCS）、BERTScore、一致性 → 综合分数（0.2*EM + 0.3*ROUGE + 0.3*BERT + 0.2*coherence）。质量等级来自 TR125；内置 3 项任务（general_knowledge、summarization、code）。传入 --fp16-baseline 可对性能下降等级进行分类。

compare —— 对比基准测试运行结果

chimeraforge compare --baseline run1.json --candidate run2.json,run3.json --json

按（模型、后端、量化、工作负载、context_length）匹配配置；计算吞吐量、TTFT 和持续时间的差异，并汇总改进或退化情况。

refit —— 更新规划器系数

chimeraforge refit --bench-dir ./results/ --output fitted_models.json --validate

贝叶斯混合（按键进行置信度加权）、硬件偏移、幂律重新拟合，以及用于控制写入操作的 10 项验证套件（--validate）。

report —— 生成报告

chimeraforge report --results-dir ./results/ --format markdown --output report.md

生成 Markdown（兼容 GitHub）和自包含、可防 XSS 的 HTML；提供统计分析（RMSE、MAE、MAPE、R^2）和按配置划分的百分位数表。

serve —— 本地规划 HTTP API

chimeraforge serve --port 8765 通过环回 HTTP 提供经过验证的规划器服务，默认离线。POST /v1/plan 返回已保存的计划构件；格式错误的输入会返回结构化错误。参阅本地 API 契约。

mcp —— 向 AI 助手提供规划器服务

chimeraforge mcp
chimeraforge mcp --transport streamable-http --port 8766

运行上文所述的 MCP 服务；默认使用 stdio，也可显式选择 Streamable HTTP 环回模式。需要运行 pip install "chimeraforge[mcp]"。

---

建模内容

维度	计算方式	来源
VRAM / KV-cache	根据真实模型架构进行第一性原理计算；支持 KV 量化以及感知 TP/PP 的分片；MLA/SWA 缓存形状；混合模型仅在注意力层缓存，并按序列保存其循环状态	派生（精确算术）
最大并发数	每个 GPU 上受 KV-cache 限制的序列数	精确
吞吐量（解码）	在参考设备上进行实测查询；其他设备按带宽缩放；否则使用 roofline。extrapolated 值会标注其锚点：行、设备和比率	实测 / 外推 / 估算
TTFT（预填充）	受计算限制（GPU FP16 TFLOPS x MFU），下限为受内存限制的权重读取时间；通过 --max-num-batched-tokens 进行分块预填充	估算
质量	实测综合分数查询、基于系列先验的估算或未知——每个单元格都标注样本量，以及该样本量能够分辨的最小差异；--quality-from 可导入真实的 lm-evaluation-harness 运行结果	实测 / 估算 / 未知
成本	GPU 每小时价格 x 集群规模（每 1M 个 token 的价格不受副本数量影响）	派生（精确算术）
能耗	基于 TDP 的月度 kWh、每 1M 个 token 的成本（+能耗）、每瓦 tok/s	估算
碳排放（可选）	能耗 x 电网排放强度（通过 OWID 获取 Ember 生命周期 gCO2e/kWh 数据，按国家和年份划分）；仅包含 SCI 运行项	估算
安全性	TR134/TR142 拒绝率查询（可选门控）	实测 / 未知

**硬件：**50 款 GPU：

• 消费级： Ampere/Ada/Blackwell（RTX 30/40/50 系列）和 AMD RDNA4（RX 9070 / 9070 XT / 9060 XT）。
• 工作站： RTX PRO 6000 Blackwell（Workstation、Max-Q、Server）、Radeon AI PRO R9700，以及 Intel Arc Pro B60/B65。
• 数据中心： A100 40/80GB、H100、H200、B200、L4、T4，以及 AMD MI300X/MI325X/MI350X/MI355X/MI455X。
• 统一内存： 目前销售的 Mac 中搭载的所有 Apple Silicon 芯片（A18 Pro、M4、M5、M5 Pro/Max/Ultra 和 M6，按 GPU 核心数变体区分），以及 AMD Ryzen AI Max+ 395 和 NVIDIA DGX Spark。

每款设备都列出 VRAM、带宽、FP16 TFLOPS、TDP 和互连（NVLink/Infinity Fabric/PCIe）。每项数据都附有来源 URL、采集日期、TFLOPS 数值所依据的数据表列，以及 $/hr 是租赁价格还是摊销后的购买成本。

统一内存设备由 CPU 和 GPU 共用一个内存池，因此不会将整个内存池都视为 VRAM：

• --unified-memory-fraction 指定 GPU 可使用的内存比例。此参数必填，且没有默认值，因为操作系统和其他应用也需要使用内存。
• 每个条目都会列出所有在售内存配置（M5 Max 40 核 GPU 有 48、64 或 128 GB 配置）。命名方案假定使用最大配置，并会明确说明；使用 --gpu-vram-gb 可更正该假设。--hardware auto 则使用已安装的内存。
• 方案会提醒：CPU 和 GPU 共用同一个带宽数值，因此解码速度只是上限。
• Apple Silicon 的方案使用 macOS 行，此时 vLLM 仅支持 CPU；Strix Halo 使用 ROCm 行。

厂商未公布的数据会保持未知，未知不等于零：

• 未公布价格（RTX PRO 6000、Instinct、Arc Pro、R9700）：预算检查会拒绝该显卡，而不是按 $0 计价。请传入 --gpu-price-per-hour。
• 未公布密集 FP16 数值（Arc Pro，以及 RTX PRO 6000 Server Edition，其“1 PFLOP”未标明精度）：TTFT 会按受内存带宽限制的最低值报告，该值是下限；传入 --ttft-slo 时会直接拒绝，而不会据此检查。请使用 scripts/build_hardware_data.py 重新生成并验证数据。未列出的 GPU 不再受限：可使用 --gpu-vram-gb 和 --gpu-bandwidth-gbps（以及可选的 --gpu-fp16-tflops / --gpu-tdp-w / --gpu-interconnect-gbps / --gpu-price-per-hour）为任意显卡规划；--hardware auto 则读取已安装的显卡。 **已知限制（如实说明）：**目前尚未对推测解码建模。预填充下限是根据 MBU_DEFAULT 推导出的界限，而 MBU_DEFAULT 是基于单个数据点校准的——应将其理解为“不会比这更快”，而不是预测值。分块预填充开销根据该机制所隐含的 KV 重读量推导，再限制在唯一已发布的上限（预算为 512 个 token 时为 25%，Sarathi-Serve arXiv:2403.02310）；分块量化的陡降点（实测 257 个 token 的预算比 256 个慢约 32%）确实存在、影响显著，而且我们有意不对其建模——规划器会改为发出警告。前缀缓存会对预填充节省量建模，但不会对 KV 节省量建模（有意采用保守估计）。推理 token 会纳入模型，但比例由你输入（--reasoning-tokens），绝不自行推断。对于 MoE，会对激活参数量与总参数量进行建模，但不会对专家并行和路由负载不均衡建模。对于混合架构，会从模型自身的配置读取注意力层划分，并根据 transformers 源码中的形状推导 Mamba-2/Mamba-1/gated-DeltaNet 的循环状态；Kimi 的 KDA 状态根据 DeltaNet 惯例推断，并会明确说明这一点；无法确定层模式的架构（Falcon-H1，一种并行混合架构）则会在每一层都保留完整 KV，而不会猜测。Multi-LoRA 会精确计算适配器 VRAM，但其解码开销是根据单次已发布的扫描结果按秩估算的，且不会对每个适配器的 KV 碎片化建模。异构集群会精确求解资源分配，但假设存在当前没有任何引擎提供的请求路由器，并会继承组合中每种 GPU 类型的吞吐量估算误差。vLLM/TGI/SGLang 的量化支持范围为 FP16 + FP8 + AWQ/GPTQ；FP8 和 W4A16 的质量是估算值，而非实测值——TR 质量语料仅覆盖 GGUF k 量化。随附的质量语料只有 20 个项目，无法分辨小于约 21 个百分点的差异（Miller，arXiv:2411.00640 Eq. 9），因此其中每个实测量化差异都报告为与 FP16 基线无法区分，而非报告为差异——运行实际测试工具，并通过 --quality-from 提供结果，即可获得足以支持区分的单元格。质量是在 2K 上下文下测量的；对于 >=64K 时的窄量化，质量会报告为 UNKNOWN，因为已发布结果显示损失最高可达 59%（arXiv:2505.20276）。TP 和 PP 吞吐量是根据通信模型得出的估算值，并非实测值，也不能在同一规划中组合使用。排队分析是解析式的（考虑方差），不是离散事件模拟器。随附语料主要基于一台设备（RTX 4080 12GB）拟合；在你对自己的 GPU 运行 measure 之前，其他 GPU 都根据带宽/计算能力进行缩放。现在已公布这种缩放与实测之间的偏差，而非将其视为理所当然：与第三方基准测试相比，屋顶线模型对 HBM 设备过于乐观（解码中位数 +58%），对 GDDR 显卡则过于悲观（解码中位数 -36%），而其 TTFT 误差方向相反（TR147）。统一内存设备会根据你指定的内存池占比进行规划（--unified-memory-fraction，无默认值）。操作系统预留量由你指定；CPU 和 GPU 共用一条带宽，因此解码结果是上限；厂商均未公布其 GPU 的 FP16 性能或单设备价格。各平台的引擎可用性依据每个引擎自己的文档进行检查，但部署操作系统是输入项（--platform，默认值为 linux），规划器无法自行检测。若引擎文档未说明某个平台的支持情况，规划会发出警告，而不会拒绝。用户提供的显卡没有已知厂商，因此不会检查其引擎支持情况，且每个候选项都会对此作出说明。--hardware auto 会通过 doctor 的厂商专用探测读取本地 GPU，并针对这台机器的操作系统进行规划，除非另行指定 --platform。在 Mac 上，自动检测会根据芯片和已安装内存，匹配该配置对应的销售版本。MCP 支持 stdio 和选择启用的本地回环 Streamable HTTP 传输。HTTP 默认离线运行，拥有有界会话数和工作线程数，并非公开托管服务；超时的同步任务会继续占用工作线程，直到任务完成。

---

研究得出的结论

第二阶段（TR123-TR133，约 106,000 次测量）提炼出一套由产物佐证的部署框架——规划器应用的正是这些规则：

决策	建议	证据
单 Agent 后端	Ollama Q4_K_M	吞吐量／成本比最高；质量仅低 4.1 个百分点（TR123-TR125）
多 Agent 后端（N>=4）	vLLM FP16	连续批处理带来 2.25 倍优势（TR130-TR132）
编译策略	仅预填充阶段，Linux，Inductor+Triton	提速 24-60%；解码阶段崩溃率为 100%（TR126）
量化	默认使用 Q4_K_M；质量关键场景使用 Q8_0；绝不使用 Q2_K	在 5 个模型中普遍是最佳折中（TR125）
上下文预算	12 GB 显存时，超过 4K 个 token 使用 Ollama	显存溢出会造成 25-105 倍的性能断崖（TR127）
容量规划	chimeraforge plan	已验证的 R^2>=0.859；比 M/D/1 准确 20.4 倍（TR133）
安全筛查	plan --safety-target（可选启用）	按配置评估拒绝率和 RTSI 风险；排除安全性崩溃的配置单元（TR134/TR142）

主要发现（完整数据见技术报告）：Rust 在单 Agent 场景中胜过 Python（吞吐量提升 15.2%，TTFT 降低 58%，内存占用降低 67%——TR112）；双 Ollama 实例实现近乎完美的多 Agent 并行度（约 99%），而单实例为 82.2%（TR110/TR113/TR114）；vLLM 的连续批处理在 N=8 时带来 2.25 倍优势，瓶颈在 GPU 内存带宽，而非技术栈（TR130-TR132）。

完整研究： docs/archive/technical_reports.md 收录了全部 32 份报告的索引；包含方法论和原始数据引用的完整档案位于 outputs/publish_ready/reports/。

---

数据的生成方式

• 约 204,000 次主要测量，覆盖 32 份技术报告（TR108-TR137，以及 TR142/TR146 安全性溯源），在 RTX 4080 Laptop（12 GB；192 位 GDDR6，432 GB/s）上完成。所有跨 GPU 估算都以这台参考设备为基准进行缩放。已去重：TR137/TR142 是对已计入数据的综合分析。规划器自身的查找表仅包含其中一小部分（23 行吞吐量数据）；简介下方的表格列出了其确切规模。
• 严谨性： 每次运行都在独立的新进程中进行（无热缓存偏差），强制冷启动，每种配置运行 3-5 次以确保统计置信度，并以结构化 JSON/CSV 格式记录完整溯源信息。每项结论都能追溯到可重新运行的原始数据。
• 项目背景： ChimeraForge 是上层 Banterhearts 项目中可直接使用的 CLI 组件（该项目包含约 1,337,000 次主要测量和评审测量，覆盖 54 份 TR）；安全攻击面和服务技术栈的研究位于姊妹仓库中。
• 3,828 项自动化测试（通过 pytest --collect-only tests/ 收集）覆盖规划器模型、门控搜索、解析器、发现、安全、基准测试后端和 MCP 服务——与 GPU 解耦，核心测试套件无需运行中的后端。带日期的测试收集与使用方检查 区分了测试收集与实际执行。此前完整的本地运行记录了 3,798 项通过和 3 项跳过。

要复现任意数据：在 outputs/publish_ready/reports/ 下的报告中找到对应结论，沿着引用找到数据文件夹，检查 CSV/JSON 文件，然后重新运行提供的脚本或笔记本。参见 docs/archive/methodology.md。

仓库布局

路径	内容
src/chimeraforge/	chimeraforge CLI + 容量规划器（pip 包）
src/python/banterhearts/	Python Agent 基准测试、监控、分析
src/rust/	Rust 单 Agent 和多 Agent 实现（Tokio + 4 种替代运行时）
outputs/publish_ready/reports/	权威 TR 存档（TR108-TR137）+ 综合报告——查阅研究发现从这里开始
docs/	指南、API 参考和技术报告索引——了解使用方法从这里开始
experiments/、data/、benchmarks/	复现实验脚手架、基线和原始基准测试产物

文档

• docs/README.md —— 文档索引和导航
• docs/quick_start.md —— 首次运行基准测试（Python + Rust）
• docs/API.md —— 软件包的 Python API 参考
• docs/archive/technical_reports.md —— 全部 32 份技术报告的索引
• docs/archive/dual_ollama_setup.md —— 复现多 Agent 结果的必读文档
• docs/archive/methodology.md / docs/archive/rust_vs_python.md —— 方法论和完整的语言比较

贡献

欢迎贡献——请参阅 CONTRIBUTING.md。欢迎参与的领域包括：新增基准测试配置、优化策略、新模型/硬件、文档和分析工具。

许可证

MIT——请参阅 LICENSE。

致谢

电网碳强度数据：Ember，《Yearly Electricity Data》（2026），由 Our World in Data（energy-data、Ritchie、Rosado 和 Roser）处理；两者均采用 CC BY 4.0 许可。随附的快照记录了读取数据时精确的 OWID 提交版本。

本项目作为 Banterhearts LLM Performance Research Program 的一部分开展：第 1 阶段（TR108-TR122）确立了测量方法和跨语言比较；第 2 阶段（TR123-TR133）产出了部署框架和容量规划器；第 3 阶段（TR134-TR137）测量了推理优化的安全成本——现已成为规划器的可选安全门控。

---

仓库： https://github.com/Sahil170595/Chimeraforge - PyPI： https://pypi.org/project/chimeraforge/ - 状态： Beta，正在积极开发

已保存的计划和 Python 集成

chimeraforge plan --model-size 3b --no-network --save plan.json 会将生效的输入、解析后的事实和候选项来源信息保存在带版本号的产物中。经过验证的 Python API 接受 PlanRequest，并返回相同规划核心的结果。请参阅API 和产物规范。