Chimeraforge

一款本地优先、与模型无关的 LLM 部署规划器。 它把"用哪个模型、什么量化、哪块 GPU、什么后端——需要多少张、能不能装下、能否满足 SLO、要花多少钱"变成快速、诚实、可度量的答案，从你的 shell、你的 Python、或你的 AI 助手中直接获得。

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

信任原则

每个数字都标注为 measured、estimated 或 unknown，工具拒绝伪造它无法背书的数字。 VRAM 和 KV-cache 根据模型的真实架构计算（精确）。吞吐量在有数据时是实测查找，否则是明确的带宽上限估算——绝不冒充它本不是的数据。低于捆绑语料库的质量报告为 unknown，而不是编造的分数。0 结果的计划会指出拒绝所有候选者的具体门槛，而不是泛泛的"未找到"。无遥测、无回传，可离线运行。

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

一个工具，12 条命令： plan - suggest - measure - validate - catalog - safety - bench - eval - compare - refit - report - mcp。

经验语料库可追溯至技术报告 TR108-TR137（消费级 GPU 上约 204,000 条真实测量数据）。完整功能历史见 CHANGELOG。

Related MCP server: infra-advisor-mcp

安装

无需安装即可试用：

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 (BERTScore, ROUGE-L)
pip install chimeraforge[refit]     # + coefficient refitting (numpy, scipy)
pip install chimeraforge[all]       # everything

需要 Python 3.10+。核心安装涵盖规划器和面向网络的命令（httpx 是核心依赖）。plan / suggest / catalog 完全离线运行；bench / measure / safety 需要运行中的后端（Ollama、vLLM 或 TGI）。支持 Windows / macOS / Linux。

快速上手

# 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 meta-llama/Llama-3.3-70B-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

MCP 服务器——给 Claude / GPT / Cursor 同样的数字

GPU 容量规划恰恰是助手最容易出错的地方：训练截止时的硬件价格和规格，加上凭记忆做 KV-cache/批处理算术极易出错。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 在自包含环境中运行服务器。如果你已经将 pip install "chimeraforge[mcp]" 安装到客户端启动的环境中，也可以改用 "command": "chimeraforge", "args": ["mcp"]。

暴露三个工具：chimeraforge_plan（完整门槛搜索）、chimeraforge_resolve_model（将模型 ID 落实到其真实参数/架构）和 chimeraforge_list_hardware。每个结果都带有与 CLI 相同的 measured / estimated / unknown 来源标注，工具描述会告诉模型优先使用这些数据而非自身知识。chimeraforge_plan 还返回一个 launch 字段——推荐配置的 serve 命令——这样助手就能回答"那怎么运行"而不必编造参数。

命令

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 meta-llama/Llama-3.3-70B-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/...）。

• 在（模型 x 量化 x 后端 x N 副本 x 批处理/GPU）空间中通过 5 道门槛流水线搜索：VRAM -> 质量 -> 安防（可选）-> 延迟 -> 预算。

• 建模真实服务物理：连续批处理（vLLM/TGI）、prefill/decode 分离（TTFT + TPOT）、KV-cache 约束的并发度，以及方差感知的排队（--workload）。

• 适配单 GPU 装不下的模型： --tensor-parallel/--tp {N|auto} 将权重 + KV 分片到 N 块 GPU 上（Megatron 风格，已建模通信开销）；--pipeline-parallel/--pp {N|auto} 改为将层拆分到 N 个阶段（在慢速互连上更便宜，需要批处理来填满流水线）。暂不可组合使用。

• 后端提供什么就服务什么： GGUF 量化在 Ollama 上提供；vLLM/TGI 获得 FP16 和 FP8（仅在具有 FP8 张量核心的 GPU 上——Ada/Hopper/Blackwell/CDNA3）。规划器不再在 vLLM 上以 llama.cpp 加速的价格建议 GGUF 检查点。

• KV-cache 量化（--kv-quant {fp16,q8,q4}）缩小缓存并提高最大并发度——在长上下文下收益最大。

