FastContext 评测实战：在 Docker 中跑通 SWE-bench Multilingual 端到端流水线的完整教程-开发者社区

【免费下载链接】fastcontext

FastContext: Training Efficient Repository Explorer for Coding Agents

项目地址：https://gitcode.com/gh_mirrors/fas/fastcontext

FastContext 是一个面向 coding agent 的轻量级仓库探索子代理（repository explorer）：主编码代理把"找代码"这件事以自然语言委托给它，它用只读的Read、Glob、Grep工具并行检索代码库，最后返回紧凑的"文件:行号"引用。本文带你从零开始，在 Docker 中跑通 FastContext 基于 SWE-bench Multilingual 的端到端评测流水线——从克隆仓库、构建 wheel、配置双模型凭据，到启动评测、解读评分结果。

1. 先搞懂：评测流水线里谁在干什么？

在评测中，FastContext 并不是"主角"，而是主编码代理的外挂探索器：

主代理（mini-swe-agent）：通过 bash 工具解决 SWE-bench 实例，负责改代码、跑测试、提交 patch；
FastContext 子代理：以 CLI 形式预装在容器内，主代理用fastcontext -q "..." --citation调用它，拿到相关代码的文件路径与行号区间后直接精读，省去自己漫无目的的全库搜索。

仓库中与评测直接相关的模块：

模块	说明
bench_mini_swe_agent.py	端到端评测入口（Docker 内跑 mini-swe-agent + FastContext）
example.env	模型凭据配置模板（主代理 + FastContext 两套）
gpt-multi-fc.yaml	内置主代理提示词配置（含 FastContext 使用策略）
bench_fastcontext.py	独立探索评测运行器
run_score.py	引用质量评分（文件级/行级 P/R/F1）

2. 前置准备：Python 3.12 + uv + Docker 🛠️

FastContext 要求Python 3.12+，包管理使用 uv，评测流水线依赖本地 Docker（每个 SWE-bench 实例都会在独立容器中运行）。

# 1. 克隆仓库 git clone https://gitcode.com/gh_mirrors/fas/fastcontext cd fastcontext # 2. 拉取 mini-swe-agent 子模块（评测入口会 import 它） git submodule update --init --recursive # 3. 构建本地 wheel —— 流水线会把它复制进容器安装 uv build # 产物: dist/fastcontext-0.1.0-py3-none-any.whl

💡 如果没执行uv build，评测启动时会直接报错退出（见 bench_mini_swe_agent.py 的 wheel 存在性检查）。

3. 配置 .env：主代理与 FastContext 双凭据 🔑

评测需要两套模型凭据：主代理（解题模型，走 litellm 命名）和 FastContext 子代理（容器内独立配置）：

cp benchmark/evaluation/configs/example.env .env

编辑 .env，关键变量如下：

# 主代理（解题模型） MAIN_MODEL=azure/deepprompt-gpt-5.4-2026-03-05-global MAIN_TEMPERATURE=0.0 AZURE_API_KEY=your-main-agent-api-key-here AZURE_API_BASE=https://your-endpoint.openai.azure.com/ AZURE_API_VERSION=2024-12-01-preview # FastContext 子代理（以环境变量注入容器） FASTCONTEXT_MODEL=deepprompt-gpt-5.4-2026-03-05-global FASTCONTEXT_API_KEY=your-fastcontext-api-key-here FASTCONTEXT_BASE_URL=https://your-endpoint.openai.azure.com/ FASTCONTEXT_API_TYPE=azure FASTCONTEXT_API_VERSION=2024-12-01-preview

所有FASTCONTEXT_*变量会被原样注入容器内的每次docker exec调用（见 bench_mini_swe_agent.py），因此主代理和 FastContext可以各自使用不同的模型与 API key。主代理也支持OPENAI_API_KEY/ANTHROPIC_API_KEY直连方式。

4. 一键启动端到端流水线 🚀

uv run --group benchmark python benchmark/evaluation/bench_mini_swe_agent.py \ --bench swebench-multilingual \ --agent-config prompts/gpt-multi-fc.yaml \ --config .env \ --output preds.json \ --logs-dir logs \ --workers 1

常用参数速查：

参数	作用	新手建议
`--bench`	数据集名，`swebench-multilingual`对应`SWE-bench/SWE-bench_Multilingual`	保持默认
`--agent-config`	主代理提示词 YAML，内置 prompts/ 下 6 个配置	用 gpt-multi-fc.yaml
`--run-head N`	只跑前 N 个实例	首次强烈建议`--run-head 2`
`--filter REGEX`	按 instance_id 正则过滤	配合`--run-head`调试
`--workers`	并行实例数	从 1 开始，避免 API 限流
`--no-fastcontext`	基线模式（不装 FastContext），需配`--baseline-agent-config`	用于对照实验
`--redo-existing`	重跑已有预测的实例	默认自动断点续跑

