Benchwarmers

让我上场吧，教练。
替补席上的每个模型都能获得出场时间。

Benchwarmers 是面向大模型的可自托管面板网关。你的应用请求一个模型组，整个面板便会作答：你为这类工作挑选的模型，加上轮换上场的探索席位，让你使用最少的模型也有机会参与。每个答案都会并排返回，并标明模型和席位。你根据实际工作评估它们并记录结果，而这些结果将决定谁能入选下一个面板。

最适合的用途：

• 同时询问多个模型。 发出一个请求（采用 OpenAI、Anthropic、 Gemini 或 Ollama 格式），即可获得一组答案。它们意见不一致的地方，正是值得关注的地方。
• Agent 也能使用。 Claude Code 和其他调用工具的客户端可通过路由模式使用一个集合：每轮使用一名成员，在整个对话中保持不变，并支持故障转移，且每次调用都有记录。
• 进行评审。 代码评审、对代码的断言、设计：不同模型能发现不同的问题，而且两个模型意见一致也不代表就正确。
• 发挥每个模型的优势。 针对不同工作类型（评审者、设计者、枚举者）建立集合，并为每种类型配备最擅长此类工作的模型。
• 让每个模型都有上场机会。 探索器会轮流尝试其余候选模型，让新模型和免费模型有机会与您信赖的模型一同接受测试，而无需您手动选择。
• 在自己的项目上进行基准测试。 根据您自己的代码仓库构建评审套件，并结合您对实际工作的评判，而非依赖公开排行榜。
• 知道该让谁坐冷板凳。 找出哪些模型总是自信地给出错误答案、哪些模型已不再响应（自动退役），以及哪些模型在触发速率限制后正在休息。
• 让免费和低价模型发挥作用。 执行运行状况探测，根据提供商公布的信息获取并执行速率限制；为每个应用提供一个端点，可接入任何 OpenAI 兼容的提供商或聚合平台，也可接入 Anthropic 和 Gemini 自有的 API。

相关工具	示例	功能	Benchwarmers 的不同之处
网关和路由器	LiteLLM、OpenRouter、Portkey	将一个请求发送给一个模型，并提供故障回退	将一个提示词分发给一组模型并返回所有答案；对于 Agent，则根据记录将请求路由给一名成员
多模型评议和集成	LLM Council、Mixture-of-Agents	将多个模型的回答合并成一个答案	保留每个答案，因为发言者及其所说内容就是证据；只有在您提出要求时才提供合并后的摘要
并排聊天	Open WebUI、LMArena	并排显示多个答案	为每个答案记录评判结果，并据此挑选下一组模型
评估框架	promptfoo、Inspect、SWE-bench	使用固定测试集离线为模型评分	根据您的实际工作和代码为模型评分，并持续轮换新模型

目录

• 试用
• 工作原理
• 向一组模型提问
• 通过命令行使用
• 通过 Claude Code 和其他 Agent 使用
• 套件
• Docker 和托管
• 哪些内容会离开您的设备
• 限制
• 安全性
• 开发
• 许可证

日常使用（仪表盘页面、连接应用、批量入门）请参阅 USAGE.md。在服务器或托管平台上运行请参阅 HOSTING.md。为他人设置此工具的编码 Agent 应从 AGENTS.md 开始。

试用

v0.3，早期版本。 可在 Windows、macOS 和 Linux 上使用 Python 3.11 或更高版本运行，支持从 PyPI、npm、代码检出或 Docker 获取。功能还不完善；如果本文档有未详述之处，请直接阅读代码。

最快的方式：安装 Python 3.11+，然后从 PyPI 安装：

pipx install benchwarmers        # 或：uv tool install benchwarmers
benchwarmers                     # 或者先试用，无需安装：uvx benchwarmers

也可以从 npm 获取，同时需要 Node 18+：

npx @wendellresearch-ai/benchwarmers

两种方式都会提供相同的两个命令：benchwarmers 和它的短名称 bench。它会将你的数据保存在用户配置文件夹中（设置 BENCHWARMERS_HOME 可选择其他文件夹），首次运行时会完成初始化，并在 http://localhost:8122 打开仪表板，后续的第 3 至 5 步会在此继续。内置 模型客户端会执行所有调用，因此无需安装其他组件。两种方式都没有 依赖：应用使用 Python 标准库。

从源代码运行：

1. 获取代码并准备 Python 3.11+ 环境：

   git clone https://github.com/WendellResearch-AI/benchwarmers
   cd benchwarmers
   python -m venv .venv             # 无需通过 pip 安装任何内容：标准库已足够
   

   内置模型客户端（metrics/client.py）会执行所有调用。 llm CLI 可作为其插件的替代方案： 将它安装到虚拟环境中，并在 Settings 中选择它（或设置 BENCH_CLIENT=llm，该设置优先）。

