PDFMathTranslate项目API使用指南：Python与HTTP接口详解

PDFMathTranslate项目API使用指南：Python与HTTP接口详解

PDFMathTranslate PDF scientific paper translation with preserved formats - 基于 AI 完整保留排版的 PDF 文档全文双语翻译，支持 Google/DeepL/Ollama/OpenAI 等服务，提供 CLI/GUI/Docker/Zotero 项目地址: https://gitcode.com/gh_mirrors/pd/PDFMathTranslate

项目概述

PDFMathTranslate是一个专注于处理PDF文档中数学公式的翻译工具，特别适合学术论文和技术文档的本地化工作。该项目提供了两种灵活的API调用方式，满足不同场景下的集成需求。

环境准备

在使用API前，请确保满足以下条件：

1. 已安装Redis服务并正常运行
2. 已正确安装PDFMathTranslate项目及其依赖

Python API接口

核心方法

项目提供了两个主要的Python方法供开发者调用：

1. translate() - 用于文件路径翻译
2. translate_stream() - 用于文件流翻译

基础参数说明

所有翻译方法都支持以下关键参数：

| 参数名 | 类型 | 说明 | 可选值 | |--------|------|------|--------| | lang_in | str | 源语言代码 | en, zh等 | | lang_out | str | 目标语言代码 | en, zh等 | | service | str | 翻译服务提供商 | google, baidu等 | | thread | int | 并发线程数 | 根据系统配置调整 |

使用示例

文件路径翻译

from pdf2zh import translate

params = {
    'lang_in': 'en',
    'lang_out': 'zh',
    'service': 'google',
    'thread': 4,
}

# 返回值为列表，每个元素对应输入文件的翻译结果
results = translate(files=['paper.pdf', 'report.pdf'], **params)

# 获取第一个文件的翻译结果
mono_file, dual_file = results[0]

文件流翻译

from pdf2zh import translate_stream

with open('thesis.pdf', 'rb') as f:
    # 直接处理文件二进制流
    mono_stream, dual_stream = translate_stream(stream=f.read(), **params)

返回值说明

两种方法都返回一个二元组：

• 第一个元素：单语版PDF内容（目标语言）
• 第二个元素：双语对照版PDF内容

HTTP REST API接口

服务部署

要启用HTTP接口，需要启动两个服务组件：

1. Web服务（Flask）

pdf2zh --flask

2. 任务队列处理（Celery）

pdf2zh --celery worker

API端点说明

1. 提交翻译任务

请求方式：POST
端点：/v1/translate
参数：

• file：PDF文件（表单字段）
• data：JSON格式的翻译参数（表单字段）

示例：

curl http://localhost:11008/v1/translate \
  -F "file=@research.pdf" \
  -F "data={\"lang_in\":\"en\",\"lang_out\":\"zh\",\"service\":\"google\",\"thread\":4}"

响应：

{"id":"d9894125-2f4e-45ea-9d93-1a9068d2045a"}

2. 查询任务状态

请求方式：GET
端点：/v1/translate/<task_id>

响应状态：

• PROGRESS：进行中（包含进度信息）
• SUCCESS：已完成
• FAILURE：失败
• PENDING：排队中

示例响应：

{"info":{"n":13,"total":506},"state":"PROGRESS"}

3. 获取翻译结果

单语版下载：

curl http://localhost:11008/v1/translate/<task_id>/mono --output output-mono.pdf

双语版下载：

curl http://localhost:11008/v1/translate/<task_id>/dual --output output-dual.pdf

4. 取消任务

请求方式：DELETE
端点：/v1/translate/<task_id>

curl http://localhost:11008/v1/translate/d9894125-2f4e-45ea-9d93-1a9068d2045a -X DELETE

最佳实践建议

1. 线程数选择：根据CPU核心数合理设置thread参数，通常4-8个线程可获得较好性能
2. 任务管理：对于HTTP接口，建议实现定期轮询状态机制，而非持续等待
3. 错误处理：总是检查API响应状态，处理可能的异常情况
4. 资源清理：长时间运行的服务应定期清理已完成的任务记录

常见问题解答

Q: 为什么需要Redis服务？
A: Redis用于任务队列管理和状态跟踪，是Celery任务调度的基础组件。

Q: 翻译服务(service参数)如何选择？
A: Google翻译准确度高，Baidu翻译对中文支持更好，可根据实际需求选择。

Q: 如何处理大型PDF文件？
A: 建议分章节处理，或增加线程数提高并行处理能力。

PDFMathTranslate PDF scientific paper translation with preserved formats - 基于 AI 完整保留排版的 PDF 文档全文双语翻译，支持 Google/DeepL/Ollama/OpenAI 等服务，提供 CLI/GUI/Docker/Zotero 项目地址: https://gitcode.com/gh_mirrors/pd/PDFMathTranslate