• 成本现实性（--duty-cycle、--gpu-price-multiplier）：头条的 $/1M-tok 价格假设的是满载集群。你还要为预留的余量和每个空闲小时付费，因此 8B 模型在 2 req/s 下的实际数字是满载时 $2.71/1M，30% 负载时 $9.04/1M，而容量满载时为 $0.92。Spot/预留定价是你的输入，不是捆绑的猜测。

• 自托管与 API 盈亏平衡（--compare-api）：将你的工作负载与托管 API 定价对比，报告自托管开始胜出的月度用量。价格是带每个提供商来源 URL 的日期快照，超过 90 天标记为过期——绝不冒充实时报价——前沿 API 被标注为不同质量层级，而非当作同级别对比。

• 前缀缓存（--prefix-cache-hit-rate）：聊天机器人和代理流量复用长系统提示词，因此大部分 prefill 已被缓存。在 4k 提示词和 90% 命中率下，8B 模型的 TTFT 从 166ms 降至 17ms。默认为 0 且从不推断，共享前缀节省的 KV 被刻意不扣除——KV 容量不足正是把"装得下"变成 OOM 的原因。

• 推理模型（--reasoning-tokens N）：隐藏的思考 token 由 GPU 解码并保存在 KV 中，即使调用方永远看不到它们。只计算可见输出会按推理比例低估 decode——在我们自己的检查中，1000 个隐藏 token 将 8B 计划的 p95 从 363ms 推高到 6128ms。默认为 0 且从不推断：该比例是你工作负载的属性，不是权重的属性。

• 注意力形态感知的 KV： MLA（DeepSeek-V2/V3）缓存压缩的潜在向量而非每头 K/V——将其按 GQA 计算会高估 DeepSeek-V3 的缓存 57 倍——滑动窗口模型在窗口之外停止增长缓存。层模式未声明的窗口不会被应用，因为 KV 容量不足正是把"装得下"变成 OOM 的原因。

• 混合专家（MoE）感知： VRAM 按总参数量计算（每个专家都驻留内存），而吞吐量和 TTFT 使用活跃参数量（一个 token 只读取它路由到的专家）。将 MoE 模型当作稠密模型会在 Mixtral-8x7B 上低估其吞吐量 3.6 倍，在 DeepSeek-V3 上约 18 倍。活跃数量从模型真实的专家几何结构推导，与已发布数据吻合。

• 能耗（--electricity-rate）：月度 kWh 成本、$/1M-tok (+energy) 和 tok/s-per-watt，与预算门槛并列报告（不并入其中）。

• 启动命令导出（--launch）：为胜出配置输出 vllm serve / ollama run / TGI docker run 命令，填入计划自身的上下文长度、TP/PP 度数、批大小和 KV dtype——这些正是容易手算出错的地方。它不会编造无法推导的内容：GGUF 量化级别变成一条注释，建议服务原生等效检查点，而不是虚构的 --quantization 参数。

• 每个预测都有来源标注（measured / estimated / unknown）；当无配置可行时解释被拒绝的约束门槛。

• 已在注册表数据上验证：VRAM R^2=0.968，吞吐量 R^2=0.859，质量 RMSE=0.062，延迟 MAPE=1.05%（比解析 M/D/1 好 20.4 倍，TR133）。无机器学习——经验查找表配合第一性原理插值（注册表外模型使用上限估算）。

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）。

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

三种工作负载配置（单请求 / 批处理 / 服务器-Poisson）；测量吞吐量、TTFT 和延迟的 p50/p90/p95/p99；基于 CV 的稳定性警告；JSON 输出。

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

按（模型、后端、量化、工作负载、上下文长度）匹配配置；计算吞吐量/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），带每配置百分位表。

mcp —— 将规划器提供给 AI 助手

chimeraforge mcp

运行上述 stdio MCP 服务器。需要 pip install "chimeraforge[mcp]"。

建模了什么

硬件： 22 款 GPU——消费级 Ada + Blackwell（RTX 40/50 系列）、数据中心级（A100 40/80GB、H100、H200、B200、L4、T4）以及 AMD MI300X——每款均含 VRAM、带宽、FP16 TFLOPS、TDP 和互联参数（NVLink/Infinity/PCIe）。

