BabelDOC で、カスタムの OpenAI ベース URL を使って PDF を翻訳する。

早わかり: 3つのフラグですべての翻訳呼び出しをルーティングする。

BabelDOC のコマンドラインは、エンドポイントを直接受け取ります。--openai は LLM 翻訳エンジンを有効にし、--openai-base-url はリクエストの送り先を設定し、--openai-api-key が認証を行い、--openai-model がモデル id を選びます。README 自身のサンプルがまさにこのフラグの組み合わせを示しており、翻訳サービスに関する注記は、サポートされているのは OpenAI 互換の LLM だけだと述べています。これは、マルチベンダーの OpenAI 互換ゲートウェイを、回避策ではなく自然な適合先にしています。 モデル id はそのままの文字列として転送されるため、エンドポイントが提供するものなら何でも動作します。upstream のドキュメント自体が、GLM や DeepSeek ファミリーの OpenAI 互換に相性の良いモデルを推奨しており、APIsRouter を通じてそれらは、同じベース URL の裏で Claude や Gemini の id と並びます。

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"

BabelDOC が、PDF をどうモデル呼び出しに変換するか。

BabelDOC(GitHub 上では funstory-ai、スター数はおよそ9K、Immersive Translate の開発チームによるもの)は、レイアウトを保持する PDF 文書翻訳ツールです。文書構造を解析し、数式や図を保護し、段落を見つけ、LLM でそれらを翻訳し、翻訳済みのモノ版と対訳の両方のバージョンとして PDF を再構築します。CLI と Python API として提供され、ホスト型の BabelDOC サービスに対するセルフホスト版という位置づけです。 翻訳フェーズがエンドポイントの重要な出番です。1つの文書は、段落サイズの多数のチャット補完リクエストになり、--qps フラグ(デフォルト毎秒4クエリ)によってスロットリングされ、ワーカープール(pool-max-workers、デフォルトは QPS の値)によって処理されます。この形には2つの帰結があります。第一に、翻訳はボリュームのワークロードです。長い PDF は数百件の小さな呼び出しになるため、トークン単価が急速に積み重なります。第二に、モデルが主に読むだけの検索系ワークロードとは異なり、翻訳は読む分とほぼ同じだけ書き込むため、id を比較する際には入力価格と同じくらい出力トークンの価格も重要です。 BabelDOC は翻訳結果もキャッシュするため、--ignore-cache を渡さない限り、文書を再実行すると以前の結果が再利用されます。用語集の CSV(--glossary-files)は実行全体で用語を固定し、--max-pages-per-part は非常に大きな文書を、自動で翻訳・統合される複数の部分に分割します。

フルセットアップ: CLI フラグ、または TOML 設定ファイル。

繰り返し使う場合は、同じ設定を --config で渡す TOML ファイルに置けます。[babeldoc] テーブルは、同一のキーをケバブケースで受け付けます。openai、openai-model、openai-base-url、openai-api-key に加え、スループットと出力のオプションです。これでキーがシェル履歴に残らず、翻訳プロファイルを文書間で再現可能にできます。 以下の設定は、実用的なボリューム向けプロファイルです。大量の文書向けに速い id を使い、プールされたゲートウェイに合わせて QPS を引き上げ、両方の出力モードを維持しています。ニュアンスがスループットより重要な文書では、openai-model をより強力な id に切り替えてください。

