inferbench

InferBench

每篇介绍“最佳本地大模型引擎”的文章，测试的都是别人的机器。InferBench 测试的是你的机器。

本地推理引擎都会在自己的硬件上进行基准测试，并把结果发布在自己的 README 中。但没有哪款工具能告诉你，在你眼前这台机器上，哪个引擎的速度最快。InferBench 会针对你机器上已安装的受支持引擎，运行一组固定且多样化的提示词，并报告真实测得的每秒令牌数——而不是从别人的博客文章里复制一个数字。

安装、首次运行，以及使用缓存模型进行的真实 omlx 基准测试：

npx inferbench-cli run --engines llama.cpp --model "bartowski/Qwen2.5-1.5B-Instruct-GGUF:Q4_K_M"

目录

• 安装
• 功能
• 快速入门
• CLI 命令参考
• 库 API 参考
• 测量方式
• 比较
• 项目初衷
• 文档
• 常见问题
• 贡献
• 安全
• 许可证

安装

InferBench 提供两个彼此独立、同等重要的包——选择适合你工具链的包，也可以两个都安装。两者都不会被弃用或取代；它们使用相同的测量架构，对两个相同的受支持引擎进行测试。

# npm -- JavaScript/TypeScript CLI
npm install -g inferbench-cli
# or, no install:
npx inferbench-cli run --engines llama.cpp --model "<repo>:<quant>"

# PyPI -- Python CLI + library (genuine port, not a wrapper around the Node binary)
pip install inferbench-cli

两个包目前都已发布并可安装。 npm install -g inferbench-cli 和 pip install inferbench-cli 均可正常使用——详见 npmjs.com/package/inferbench-cli 和 pypi.org/project/inferbench-cli， 也可查看 python/README.md 和 docs/getting-started.md 中针对 Python 的操作指南，以及 CHANGELOG.md 中各个发行版的版本历史。

npm 包需要 Node.js >=18，PyPI 包需要 Python >=3.10。无论选择哪种方式，都必须预先安装至少一个受支持的引擎（InferBench 不会为你安装引擎）：

• llama.cpp：brew install llama.cpp（macOS），或从 ggml-org/llama.cpp 构建
• omlx：brew tap jundot/omlx https://github.com/jundot/omlx && brew install omlx（仅限 Apple Silicon）

功能

• 跨引擎，使用相同的测量代码。 InferBench 会启动每个引擎各自的 OpenAI 兼容 HTTP 服务（llama-server、omlx serve），并通过相同的计时代码向每个引擎发送完全相同的提示词集，而不是比较各引擎自己的基准测试工具以不同方式生成的数字。
• 测量完整响应正文的耗时，而非响应头。 此代码的早期版本会在 HTTP 响应对象解析完成后立即测量耗时，但这只记录了响应头到达的时间；在发现这个问题之前，它曾报告出物理上不可能的 64,646 tok/s。现在，两个发行版都会测量完整响应正文的耗时，并且每种语言的测试框架中都有回归测试来防止此问题再次出现。
• 固定扫描 8 个提示词，并进行预热。 先通过一次不计入结果的补全来消除首次请求延迟，然后分别测量 8 个不同提示词，并报告 tok/s 的平均值／最小值／最大值（结果表中为 n=8）。
• 两个独立维护的发行版，输出一致。 npm 的 inferbench-cli（TypeScript）和 PyPI 的 inferbench-cli（真正的 Python 移植版，并非封装 Node 二进制文件）提供相同的 CLI 标志和相同的 JSON 报告字段名称。
• 机器可读的报告。 两个发行版都支持通过 --json / --out <file> 将完整的 BenchmarkReport 写入 camelCase JSON，因此 CI 或 Agent 无需针对生成报告的语言进行特殊处理即可解析报告。
• 本地云成本对照（Python 库）。 compare_to_cloud() 会查询静态、注明日期的云 API 价格，并与测得的本地吞吐量一同提供——它会明确说明价格是快照而非实时报价；遇到无法识别的模型时会返回 None，而不会猜测价格。
• 路径安全的 --out。 如果相对路径形式的 --out 值解析后指向当前工作目录之外，就会被拒绝，因此 Agent 提供的输出路径无法逃出预期目录。

快速入门

# llama.cpp -- pass a Hugging Face repo spec; llama.cpp downloads and
# caches it automatically, no manual step required
inferbench run --engines llama.cpp --model "bartowski/Qwen2.5-1.5B-Instruct-GGUF:Q4_K_M"

# omlx -- pass the model-directory subdirectory name under ~/.omlx/models/;
# omlx has no CLI download flow, so the model must already be present there
# (download it once via `omlx`'s own admin dashboard, or huggingface_hub's
# snapshot_download into that directory)
inferbench run --engines omlx --model "qwen2.5-1.5b-instruct-4bit"

