26 KiB
DocuTranslate
简体中文 / English / 日本語 / Tiếng Việt
Một công cụ dịch thuật tệp tin cục bộ gọn nhẹ dựa trên các Mô hình Ngôn ngữ Lớn (LLM).
- ✅ Hỗ trợ Đa định dạng: Dịch các file
pdf,docx,xlsx,md,txt,json,epub,srt,ass, và nhiều hơn nữa. - ✅ Tự động Tạo Thuật ngữ (Glossary): Hỗ trợ tự động tạo bảng thuật ngữ để đảm bảo sự đồng nhất về thuật ngữ.
- ✅ Nhận dạng Bảng, Công thức, Mã trong PDF: Tận dụng các công cụ phân tích PDF như
doclingvàmineruđể nhận dạng và dịch các bảng, công thức và mã code thường thấy trong các bài báo học thuật. - ✅ Dịch thuật JSON: Hỗ trợ chỉ định các giá trị cần dịch trong JSON bằng đường dẫn (sử dụng cú pháp
jsonpath-ng). - ✅ Bảo toàn Định dạng Word/Excel: Hỗ trợ file
docxvàxlsx(hiện chưa hỗ trợdochoặcxls) trong khi vẫn giữ nguyên định dạng gốc. - ✅ Hỗ trợ Đa Nền tảng AI: Hỗ trợ hầu hết các nền tảng AI, cho phép dịch thuật AI đồng thời hiệu suất cao với các prompt tùy chỉnh.
- ✅ Hỗ trợ Bất đồng bộ (Async): Được thiết kế cho các kịch bản hiệu suất cao, cung cấp hỗ trợ bất đồng bộ đầy đủ và các giao diện cho đa nhiệm song song.
- ✅ Hỗ trợ Mạng LAN & Đa người dùng: Hỗ trợ sử dụng đồng thời bởi nhiều người dùng trong cùng một mạng cục bộ (LAN).
- ✅ Giao diện Web Tương tác: Cung cấp sẵn Giao diện Web (Web UI) và RESTful API để dễ dàng tích hợp và sử dụng.
- ✅ Các gói Portable Gọn nhẹ: Các gói portable cho Windows và Mac dưới 40MB (các phiên bản không sử dụng
doclingđể phân tích PDF cục bộ).
Khi dịch
Nhóm Cộng đồng QQ: 1047781902
Các Gói Tích hợp
Dành cho những người dùng muốn bắt đầu nhanh chóng, chúng tôi cung cấp các gói tích hợp trên GitHub Releases. Chỉ cần tải xuống, giải nén và nhập API-Key nền tảng AI của bạn để bắt đầu sử dụng.
- DocuTranslate: Phiên bản tiêu chuẩn. Sử dụng
minerU(online hoặc triển khai cục bộ) để phân tích PDF. Hỗ trợ gọi API minerU cục bộ. (Được khuyến nghị) - DocuTranslate_full: Phiên bản đầy đủ. Bao gồm công cụ phân tích PDF cục bộ tích hợp sẵn là
docling. Chọn phiên bản này nếu bạn cần phân tích PDF offline mà không cần minerU.
Cài đặt
Sử dụng pip
# Cài đặt cơ bản
pip install docutranslate
# Nếu bạn cần sử dụng docling để phân tích PDF cục bộ
pip install docutranslate[docling]
Sử dụng uv
# Khởi tạo môi trường
uv init
# Cài đặt cơ bản
uv add docutranslate
# Cài đặt phần mở rộng docling
uv add docutranslate[docling]
Sử dụng git
# Khởi tạo môi trường
git clone https://github.com/xunbu/docutranslate.git
cd docutranslate
uv sync
Sử dụng docker
docker run -d -p 8010:8010 xunbu/docutranslate:latest
# docker run -it -p 8010:8010 xunbu/docutranslate:latest
# docker run -it -p 8010:8010 xunbu/docutranslate:v1.5.4
Khái niệm Cốt lõi: Workflow (Quy trình làm việc)
DocuTranslate sử dụng hệ thống Workflow - mỗi workflow là một đường ống dịch thuật hoàn chỉnh cho một loại tệp cụ thể.
Luồng cơ bản:
- Chọn workflow dựa trên loại tệp
- Cấu hình workflow (LLM, công cụ phân tích, định dạng đầu ra)
- Thực thi dịch thuật
- Lưu kết quả
Khởi chạy Web UI và Dịch vụ API
Để thuận tiện cho việc sử dụng, DocuTranslate cung cấp Giao diện Web đầy đủ chức năng và RESTful API.
Khởi chạy Dịch vụ:
# Khởi chạy dịch vụ, mặc định lắng nghe trên cổng 8010
docutranslate -i
# Khởi chạy trên một cổng cụ thể
docutranslate -i -p 8011
# Cho phép các yêu cầu CORS
docutranslate -i --cors
# Bạn cũng có thể chỉ định cổng thông qua biến môi trường
export DOCUTRANSLATE_PORT=8011
docutranslate -i
- Giao diện Tương tác: Sau khi khởi chạy dịch vụ, vui lòng truy cập
http://127.0.0.1:8010(hoặc cổng bạn đã chỉ định) trên trình duyệt. - Tài liệu API: Tài liệu API đầy đủ (Swagger UI) nằm tại
http://127.0.0.1:8010/docs.
Ví dụ Sử dụng
Sử dụng Client SDK Đơn giản (Được khuyến nghị)
Cách dễ nhất để bắt đầu là sử dụng lớp Client, cung cấp một API đơn giản và trực quan cho việc dịch thuật:
from docutranslate.sdk import Client
# Khởi tạo client với cài đặt nền tảng AI của bạn
client = Client(
api_key="YOUR_OPENAI_API_KEY", # hoặc bất kỳ API key nền tảng AI nào khác
base_url="https://api.openai.com/v1/",
model_id="gpt-4o",
to_lang="Chinese", # Ngôn ngữ đích
concurrent=10, # Số lượng yêu cầu đồng thời
)
# Ví dụ 1: Dịch các tệp văn bản thuần túy (không cần công cụ phân tích PDF)
result = client.translate("path/to/your/document.txt")
print(f"Dịch hoàn tất! Đã lưu tại: {result.save()}")
# Ví dụ 2: Dịch tệp PDF (yêu cầu mineru_token hoặc triển khai cục bộ)
# Tùy chọn A: Sử dụng MinerU online (yêu cầu token: https://mineru.net/apiManage/token)
result = client.translate(
"path/to/your/document.pdf",
convert_engine="mineru",
mineru_token="YOUR_MINERU_TOKEN", # Thay thế bằng MinerU Token của bạn
formula_ocr=True, # Bật nhận dạng công thức
)
result.save(fmt="html")
# Tùy chọn B: Sử dụng MinerU triển khai cục bộ (khuyên dùng cho mạng nội bộ/offline)
# Đầu tiên khởi chạy dịch vụ MinerU cục bộ, tham khảo: https://github.com/opendatalab/MinerU
result = client.translate(
"path/to/your/document.pdf",
convert_engine="mineru_deploy",
mineru_deploy_base_url="http://127.0.0.1:8000", # Địa chỉ MinerU cục bộ của bạn
mineru_deploy_backend="hybrid-auto-engine", # Loại backend
)
result.save(fmt="markdown")
# Ví dụ 3: Dịch tệp Docx (giữ nguyên định dạng)
result = client.translate(
"path/to/your/document.docx",
insert_mode="replace", # replace (thay thế)/append (thêm vào sau)/prepend (thêm vào trước)
)
result.save(fmt="docx") # Lưu dưới định dạng docx
# Ví dụ 4: Xuất dưới dạng chuỗi mã hóa base64 (để truyền qua API)
base64_content = result.export(fmt="html")
print(f"Độ dài nội dung đã xuất: {len(base64_content)}")
# Bạn cũng có thể truy cập workflow bên dưới để thực hiện các thao tác nâng cao
# workflow = result.workflow
Các tính năng của Client:
- Tự động phát hiện: Tự động phát hiện loại tệp và chọn workflow phù hợp
- Cấu hình linh hoạt: Ghi đè bất kỳ cài đặt mặc định nào cho mỗi lần gọi dịch
- Nhiều tùy chọn đầu ra: Lưu vào đĩa hoặc xuất dưới dạng chuỗi Base64
- Hỗ trợ Bất đồng bộ: Sử dụng
translate_async()cho các tác vụ dịch đồng thời
Tham số Client SDK
| Tham số | Loại | Mặc định | Mô tả |
|---|---|---|---|
| api_key | str |
- | API key nền tảng AI |
| base_url | str |
- | Base URL nền tảng AI (ví dụ: https://api.openai.com/v1/) |
| model_id | str |
- | ID Model sử dụng để dịch |
| to_lang | str |
- | Ngôn ngữ đích (ví dụ: "Chinese", "English", "Japanese") |
| concurrent | int |
10 | Số lượng yêu cầu LLM đồng thời |
| convert_engine | str |
"mineru" |
Công cụ phân tích PDF: "mineru", "docling", "mineru_deploy" |
| mineru_deploy_base_url | str |
- | Địa chỉ API minerU cục bộ (khi dùng convert_engine="mineru_deploy") |
| mineru_deploy_parse_method | str |
"auto" |
Phương pháp phân tích minerU cục bộ: "auto", "txt", "ocr" |
| mineru_deploy_table_enable | bool |
True |
Bật nhận dạng bảng cho minerU cục bộ |
| mineru_token | str |
- | Token API minerU (khi sử dụng minerU online) |
| skip_translate | bool |
False |
Bỏ qua dịch thuật, chỉ phân tích tài liệu |
| output_dir | str |
"./output" |
Thư mục đầu ra mặc định cho save() |
| chunk_size | int |
3000 | Kích thước đoạn văn bản (chunk) để LLM xử lý |
| temperature | float |
0.3 | Tham số temperature của LLM |
| timeout | int |
60 | Thời gian chờ yêu cầu tính bằng giây |
| retry | int |
3 | Số lần thử lại khi thất bại |
| provider | str |
"auto" |
Loại nhà cung cấp AI (auto, openai, azure, v.v.) |
| force_json | bool |
False |
Bắt buộc chế độ đầu ra JSON |
| rpm | int |
- | Giới hạn số yêu cầu mỗi phút |
| tpm | int |
- | Giới hạn số token mỗi phút |
Các phương thức Kết quả (Result Methods)
| Phương thức | Tham số | Mô tả |
|---|---|---|
| save() | output_dir, name, fmt |
Lưu kết quả dịch vào đĩa |
| export() | fmt |
Xuất dưới dạng chuỗi mã hóa Base64 |
| supported_formats | - | Lấy danh sách các định dạng đầu ra được hỗ trợ |
| workflow | - | Truy cập đối tượng workflow bên dưới |
import asyncio
from docutranslate.sdk import Client
async def translate_multiple():
client = Client(
api_key="YOUR_API_KEY",
base_url="https://api.openai.com/v1/",
model_id="gpt-4o",
to_lang="Chinese",
)
# Dịch nhiều file đồng thời
files = ["doc1.pdf", "doc2.docx", "notes.txt"]
results = await asyncio.gather(
*[client.translate_async(f) for f in files]
)
for r in results:
print(f"Đã lưu: {r.save()}")
asyncio.run(translate_multiple())
Sử dụng Workflow API (Để Kiểm soát Nâng cao)
Để kiểm soát nhiều hơn, hãy sử dụng trực tiếp Workflow API. Mỗi workflow tuân theo cùng một mẫu:
# Mẫu:
# 1. Tạo TranslatorConfig (cài đặt LLM)
# 2. Tạo WorkflowConfig (cài đặt workflow)
# 3. Tạo instance Workflow
# 4. workflow.read_path(file)
# 5. await workflow.translate_async()
# 6. workflow.save_as_*(name=...) hoặc export_to_*(...)
Các Workflow và Phương thức Đầu ra có sẵn
| Workflow | Đầu vào | save_as_* | export_to_* | Các tùy chọn Config chính |
|---|---|---|---|---|
| MarkdownBasedWorkflow | .pdf, .docx, .md, .png, .jpg |
html, markdown, markdown_zip |
html, markdown, markdown_zip |
convert_engine, translator_config |
| TXTWorkflow | .txt |
txt, html |
txt, html |
translator_config |
| JsonWorkflow | .json |
json, html |
json, html |
translator_config, json_paths |
| DocxWorkflow | .docx |
docx, html |
docx, html |
translator_config, insert_mode |
| XlsxWorkflow | .xlsx, .csv |
xlsx, html |
xlsx, html |
translator_config, insert_mode |
| SrtWorkflow | .srt |
srt, html |
srt, html |
translator_config |
| EpubWorkflow | .epub |
epub, html |
epub, html |
translator_config, insert_mode |
| HtmlWorkflow | .html, .htm |
html |
html |
translator_config, insert_mode |
| AssWorkflow | .ass |
ass, html |
ass, html |
translator_config |
Các Tùy chọn Cấu hình Chính
Các tùy chọn TranslatorConfig chung:
| Tùy chọn | Loại | Mặc định | Mô tả |
|---|---|---|---|
base_url |
str |
- | Base URL của nền tảng AI |
api_key |
str |
- | API key của nền tảng AI |
model_id |
str |
- | ID Model |
to_lang |
str |
- | Ngôn ngữ đích |
chunk_size |
int |
3000 | Kích thước đoạn văn bản (chunk) |
concurrent |
int |
10 | Số lượng yêu cầu đồng thời |
temperature |
float |
0.3 | Nhiệt độ LLM |
timeout |
int |
60 | Thời gian chờ yêu cầu (giây) |
retry |
int |
3 | Số lần thử lại |
Các tùy chọn Dành riêng cho Định dạng:
| Tùy chọn | Các Workflow áp dụng | Mô tả |
|---|---|---|
insert_mode |
Docx, Xlsx, Html, Epub | "replace" (mặc định), "append", "prepend" |
json_paths |
Json | Biểu thức JSONPath (ví dụ: ["$.*", "$.name"]) |
separator |
Docx, Xlsx, Html, Epub | Dấu phân cách văn bản cho các chế độ "append" / "prepend" |
convert_engine |
MarkdownBased | "mineru" (mặc định), "docling", "mineru_deploy" |
Ví dụ 1: Dịch một tệp PDF (Sử dụng MarkdownBasedWorkflow)
Đây là trường hợp sử dụng phổ biến nhất. Chúng tôi sẽ sử dụng engine mineru để chuyển đổi PDF sang Markdown, và sau đó dịch nó bằng LLM. Ví dụ này sử dụng thực thi bất đồng bộ.
import asyncio
from docutranslate.workflow.md_based_workflow import MarkdownBasedWorkflow, MarkdownBasedWorkflowConfig
from docutranslate.converter.x2md.converter_mineru import ConverterMineruConfig
from docutranslate.translator.ai_translator.md_translator import MDTranslatorConfig
from docutranslate.exporter.md.md2html_exporter import MD2HTMLExporterConfig
async def main():
# 1. Xây dựng Cấu hình Translator
translator_config = MDTranslatorConfig(
base_url="https://open.bigmodel.cn/api/paas/v4", # Base URL Nền tảng AI
api_key="YOUR_ZHIPU_API_KEY", # API Key Nền tảng AI
model_id="glm-4-air", # ID Model
to_lang="English", # Ngôn ngữ đích
chunk_size=3000, # Kích thước đoạn văn bản
concurrent=10, # Mức độ đồng thời
# glossary_generate_enable=True, # Bật tự động tạo thuật ngữ
# glossary_dict={"Jobs":"Steve Jobs"}, # Truyền vào từ điển thuật ngữ
# system_proxy_enable=True, # Bật proxy hệ thống
)
# 2. Xây dựng Cấu hình Converter (Sử dụng minerU)
converter_config = ConverterMineruConfig(
mineru_token="YOUR_MINERU_TOKEN", # MinerU Token của bạn
formula_ocr=True # Bật nhận dạng công thức
)
# 3. Xây dựng Cấu hình Workflow Chính
workflow_config = MarkdownBasedWorkflowConfig(
convert_engine="mineru", # Chỉ định engine phân tích
converter_config=converter_config, # Truyền cấu hình converter
translator_config=translator_config, # Truyền cấu hình translator
html_exporter_config=MD2HTMLExporterConfig(cdn=True) # Cấu hình xuất HTML
)
# 4. Khởi tạo Workflow
workflow = MarkdownBasedWorkflow(config=workflow_config)
# 5. Đọc file và thực thi dịch thuật
print("Đang bắt đầu đọc và dịch file...")
workflow.read_path("path/to/your/document.pdf")
await workflow.translate_async()
# Hoặc sử dụng phương thức đồng bộ
# workflow.translate()
print("Dịch hoàn tất!")
# 6. Lưu kết quả
workflow.save_as_html(name="translated_document.html")
workflow.save_as_markdown_zip(name="translated_document.zip")
workflow.save_as_markdown(name="translated_document.md") # Markdown với hình ảnh được nhúng
print("Các file đã được lưu vào thư mục ./output.")
# Hoặc lấy trực tiếp chuỗi nội dung
html_content = workflow.export_to_html()
html_content = workflow.export_to_markdown()
# print(html_content)
if __name__ == "__main__":
asyncio.run(main())
Các Workflow khác
Tất cả các workflow đều tuân theo cùng một mẫu. Import config và workflow tương ứng, sau đó cấu hình:
# TXT: from docutranslate.workflow.txt_workflow import TXTWorkflow, TXTWorkflowConfig
# JSON: from docutranslate.workflow.json_workflow import JsonWorkflow, JsonWorkflowConfig
# DOCX: from docutranslate.workflow.docx_workflow import DocxWorkflow, DocxWorkflowConfig
# XLSX: from docutranslate.workflow.xlsx_workflow import XlsxWorkflow, XlsxWorkflowConfig
# EPUB: from docutranslate.workflow.epub_workflow import EpubWorkflow, EpubWorkflowConfig
# HTML: from docutranslate.workflow.html_workflow import HtmlWorkflow, HtmlWorkflowConfig
# SRT: from docutranslate.workflow.srt_workflow import SrtWorkflow, SrtWorkflowConfig
# ASS: from docutranslate.workflow.ass_workflow import AssWorkflow, AssWorkflowConfig
Các tùy chọn config chính:
- insert_mode:
"replace","append", hoặc"prepend"(cho docx/xlsx/html/epub) - json_paths: Biểu thức JSONPath cho dịch thuật JSON (ví dụ:
["$.*", "$.name"]) - separator: Dấu phân cách văn bản cho các chế độ
"append"/"prepend"
Điều kiện tiên quyết và Cấu hình chi tiết
1. Lấy API Key Mô hình Lớn
Chức năng dịch thuật dựa vào các Mô hình Ngôn ngữ Lớn (LLM). Bạn cần lấy base_url, api_key, và model_id từ nền tảng AI tương ứng.
Các model được khuyến nghị:
doubao-seed-1-6-flashcủa Volcengine, dòngdoubao-seed-1-6,glm-4-flashcủa Zhipu,qwen-plus,qwen-flashcủa Alibaba Cloud,deepseek-chatcủa Deepseek, v.v.
302.AI 👈 Đăng ký qua link này để nhận $1 tín dụng miễn phí.
| Tên Nền tảng | Lấy API Key | Base URL |
|---|---|---|
| ollama | http://127.0.0.1:11434/v1 | |
| lm studio | http://127.0.0.1:1234/v1 | |
| 302.AI | Nhấn để lấy | https://api.302.ai/v1 |
| openrouter | Nhấn để lấy | https://openrouter.ai/api/v1 |
| openai | Nhấn để lấy | https://api.openai.com/v1/ |
| gemini | Nhấn để lấy | https://generativelanguage.googleapis.com/v1beta/openai/ |
| deepseek | Nhấn để lấy | https://api.deepseek.com/v1 |
| Zhipu AI | Nhấn để lấy | https://open.bigmodel.cn/api/paas/v4 |
| Tencent Hunyuan | Nhấn để lấy | https://api.hunyuan.cloud.tencent.com/v1 |
| Alibaba Bailian | Nhấn để lấy | https://dashscope.aliyuncs.com/compatible-mode/v1 |
| Volcengine | Nhấn để lấy | https://ark.cn-beijing.volces.com/api/v3 |
| SiliconFlow | Nhấn để lấy | https://api.siliconflow.cn/v1 |
| DMXAPI | Nhấn để lấy | https://www.dmxapi.cn/v1 |
| Juguang AI | Nhấn để lấy | https://ai.juguang.chat/v1 |
2. Công cụ Phân tích PDF (Bỏ qua nếu bạn không cần dịch PDF)
2.1 Lấy Token minerU (Phân tích PDF Online, Miễn phí, Được khuyến nghị)
Nếu bạn chọn mineru làm engine phân tích tài liệu (convert_engine="mineru"), bạn cần đăng ký nhận Token miễn phí.
- Truy cập Trang web minerU để đăng ký và nộp đơn xin API.
- Tạo API Token mới trong Giao diện Quản lý API Token.
Lưu ý: Token minerU có giá trị trong 14 ngày. Vui lòng tạo lại sau khi hết hạn.
2.2. Cấu hình Engine docling (Phân tích PDF Cục bộ)
Nếu bạn chọn docling làm engine phân tích tài liệu (convert_engine="docling"), nó sẽ tải xuống các model cần thiết từ Hugging Face trong lần sử dụng đầu tiên.
Một lựa chọn tốt hơn là tải xuống
docling_artifact.ziptừ GitHub Releases và giải nén nó vào thư mục làm việc của bạn.
Giải pháp cho Vấn đề Mạng khi Tải Model docling:
- Thiết lập Hugging Face Mirror (Được khuyến nghị):
- Phương pháp A (Biến môi trường): Đặt biến môi trường hệ thống
HF_ENDPOINTvà khởi động lại IDE hoặc terminal của bạn.
HF_ENDPOINT=https://hf-mirror.com
- Phương pháp B (Trong Code): Thêm đoạn mã sau vào đầu tập lệnh Python của bạn.
import os
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'
- Sử dụng Offline (Tải trước Gói Model):
- Tải xuống
docling_artifact.ziptừ GitHub Releases. - Giải nén nó vào thư mục dự án của bạn.
- Chỉ định đường dẫn model trong cấu hình (nếu model không nằm trong cùng thư mục với tập lệnh):
from docutranslate.converter.x2md.converter_docling import ConverterDoclingConfig
converter_config = ConverterDoclingConfig(
artifact="./docling_artifact", # Trỏ đến thư mục đã giải nén
code_ocr=True,
formula_ocr=True
)
2.3. Dịch vụ MinerU Triển khai Cục bộ
Đối với môi trường offline/mạng nội bộ, hãy triển khai minerU cục bộ với API được kích hoạt. Đặt mineru_deploy_base_url thành endpoint API minerU của bạn.
Client SDK:
from docutranslate.sdk import Client
client = Client(
api_key="YOUR_LLM_API_KEY",
model_id="llama3",
to_lang="Chinese",
convert_engine="mineru_deploy",
mineru_deploy_base_url="http://127.0.0.1:8000", # Địa chỉ API minerU của bạn
)
result = client.translate("document.pdf")
result.save(fmt="markdown")
Câu hỏi thường gặp (FAQ)
H: Đầu ra vẫn là ngôn ngữ gốc? Đ: Kiểm tra nhật ký (logs) để tìm lỗi. Thường là do hết tín dụng API hoặc vấn đề mạng.
H: Cổng 8010 bị chiếm dụng?
Đ: Sử dụng docutranslate -i -p 8011 hoặc thiết lập DOCUTRANSLATE_PORT=8011.
H: PDF scan có được hỗ trợ không?
Đ: Có, sử dụng engine mineru với khả năng OCR.
H: Dịch PDF lần đầu tiên rất chậm?
Đ: docling cần tải xuống các model trong lần chạy đầu tiên. Hãy sử dụng Hugging Face mirror hoặc tải trước gói artifact.
H: Sử dụng trong mạng nội bộ/offline được không? Đ: Có. Sử dụng LLM cục bộ (Ollama/LM Studio) và minerU hoặc docling cục bộ.
H: Cơ chế cache PDF?
Đ: MarkdownBasedWorkflow lưu trữ kết quả phân tích trong bộ nhớ (10 lần phân tích gần nhất). Cấu hình qua DOCUTRANSLATE_CACHE_NUM.
H: Bật proxy?
Đ: Thiết lập system_proxy_enable=True trong TranslatorConfig.
Lịch sử Sao
Hỗ trợ Quyên góp
Hoan nghênh ủng hộ tác giả. Vui lòng ghi rõ lý do quyên góp trong phần bình luận!




