第十二章：最佳实践与常见问题排障
本章汇总使用 DocuTranslate 的最佳实践、成本与质量优化建议，以及官方 FAQ 与常见问题的排查方法，作为整个教程的收尾与速查手册。
12.1 官方 FAQ
Q：翻译出来的还是原文？
A：查看日志报错，通常是 AI 平台欠费或网络问题导致模型请求失败，DocuTranslate 回退成原文。先确认 API-Key 有余额、base_url 正确、网络可达。
Q：8010 端口被占用？
A：换端口启动 docutranslate -i -p 8011，或设置环境变量 DOCUTRANSLATE_PORT=8011。
Q：支持 PDF 扫描件吗？
A：支持。使用 mineru 引擎具备 OCR 能力，可识别扫描件中的文字。
Q：内网 / 离线环境能用吗？
A：可以。翻译用本地 LLM（Ollama / LM Studio / vLLM 等）；如需本地解析 PDF，则本地部署 MinerU（convert_engine="mineru_deploy"）。两者都本地化即可完全离线。
Q：PDF 有缓存机制吗？
A：有。MarkdownBasedWorkflow 在内存中缓存解析结果（最近 10 次），可通过 DOCUTRANSLATE_CACHE_NUM 调整。对同一 PDF 反复调参翻译时可复用解析结果，省时省钱。
Q：如何启用代理？
A：在 TranslatorConfig / Client 中设置 system_proxy_enable=True，或用环境变量 DOCUTRANSLATE_SYSTEM_PROXY_ENABLE=true / DOCUTRANSLATE_PROXY_ENABLED=true。
12.2 常见问题排查清单
遇到问题时，按以下顺序排查：
- 看日志：Web 界面进度区、终端输出、Docker 日志（
docker logs <容器>）通常直接给出报错原因。 - 模型连通性：用小文件（几行 txt）测试，确认
base_url/api_key/model_id三者匹配、平台有余额。 - 目标语言：确认
to_lang填的是自然语言名（如「中文」而非「zh」，虽然多数模型都能理解）。 - PDF 相关：翻 PDF 报错先分清是解析阶段（MinerU Token 过期 / 本地服务未启动）还是翻译阶段（模型问题）。MinerU 在线 Token 有 14 天有效期，过期要重建。
- 速率限制：出现大量 429 / 超时，说明并发过高，调低
concurrent或设置rpm/tpm。 - 格式不支持：确认不是
doc/xls（需先转docx/xlsx）。 - 版本差异：命令 / 字段对不上时，用
docutranslate --version看版本，用docutranslate --help和/docs核对当前版本的真实参数。
12.3 质量优化最佳实践
- 选对模型：翻译任务用高性价比的 flash 类模型（
glm-4-flash、doubao-seed-1-6-flash、qwen-flash、deepseek-chat）通常已足够，不必上顶级推理模型。 - 术语对齐：术语密集的论文 / 系列小说务必开启自动术语表（
glossary_generate_enable），并用glossary_dict兜底关键术语（见第八章）。 - 自定义提示词：用
custom_prompt明确领域、风格、不译规则，能显著改善专业文本的译文质量。 - 低温度：翻译保持
temperature较低（如 0.3）以求稳定、忠实。 - PDF 开公式/代码识别：学术论文开启
formula_ocr、code_ocr，避免公式和代码被破坏。 - 输出格式：论文优先导出 HTML（公式、表格显示效果最好）；要保留 Word 排版用 DocxWorkflow 而非 Markdown 中转。
12.4 成本与性能优化
- 控制并发：
concurrent越大越快，但要匹配平台的 RPM/TPM 上限，否则触发限速反而更慢。用rpm/tpm做硬限流。 - 合理分块：
chunk_size用默认或按模型上下文微调；过小增加请求数与拼接损耗，过大可能超上下文。 - 关闭思考：普通文档翻译把
thinking设为none/disable，省 token、提速。 - 利用缓存：反复调参翻同一 PDF 时，解析缓存能省下重复的 MinerU 解析（时间与在线额度）。
- 批量异步：批量任务用
translate_async+asyncio.gather并发多个文件（见第六章），但注意总并发量。 - 本地化省钱：量大且对隐私敏感时，用本地模型 + 本地 MinerU，边际成本趋近于零（只耗电与算力）。
12.5 安全与隐私实践
- 在线 MinerU 会上传 PDF：对涉密 / 敏感 PDF，改用本地部署 MinerU。
- 云端模型会发送内容：敏感文本用本地 LLM（Ollama / LM Studio）。
- 对外服务加认证：
--host 0.0.0.0暴露服务时，务必用反向代理加 HTTPS 与访问认证，并用DOCUTRANSLATE_ENV_FORCE_OVERRIDE=true锁定模型配置，防止 API-Key 被滥用。 - 及时清理：通过 API / MCP 完成的任务用
release_task释放临时文件；容器部署定期清理output。 - 保护密钥：不要把 API-Key 硬编码进公开仓库，用环境变量 /
.env（并加入.gitignore）管理。
12.6 场景速查
| 场景 | 推荐组合 |
|---|---|
| 翻译学术论文 | Markdown 工作流 + 在线 MinerU + 开公式/代码识别 + 自动术语表 + 导出 HTML |
| 翻译小说 / 电子书 | TXT/EPUB 工作流 + 自定义提示词（文学风格）+ 术语表（人名地名）+ 适当高并发 |
| 翻译 Word 且保留排版 | DocxWorkflow + insert_mode=replace（或 append 双语对照） |
| 翻译 Excel 部分区域 | XlsxWorkflow + translate_regions |
| 翻译 i18n 语言包 | JsonWorkflow + json_paths 精确指定字段 |
| 翻译字幕 | Srt/AssWorkflow（保留时间轴） |
| 全离线 / 内网 | 本地 LLM（Ollama）+ 本地 MinerU（mineru_deploy） |
| 团队共享 | docutranslate -i --host 0.0.0.0 + 环境变量锁定配置 + 反向代理认证 |
| 接入 AI 助手 | MCP（-i --with-mcp 联合模式，共享任务队列） |
12.7 结语
至此，本教程从项目定位、安装部署、Web 界面、模型与解析引擎配置，到格式与工作流、Client SDK、Workflow API、术语表与提示词、REST API、MCP 集成、环境变量与部署，最后到最佳实践与排障，完整覆盖了 DocuTranslate 的使用与开发。
DocuTranslate 迭代很快，建议把以下三处作为长期权威参考：
- 官方仓库：github.com/xunbu/docutranslate
- 本地 API 文档：
http://127.0.0.1:8010/docs - 命令行帮助：
docutranslate --help
当文中命令、字段与你的版本不一致时，一律以上述实时来源为准。祝翻译愉快！