# Both installed engines, machine-readable output, saved to a file
inferbench run --model "<spec>" --json --out report.json

以下是针对实际运行的 llama-server 进程进行实时测试的真实输出：

$ inferbench run --engines llama.cpp --model "bartowski/Qwen2.5-1.5B-Instruct-GGUF:Q4_K_M"
Hardware: Apple M4 (darwin/arm64), 16GB

llama.cpp: starting server...
llama.cpp: warming up...
llama.cpp: [1/8] benchmarking...
...
llama.cpp: [8/8] benchmarking...

Results:
  llama.cpp: avg 75.54 tok/s (range 69.54-79.78, n=8)

Recommendation: llama.cpp -- highest measured throughput on this run (75.54 tok/s avg) -- specific to this hardware and model, not a universal ranking

警告

--model 在不同引擎中的含义不同（对 llama.cpp 来说是可下载的 HF 规格，对 omlx 来说是预先下载的本地目录名称），因为这两个引擎的模型获取能力确实不同——omlx 的 serve 命令没有用于直接从 Hugging Face 拉取任意模型的标志。因此，要在一条命令中让两个引擎使用同一个模型，就必须事先将模型以两个引擎各自要求的形式准备好。

CLI 命令参考

inferbench run [options]

Options:
  --model <spec>    Model spec (engine-specific, see Quickstart above)   [required]
  --engines <list>  Comma-separated engines to test (default: all installed --
                    omlx, llama.cpp)
  --max-tokens <n>  Max completion tokens per prompt (default: 200)
  --json            Output machine-readable JSON instead of a human table
  --out <file>      Also write the full JSON report to this file
  --verbose         Show raw engine server stdout/stderr

成功运行且至少测试了一个引擎时，退出代码为 0；遇到用法错误或未安装任何受支持的引擎时，退出代码为 1。Python CLI 有一处细小且已记录的差异：缺少必需的 --model 标志时，会以 2 退出（这是 argparse 在解析阶段发生错误时采用的标准约定），而不是以 1 退出。

库 API 参考

Python 包（pip install inferbench-cli）提供了有文档说明的库接口，供脚本或笔记本使用，而非通过 CLI 使用。npm 包的 package.json main 字段指向 CLI 脚本本身（dist/cli.js，导入时会产生运行参数解析器的副作用），且未声明单独的库入口点，因此目前只有 Python 发行版支持作为库导入。

from inferbench import (
    benchmark_engine, detect_hardware, all_engines, resolve_engines,
    recommend, compare_to_cloud, report_to_dict, write_json_report,
)

符号	签名	返回内容
detect_hardware()	() -> HardwareProfile	平台、架构、CPU 型号字符串、总内存（GB），以及机器是否为 Apple Silicon。
all_engines()	() -> List[EngineAdapter]	每个受支持引擎（omlx、llama.cpp）的适配器实例。
resolve_engines(names)	(names: List[str]) -> List[EngineAdapter]	用户提供的去重引擎列表对应的适配器；遇到无法识别的名称时会引发错误。
benchmark_engine(adapter, *, model, ...)	(adapter, *, model: str, max_tokens=None, prompts=None, verbose=False, on_progress=None) -> EngineBenchmarkResult	对单个引擎运行固定提示词测试，并返回结构化结果。对于“未安装引擎”或单条提示词运行失败的情况绝不会引发错误——这些状态会记录在返回对象中。
recommend(results)	(results: List[EngineBenchmarkResult]) -> Optional[Recommendation]	在已安装且成功测试的引擎中，测得平均 tok/s 最高的引擎。
compare_to_cloud(cloud_model)	(cloud_model: str) -> Optional[CostComparison]	对已知云端模型（目前为 claude-5-haiku、claude-5-sonnet）返回静态的、注明日期的每 1K 输出 token 价格及披露说明；无法识别模型时返回 None。
report_to_dict(report) / write_json_report(report, path)	(report: BenchmarkReport) -> dict / (report, path: str) -> None	将 BenchmarkReport 序列化为与 CLI 的 --json / --out 生成的相同 camelCase JSON 格式。

from inferbench import benchmark_engine, detect_hardware, all_engines, recommend, compare_to_cloud

hardware = detect_hardware()
results = [
    benchmark_engine(adapter, model="qwen2.5-1.5b-instruct-4bit")
    for adapter in all_engines()
]
best = recommend(results)
print(f"{hardware.cpu_model}: {best.engine} -- {best.reason}")

# What would the same output volume cost on a cloud API instead?
cost = compare_to_cloud("claude-5-haiku")
if cost:
    print(f"{cost.cloud_model}: ${cost.cloud_cost_per_1k_tokens_usd}/1K tokens (snapshot {cost.pricing_snapshot_date})")