2. 创建数据文件夹。 所有属于你的内容（端点、模型注册信息、 集合、评估结果、探测历史记录、任务回答）都保存在其中，而不会放在代码里：

   python scripts/init.py           # 或：python scripts/init.py <folder>
   

   它会从 examples/ 初始化文件夹（除非你指定文件夹，否则会使用操作系统中 每用户的数据文件夹），并通过 .benchwarmers-home 文件将代码检出目录指向该文件夹；该设置可由 BENCHWARMERS_HOME 覆盖。使用 --endpoint NAME BASE_URL --key 时，它还会添加第一个端点并提示输入 密钥；密钥会保存到 llm 的用户文件夹中的密钥文件（keys.json； 如果你安装了 llm CLI，则与其共享，否则无需关心），绝不会写入数据文件夹。 也可以在环境变量中设置 BENCHWARMERS_KEY_<NAME>。

3. 启动仪表板。 尚未配置端点时，仪表板会打开添加端点页面：在服务商的独立 页面上登录（OpenRouter、NanoGPT、Hugging Face、Pollinations、你的 ChatGPT 套餐、GitHub Models 或本地 Ollama），或者粘贴任意兼容 OpenAI 的 API 密钥； 也包括 Open WebUI 或 LiteLLM 等聚合平台。Anthropic 和 Gemini 密钥也可通过 这些服务商自己的 API 调用（在同一对话框中选择 API）。这里只提供支持其他应用 登录的服务商；要添加服务商，请修改 metrics/connect.py（其中的文档字符串 说明了具体方法）。

   python serve.py                  # http://localhost:8122
   

4. 从中接入几个模型（“Onboard a model”）：勾选一个或多个；每个模型都会依次 完成注册、探测并运行测试套件，按钮旁会显示进度。Quick 现在会进行探测， 并将测试套件留给计划任务执行；Quick + ad hoc 还会禁止基准测试工具主动 调用模型，适用于按用量计费或试用密钥。

5. 在 Collections 页面创建集合（面板始终包含的模型，以及面板的用途）。 仪表板会在自己的端口上响应网关路由 （http://127.0.0.1:8122/v1）；python gateway.py 则会在 http://127.0.0.1:8123/v1 单独运行网关。

工作原理

• 集合和席位。 集合会指定面板始终包含的模型，以及适用的工作类型（审查、设计、枚举……）。 每次调用都会根据某个模型闲置的时长，为其安排探索席位，让评测台持续了解路由器不再询问的模型。
• 评判结果。 每个席位的回答都会附带调用 ID。将回答与实际工作进行核对后，请记录它是否有用，以及其中哪些说法属实或不实。决定下一个面板的是评判结果，而非感觉；经常自信地答错的模型会显示为这类模型。
• 目录。 上下文窗口、输出上限、工具、视觉能力和价格，取自实际提供模型的服务商在 models.dev 上的信息，其次是 OpenRouter 的公开目录和 FreeLLMAPI，以及你手动设置的任何信息。
• 健康状态。 每天早上，每个模型都会收到一个只需回答一个词的提示词；每周还会收到一个简短提示词和一个较长提示词，用于测量速度。如果模型不再响应，或其端点不再提供服务，在一次确认调用后便会自动退役，同时保留相关证据；只需点击一次即可恢复。内置调度器会在你通过 Settings 启用后运行所有这些操作；全新安装在此之前不会发起任何调用。
• 速率限制和用量。 限制信息来自服务商的速率限制标头和错误消息，也来自你为每个连接或模型设置的限制（每分钟、每天或每月的请求数；每分钟或每天的令牌数）。限制按连接分别记录，因为共用同一密钥的模型也会共享这些限制，并且会强制执行：如果等待时间在可接受范围内，调用就会等待；否则会在发出前被拒绝。每次调用都会连同其令牌数记录在月度用量台账中，Quotas 页面会显示剩余额度和重置时间。
• 发现。 将 models.dev 和 FreeLLMAPI 合并为一个值得添加的模型列表，并列出此安装可通过哪些路由访问每个模型。

向面板提问

任何兼容 OpenAI 的客户端都可以使用：向模型 bench/<collection> 提问。

curl http://127.0.0.1:8122/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "bench/<collection>", "messages": [{"role": "user", "content": "Where can this function return a stale value? ..."}]}'

