企业官网建设流程全解析

Agent-as-a-Router（ACRouter）是面向编程任务的大模型路由框架的官方开源实现：它把每个编码任务动态分发给最合适的后端模型，在"性能—成本"之间取得平衡。本仓库自带完整基准数据集CodeRouterBench、参考输出与离线回放脚本，无需任何 API Key、无需调用线上模型，就能一键复现论文中的 ID 测试集与 OOD176 基准主结果。本文带你从零搭建环境，走完 ID 复现、ACRouter OOD176 复现、基线对比表格生成的全流程，最后再把路由能力接入 Claude Code Router、cc-switch 等实际工具。

一、项目结构速览：复现前先看哪里放了什么

仓库是"脚本优先"的组织方式，核心目录如下（完整说明见 docs/HANDBOOK.md）：

基准数据的核心文件是 data/coderouterbench/ood176_results_long.csv（176 个 OOD 任务 × 8 个后端模型 = 1408 行结果）与 data/coderouterbench/id_results_long.csv（9999 个 ID 任务 × 8 模型）。复现脚本直接读取data/matrices/下缓存的任务×模型结果矩阵，因此全程离线可跑，不消耗任何 API 额度。

二、环境准备：conda 环境 + 依赖一键安装

建议 Python 3.11。按 README.md 的 Quick Start 操作：

# 1) 克隆仓库（如已在本地可直接进入目录） git clone https://gitcode.com/gh_mirrors/ag/agent-as-a-router cd agent-as-a-router # 2) 创建并激活虚拟环境 conda create -n acrouter python=3.11 -y conda activate acrouter # 3) 安装依赖并安装本地包 python -m pip install --upgrade pip setuptools wheel python -m pip install -r requirements.txt python -m pip install -e .

安装完成后，先跑一遍单元测试确认环境健康：

python -m unittest discover -s tests

💡 提示：默认离线回放不需要requirements-sandbox.txt，那份依赖清单只给想重新跑 Docker / Apptainer 沙箱验证的用户准备。

三、第一步：复现 ID 测试集（run_id.py）

在分布内（In-Distribution）测试集上，ACRouter 使用分层（hierarchical）策略对 2919 个测试任务做路由回放：

python scripts/run_id.py --output-dir outputs/tmp/id

预期输出（与论文一致即复现成功）：

ID n=2919 AvgPerf=50.14 CumReg=202.0 $Total=22.31 Perf/$=2.25 rAcc=0.2395 selection=outputs/tmp/id/id_selection.json decisions=outputs/tmp/id/id_decisions.jsonl

各指标含义：

• AvgPerf%：平均性能得分
• CumReg：相对理想选择的累积遗憾（越低越好）
• $Total / Perf/$：总花费（美元）与每美元换来的性能
• rAcc：相对性能 Oracle 的命中率

脚本会写出id_selection.json（模型选择结果）与id_decisions.jsonl（逐任务路由决策），方便和仓库内置的 outputs/current/id_selection.json 逐项对照。入口实现见 scripts/run_id.py，还支持--tune-split、--eval-split、--policy等参数调整调优/评估切分与路由策略。

四、第二步：复现 ACRouter 在 OOD176 上的主结果

OOD176 是当前公开发布的分布外（Out-of-Distribution）基准：176 个 Agent 式编程任务（来自 FeatureBench、LongCLI、SWE-CI 等），8 个后端模型。核心脚本是 scripts/run_acrouter_ood176.py，默认读取统一矩阵data/matrices/phase2_ood/unified/matrix_acrouter_ood176.json：

python scripts/run_acrouter_ood176.py --output-dir outputs/tmp/acrouter_ood176

预期输出：

ACRouter-OOD176 n=176 AvgPerf=73.30 CumReg=15.9 $Total=86.72 Perf/$=0.85 ...

对应论文主表中的这一行：

脚本内置--expected-n 176校验，若矩阵行数不对会直接报错，避免"数据不对还跑出一堆数"的尴尬。运行结果ood_metrics.json、ood_decisions.jsonl会写入你指定的--output-dir。

可选：从 Hugging Face 快照运行