MCP 服务

InferBench 提供了一个 模型上下文协议 服务，让 AI Agent （Claude、Cursor 或任何兼容 MCP 的客户端）无需人工手动调用 CLI，即可直接运行硬件基准测试。

安装附加组件：

pip install "inferbench-cli[mcp]"

将其添加到 MCP 客户端的配置中（对于 Claude Desktop，配置文件为 claude_desktop_config.json）：

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

该服务提供一个名为 run 的工具，它会使用给定的子命令和参数以及 --json，调用已发布的 inferbench npm 二进制文件，并返回解析后的结果：

run(["run", "--engines", "llama.cpp", "--model", "bartowski/Qwen2.5-1.5B-Instruct-GGUF:Q4_K_M"])

传输方式为 stdio，因此无需托管任何内容：MCP 客户端会将服务作为本地子进程启动。源代码：python/src/inferbench/mcp_server.py。

测量方式

InferBench 不会调用各引擎自带的基准测试工具，也不会解析这些工具的输出。这种方式最初就在计划中，但后来发现完全行不通：omlx 没有 CLI 基准测试命令——它的“Performance Benchmark”功能只能在管理控制面板中通过 GUI 一键运行。在编写任何适配器代码之前，我们直接查阅了其实际 README，确认了这一点。

相反，InferBench 会启动各引擎自带的、已标准化的 OpenAI 兼容 HTTP 服务（omlx serve、llama-server），然后将完全相同的提示词通过完全相同的测量代码发送给每个引擎，并计时完整响应（而不仅是首字节时间）。这是在内部机制截然不同的引擎之间进行真正公平比较的唯一方法，也是唯一能用于 omlx 的方法。

“推荐”的含义（以及不代表什么）： 每份报告中的推荐结果，都会列出本次运行、这台硬件、这个模型上实测平均每秒 token 数最高的引擎——并不代表对哪种引擎最好这一问题的普遍结论。更换模型、机器，或遇上不同日期的温度条件，都可能改变结果；在开发此工具期间，同一硬件和模型上的两次运行曾得出 omlx 和 llama.cpp 排名相反的结果，而这恰好说明了为什么此工具要进行实时测量，而不是引用固定数值。

对比

有三款真实且由不同团队独立维护的工具处于同一领域，但各自的适用范围不同。任何未从所链接项目自身文档中获取的单元格都会特别标注。

	InferBench	llama-bench（随 llama.cpp 捆绑）	local-llm-bench	inference-benchmarker（Hugging Face）
覆盖的引擎	omlx、llama.cpp	仅 llama.cpp	Ollama、LM Studio、omlx，以及任意 OpenAI 兼容端点	任意 OpenAI 兼容聊天 API（TGI、vLLM 等）
测量内容	对固定的 8 条提示词进行测试，测量单请求平均/最小/最大 tok/s	测量提示词处理和 token 生成的 tok/s，可调整批次大小、缓存类型和线程数	在自定义真实场景中测量“有效” tok/s（输出 token 数 / 包含预填充在内的总耗时）	随着请求速率（QPS）增加进行并发/吞吐量测试，侧重生产环境服务
单次运行跨引擎比较	是	否——一次只能测试一个引擎	是，每次调用时选择引擎	是，每次调用时可选择任意使用该 API 的服务
输出格式	人类可读表格、JSON	Markdown、CSV、JSON、JSONL、SQL	JSON 保存到磁盘 + 单独的 compare.py 脚本	JSON
分发方式	npm + PyPI，通过 pip install / npm install -g 安装	包含在 llama.cpp 构建中，无需单独安装软件包	git clone + python3 bench.py（无 PyPI/npm 软件包）	cargo install、预编译二进制文件或 Docker 镜像
平台	llama.cpp 支持跨平台；omlx 仅支持 Apple Silicon	跨平台（与 llama.cpp 相同）	文档说明并展示了在 Apple Silicon 上的用法（MLX/GGUF 引擎）	跨平台，面向 GPU 服务端部署构建

为什么要开发此工具

对越来越多的开发者来说，在消费级硬件上进行本地推理已成为默认选择，而每个引擎自带的竞品对比都有一个显而易见的动机问题：没有哪家厂商能公正地评判自己的数据。InferBench 没有自有引擎可供销售，这正是它存在的全部意义。

此工具真正要回答的更难的问题，并不是“哪种引擎总体上最快”——这个问题没有统一答案，因为结果取决于你的具体硬件、具体模型和具体工作负载。它要回答的是“此时此刻，在这台机器上，对于这个模型，哪种引擎最快”——只有在你自己的硬件上运行的工具才能诚实地回答这个问题。

文档