回复会在消息中包含每个席位的答案，并在 bench 字段中以数据形式提供相同席位的信息：模型、席位、状态、耗时秒数和调用 ID。对于只显示一个答案的聊天窗口，请使用 bench/<collection>:merged 提问：合并模型会生成一个答案，说明各席位在哪些方面意见一致、哪些方面存在分歧；每个席位的答案仍会保留在 bench 中。检查完毕后，为每次调用记录判定：

curl http://127.0.0.1:8122/bench/verdict -H "Content-Type: application/json" \
  -d '{"call": "<call id>", "useful": true, "note": "found the real bug", "real": ["..."], "false": ["..."]}'

也可以通过仪表板操作。完整契约请参阅 GATEWAY.md：图片、提示词长度、谁可以调用，以及回复的结构。

其他客户端。 同一面板也会以其他 API 的格式作答，因此只要客户端支持其中一种格式，就能将服务的地址用作基本 URL：

格式	路由	适用对象
OpenAI 聊天补全	POST /v1/chat/completions	OpenAI SDK、大多数聊天应用
OpenAI Responses	POST /v1/responses	responses.create 客户端（不会存储任何内容）
OpenAI 旧版补全	POST /v1/completions	发送 prompt 的工具
Anthropic Messages	POST /v1/messages	配置了 base_url 的 Anthropic SDK
Ollama	POST /api/chat、POST /api/generate、GET /api/tags	Open WebUI 的 Ollama 连接、Ollama 应用
Gemini	POST /v1beta/models/bench/<collection>:generateContent	配置了 base_url 的 Google GenAI SDK

curl http://127.0.0.1:8122/v1/messages -H "Content-Type: application/json" \
  -d '{"model": "bench/<collection>", "max_tokens": 1024, "messages": [{"role": "user", "content": "..."}]}'

所有格式都支持按需流式传输：回复会立即开始，每个席位完成后，其答案便会到达。面板以文本作答，因此携带工具的请求会被拒绝，并返回 400 错误，指向 路由模式（bench/<collection>:route，使用其中一个成员及其工具；见下文）。GATEWAY.md 的“Other API formats”一节提供了每种格式对应的 curl 命令，并说明哪些请求会被拒绝或忽略。

从命令行

bench（或 benchwarmers，两者是同一个程序）无需仪表板，也能完成仪表板的工作：提问和评判，并运行基准测试本身。它是运行中服务的客户端，因此同样的命令也适用于另一台机器上的服务。

bench status                                   正在运行什么，以及运行在哪里
bench collections                              可以提问的内容
bench ask core "Where can this return a stale value?" -f cache.py
git diff | bench ask core "Review this diff"   管道内容即为提示词
bench verdict <call id> --useful --real "the race in refresh()" --false "the SQL injection"

bench models --find mercury                    模型名册，以及每个模型的状态
bench candidates --new                         端点提供但尚未加入基准测试的内容
bench onboard <served name> --wait             将其加入（注册、探测、评分）
bench model retire <alias> --reason "..."      以及恢复：bench model restore <alias>
bench collection save reviewers --members a,b,c --description "adversarial review"
bench collection save reviewers --add d --remove a
bench endpoint add openrouter --base https://openrouter.ai/api/v1   （会提示输入密钥，且输入内容不可见）
bench key create my-app --collections core --rpm 30
bench settings scheduler run --off perf

任何命令都可以使用 --help 查看选项和示例；--json 会输出服务的响应，供脚本使用。--url 可让某条命令指向另一台服务。ask 会将每个席位的回答输出到标准输出，并将用于评判它们的调用 ID 表输出到标准错误，因此 bench ask core "..." > review.md 只会保留回答。退役模型、删除集合或端点以及撤销密钥前都会先询问；脚本可用 --yes 自动确认。密钥绝不能作为参数传入（机器上的其他用户可以读取这些参数）：endpoint add 会提示输入密钥，也可以通过标准输入读取密钥，使用 --key-stdin 即可。

PATH 中可能会优先找到另一个名为 bench 的程序（Frappe 框架的程序）；请改用 benchwarmers，它支持相同的命令。

变量	含义
BENCHWARMERS_URL	服务地址，默认为 http://127.0.0.1:8122
BENCHWARMERS_ADMIN_TOKEN	服务的管理员令牌（若服务有此令牌）；除 ask、collections 和 verdict 外，每条命令都会通过 Authorization: Bearer 发送此令牌
BENCHWARMERS_KEY	网关密钥；在需要密钥时用于 ask、collections 和 verdict
BENCHWARMERS_TIMEOUT	等待面板的秒数，默认为 900

退出码：0 表示完成，1 表示拒绝或失败（原因输出到标准错误），2 表示用法错误，3 表示 BENCHWARMERS_URL 上没有服务。

