Wenyi AI翻译 config.yaml逐项精讲：7大配置分类+20余个关键项完全注解

Wenyi AI翻译 config.yaml逐项精讲：7大配置分类+20余个关键项完全注解

【免费下载链接】wenyi将被语言阻隔的作品，带到读者的语言中。Bringing literature into your language.项目地址: https://gitcode.com/BigDawnGhost/wenyi

Wenyi 是一款开源的AI 书籍翻译工具——"将被语言阻隔的作品，带到读者的语言中"，支持 EPUB / DOCX / PDF / 字幕等格式的长篇翻译，内置全书理解、实时术语表与证据式审校。而 config.yaml 就是它的"总开关"：7 大顶级分类、20 余个关键项，决定语言方向、模型路由、质量策略和输出格式，全程无需改一行代码。本文对每一项配置做逐条注解，帮你从零配好第一本小说翻译。

一眼看懂：config.yaml 的 7 大配置分类 🗂️

打开 config.yaml（首次运行会自动生成带注释的默认版本），你会看到 7 个顶级分类：

分类	作用	新手关注度
language	源语言与目标语言	⭐⭐⭐ 必须会
llm	模型预设、提供商与操作路由	⭐⭐⭐ 核心
segment	翻译批次与段落切分	⭐⭐ 一般动
pipeline	质量与成本的流程开关（最多）	⭐⭐⭐ 核心
honorific	日语敬称处理策略	⭐ 按需
paths	状态目录位置	⭐ 默认即可
output	单语/双语与排版输出	⭐⭐ 导出前必看

💡 官方逐项说明见 docs/zh/configuration.md，流程背景见 docs/zh/pipeline.md。配置解析逻辑在 packages/core/wenyi_core/config.py，未知配置项会被直接拒绝，所以照抄本文写法最稳妥。

分类一：language —— 翻译方向怎么选

language: source: auto target: zh

• source: auto：让模型自动识别源语言；也可以显式指定ja/en/ko/ru/de等。
• target：目标语言，默认zh（简体中文），完整列表包含zh-Hant、en、ja、ko、fr、de、es、it、pt-BR、ru等，运行uv run wenyi languages可查看。
• 源语言与目标语言直接互译，不经中文中转；改成英语译文只需写target: en。
• ⚠️ 更换target会建立独立状态目录，旧译文不会自动迁移，属于常见"坑"。

分类二：llm —— 模型预设与操作路由（最重要）⚡

llm: preset: deepseek

只写一行就能跑起来：preset: deepseek会自动展开为连接、模型配置和strong / cheap / fast 三个档位映射（默认三档都用deepseek-flash并开启 thinking）。API Key 只从环境变量（如DEEPSEEK_API_KEY）读取，不要写进配置文件。

需要更强控制时，可叠加三类字段：

字段	作用
providers.<id>	定义提供商连接：kind、base_url、api_key_env、timeout、max_retries、max_concurrency
models.<id>	定义模型请求配置：所属连接、远端模型 ID、max_output_tokens等
routes.<操作>	把某个操作（如polish.body、review.verify）单独路由到指定模型或档位

也就是说，翻译用强模型、术语抽取用便宜模型、润色用专属模型这种混用，全在llm里完成。此外还有两个省钱利器：

• quotas：按分钟限制请求数（RPM）和 token 数（TPM），多连接可共享同一quota_group；
• budget：max_requests/max_tokens/deadline_seconds给整次运行设预算上限。

想确认当前配置实际生效了什么，运行uv run wenyi models list即可，无需密钥、不发送请求。

配好llm后，翻译总览页能按步骤、按模型、按提供商回看每一次调用的 token 用量与耗时

分类三：segment —— 批次与段落怎么切

segment: max_tokens_per_batch: 1800 max_tokens_per_segment: 1200

• max_tokens_per_batch：单个翻译批次的源文 token 预算（按 tiktokencl100k_base估算）。批越大，上下文越连贯，但对模型输出能力要求越高。
• max_tokens_per_segment：超长段落按句边界拆分的阈值，导出时会自动合并回原段落。

新手建议：先保持默认，遇到"段落被截断"或"上下文不足"类问题再微调。

分类四：pipeline —— 质量与成本的 18 个开关 🎛️

