Traduza PDFs com o BabelDOC em uma base URL OpenAI personalizada.

Resposta rápida: três flags roteiam toda chamada de tradução.

A linha de comando do BabelDOC recebe o endpoint diretamente: --openai habilita o tradutor de LLM, --openai-base-url define para onde as requisições vão, --openai-api-key autentica, e --openai-model escolhe o id do modelo. Os próprios exemplos do README mostram exatamente esse conjunto de flags, e a nota do serviço de tradução afirma que só LLMs compatíveis com OpenAI são suportados, o que faz de um gateway multi-fornecedor compatível com OpenAI o ajuste natural em vez de um workaround. Como o id do modelo é encaminhado como uma string simples, qualquer coisa que o endpoint sirva funciona: os próprios documentos upstream recomendam modelos amigáveis a compatibilidade OpenAI das famílias GLM e DeepSeek, e através da APIsRouter esses ficam ao lado de ids Claude e Gemini atrás da mesma 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"

Como o BabelDOC transforma um PDF em chamadas de modelo.

O BabelDOC (funstory-ai no GitHub, cerca de 9 mil estrelas, do time por trás do Immersive Translate) é um tradutor de documentos PDF que preserva o layout: ele analisa a estrutura do documento, protege fórmulas e figuras, encontra parágrafos, os traduz com um LLM, e reconstrói o PDF como uma versão mono traduzida e uma versão dual lado a lado. Ele vem como uma CLI e uma API Python, e é a contraparte auto-hospedada do serviço BabelDOC hospedado. A fase de tradução é onde o endpoint importa. Um documento vira muitas requisições chat-completions do tamanho de um parágrafo, limitadas pela flag --qps (padrão 4 consultas por segundo) e processadas por um pool de workers (pool-max-workers, com padrão no valor de QPS). Esse formato tem duas consequências. Primeiro, tradução é uma carga de volume: um PDF longo são centenas de chamadas pequenas, então o preço por token se acumula rápido. Segundo, ao contrário de cargas de recuperação onde o modelo majoritariamente lê, tradução escreve aproximadamente tanto quanto lê, então o preço de token de saída importa tanto quanto o preço de entrada quando você compara ids. O BabelDOC também faz cache das traduções, então rodar um documento novamente reutiliza resultados anteriores a menos que você passe --ignore-cache. CSVs de glossário (--glossary-files) fixam terminologia ao longo da execução, e --max-pages-per-part divide documentos muito grandes em partes que são traduzidas e mescladas automaticamente.

Configuração completa: flags de CLI ou o arquivo de config TOML.

Para uso repetido, as mesmas configurações vivem em um arquivo TOML passado com --config. A tabela [babeldoc] aceita as mesmas chaves em kebab-case: openai, openai-model, openai-base-url, openai-api-key, mais as opções de throughput e saída. Isso mantém a chave fora do histórico do seu shell e torna um perfil de tradução reproduzível entre documentos. A config abaixo é um perfil prático de volume: um id rápido para o grosso dos documentos, QPS elevado para combinar com um gateway com pool, e ambos os modos de saída mantidos. Troque openai-model para um id mais forte em documentos onde nuance importa mais que throughput.

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

# Serviço de tradução
openai = true
openai-model = "deepseek-v4-flash"
openai-base-url = "https://api.apisrouter.com/v1"
openai-api-key = "sk-YOUR-APISROUTER-KEY"

# Controle de saída
no-dual = false
no-mono = false
watermark-output-mode = "no_watermark"

Escolhendo um modelo de tradução.

O fluxo de comparação é concreto: traduza as mesmas dez páginas com dois ids (o cache com chave por execução os mantém separados), leia os duais lado a lado, e verifique o log de uso por chave para o que cada passada custou. A maioria dos times chega a um padrão rápido mais um perfil premium para documentos que merecem, ambos como arquivos TOML.

