Dịch PDF bằng BabelDOC trên một base URL OpenAI tùy chỉnh.

Câu trả lời nhanh: ba flag định tuyến mọi lệnh gọi dịch.

Dòng lệnh của BabelDOC nhận endpoint trực tiếp: --openai bật bộ dịch LLM, --openai-base-url đặt nơi request đi tới, --openai-api-key xác thực, và --openai-model chọn id model. Các ví dụ trong README chính là bộ flag này, và ghi chú về translation-service của nó nói rõ chỉ các LLM tương thích OpenAI được hỗ trợ, điều này khiến một gateway tương thích OpenAI đa vendor trở thành lựa chọn tự nhiên chứ không phải một cách vòng. Vì id model được chuyển tiếp dưới dạng một chuỗi trơn, bất cứ gì endpoint phục vụ đều hoạt động: chính tài liệu upstream khuyên dùng các model thân thiện tương thích OpenAI từ họ GLM và DeepSeek, và qua APIsRouter chúng nằm cạnh các id Claude và Gemini sau cùng một base URL.

babeldoc --files paper.pdf \
  --lang-in en --lang-out zh \
  --openai \
  --openai-model "deepseek-v4-flash" \
  --openai-base-url "https://api.apisrouter.com/v1" \
  --openai-api-key "$APISROUTER_API_KEY"

Cách BabelDOC biến một PDF thành các lệnh gọi model.

BabelDOC (funstory-ai trên GitHub, khoảng 9K star, từ đội đứng sau Immersive Translate) là một bộ dịch tài liệu PDF giữ nguyên bố cục: nó phân tích cấu trúc tài liệu, bảo vệ công thức và hình ảnh, tìm các đoạn văn, dịch chúng bằng một LLM, và dựng lại PDF thành một bản dịch đơn ngữ và một bản song ngữ đối chiếu. Nó xuất bản dưới dạng một CLI và một Python API, và là phiên bản tự host tương ứng của dịch vụ BabelDOC được lưu trữ. Giai đoạn dịch là nơi endpoint quan trọng. Một tài liệu trở thành rất nhiều request chat-completions cỡ đoạn văn, được điều tiết bởi flag --qps (mặc định 4 truy vấn mỗi giây) và xử lý bởi một pool worker (pool-max-workers, mặc định bằng giá trị QPS). Hình dạng đó có hai hệ quả. Thứ nhất, dịch thuật là một khối lượng công việc: một PDF dài là hàng trăm lệnh gọi nhỏ, nên giá theo từng token cộng dồn nhanh. Thứ hai, khác với các khối lượng công việc truy xuất nơi model chủ yếu đọc, dịch thuật viết ra gần bằng lượng nó đọc vào, nên giá token đầu ra quan trọng ngang giá đầu vào khi bạn so sánh các id. BabelDOC cũng cache các bản dịch, nên chạy lại một tài liệu tái sử dụng kết quả trước đó trừ khi bạn truyền --ignore-cache. Các file CSV thuật ngữ (--glossary-files) ghim thuật ngữ xuyên suốt lần chạy, và --max-pages-per-part chia các tài liệu rất lớn thành các phần được dịch và ghép lại tự động.

Cài đặt đầy đủ: flag CLI hoặc file cấu hình TOML.

Để dùng lặp lại, cùng các cài đặt sống trong một file TOML truyền qua --config. Bảng [babeldoc] chấp nhận đúng các khóa đó ở dạng kebab-case: openai, openai-model, openai-base-url, openai-api-key, cộng các tùy chọn thông lượng và đầu ra. Điều này giữ key ngoài lịch sử shell của bạn và khiến một profile dịch có thể tái tạo qua nhiều tài liệu. Cấu hình dưới đây là một profile khối lượng thực tế: một id nhanh cho phần lớn tài liệu, QPS nâng lên để khớp với một gateway pooled, và giữ cả hai chế độ đầu ra. Đổi openai-model sang một id mạnh hơn cho các tài liệu nơi sắc thái quan trọng hơn thông lượng.

[babeldoc]
lang-in = "en-US"
lang-out = "zh-CN"
qps = 10
pool-max-workers = 10

# Translation service
openai = true
openai-model = "deepseek-v4-flash"
openai-base-url = "https://api.apisrouter.com/v1"
openai-api-key = "sk-YOUR-APISROUTER-KEY"

# Output control
no-dual = false
no-mono = false
watermark-output-mode = "no_watermark"

Chọn model dịch.

Quy trình so sánh rất cụ thể: dịch cùng mười trang bằng hai id (cache theo từng lần chạy giữ chúng tách biệt), đọc các bản song ngữ cạnh nhau, và kiểm tra log sử dụng theo từng key xem mỗi lượt tốn bao nhiêu. Hầu hết các đội chốt một mặc định nhanh cộng một profile cao cấp cho các tài liệu xứng đáng, cả hai đều là file TOML.