[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"

翻訳モデルを選ぶ。

比較のワークフローは具体的です。同じ10ページを2つの id で翻訳し(実行ごとにキー付けされたキャッシュが両者を分けてくれます)、対訳を並べて読み、キーごとの利用ログでそれぞれの実行にかかったコストを確認してください。多くのチームは、速いデフォルトと、それに値する文書向けのプレミアムプロファイルの両方に落ち着きます。どちらも TOML ファイルとして。

• ボリューム文書(マニュアル、一度読めば十分な論文)には deepseek-v4-flash が向いています。技術文章に対する翻訳品質は保たれ、ページあたりのコストはほぼ無視できる水準です。
• 中国語向けの翻訳は glm-5.2 と DeepSeek ファミリーの得意分野です。upstream のドキュメント自体が、GLM と DeepSeek のモデルを、行儀の良い OpenAI 互換の選択肢として挙げています。
• ニュアンスが重要な文書(契約書、出版される翻訳)は claude-sonnet-4-6 や claude-haiku-4-5-20251001 に値します。長い文書全体にわたって、用語と語調をより忠実に維持します。
• 出力トークンはここで重要になります。翻訳は読む分とほぼ同じだけ書くため、入力だけでなく出力価格の列でも id を比較してください。
• 用語集は速い id と組み合わせてください。用語集の CSV は、速いモデルが時折ぶれる用語を固定し、技術文書での品質差の多くを埋めてくれます。

従量課金 · 公式価格より安い

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

失敗パターンとスループットのチューニング。

QPS は、ゲートウェイと相互作用するつまみです。デフォルトの毎秒4クエリは控えめであり、プールされた上流の容量は通常もっと多くをさばけます。--qps を(それに追従する pool-max-workers とともに)引き上げることが、300ページの文書が午後いっぱいかかるのを止める方法です。冷たく大きな数字に飛びつくのではなく、429 レスポンスを見ながら段階的に上げてください。レート制限を受けた段落はリトライし、実行全体を遅くしてしまうからです。 これらのフラグは --openai が設定されているときにのみ適用されます。--openai なしでベース URL だけを渡すと、翻訳エンジンは無効なままで、PDF は解析されるものの一切翻訳されない実行として表面化します。モデル id はエンドポイントの /v1/models 一覧に対する正確な文字列であり、タイプミスは最初の段落の呼び出しで model-not-found として失敗します。401 は、キーとベース URL が対応していないことを意味します。 レイアウトの問題はエンドポイントの問題ではありません。重なり合ったテキスト、失われた数式、壊れた表は、PDF 解析側(--enhance-compatibility、スキャン文書向けの --ocr-workaround、リッチテキストの切り替えを試してください)に起因し、モデルを切り替えても直りません。逆もまた真です。誤訳された用語はモデルか用語集の問題であり、パーサーの問題ではありません。 キャッシュは変更を覆い隠すことがあります。モデルを切り替えた後、新しい id に古い id がすでにカバーした内容を再翻訳させたい場合は --ignore-cache を渡してください。そうしないと、キャッシュされた段落はそのままです。

ゲートウェイ経由で BabelDOC を使うのは誰か。

• 論文を大量に翻訳する研究者で、文書ごとに数百件の小さな呼び出しがあるため、ボリューム価格とキーごとの利用状況の可視性がすべてを左右する人。
• バイリンガルなドキュメントを標準化するチームで、速いデフォルトプロファイルとプレミアムプロファイルを、異なるモデル文字列で同じエンドポイントに対して実行する人。
• 言語ペアにとって最も強力な翻訳モデルが異なるベンダーにある市場のユーザー。GLM・DeepSeek・Claude・Gemini の id がすべて1つのキーの裏にあります。
• 機密文書のためにホスト型サービスを自前のものに置き換えるセルフホスターで、解析をローカルに保ち、段落のテキストだけを1つの監査可能なエンドポイントに送る人。
• 特定ベンダーの請求手段にアクセスできない開発者。チャージ制でカード不要のアクセスなら、プロバイダーごとのサインアップという依存を取り除けます。

エンドポイントを検証し、最初の文書をデバッグする。

長い実行を始める前に、あなたのキーがアドレスできるモデルを一覧してください。--openai-model は、提供されている id と正確に一致していなければなりません。 次に、何か小さなもの(1ページの PDF、あるいは大きな PDF に対する --pages 1)を最初から最後まで翻訳してみてください。最初の段落での 401 は、キーがベース URL と一致していないことを意味します。model-not-found は id のタイプミスです。解析はするのに一度もエンドポイントを呼び出さない実行は、--openai が抜けています。リトライメッセージを伴う頻繁な停止は、QPS がエンドポイントの持続可能な水準より高く設定されていることを示しています。下げてから、また段階的に上げてください。 文書が流れ始めたら、APIsRouter コンソールがリクエストごとのモデル、トークン数、支出を表示します。翻訳のコストは両方向(入力と出力)で文書の長さに応じてスケールするため、キーごとの利用ログこそが、見積もるのではなく、各モデルのページあたりの実際のコストを知る方法です。

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

よくある質問