已知限制（如实说明）： 尚未对投机解码（speculative decoding）建模。前缀缓存只统计了 prefill 阶段节省的显存，并未统计 KV 缓存（刻意保持保守）。Reasoning token 已建模，但占比是由你用 --reasoning-tokens 传入的，绝不自动推断。对于 MoE，激活参数数 * 是*会建模的，但专家并行（expert parallelism）和路由非均衡未建模。vLLM/TGI 的量化支持 FP16 + FP8（AWQ/GPTQ 暂不支持）；FP8 质量按估算，而非实测。TP 与 PP 的吞吐量只是基于通信模型得出的 估算，并非实测值，且不能合并到同一个 plan 中。排队容量是解析化（能感知方差），并不是离散事件模拟器。训练库主要在单台 RTX 4080 12GB 设备上适配；其他 GPU 会先从带宽/算力推算，直到你在自己的机器上 measure 得到测量结果。MCP 服务器仅支持 stdio 传输（Claude Code/Desktop、本地 Cursor），还没有 host 式的远程传输。

研究得到的结论

阶段 2（TR123-TR133，约 10.6 万次测量）沉淀为了一整套基于产物、可落到部署的框架——也就是规划器实际遵守的同一套规则：

核心发现（完整数据见各 TR）：Rust 在单 agent 上优于 Python（+15.2% 吞吐、-58% TTFT、-67% 内存——TR112）；双 Ollama 接近完美的多 agent（约 99%）并行度，而单实例仅 82.2%（TR110/TR112 113 及其后续）；vLLM 的连续批处理在 N=8 时带来 2.25 倍优势，强制短板在 GPU 内存带宽，而未非框架自身（TR130-TR132）。

完整 research 看这里： docs/archive/technical_reports.md 索引，全部 32 份报告；包含方法论与原始数据引用的完整归档位于 outputs/publish_ready/reports/。

数据是如何得出的

• 约 20.4 万次主测量来自 32 份技术报告（TR108-TR137，外加 TR142/TR146 安全数据来源），实验环境为 RTX 相关 Laptop（12 GB）。去重后：TR137/TR142 是已统计数据的整理结果，不再单独计数。

• 严谨性： 每次运行采用全新进程隔离（避免 warm-cache 干扰），强制冷启动，每个配置运行 3-5 次以达到统计显著性，并使用带完整溯源的结构化 JSON/CSV 日志。所有结论都可回溯原始数据重新复现。

• 项目背景： ChimeraForge 是父项目 Banterhearts 的 CLI 产物（约 133.7 万次主测量 + 裁判模型测量，跨 54 个 TR）；安全攻击池和相关服务栈研究位于相邻 repos 中。

• 549 个自动化测试（pytest tests/）覆盖 planner 模型、gate 搜索、resolver、发现、安全、 bench 后端以及 MCP 服务器——核心测试已与 GPU 解耦，无需真实后端也可运行。

复现任何数字：在 outputs/publish_ready/reports/ 中找到对应报告，按其中的引述定位数据目录，检查对应 CSV/JSON，再重新跑提供的脚本或 notebook。详见 docs/archive/methodology.md。

仓库结构

文档

• 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 —— 复现 multi-agent 结果所必需

• **docs/archive/methodology.md / docs/archive/rust_vsPython.md —— 方法论与完整语言对比

贡献

欢迎贡献，见 CONTRIBUTING.md。适合的领域：新增 benchmark 配置、新的优化策略、更多模型/硬件、文档及数据分析工具。

许可证

MIT — 见 LICENSE。

致谢

本项目是 Banterhearts LLM 性能研究计划的一部分：阶段 1（TR108-TR122）建立了测量方法论和跨语言对比；阶段 2（TR123-TR133）产出了部署框架与容量规划器；阶段 3（TR134-TR137）量化了推理优化带来的安全成本——现在已作为 planner 中的 opt-in 安全门。

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