• docs/getting-started.md —— 介绍两种发行版的安装、首次运行，以及如何使用库而非 CLI。
• docs/concepts.md —— 介绍测量架构、硬件检测器、推荐规则和退出代码约定。
• docs/integrations/ci.md —— 说明为什么 InferBench 刻意不作为逐 PR 的 CI 门禁，以及有哪些模式更适用。

演示

将机器可读的输出写入文件，使用 --json --out，适用于 CI 或由 Agent 解析结果：

并排对比多个引擎的基准测试，并根据实际测量结果给出推荐：

常见问题

InferBench 究竟是什么？ 这是一款用于对本机已安装的本地大模型推理引擎进行基准测试的工具，目前支持 omlx 和 llama.cpp。它会针对已安装的引擎运行一组固定且多样的提示词，测量每个引擎的实际每秒令牌数，并推荐本次运行中速度最快的引擎。它以同名的两个软件包形式发布：一个在 npm 上（JavaScript/TypeScript），另一个在 PyPI 上（Python）。

InferBench 与 llama.cpp 自带的 llama-bench 有何不同？ llama-bench（与 llama.cpp 捆绑提供）只对 llama.cpp 本身进行基准测试，并提供精细的调优选项（批次大小、缓存类型、线程数、重复次数等），还可输出为 Markdown、CSV、JSON、JSONL 或 SQL。InferBench 则对多个引擎进行基准测试，目前支持 omlx 和 llama.cpp，两者使用相同的提示词集和测量代码，因此在你的硬件上测得的每秒令牌数可以直接相互比较，而不是仅针对单个引擎分别进行调优。

InferBench 能在 Linux 和 Windows 上运行吗，还是只能在 macOS 上运行？ llama.cpp 引擎可在 llama.cpp 本身支持的任何平台上运行（Linux、macOS、Windows），因为 InferBench 只会启动 llama-server 并测量其兼容 OpenAI 的端点。omlx 引擎仅支持 Apple Silicon，这与 omlx 自身的适用范围一致。在 Linux 或 Windows 上，--engines omlx 会报告该引擎未安装，InferBench 则会对实际存在的受支持引擎进行基准测试。npm 软件包需要 Node.js >=18，PyPI 软件包需要 Python >=3.10。

InferBench 会为我下载模型吗？ 对于 llama.cpp，会——传入 Hugging Face 仓库规格，llama-server 自带的 -hf 标志就会下载并缓存模型。对于 omlx，不会——omlx 的 serve 命令只会发现本地目录中已有的模型，因此你需要先将模型下载到该目录中。

有任何数据会离开我的设备吗？ 不会。每个基准测试请求都会发送到 InferBench 自行在 127.0.0.1 上启动的服务。数据不会上传到任何地方。

为什么 --engines 有时需要为每个引擎使用不同的 --model 值？ 因为 omlx 和 llama.cpp 确实采用不同的模型获取机制——请参阅上文快速入门中的“已知限制”说明。

这个推荐能保证该引擎在一般情况下对我来说最快吗？ 不能。它只是本次运行中测得的最快引擎。请重新运行测试——使用你自己的硬件、自己的模型和当前的环境——而不要相信来自另一台设备或另一天的数据。

将 --out 指向来自 Agent 或其他可信度较低的输入的路径安全吗？ 安全，但有一项明确说明的限制：如果相对路径解析后指向当前工作目录之外，--out 会拒绝该路径（例如 --out ../../etc/cron.d/x），以防通过 Agent 提供的路径调用基准测试时，被诱骗而向预期目录之外写入。绝对路径仍会被接受，因为这是调用方直接传入的值，并非通过 .. 遍历逃逸得到的路径。

如果没有安装受支持的引擎，或者运行中途失败，会发生什么？ 如果找不到 omlx 或 llama.cpp，InferBench 会以代码 1 退出，并显示列出这两种安装命令的消息，而不会静默返回空结果。如果已安装某个引擎，但某次运行失败，报告中该引擎对应的行会显示 FAILED 和底层错误，而不是一个数字；其他已完成运行的引擎仍会给出实际结果，并仍可参与推荐。

我可以将 InferBench 用于商业用途吗？它免费吗？ 可以。InferBench 采用 Apache License 2.0，允许商业使用、修改和再分发，且无需支付许可费。它不依赖任何付费 API——每个基准测试请求都会发送到它在你自己的设备上本地启动的服务。

贡献

完整指南请参阅 CONTRIBUTING.md，其中涵盖 TypeScript 和 Python 代码库。欢迎提交问题和 PR。目前暂未纳入的范围包括更多引擎适配器、托管式集群仪表板，以及更丰富的推荐评分。如果你想着手实现其中任何一项，请提交问题。

安全

漏洞报告流程请参阅 SECURITY.md。

许可证

Apache 2.0，详见 LICENSE。