这是整个配置里选项最多的一块，可分为四组理解：

基础质量开关

配置项	默认	说明
review	true	全书翻译完成后自动执行取证式审校；--no-review可跳过
polish	true	强模型全文润色，质量提升明显，但显著增加耗时和成本
rolling_context_segments	6	每批翻译附带的前文译文段数
book_understanding	true	预扫全书生成章节梗概+全书概览，注入每个翻译批次；关闭可省预扫成本

并发与重试

• prescan_concurrency: 4—— 预扫章节梗概的并发数，设为1串行执行；
• annotation_alignment: true—— EPUB 脚注/尾注的链接定位，关闭后链接退化为段末标记；
• review_concurrency: 4—— 基于同一份只读译文快照的审校块并发上限；
• review_output_retries: 2—— 审校响应格式异常时的额外重试次数（连同首次共 3 次）。

审校 Agent 系列（review_agent_*/review_fix_*）

这组实现了"翻译 → 初审 → 取证核查 → 影子修订 → 盲审确认"的完整质量环：

• review_agent_loop：初审发现候选问题后，允许 Agent 选择性请求证据再判定；
• review_agent_max_evidence_rounds: 2：取证最多 2 轮，用完后必须给出结论；
• review_conflict_arbitration：各审校块对同一术语/表达的建议互相矛盾时，做终局仲裁；
• review_fix_loop+review_fix_max_rounds: 2：在内存"影子译文"上修订并盲审，最多 2 轮替换；
• review_clean_confirmations: 2：连续 2 次全书盲审无问题才接受影子译文；
• review_autofix：把审校修订正式写回章节，--no-autofix则只给建议。

术语表与 PDF 后端

• glossary_scope：chapter只带本章术语（省 token），full带全量术语表；
• pdf_backend：mineru（默认，支持扫描件）或babeldoc（经外部 HTTP bridge 尽量保留版式），配套babeldoc_bridge_url/babeldoc_timeout/babeldoc_pages三项。

pipeline.review开启后的成果在 Web 界面呈现：左右对照原文与译文，可逐段编辑、查看改动记录

分类五：honorific —— 日语敬称策略

honorific: strategy: keep_style

专治日语源文本的"敬语"问题，三选一：

• keep_style：保留原文的关系感与语气（默认，推荐）；
• normalize：统一规范化敬称；
• drop：在意义允许处省略。

非日语源文此项不产生影响，可放心保持默认。

分类六：paths —— 状态放哪里

paths: state_dir: state

state_dir存放书籍断点、章节产物、术语库、用量账本和审校记录，所有书统一使用<state_dir>/<书名>/targets/<目标语言>/结构。断点续跑全靠它——翻译中断后执行同一条命令即可接着跑。想换硬盘或隔离多本书的状态，改这里就行。

分类七：output —— 导出格式与双语排版 📖

output: mono: true bilingual: false bilingual_order: target_first bilingual_preserve_source_style: false about_page: true punctuation_normalize: true

配置项	说明
mono	生成单语译本，如<书名>.zh.epub
bilingual	额外生成原文+译文对照版（也可用--bilingual命令行触发）
bilingual_order	target_first译文在上，source_first原文在上
bilingual_preserve_source_style	true时原文保留书籍正文样式，否则以灰色淡化显示
about_page	书末附加"关于此翻译"说明页
punctuation_normalize	仅对简体中文的导出副本做标点规范化，正式状态文件不受影响

bilingual: true导出的双语 EPUB 效果：译文在上、原文以灰色淡化展示，脚注链接自动对齐

新手速查：三档配置方案 🚀

场景	关键改动
最快出稿	polish: false、book_understanding: false、review: false
均衡默认	保持出厂默认，仅设好llm.preset和环境变量
质量优先	保持全部默认，另在llm.routes给review.verify指定最强模型

📌 记住三点就不会踩坑：API Key 只进环境变量、改target语言等于开新状态、polish是成本大头。逐项细节随时对照 docs/zh/configuration.md，上手流程参考 docs/zh/usage.md。祝翻译顺利！

【免费下载链接】wenyi将被语言阻隔的作品，带到读者的语言中。Bringing literature into your language.项目地址: https://gitcode.com/BigDawnGhost/wenyi