企业官网建设流程全解析

ai-agent-book 书籍翻译实验怎么用编排模式与上下文隔离控制 Manager 上下文增长

【免费下载链接】ai-agent-book《深入理解 AI Agent：设计原理与工程实践》（李博杰 著）开源主仓库：全书正文、编译版 PDF 与按章配套代码项目地址: https://gitcode.com/GitHub_Trending/ai/ai-agent-book

ai-agent-book 仓库的 chapter10/book-translation 是第 10 章「书籍翻译 Agent」的配套实验：它要回答的问题是，当一个 Agent 在一条不断增长的对话里翻完整本书时，主上下文会随章节线性膨胀；改用**编排模式（Orchestration）**后，Manager 只保存任务、计划、调用记录和文件索引，完整译文全部落盘到文件系统，Manager 上下文因此基本恒定。本文的任务是把这个实验跑起来，用真实 token 数验证「上下文隔离如何控制 Manager 上下文增长」，并对比单 Agent 对照组。

运行前提（来自 README）：

• 从仓库根目录用uv安装第 10 章共享环境，指定 Python 3.12；
• 需要OPENAI_API_KEY（直连 OpenAI），或者只有OPENROUTER_API_KEY时自动改走 OpenRouter；
• 内置的 4 章英文小书（sample_book/）规模刻意很小，用于低成本验证机制，一次运行费用在几美分级别。

编排模式如何做到上下文隔离

先看机制，再执行。agents.py 实现了四种专职 Agent，各自拥有独立上下文：

控制 Manager 上下文增长的关键在run_orchestration()里的manager_context字典：它只包含task、guide、plan、call_log、file_index、progress六个字段，file_index里只存产物路径（如glossary.json、chapter1_zh.md），从不存放译文正文。每记录一次调用后，snapshot_manager()用tiktoken统计这份状态的序列化长度并更新峰值——这就是「Manager 上下文峰值」指标的来源。数据流为：Manager 调度 Glossary → 逐章 Translation（共享同一份术语表文件）→ Proofreading → Manager 依据报告摘要决定把哪些章节发回修订。

另外，Manager 会把编辑部指定术语（house style，EDITORIAL_MANDATE：token→词元、prompt→提示词、latency→时延、embedding→嵌入向量）强制写入共享术语表，下发给每个 Translation Agent。单 Agent 看不到术语表，只能用自己的默认译法——这也是两组实验的对照点之一。

准备环境

从仓库根目录开始：

uv sync --locked --python 3.12 --extra ch10 # 切换目录前先激活环境 # macOS/Linux: source .venv/bin/activate # Windows PowerShell: .\.venv\Scripts\Activate.ps1 # Windows cmd: .venv\Scripts\activate.bat cd chapter10/book-translation cp env.example .env # 填入 OPENAI_API_KEY

• ch10extra 包含 token 统计等本实验需要的依赖（见 pyproject.toml 中ch10 = ["agentbook[tokens,web]"]）；未安装uv时可用python -m pip install -e ".[ch10]"兜底，迁移期间也保留单项目路径python -m pip install -r requirements.txt（依赖为openai>=1.30.0、tiktoken>=0.7.0、python-dotenv>=1.0.0）。
• env.example 说明：gpt-5.6系列直连 OpenAI 需要组织验证；只填OPENROUTER_API_KEY（不填OPENAI_API_KEY）即可强制走 OpenRouter，模型名会被自动映射（gpt-5.6-luna→openai/gpt-5.6-luna）。

先做离线预演：不需要 Key 就能看到上下文预算

python demo.py --dry-run

该模式不调用任何 API，用tiktoken离线估算各 Agent 将读到的上下文规模，输出包括：四 Agent 协作图（数据经文件系统流转，Manager 只持有路径）、Manager 的 4 步执行计划、编辑部指定术语，以及「token 预算预估」。其中会直接打印：

• Glossary Agent 读全书的 token 估算；
• 每章 Translation Agent 的独立 token 估算；
• Manager 上下文（任务/计划/调用记录/文件索引，无正文）的 token 估算。

这一屏可以直观确认「Manager 上下文只随章节数加几行记录、与每章正文长度无关」，而单 Agent 的累积上下文随书长线性膨胀。确认结构无误后，再去掉--dry-run做真实运行。

