PDFMathTranslate的二次开发与API

文章概要：本文详细介绍了PDFMathTranslate的二次开发与API使用方法，包括Python API的核心功能、HTTP API的调用流程、后端服务部署与任务管理，以及API返回结果与错误处理机制。通过代码示例、流程图和表格，帮助开发者快速掌握如何集成PDF翻译功能到自己的项目中。

Python API的使用方法

PDFMathTranslate 提供了丰富的 Python API，便于开发者在自己的项目中集成 PDF 翻译功能。以下将详细介绍如何使用这些 API，并通过代码示例和流程图展示其核心功能。

---

核心功能概述

PDFMathTranslate 的 Python API 主要分为以下几个模块：

1. 文件翻译：支持从本地文件或流中读取 PDF 并进行翻译。
2. 多线程处理：通过配置线程数提高翻译效率。
3. 缓存管理：支持翻译结果的缓存，避免重复翻译。
4. 布局解析：利用 ONNX 模型解析 PDF 布局，保留公式、图表等复杂结构。

以下是一个简单的流程图，展示了翻译流程的主要步骤：

flowchart TD
    A[输入PDF文件] --> B[解析PDF布局]
    B --> C[提取文本和公式]
    C --> D[调用翻译服务]
    D --> E[生成双语PDF]
    E --> F[输出结果]

---

主要API函数

1. translate_stream

用于从字节流中读取 PDF 并翻译。

参数说明：

• stream：PDF 文件的字节流。
• lang_in：源语言代码（如 "en"）。
• lang_out：目标语言代码（如 "zh"）。
• service：翻译服务（如 "google"）。
• thread：线程数（默认为 0，单线程）。

示例代码：

from pdf2zh import translate_stream

with open("example.pdf", "rb") as f:
    stream = f.read()
    mono_pdf, dual_pdf = translate_stream(
        stream=stream,
        lang_in="en",
        lang_out="zh",
        service="google",
        thread=4
    )

2. translate_patch

用于对 PDF 的特定页面进行翻译。

参数说明：

• inf：PDF 文件的输入流。
• pages：需要翻译的页面列表（如 [1, 3, 5]）。
• callback：进度回调函数。

示例代码：

from pdf2zh import translate_patch

with open("example.pdf", "rb") as f:
    translate_patch(
        inf=f,
        pages=[1, 3, 5],
        lang_in="en",
        lang_out="zh",
        service="google"
    )

3. convert_to_pdfa

将翻译后的 PDF 转换为 PDF/A 格式。

参数说明：

• input_path：输入文件路径。
• output_path：输出文件路径。

示例代码：

from pdf2zh import convert_to_pdfa

convert_to_pdfa("translated.pdf", "translated_pdfa.pdf")

---

高级功能

多线程翻译

通过设置 thread 参数，可以启用多线程翻译，显著提升大文件的处理速度。

mono_pdf, dual_pdf = translate_stream(
    stream=stream,
    lang_in="en",
    lang_out="zh",
    service="google",
    thread=8  # 使用8个线程
)

缓存管理

通过 ignore_cache 参数控制是否使用缓存。默认情况下，翻译结果会被缓存以提升后续翻译效率。

mono_pdf, dual_pdf = translate_stream(
    stream=stream,
    lang_in="en",
    lang_out="zh",
    service="google",
    ignore_cache=True  # 忽略缓存
)

---

示例表格

以下表格总结了常用 API 的参数及其作用：

参数名	类型	说明
stream	bytes	PDF 文件的字节流
lang_in	str	源语言代码（如 "en"）
lang_out	str	目标语言代码（如 "zh"）
service	str	翻译服务（如 "google"）
thread	int	线程数（默认为 0）
ignore_cache	bool	是否忽略缓存（默认为 False）

---

通过以上内容，开发者可以快速掌握 PDFMathTranslate 的 Python API 使用方法，并根据需求灵活调整参数。如需进一步了解，可以参考项目的详细文档或源码。

HTTP API的调用流程

PDFMathTranslate提供了灵活的HTTP API接口，允许开发者通过HTTP协议与后端服务交互，实现PDF文档的翻译功能。以下是HTTP API的详细调用流程，涵盖任务提交、进度查询、结果获取等关键步骤。

1. 启动后端服务

在调用HTTP API之前，需要先启动后端服务。运行以下命令启动Flask和Celery服务：

pip install pdf2zh[backend]
pdf2zh --flask
pdf2zh --celery worker

启动后，Flask服务默认运行在http://localhost:11008，Celery用于处理异步任务。

---

2. 提交翻译任务