仓库内的矩阵已经是完整可复现数据；如果你手头没有完整仓库、只有 HF 数据集快照，也可以：

python scripts/download_hf_assets.py --minimal --dataset-dir .hf/CodeRouterBench python scripts/run_acrouter_ood176.py \ --hf-dataset-dir .hf/CodeRouterBench \ --output-dir outputs/tmp/acrouter_ood176_hf

--minimal只会拉取 OOD176 回放所需的最小文件集（下载逻辑在 scripts/download_hf_assets.py），速度更快。

五、第三步：跑全部 OOD176 基线，生成论文风格对比表

这一步会把 Oracle、Always-单模型、Random、在线 Bandit（LinTS/LinUCB）、检索式（kNN）以及各类训练策略（LogReg、RouteLLM-MF/SW、TF-IDF+MLP、微调 Qwen3.5-0.8B 等）全部在 OOD176 上回放：

python scripts/run_baselines_ood176.py --output-dir outputs/tmp/baselines_ood176

运行结束后目录下会生成：

• baseline_table.md/baseline_table.csv/baseline_table.tex：论文风格表格
• baseline_metrics.json：完整指标
• decisions/*.jsonl：每个基线的逐任务路由决策

仓库内置的参考表格位于 outputs/baselines_ood176/baseline_table.md，节选如下：

结论一目了然：ACRouter 的 AvgPerf（73.30）逼近 Oracle 上界（78.98），而累积遗憾（15.9）远低于所有单模型与静态策略基线——这就是论文"Agent 式路由"的主结果。📊

六、扩展玩法：接入自己的任务或实际工具

1）自定义基准 / 模型评测

已有自己的任务与模型结果时，用配置驱动的管线 scripts/run_pipeline.py：

python scripts/run_pipeline.py --config configs/eval_pipeline.example.json

配置模板见 configs/eval_pipeline.example.json，输入可以是现成矩阵，也可以是tasks.jsonl+model_results.jsonl（示例数据在 examples/custom_benchmark/），脚本会自动完成矩阵转换、评分与决策导出。

2）运行时集成：Claude Code Router 与 cc-switch

仓库还内置两套可直接改造的运行时集成，把路由真正"装进"日常编码工具：

• claude-code-router/：在网关层加入 ACRouter 支持，请求发出前即完成模型路由；
• cc-switch/：在代理层加入 ACRouter 支持，模型选择先于静态供应商/模型映射执行。

此外demos/下还有两个轻量演示：demos/api_coding_solver/把一道编程题在多个 API 模型间路由直到验证器通过；demos/commercial_cli_router/则按关键词策略把任务路由给本地 Codex / Claude Code / opencode CLI，支持--dry-run预览渲染后的命令。

七、常见问题（FAQ）

Q1：复现需要 API Key 吗？不需要。整个复现链路基于仓库内置缓存矩阵离线回放，仓库不调用任何外部模型 API。

Q2：结果和论文数字对不上？先确认三点：① 运行的是默认参数（ID 的hierarchical策略、OOD176 的k=2验证—升级级联）；② 没有改动data/matrices/下的源矩阵；③ 对照 outputs/current/summary.md 中的参考值（ID AvgPerf=50.14，OOD176 AvgPerf=73.30）。

Q3：为什么示例命令都写outputs/tmp/？官方命令默认把结果写到outputs/tmp/，避免覆盖仓库中已提交的参考输出；不传--output-dir才会写回outputs/参考位置。

Q4：我想在自己的工作流里 import ACRouter？执行pip install -e .后即可：

from acrouter_repro.inference import ACRouter

完整 mock 示例见 examples/inference_demo.py，你只需提供"调模型"和"验证响应"两个回调，即可把 ACRouter 的验证—升级级联策略嵌入自己的推理流程。

总结：本文按"环境准备 → ID 复现 → OOD176 复现 → 基线对比 → 工程接入"的顺序，完整走通了Agent-as-a-Router 论文主结果的离线复现。三条核心命令（run_id.py、run_acrouter_ood176.py、run_baselines_ood176.py）即可复现全部主表数字，再配合run_pipeline.py还能快速评估你自己的模型与任务集，把模型路由真正用到日常编码工作流中。