正式运行：编排模式 + 单 Agent 对照

python demo.py

不带参数运行时，会先打印四 Agent 协作的实时轨迹（Manager 制定计划 → 调度 Glossary → 逐章 Translation → Proofreading → 依报告决策修订），再打印单 Agent 对照组结果。判断是否按预期完成，依次看这几段输出：

1. 【管理者模式】各 Agent 上下文 token 消耗：按 Agent 聚合的调用次数、输入/输出 token 与上下文峰值；
2. Manager 上下文峰值（只存任务/计划/调用记录/文件索引）：N tokens：这是验证目标指标，应为远小于全书长度的量级；
3. 术语表（共享文件，各 Translation Agent 引用同一份）与审校报告 summary；
4. 术语一致性对比与术语表遵从率对比：由 consistency.py 做确定性字符串匹配统计（非模型自评），逐术语打印规定译法、默认译法与两组「遵从/出现」计数；
5. 核心对比表：主/Manager 上下文峰值、Manager LLM 决策调用上下文、全流程总 token、术语内部一致率、指定术语遵从率、参与 Agent 种类数，最后一行会给出「单 Agent 主上下文峰值是管理者模式 Manager 上下文的 N 倍」。

README 给出的示例结果（真实运行，gpt-5.6-luna，4 章小书）如下，仅作量级参考，具体数字每次运行会有小幅波动：

对照组的膨胀来源在run_single_agent()中可以直接读到：译文继续留在对话里（messages.append后逐章累积），「主上下文峰值」= 其所有调用中最大的一次 prompt tokens。

验证产物落盘

运行结束后检查--out-dir（默认output/）下的两个子目录：

• output/orchestration/：glossary.json（共享术语表，含编辑部指定术语）、各章chapterN_zh.md译文、proofreading_report.json审校报告；
• output/single_agent/：单 Agent 模式的各章译文与progress.json（断点续跑状态，provider/model 或源单元指纹不匹配时会报错拒绝复用）。

译文文件存在且 Manager 峰值指标已打印，说明本轮实验完成。

可选分支

常用参数（完整列表见python demo.py --help）：

注意两点：--skip-single会跳过对照组，因此不产出核心对比表，只在你单独验证编排模式流程时使用；术语一致性 / 遵从率统计针对英文→中文调校，改翻译方向仍可正常翻译，但统计表意义有限。

离线验证（无需 API Key）

# 从仓库根目录；pytest 需要 dev 依赖 uv sync --locked --python 3.12 --extra ch10 --extra dev source .venv/bin/activate cd chapter10/book-translation python -m pytest tests python demo.py --dry-run

tests/ 包含术语表与审校报告的空值 / 非法结构回归测试（如 glossary 为null、issues非列表、issue 条目非 dict），测试打桩 LLM 调用，无需 Key。

限制与后续入口

• 4 章小书只用于教学预演，不代表大规模真实书籍的绝对 token 数值；换更强/更弱模型时，两种模式的差距会变化（更强的单 Agent 更容易自发命中部分常识译法，但仍无法覆盖没有唯一标准的术语，也仍会跨章漂移）。
• 术语一致性 / 遵从率是确定性字符串匹配，可能漏判措辞更灵活的译法变体；每次运行的具体数字会因模型输出随机性小幅波动，量级与结论稳定复现。
• README 给出的正式验收入口是真实书籍 campaign：用本仓库英文版技术书第 1–2 章（242,090 字节正文、23 个插图引用、14 个围栏代码块）运行

python run_official_experiment.py \ --provider ark \ --model doubao-seed-1-6-flash-250615

它同时执行四角色管理者组与单 Agent 组，把每次真实 API 的 provider/model、输入/输出 token 与时延写入validation/real_<UTC>/evidence.json，validation/latest.json在所有执行门满足后才标记complete。需要跑正式验收时从该入口进入。

【免费下载链接】ai-agent-book《深入理解 AI Agent：设计原理与工程实践》（李博杰 著）开源主仓库：全书正文、编译版 PDF 与按章配套代码项目地址: https://gitcode.com/GitHub_Trending/ai/ai-agent-book