⚡ 断点续跑是内建的：preds.json中已有model_patch的实例会自动跳过，中断后直接重新执行同一条命令即可续跑。

5. 容器里发生了什么？

每个实例都会：

拉起专属 SWE-bench 镜像（命名规则：swebench/sweb.eval.x86_64.<instance_id>:latest，例如apache__druid-13704→swebench/sweb.eval.x86_64.apache_1776_druid-13704）；
执行安装脚本：复制 wheel 进容器 →apt install curl ripgrep→ 安装 uv →uv tool install fastcontext-0.1.0-py3-none-any.whl --with requests→ 软链到/usr/local/bin/fastcontext（见 setup_fastcontext_in_container，容器化环境参考 benchmark/environment/Dockerfile）；
注入FASTCONTEXT_*环境变量后，主代理在容器内解题，期间可随时调用fastcontext -q "..." --citation；
结束后写出三类产物：

preds.json：SWE-bench predictions 格式（instance_id → model_patch），可直接用于官方评测；
logs/<experiment>/<instance_id>/<id>.traj.json：主代理完整轨迹；
logs/.../fastcontext_trajs/：从容器中提取的 FastContext 探索轨迹（trajectory_*.jsonl），方便复盘"探索器到底读了什么"。

6. 进阶：独立探索评测与引用评分（可选）🎯

如果只想评测 FastContext 的探索质量（而非端到端解题），可以走独立的 subagent 评测：

cd benchmark/swebench cp run.sh.sample run.sh # 在 run.sh 中填入 BASE_URL / MODEL / API_KEY uv run --group benchmark python bench_fastcontext.py \ --bench swebench-multilingual \ --experiment fastcontext-eval \ --prediction-file predictions.jsonl \ --local-mount-dir /absolute/path/to/output \ --num-threads 1

run.sh.sample 会在每个容器内安装 ripgrep 与 uv、装好 FastContext 后，以--max-turns 15跑一次完整探索。得到结果后，把最终回答整理为含instance_id与finial_response字段的 JSONL，即可评分：

uv run --group benchmark python benchmark/evaluation/run_score.py \ swebench-multilingual result_finial_response.jsonl

run_score.py 会把 FastContext 输出的<final_answer>引用与真实 patch 对比（解析逻辑见 utils.py），输出文件级与行级两组 precision / recall / F1；统计只覆盖 patch 中真正的源码文件（C/C++/Go/Java/JS/TS/PHP/Ruby/Rust）。

7. 解读结果：同时看 Score 和 Token 📊

论文主结果一览（三个主代理 × 三种探索配置，跨 SWE-bench Multilingual / Pro / SWE-QA）：

几个值得记住的数字：

GPT-5.4 主代理 + FC-4B-RL 探索器：SWE-bench Multilingual 得分74.7（+3.0），主代理 token 降至338k（-26.0%）；
端到端最高+5.5分（FC-30B-SFT 于 SWE-bench Pro），主代理 token 最多节省60.3%（SWE-QA）；
Token 节省主要来自 File Reading 与 Code Search 两大块——这正是被"搬"到 FastContext 里的探索开销：

📌 想自己验证这套 tradeoff？跑一组--no-fastcontext基线（指定--baseline-agent-config），再对比两次的logs/轨迹 token 统计即可。

8. 实用技巧与常见问题 🧰

现象	原因与对策
`fastcontext wheel not found at dist/...`	忘记`uv build`，执行一次即可
`MAIN_MODEL is required in config file`	`.env`未填`MAIN_MODEL`，注意是 litellm 模型名
Docker 拉镜像超时	确认 Docker 守护进程在运行；首个实例拉镜像较慢属正常
单实例卡住	用`--filter`精确定位该 instance_id，`--run-head`小步验证
API 限流报错	把`--workers`降为 1，断点续跑机制会保留已完成实例

上手调试推荐路线：--run-head 2 --filter小规模试跑 → 检查logs/下主轨迹与fastcontext_trajs/→ 放量到--workers 2~4→ 最后用preds.json做官方评分。

写在最后

FastContext 把"探索仓库"从主代理的上下文负担里剥离出去，评测流水线的价值也正在于此：用 SWE-bench Multilingual 这样的真实多语言代码库，量化"委托探索"带来的得分收益与token 节省。核心入口就在 benchmark/evaluation/ 与 benchmark/swebench/，探索器本体在 src/fastcontext/（CLI 见 cli.py）。祝你在自己的模型组合上跑出漂亮的第一组结果！