通过/v1/translate接口提交PDF文件进行翻译。以下是一个示例请求：

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

参数说明：

• file: 上传的PDF文件。
• data: JSON格式的翻译配置，包括：
  • lang_in: 源语言（如en）。
  • lang_out: 目标语言（如zh）。
  • service: 翻译服务（如google、deepl）。
  • thread: 线程数。

响应示例：

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

返回的任务ID用于后续操作。

---

3. 查询任务进度

通过/v1/translate/{task_id}接口查询任务进度：

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

响应示例：

• 任务进行中：

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

• 任务完成：

  {"state":"SUCCESS"}
  

---

4. 获取翻译结果

任务完成后，可通过以下接口获取翻译结果文件：

获取单语文件

curl http://localhost:11008/v1/translate/d9894125-2f4e-45ea-9d93-1a9068d2045a/mono \
  --output example-mono.pdf

获取双语文件

curl http://localhost:11008/v1/translate/d9894125-2f4e-45ea-9d93-1a9068d2045a/dual \
  --output example-dual.pdf

---

5. 中断或删除任务

通过DELETE方法中断或删除任务：

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

---

6. 流程图

以下为HTTP API调用流程的Mermaid流程图：

sequenceDiagram
    participant Client
    participant Flask
    participant Celery

    Client->>Flask: POST /v1/translate (提交任务)
    Flask->>Celery: 异步处理任务
    Celery-->>Flask: 返回任务ID
    Flask-->>Client: 返回任务ID

    loop 查询进度
        Client->>Flask: GET /v1/translate/{task_id}
        Flask-->>Client: 返回进度或结果
    end

    Client->>Flask: GET /v1/translate/{task_id}/mono (获取单语文件)
    Flask-->>Client: 返回文件
    Client->>Flask: GET /v1/translate/{task_id}/dual (获取双语文件)
    Flask-->>Client: 返回文件

通过以上流程，开发者可以轻松集成PDFMathTranslate的HTTP API，实现高效的PDF翻译功能。

后端服务部署与任务管理

PDFMathTranslate 的后端服务提供了强大的任务管理和部署能力，支持通过 HTTP 协议和 MCP（Microservice Communication Protocol）进行交互。本节将详细介绍如何部署后端服务以及如何管理翻译任务。

后端服务部署

PDFMathTranslate 的后端服务支持两种部署方式：

1. HTTP 服务：基于 Flask 和 Celery 的任务队列。
2. MCP 服务：基于 FastMCP 的轻量级微服务通信协议。

1. HTTP 服务部署

HTTP 服务通过 Flask 提供 RESTful API，并通过 Celery 实现异步任务处理。以下是部署步骤：

pip install pdf2zh[backend]
pdf2zh --flask
pdf2zh --celery worker

功能说明

• 提交任务：

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

  返回任务 ID：

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

• 查询任务进度：

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

  返回进度信息：

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

• 下载结果：

  • 单语文件：

    curl http://localhost:11008/v1/translate/d9894125-2f4e-45ea-9d93-1a9068d2045a/mono --output example-mono.pdf
    

  • 双语文件：

    curl http://localhost:11008/v1/translate/d9894125-2f4e-45ea-9d93-1a9068d2045a/dual --output example-dual.pdf
    

2. MCP 服务部署

MCP 服务基于 FastMCP 实现，支持 SSE（Server-Sent Events）和 STDIO 两种通信方式。以下是部署步骤：

from mcp.server import Server
from mcp.server.fastmcp import FastMCP, Context
from pdf2zh import translate_stream

def create_mcp_app() -> FastMCP:
    mcp = FastMCP("pdf2zh")

    @mcp.tool()
    async def translate_pdf(file: str, lang_in: str, lang_out: str, ctx: Context) -> str:
        with open(file, "rb") as f:
            file_bytes = f.read()
        doc_mono_bytes, doc_dual_bytes = translate_stream(
            file_bytes, lang_in=lang_in, lang_out=lang_out, service="google", thread=4
        )
        output_path = Path(file).parent
        filename = Path(file).stem
        doc_mono = output_path / f"{filename}-mono.pdf"
        doc_dual = output_path / f"{filename}-dual.pdf"
        with open(doc_mono, "wb") as f:
            f.write(doc_mono_bytes)
        with open(doc_dual, "wb") as f:
            f.write(doc_dual_bytes)
        return f"Translation complete: {doc_mono}, {doc_dual}"

    return mcp

if __name__ == "__main__":
    mcp = create_mcp_app()
    mcp.run()

功能说明

• 启动服务：

  python mcp_server.py --sse --host 127.0.0.1 --port 3001
  