来自 Claude Code 和其他 Agent

benchwarmers mcp 是一个通过 stdio 运行的 MCP 服务，提供三个工具： list_collections、ask（包含一个集合、一条提示词，以及可选的 merged、 with 和 system）和 verdict。它是一个 Benchwarmers 客户端，通过上述路由连接到 已运行的 Benchwarmers，因此请先启动仪表板（或服务）。工具描述中包含相关规则：询问一个集合，而不是 偏爱的模型；采取行动前先验证；列出每个席位；为你评判的每个席位发送一条 verdict。

Claude Code 插件。 该插件会添加 MCP 服务、/benchwarmers:ask <collection> <what to ask> 命令，以及一个 benchwarmers 技能，说明何时使用评审组会有帮助（对抗性评审、对真实文件进行穷举），以及 如何评判它：

/plugin marketplace add WendellResearch-AI/benchwarmers
/plugin install benchwarmers@benchwarmers

需要在 PATH 中安装 Node 18 或更高版本，以及 Python 3.11 或更高版本。

任何其他 MCP 客户端（或未安装插件的 Claude Code）：安装后运行 benchwarmers mcp，也可不安装而运行 uvx benchwarmers mcp 或 npx -y @wendellresearch-ai/benchwarmers mcp，或者在代码检出目录中运行 python mcp_server.py。例如：

{"mcpServers": {"benchwarmers": {"command": "npx", "args": ["-y", "@wendellresearch-ai/benchwarmers", "mcp"],
                                 "env": {"BENCHWARMERS_URL": "http://127.0.0.1:8122"}}}}

在原生 Windows 上，如果客户端无法自行启动 npx，则需要 "command": "cmd", "args": ["/c", "npx", "-y", "@wendellresearch-ai/benchwarmers", "mcp"]。

变量	含义
BENCHWARMERS_URL	服务地址，默认值为 http://127.0.0.1:8122（末尾带有 /v1 也可以）
BENCHWARMERS_KEY	来自 Settings 的网关密钥，以 Authorization: Bearer 形式发送；连接其他机器上的服务或需要密钥的服务时必需
BENCHWARMERS_TIMEOUT	等待评审组的秒数，默认值为 900

在集合上运行的 Agent。 MCP 工具会让评审组提供第二意见；Agent 也可以由集合驱动，使用路由 模式（bench/<collection>:route）：根据记录选出一名成员，让其每轮都使用自己的工具进行回复，并在整个对话期间保持不变；如果它在回复前失败，则由下一名成员接替。Claude Code 通过 ANTHROPIC_BASE_URL=http://127.0.0.1:8122 和 ANTHROPIC_MODEL=bench/core:route 指向它；Codex、opencode、Cline 以及其他支持 OpenAI、Responses 或 Ollama 协议的 Agent 使用相同的基础 URL。 GATEWAY.md 中的“路由模式”一节介绍了设置方法和限制。

测试套件

模型在代码审查任务上的得分取决于它们能否找出有问题的代码行，或判断关于某段 代码的说法是否属实。仓库附带一个入门包：

• 真实漏洞（suite/tasks/rebench-*）：来自公共项目的近期修复，取自 SWE-rebench-V2 数据集，每个任务都配有一个对照项。
• 陈述（suite/tasks/claim-*）：关于本项目代码的真实和虚假陈述，并附有相关代码。

你可以从自己的代码仓库添加任务（数据文件夹中的 config/repos.json 将名称映射到文件夹）：python suite/seed.py --repo <name> 会在真实函数中植入 逼真的漏洞，每个漏洞都配有一个干净的对照项。私有代码最适合用来创建任务，因为没有模型在它上面训练过。请参阅 suite/README.md、suite/REBENCH.md 和 BENCHMARKS.md。

Docker 和托管

一个容器运行仪表板、网关（使用同一端口，位于 /v1） 和调度器，数据文件夹作为卷挂载，且不需要 llm CLI（内置客户端会处理每次调用）。将密钥放在与 compose.yaml 同级的 .env 文件中：

BENCHWARMERS_ADMIN_TOKEN=<16 or more characters>
BENCHWARMERS_KEY_OPENROUTER=sk-or-...

然后运行 docker compose up -d，并打开 http://127.0.0.1:8122。compose 文件 仅在本机发布端口；代理配置请参阅其中的注释。

托管并始终在线： HOSTING.md 比较了 Fly.io、Railway、 Render 和使用 Caddy 的 VPS（成本、休眠、磁盘、HTTPS），并在 deploy/ 下为每种方案提供了模板。