• Documentos de volume (manuais, papers lidos uma vez) combinam com deepseek-v4-flash: a qualidade de tradução se mantém para prosa técnica e o custo por página é próximo de desprezível.
• Tradução com alvo em chinês é um jogo em casa para glm-5.2 e a família DeepSeek; os próprios documentos upstream apontam para modelos GLM e DeepSeek como escolhas bem-comportadas compatíveis com OpenAI.
• Documentos onde nuance é crítica (contratos, traduções publicadas) justificam claude-sonnet-4-6 ou claude-haiku-4-5-20251001, que acompanham terminologia e registro de forma mais fiel ao longo de documentos longos.
• Tokens de saída importam aqui. Tradução escreve tanto quanto lê, então compare ids também na coluna de preço de saída, não só na de entrada.
• Combine glossários com ids rápidos. Um CSV de glossário fixa a terminologia da qual modelos rápidos ocasionalmente se desviam, o que fecha boa parte da lacuna de qualidade em texto técnico.

Pague pelo uso · abaixo do preço oficial

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

Modos de falha e ajuste de throughput.

QPS é o botão que interage com o gateway. O padrão de 4 consultas por segundo é conservador; capacidade upstream com pool geralmente sustenta mais, e elevar --qps (com pool-max-workers o acompanhando) é como um documento de 300 páginas para de tomar a tarde inteira. Aumente gradualmente observando respostas 429 em vez de pular para um número grande a frio, porque um parágrafo com rate limit tenta de novo e desacelera a execução inteira. As flags só se aplicam quando --openai está definido. Passar uma base URL sem --openai deixa o tradutor desabilitado, o que aparece como uma execução que analisa o PDF mas nunca traduz. Ids de modelo são strings exatas contra a listagem /v1/models do endpoint; um erro de digitação falha a primeira chamada de parágrafo com model-not-found. Um 401 significa que a chave e a base URL não pertencem juntas. Problemas de layout não são problemas de endpoint. Texto sobreposto, fórmulas perdidas, ou tabelas quebradas remetem ao lado de análise do PDF (tente --enhance-compatibility, --ocr-workaround para documentos escaneados, ou o toggle de rich-text), e trocar de modelo não vai corrigi-los. O inverso também vale: terminologia mal traduzida é um problema de modelo ou glossário, não de parser. O cache pode mascarar mudanças. Depois de trocar de modelo, passe --ignore-cache se você quiser que o novo id retraduza conteúdo que o id antigo já cobriu; caso contrário, parágrafos em cache permanecem como estavam.

Quem roteia o BabelDOC por um gateway.

• Pesquisadores traduzindo papers em massa, onde centenas de chamadas pequenas por documento tornam preço de volume e visibilidade de uso por chave o jogo inteiro.
• Times padronizando documentação bilíngue, rodando um perfil padrão rápido e um perfil premium contra o mesmo endpoint com strings de modelo diferentes.
• Usuários em mercados onde os modelos de tradução mais fortes para seu par de idiomas ficam com fornecedores diferentes: ids GLM, DeepSeek, Claude, e Gemini todos atrás de uma chave.
• Self-hosters substituindo o serviço hospedado para documentos confidenciais, mantendo a análise local e enviando só o texto de parágrafo para um endpoint auditável.
• Desenvolvedores sem acesso ao faturamento de um determinado fornecedor. O acesso baseado em recarga sem exigência de cartão remove a dependência de cadastro por provedor.

Verifique o endpoint e depure o primeiro documento.

Liste os modelos que sua chave pode endereçar antes de iniciar uma execução longa; --openai-model precisa corresponder a um id servido exatamente. Depois traduza algo pequeno (um PDF de uma página, ou --pages 1 num maior) do início ao fim. Um 401 no primeiro parágrafo significa que a chave não bate com a base URL. Model-not-found é um erro de digitação no id. Uma execução que analisa mas nunca chama o endpoint está sem --openai. Travamentos frequentes com mensagens de nova tentativa apontam para QPS definido mais alto do que o endpoint sustenta; abaixe e aumente gradualmente de novo. Assim que os documentos fluem, o console da APIsRouter mostra modelo, contagens de token e gasto por requisição. O custo de tradução escala com o comprimento do documento nas duas direções (entrada e saída), e o log de uso por chave é como você aprende seu custo real por página para cada modelo em vez de estimá-lo.

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

# depois um teste de fumaça de uma página
babeldoc --config babeldoc.toml --files sample.pdf --pages 1

Perguntas frequentes