• 提交任务： 通过 SSE 或 STDIO 发送任务请求，返回翻译结果路径。

任务管理

PDFMathTranslate 的任务管理功能包括：

1. 任务状态查询：实时获取任务进度。
2. 任务中断：支持取消正在运行的任务。
3. 结果缓存：通过 Redis 缓存翻译结果，提升重复任务的效率。

任务状态查询

curl http://localhost:11008/v1/translate/{task_id}

任务中断

curl http://localhost:11008/v1/translate/{task_id} -X DELETE

缓存管理

通过 cache.py 模块实现缓存功能，支持以下操作：

• 设置缓存：

  cache.set("original_text", "translated_text")
  

• 获取缓存：

  translation = cache.get("original_text")
  

总结

PDFMathTranslate 的后端服务提供了灵活的部署方式和强大的任务管理能力，适合高并发和大规模翻译任务场景。无论是通过 HTTP 还是 MCP，用户都可以轻松集成到自己的系统中。

API返回结果与错误处理

在PDFMathTranslate的二次开发与API使用过程中，理解API的返回结果和错误处理机制是至关重要的。本节将详细介绍API的返回格式、常见错误类型及其处理方法，帮助开发者更好地集成和使用API。

---

返回结果格式

PDFMathTranslate的API返回结果通常包含以下字段：

字段名	类型	描述
state	string	任务状态，可能为SUCCESS、PROGRESS、FAILED或PENDING。
info	object	任务详细信息，如进度（n和total）或错误信息（error）。
file_mono	string	单语翻译结果文件的路径（仅state=SUCCESS时返回）。
file_dual	string	双语对照结果文件的路径（仅state=SUCCESS时返回）。

示例

{
    "state": "SUCCESS",
    "info": null,
    "file_mono": "/path/to/example-mono.pdf",
    "file_dual": "/path/to/example-dual.pdf"
}

---

错误处理

API可能返回以下常见错误类型及其处理方法：

错误类型	描述	处理方法
INVALID_PARAMETER	参数无效或缺失（如未指定输入文件或目标语言）。	检查请求参数是否符合API文档要求。
FILE_NOT_FOUND	输入文件不存在或无法访问。	确认文件路径是否正确，并检查文件权限。
TRANSLATION_FAILED	翻译过程中发生错误（如翻译服务不可用或超时）。	重试任务或检查翻译服务配置（如API密钥）。
TASK_TIMEOUT	任务执行超时。	增加超时时间或优化任务规模（如分页处理）。
INTERNAL_ERROR	服务器内部错误。	联系技术支持或检查服务器日志。

示例错误响应

{
    "state": "FAILED",
    "info": {
        "error": "TRANSLATION_FAILED",
        "message": "Translation service returned an error: Invalid API key."
    }
}

---

状态码与重试机制

API使用HTTP状态码标识请求结果：

状态码	描述
200	请求成功，任务完成或进行中。
400	请求参数错误。
404	任务ID不存在或资源未找到。
500	服务器内部错误。

对于PROGRESS状态的任务，建议通过轮询机制检查进度：

import time
import requests

task_id = "d9894125-2f4e-45ea-9d93-1a9068d2045a"
while True:
    response = requests.get(f"http://localhost:11008/v1/translate/{task_id}")
    if response.json()["state"] == "SUCCESS":
        break
    time.sleep(1)

---

高级错误处理

对于需要更复杂错误处理的场景，可以使用以下方法：

1. 自定义回调函数
   在Python API中，通过callback参数指定错误处理逻辑：

   def handle_error(error):
       print(f"Error occurred: {error}")
   
   translate(files=["example.pdf"], callback=handle_error)
   

2. 日志记录
   启用日志功能以追踪错误详情：

   import logging
   logging.basicConfig(level=logging.DEBUG)
   

3. 任务中断
   使用cancellation_event中断长时间运行的任务：

   import asyncio
   event = asyncio.Event()
   translate_stream(stream=file_content, cancellation_event=event)
   event.set()  # 中断任务
   

---

通过以上内容，开发者可以更好地理解API的返回结果和错误处理机制，从而更高效地完成二次开发任务。

本文全面介绍了PDFMathTranslate的二次开发与API使用方法，包括Python API的核心功能、HTTP API的调用流程、后端服务部署与任务管理，以及API返回结果与错误处理机制。通过详细的代码示例、流程图和表格，开发者可以快速掌握如何集成PDF翻译功能到自己的项目中，并根据需求灵活调整参数。无论是通过Python API还是HTTP API，PDFMathTranslate都提供了强大的功能和灵活的部署方式，适合各种规模的翻译任务场景。