• Tài liệu khối lượng lớn (sổ tay hướng dẫn, bài báo đọc một lần) hợp với deepseek-v4-flash: chất lượng dịch giữ vững cho văn xuôi kỹ thuật và chi phí mỗi trang gần như không đáng kể.
• Dịch sang tiếng Trung là sân nhà của glm-5.2 và họ DeepSeek; chính tài liệu upstream chỉ đến các model GLM và DeepSeek như những lựa chọn tương thích OpenAI hoạt động tốt.
• Tài liệu cần sắc thái (hợp đồng, bản dịch xuất bản) xứng đáng với claude-sonnet-4-6 hoặc claude-haiku-4-5-20251001, thứ theo sát thuật ngữ và văn phong trung thực hơn qua các tài liệu dài.
• Token đầu ra quan trọng ở đây. Dịch thuật viết ra gần bằng lượng nó đọc vào, nên so sánh các id trên cả cột giá đầu ra, không chỉ đầu vào.
• Ghép danh sách thuật ngữ với các id nhanh. Một CSV thuật ngữ ghim những thuật ngữ mà model nhanh thỉnh thoảng trôi dạt, điều này đóng phần lớn khoảng cách chất lượng trên văn bản kỹ thuật.

Trả theo mức sử dụng · thấp hơn giá chính thức

Selected models are priced below official list prices. Exact input, output, cache, and per-request prices are shown for each model.

Các kiểu lỗi và tinh chỉnh thông lượng.

QPS là núm tương tác với gateway. Mặc định 4 truy vấn mỗi giây là thận trọng; năng lực upstream pooled thường chịu được nhiều hơn, và nâng --qps (với pool-max-workers theo sau nó) là cách một tài liệu 300 trang ngừng chiếm cả buổi chiều. Tăng dần trong khi theo dõi các phản hồi 429 thay vì nhảy thẳng lên một con số lớn, vì một đoạn văn bị giới hạn tốc độ sẽ thử lại và làm chậm cả lần chạy. Các flag chỉ áp dụng khi --openai được đặt. Truyền một base URL mà không có --openai để bộ dịch bị vô hiệu hóa, biểu hiện thành một lần chạy phân tích PDF nhưng không bao giờ dịch. Id model là các chuỗi chính xác đối chiếu với danh sách /v1/models của endpoint; một lỗi gõ sai khiến lệnh gọi đoạn văn đầu tiên thất bại với model-not-found. Một lỗi 401 nghĩa là key và base URL không thuộc về nhau. Vấn đề bố cục không phải vấn đề endpoint. Văn bản chồng lấn, công thức bị mất, hoặc bảng bị vỡ bắt nguồn từ phía phân tích PDF (thử --enhance-compatibility, --ocr-workaround cho tài liệu quét, hoặc toggle rich-text), và đổi model sẽ không sửa được chúng. Điều ngược lại cũng đúng: thuật ngữ dịch sai là vấn đề model hoặc glossary, không phải vấn đề parser. Cache có thể che giấu các thay đổi. Sau khi đổi model, truyền --ignore-cache nếu bạn muốn id mới dịch lại nội dung id cũ đã bao phủ; nếu không, các đoạn văn đã cache giữ nguyên như cũ.

Ai định tuyến BabelDOC qua một gateway.

• Nhà nghiên cứu dịch bài báo hàng loạt, nơi hàng trăm lệnh gọi nhỏ mỗi tài liệu khiến giá theo khối lượng và khả năng quan sát sử dụng theo từng key là toàn bộ cuộc chơi.
• Đội chuẩn hóa tài liệu song ngữ, chạy một profile mặc định nhanh và một profile cao cấp trên cùng endpoint với các chuỗi model khác nhau.
• Người dùng ở các thị trường nơi các model dịch mạnh nhất cho cặp ngôn ngữ của họ nằm ở các vendor khác nhau: id GLM, DeepSeek, Claude, và Gemini đều đằng sau một key.
• Người tự host thay thế dịch vụ được lưu trữ cho tài liệu bảo mật, giữ việc phân tích cục bộ và chỉ gửi văn bản đoạn văn tới một endpoint có thể kiểm toán.
• Lập trình viên không có quyền truy cập billing của một vendor cụ thể. Truy cập dựa trên nạp tiền không yêu cầu thẻ loại bỏ phụ thuộc đăng ký theo từng provider.

Xác minh endpoint và debug tài liệu đầu tiên.

Liệt kê các model key của bạn có thể gọi được trước khi bắt đầu một lần chạy dài; --openai-model phải khớp chính xác một id đã phục vụ. Sau đó dịch thứ gì đó nhỏ (một PDF một trang, hoặc --pages 1 trên một file lớn hơn) từ đầu tới cuối. Một lỗi 401 trên đoạn văn đầu tiên nghĩa là key không khớp với base URL. Model-not-found là một id gõ sai. Một lần chạy phân tích nhưng không bao giờ gọi endpoint là thiếu --openai. Các lần đình trệ thường xuyên kèm thông báo thử lại chỉ tới QPS đặt cao hơn mức endpoint chịu được; hạ xuống rồi tăng dần trở lại. Khi tài liệu chảy qua, console APIsRouter hiển thị model theo từng request, số lượng token, và chi tiêu. Chi phí dịch tăng theo độ dài tài liệu ở cả hai chiều (đầu vào và đầu ra), và log sử dụng theo từng key là cách bạn học được chi phí thực tế mỗi trang cho từng model thay vì ước lượng nó.

curl -s https://api.apisrouter.com/v1/models \
  -H "Authorization: Bearer $APISROUTER_API_KEY" | head -50

# then a one-page smoke test
babeldoc --config babeldoc.toml --files sample.pdf --pages 1

Câu hỏi thường gặp