简介
DocuTranslate
文件翻译工具，借助docling与大语言模型实现多种格式文件的翻译
安装
使用pip
pip install docutranslate
使用uv
uv init
uv add docutranslate
支持的文件格式
| 输入格式 | 输出格式 |
|---|---|
| PDF（非扫描版） | Markdown（推荐） |
| Markdown | HTML |
| HTML、XHTML | |
| CSV |
前置条件
huggingface换源
不能科学上网的友友注意了
无法访问的huggingface的电脑在以下操作时请换源点击测试
- 第一次读取非markdown文本
- 第一次使用公式识别或代码识别功能
方法1
设置电脑的环境变量(记得设置后重启IDE)
HF_ENDPOINT=https://hf-mirror.com
方法2
在代码开头设置环境变量
import os
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'
###其余代码写在下方
获取大模型平台的baseurl、key、model-id
由于需要使用大语言模型进行markdown调整与翻译，所以需要预先获取模型的baseurl、key、model-id
常见的大模型平台baseurl与api获取方式可见常用ai平台
比较推荐的模型有智谱的glm-4-air、glm-4-flash（免费），阿里云的qwen-plus等。
推理模型需要支持api请求响应中区分reasoning_content和content（详见平台开发手册，ollama、lmstudio需开启对应选项）
使用方式
注意事项（第一次使用必看）
以下操作会自动从huggingface下载模型，windows需要使用管理员模式打开IDE运行脚本，并按需换源换源指南
- 第一次使用该库读取、翻译非markdown文本
- 第一次使用该库的公式识别或代码识别功能
翻译文件
from docutranslate.translater import FileTranslater
translater = FileTranslater(base_url="<baseurl>",
key="<key>",
model_id="<model-id>")
# 不开启公式、代码识别（默认输出为markdown文件）
translater.translate_file("<文件路径>", to_lang="中文")
# 开启公式、代码识别（需要下载更多模型）
translater.translate_file("<文件路径>", to_lang="中文", formula=True, code=True)
# 在先修复文本再翻译（适用于翻译pdf，但更耗时耗费）
translater.translate_file("<文件路径>", to_lang="中文",refine=True)
下载模型时请用管理员模式打开终端运行文件（windows），并按需换源 输出文件默认放在
./output中
使用不同的agent分别进行文本修正和翻译
from docutranslate import FileTranslater
from docutranslate.Agents import MDRefineAgent, MDTranslateAgent
translater = FileTranslater()
refine_agent = MDRefineAgent(baseurl="<baseurl-1>", key="<key-1>", model_id="<model-id-1>")
translate_agent = MDTranslateAgent(baseurl="<baseurl-2>", key="<key-2>", model_id="<model-id-2>")
translater.translate_file("<文件路径>", to_lang="中文", refine_agent=refine_agent,
translate_agent=translate_agent)
文件转换(pdf/markdown/HTML/Doc等->markdown/html)
from docutranslate import FileTranslater
translater = FileTranslater(base_url="<baseurl>",
key="<key>",
model_id="<model-id>")
# 文件转html
translater.read_file("<文件路径>").save_as_html()
# 文件转markdown
translater.read_file("<文件路径>").save_as_markdown()
参数说明
创建FileTranslater
from docutranslate import FileTranslater
translater = FileTranslater(base_url="<baseurl>", # 默认的模型baseurl
key="<key>", # 默认的模型api-key
model_id="<model-id>", # 默认的模型id
chunksize=4000, # markdown分块长度（单位byte），分块越大效果越好，不建议超过4096
max_concurrent=10, # 并发数，受到ai平台并发量限制，如果文章很长建议适当加大到20以上
docling_artifact=None, # 使用提前下载好的docling模型
timeout=2000,# 调用api的超时时间
tips=True # 开场提示
)
翻译文件
translater.translate_file(r"<要翻译的文件路径>",
to_lang="中文",
formula=False, # 是否启用公式识别
code=False, # 是否启用代码识别
refine=False, # 是否在翻译前先修正一遍markdown文本（较耗时）
output_format="markdown", # "markdown"与"html"两种输出格式
output_dir="./output", # 默认输出文件夹
refine_agent=None, # 修正Agent
translate_agent=None # 翻译Agent
)
常用ai平台
| 平台名称 | 获取APIkey | baseurl |
|---|---|---|
| ollama | http://127.0.0.1:11434/v1 | |
| lm studio | http://127.0.0.1:1234/v1 | |
| openrouter | 点击获取 | https://openrouter.ai/api/v1 |
| openai | 点击获取 | https://api.openai.com/v1/ |
| deepseek | 点击获取 | https://api.deepseek.com/v1 |
| 智谱ai | 点击获取 | https://open.bigmodel.cn/api/paas/v4 |
| 腾讯混元 | 点击获取 | https://api.hunyuan.cloud.tencent.com/v1 |
| 阿里云百炼 | 点击获取 | https://dashscope.aliyuncs.com/compatible-mode/v1 |
| 火山引擎 | 点击获取 | https://ark.cn-beijing.volces.com/api/v3 |
| 硅基流动 | 点击获取 | https://api.siliconflow.cn/v1 |
| DMXAPI | 点击获取 | https://www.dmxapi.cn/v1 |
FAQ
- 是否支持扫描件
暂不支持
- 第一次使用很慢是怎么回事
第一次是使用时docling需要从huggingface下载转换输入文件为markdown的模型
通过设置环境变量换源或科学上网可能有助于提高下载速度
huggingface换源，请设置环境变量：
HF_ENDPOINT=https://hf-mirror.com
- 如何内网使用（不联网）
可以，对于docling提供的解析pdf、html等功能，可以使用以下方式提前下载所需的模型
from docutranslate.utils.docling_utils import get_docling_artifacts
print(get_docling_artifacts()) # 会显示模型下载文件夹，通常在`C:\Users\<user>\.cache\docling\models`
创建FileTranslater时携带模型文件夹即可
from docutranslate import FileTranslater
translater = FileTranslater(base_url="<baseurl>",
key="<key>",
model_id="<model-id>", # 使用的模型id
docling_artifact=r"C:\Users\<user>\.cache\docling\models"
)
对于llm功能，可以使用ollama或lm studio等方式本地部署。