编辑此页 / 查看本页的源代码
实验 10-3：书籍翻译 Agent —— 管理者模式（Orchestration）¶
配套代码，演示如何用管理者模式把长文档翻译拆给多个专职 Agent。核心是 上下文隔离与控制 Manager 上下文膨胀：Manager 只保存任务、计划、各 Agent 调用记录和文件索引，完整译文全部落盘到文件系统，因此无论书有多长， Manager 的上下文都基本恒定。
目的¶
对比「单 Agent 一条对话翻完整本书」与「管理者模式多 Agent 协作」两种方案，用 真实 token 数说明后者如何控制主/Manager 上下文膨胀，并用共享术语表保证 全书术语一致。
架构：四种 Agent¶
| Agent | 输入（独立上下文） | 产出 | 上下文特点 |
|---|---|---|---|
| Glossary Agent | 全书内容 | 结构化术语表 glossary.json |
读全书，产出后即释放 |
| Translation Agent | 当前章节 + 术语表 + 翻译指南 | chapterN_zh.md |
每章一个独立实例，只看到自己这一章 |
| Proofreading Agent | 所有译文 + 术语表 | 审校报告 proofreading_report.json |
做一致性 / 流畅性检查 |
| Manager Agent | 任务 + 文件索引 + 报告摘要 | 调度决策（是否发回修订） | 只存元信息，不存正文 |
数据流：Manager 调度 Glossary → 逐章 Translation（共享同一份术语表文件）→ Proofreading → Manager 依据报告决定是否把个别章节发回 Translation 修订。译文与 术语表都通过文件系统传递，Manager 只在上下文里保存文件路径。
关键设计：Manager 把「编辑部指定术语」（house style，如 token→词元、 prompt→提示词、latency→时延）强制写入共享术语表，下发给每个 Translation Agent， 从而把指定译法贯彻到全书。单 Agent 看不到术语表，只能用自己的默认译法。
目录¶
book-translation/
├── agents.py # 四种 Agent + 两种运行方式 + token 追踪
├── consistency.py # 术语一致性 / 术语表遵从率（确定性字符串匹配）
├── demo.py # 一键演示：跑管理者模式 + 单 Agent 对照，打印对比表
├── sample_book/ # 自带英文技术小书（4 个短章节，含术语与代码）
│ ├── chapter1.md ... chapter4.md
├── output/ # 运行时生成：术语表 / 各章译文 / 审校报告（已 gitignore）
├── requirements.txt
└── env.example
运行¶
python demo.py 会先打印四 Agent 协作的实时轨迹（Manager 制定计划 → 调度
Glossary → 逐章 Translation → Proofreading → 依报告决定修订），再打印各 Agent 的
token 消耗与管理者模式 vs 单 Agent 的核心对比表。
- 模型默认
gpt-5.6-luna（当前便宜旗舰），可用OPENAI_MODEL覆盖；如需自建/代理端点，设OPENAI_BASE_URL。 - Key 与通用回退：优先用
OPENAI_API_KEY直连 OpenAI；若未设置该变量但设了OPENROUTER_API_KEY，则自动改走 OpenRouter，并把模型名映射到其命名空间 （gpt-5.6-luna→openai/gpt-5.6-luna）。提示：gpt-5.6系列直连 OpenAI 需组织验证， 只填OPENROUTER_API_KEY（不填OPENAI_API_KEY）即可强制走 OpenRouter，更省事。 - 任务规模刻意很小（4 个短章节），一次运行成本约几百分之一美元。
- 不带任何参数运行与旧版行为完全一致。
命令行参数（python demo.py --help）¶
| 参数 | 作用 | 默认 |
|---|---|---|
--dry-run |
离线预演：只画四 Agent 协作图、Manager 计划、编辑部术语与各 Agent 的 token 预算，不调用任何 API、无需 Key | 关闭 |
--sample-dir DIR |
待翻译书籍目录（读取其中 *.md，按文件名排序） |
sample_book/ |
--out-dir DIR |
产物根目录（其下再分 orchestration/、single_agent/） |
output/ |
--source-lang LANG / --target-lang LANG |
源 / 目标语言（仅影响提示词措辞） | 英文 / 中文 |
--no-glossary |
关闭 Glossary Agent（仅保留编辑部指定术语） | 启用 |
--no-proofreading |
关闭 Proofreading Agent 与 Manager 修订闭环 | 启用 |
--model MODEL |
临时覆盖模型（等价于设 OPENAI_MODEL） |
gpt-5.6-luna |
--skip-single |
只跑管理者模式，跳过单 Agent 对照组 | 关闭 |
注意：内置的术语一致性 / 遵从率统计（
consistency.py）针对 英文→中文 调校； 改翻译方向仍可正常翻译，但该统计表意义有限。
无 Key / 离线快速查看架构：
该模式用 tiktoken 离线估算各 Agent 会读到的上下文规模，直观印证「Manager 上下文
只随章节数加几行记录、与每章正文长度无关」，而单 Agent 的累积上下文随书长线性膨胀。
token 统计口径¶
- 子 Agent / 单 Agent 的输入、输出 token 取 OpenAI 返回的真实 usage。
- 「上下文峰值」= 某 Agent 所有调用中，单次输入上下文（prompt tokens）的最大值， 用来衡量上下文膨胀。
- Manager 上下文峰值：Manager 状态（任务/计划/调用记录/文件索引）序列化后用
tiktoken统计的 token 数峰值 —— 它从不包含完整译文。
结论（真实运行结果，gpt-5.6-luna，4 章）¶
| 指标 | 管理者模式 | 单 Agent |
|---|---|---|
| 主/Manager 上下文峰值 (tokens) | 697 | 2320 |
| Manager LLM 决策调用上下文 (tokens) | 783 | — |
| 全流程总 token | 11849 | 6886 |
| 术语内部一致率 | 100% | 89% |
| 指定术语遵从率 | 100% | 53% |
| 参与 Agent 种类数 | 4 | 1 |
- 控制上下文膨胀：单 Agent 的主上下文随章节累积，峰值达 2320 tokens；管理者 模式下 Manager 上下文峰值仅 697 tokens（约 3.3 倍差距）。更重要的是，Manager 上下文与书的长度基本无关（只加一行调用记录/文件索引），而单 Agent 的累积 上下文会随章节线性增长——书越长，差距越大。子 Agent 的上下文各自隔离、互不污染 （每个 Translation 实例峰值仅约 547 tokens）。
- 术语一致性：管理者模式把编辑部指定术语写入共享术语表并强制下发，4 个指定 术语在全书的遵从率 100%；单 Agent 看不到术语表，遵从率仅 53%。换用更强 的 gpt-5.6-luna 后，单 Agent 会自发采用部分「常识译法」（token→词元、 prompt→提示词都命中了指定译法），但对没有唯一标准的术语仍各行其是（latency 全书 译成「延迟」而非规定的「时延」，embedding 译成「嵌入」而非「嵌入向量」，各 0/4、 0/3 遵从）。更关键的是，单 Agent 即便同一个术语也会跨章漂移——token 在部分章 译成「词元」、另一些章直接留「token」，术语内部一致率因此掉到 89%；管理者模式靠 共享术语表把这两类问题一起消除（内部一致率 100%、遵从率 100%）。
- 代价：管理者模式花了明显更多 token（11849 vs 6886，额外的术语表抽取、审校、 调度调用，且推理模型输出更长），换来的是主上下文可控与术语可强制统一—— 这正是长文档翻译真正需要的性质。
说明：术语一致性用确定性字符串匹配统计（见
consistency.py），不是让模型自评。 具体数字每次运行会有小幅波动，但上述量级与结论稳定复现。
局限¶
- 上表在
gpt-5.6-luna上验证；换更强/更弱的模型，两种模式的差距会变化——越强的 单 Agent 越容易自发命中部分常识译法（遵从率从更弱模型的近 0% 升到本次的 53%）， 但仍无法覆盖没有唯一标准的术语，也仍会跨章漂移，管理者模式的共享术语表始终 100%。 - 样例书刻意做得很小（4 个短章节），目的是清晰暴露机制，不代表大规模真实书籍的 绝对 token 数值。
- 术语表遵从率、术语一致性都用确定性字符串匹配（
consistency.py），不是模型自评， 可能漏判措辞更灵活的译法变体。 - 每次运行的具体数字会因模型输出的随机性小幅波动（上表为最近一次真实运行结果）， 但量级与结论稳定复现。