Render 只需单击一次：使用付费实例、1 GB 磁盘和自动生成的管理员令牌。Fly.io 从检出代码到完成只需四条命令（cp deploy/fly.toml .、 fly launch --copy-config --no-deploy、fly secrets set BENCHWARMERS_ADMIN_TOKEN=...、fly deploy）。Railway 可通过命令行 或浏览器完成几个步骤，详见 HOSTING.md。

哪些数据会离开你的设备

Benchwarmers 不需要账号、不收集遥测数据，也没有自己的服务器；不会有任何数据发送给 Wendell Research。它会发送哪些内容，以及发送到哪里：

• 你的提示词，仅发送到你添加的端点：提供商、聚合器、 Open WebUI 之类的中心，或本地运行时。这也包括探测、套件和引导流程，它们会使用你的密钥进行调用。只添加你愿意将这些工作发送到的端点。
• 目录读取，不需要密钥，也不包含你的任何数据：每天读取一次 models.dev 和 FreeLLMAPI，以及 OpenRouter 的公开模型列表。
• 登录，仅在你选择登录时发生：前往提供商自己的登录页面。
• 图表：仪表板的浏览器页面会从 jsDelivr 加载固定版本的 Observable Plot。
• 播种真实缺陷任务，仅在你运行 suite/rebench.py 时发生：从 Hugging Face 获取 SWE-rebench-V2 条目，从 GitHub 获取文件。

密钥保留在环境变量或 llm 的密钥文件中（位于其用户文件夹内的 keys.json），绝不会存入数据文件夹。PRIVACY.md 和 SECURITY.md 中提供了详细信息。

限制

• 工具只能通过路由模式使用。 面板会以文本作答；带工具的请求会被拒绝，而不是删减。路由模式只会将轮次发送给使用 chat-completions 端点的成员，并将固定对话保存在内存中（重启后，每个对话都会重新选择成员）。该模式已与 Claude Code 完成端到端测试；Codex、opencode 和 Cline 的配置则根据其文档编写。影子席位（由其他成员回答 Agent 的轮次以供评估）已列入计划，尚未实现。
• 部分功能仅通过模拟对象检查。 原生 Anthropic 和 Gemini 端点，以及 LiteLLM 和 CLI Proxy API hub 适配器，均依据相关 API 的文档和源代码构建，并通过模拟服务进行测试，尚未在真实服务上测试。
• 合并后的回复会在合并完成后一次性送达；各席位的回复则会在完成后立即流式传输。
• 节奏控制和用量账本仅适用于内置客户端。 通过 llm CLI 发起的调用（如果选择使用）既不会进行节奏控制，也不会计入用量。
• 调用会产生费用。 探测、接入和套件运行都会使用你的密钥和免费额度。为此，接入流程一次只运行一个模型（Quick 会将套件分散到计划的多轮运行中）；套件每轮运行都会进行节奏控制，不会突发调用。
• 调度器运行在服务端。 仪表板（或容器、服务）运行时，调度任务会执行；如果错过运行时间，服务恢复后会在七天内补跑一次。
• 本质上是为一人单次安装而设计。 虽然支持登录和网关密钥，适用于局域网或服务器，但没有按用户划分的视图或角色。
• 接入队列保存在仪表板的内存中。 重启仪表板会丢弃批次中剩余的任务；每个已启动模型的日志都会保留在 runs/ 中。
• 免费额度可能随时变动，恕不另行通知。 Discover 的价格来自公开目录；某些提供商的免费模型只能在其自有应用中使用（可在 Settings 中按提供商切换）。

安全

默认情况下，两台服务器都监听 127.0.0.1，并且只接受针对自身主机名的同源写入请求，因此浏览器中的网页无法驱动它们。若要监听其他地址，必须先设置 BENCHWARMERS_ADMIN_TOKEN；否则服务器会拒绝启动。设置该变量后，仪表板会要求登录，网关则使用具名、可撤销的网关密钥。Settings 中的 Server and access 页面会显示当前状态（是否已设置密钥，但不会显示密钥值）。

SECURITY.md 介绍了完整的安全模型以及漏洞报告方式。

开发

python scripts/check.py             # 运行所有自检和测试（--quick 会跳过较慢的测试）

核心部分仅使用 Python 标准库。CI 会在 Linux 和 Windows 上使用 Python 3.11 至 3.13 运行检查，并在 macOS 上运行检查。

Benchwarmers 暂不接受外部贡献；待项目更加成熟后会开放贡献。安全问题请通过 SECURITY.md 报告。

许可证

MIT，版权所有 (c) 2026 Wendell Research（LICENSE）。入门任务和随附字体各自采用独立许可证，详见 NOTICE。使用还受 TERMS.md 约束。