Traduci PDF con BabelDOC su un URL base OpenAI personalizzato.

Risposta rapida: tre flag instradano ogni chiamata di traduzione.

La riga di comando di BabelDOC prende l'endpoint direttamente: --openai abilita il traduttore LLM, --openai-base-url imposta dove vanno le richieste, --openai-api-key autentica, e --openai-model sceglie l'id del modello. Gli stessi esempi del README mostrano esattamente questo set di flag, e la nota sul servizio di traduzione afferma che sono supportati solo LLM compatibili OpenAI, il che rende un gateway multi-fornitore compatibile OpenAI la soluzione naturale piuttosto che un espediente. Poiché l'id del modello viene inoltrato come stringa semplice, funziona qualsiasi cosa l'endpoint serva: la documentazione stessa a monte raccomanda modelli compatibili OpenAI delle famiglie GLM e DeepSeek, e tramite APIsRouter questi siedono accanto agli id Claude e Gemini dietro lo stesso URL base.

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"

Come BabelDOC trasforma un PDF in chiamate al modello.

BabelDOC (funstory-ai su GitHub, circa 9K stelle, dal team dietro Immersive Translate) è un traduttore di documenti PDF che preserva il layout: analizza la struttura del documento, protegge formule e figure, trova i paragrafi, li traduce con un LLM, e ricostruisce il PDF come una versione mono tradotta e una versione dual affiancata. Viene distribuito come CLI e API Python, ed è la controparte self-hosted del servizio BabelDOC ospitato. La fase di traduzione è dove l'endpoint conta. Un documento diventa molte richieste chat-completions delle dimensioni di un paragrafo, limitate dal flag --qps (predefinito 4 query al secondo) ed elaborate da un pool di worker (pool-max-workers, che di default segue il valore QPS). Questa forma ha due conseguenze. Primo, la traduzione è un carico di lavoro di volume: un PDF lungo sono centinaia di piccole chiamate, quindi il prezzo per token si accumula in fretta. Secondo, a differenza dei carichi di retrieval dove il modello per lo più legge, la traduzione scrive quasi quanto legge, quindi il prezzo dei token di output conta quanto quello dell'input quando confronti gli id. BabelDOC mette anche in cache le traduzioni, quindi rieseguire un documento riusa i risultati precedenti a meno che tu non passi --ignore-cache. I CSV di glossario (--glossary-files) fissano la terminologia per tutta l'esecuzione, e --max-pages-per-part divide i documenti molto grandi in parti che vengono tradotte e unite automaticamente.

Configurazione completa: flag CLI o il file di config TOML.

Per un uso ripetuto, le stesse impostazioni vivono in un file TOML passato con --config. La tabella [babeldoc] accetta le stesse chiavi identiche in kebab-case: openai, openai-model, openai-base-url, openai-api-key, più le opzioni di throughput e output. Questo tiene la chiave fuori dalla cronologia della shell e rende un profilo di traduzione riproducibile tra i documenti. La config qui sotto è un profilo di volume pratico: un id veloce per la massa dei documenti, QPS alzato per corrispondere a un gateway pooled, ed entrambe le modalità di output mantenute. Cambia openai-model verso un id più forte per i documenti dove la sfumatura conta più del throughput.

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

Scegliere un modello di traduzione.

Il flusso di confronto è concreto: traduci le stesse dieci pagine con due id (la cache, con chiave per esecuzione, li mantiene separati), leggi i dual fianco a fianco, e controlla il log di utilizzo per chiave per cosa è costato ogni passaggio. La maggior parte dei team approda a un default veloce più un profilo premium per i documenti che lo meritano, entrambi come file TOML.

• I documenti di volume (manuali, paper letti una volta) si adattano a deepseek-v4-flash: la qualità di traduzione tiene per la prosa tecnica e il costo per pagina è vicino a trascurabile.
• La traduzione verso il cinese è terreno di casa per glm-5.2 e la famiglia DeepSeek; la documentazione a monte stessa indica modelli GLM e DeepSeek come scelte compatibili OpenAI ben educate.
• I documenti dove la sfumatura è critica (contratti, traduzioni pubblicate) giustificano claude-sonnet-4-6 o claude-haiku-4-5-20251001, che seguono terminologia e registro in modo più fedele su documenti lunghi.
• I token di output contano qui. La traduzione scrive quanto legge, quindi confronta gli id anche sulla colonna del prezzo di output, non solo sull'input.
• Abbina i glossari agli id veloci. Un CSV di glossario fissa la terminologia su cui i modelli veloci a volte derivano, il che chiude gran parte del divario di qualità sul testo tecnico.

Pagamento a consumo · sotto i prezzi ufficiali

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

Modalità di errore e tuning del throughput.

QPS è la manopola che interagisce con il gateway. Il default di 4 query al secondo è prudente; la capacità pooled a monte di solito ne sostiene di più, e alzare --qps (con pool-max-workers che lo segue) è come un documento di 300 pagine smette di richiedere tutto il pomeriggio. Aumentalo gradualmente osservando le risposte 429 piuttosto che saltare a un numero grande a freddo, perché un paragrafo limitato dal rate riprova e rallenta l'intera esecuzione. I flag si applicano solo quando --openai è impostato. Passare un URL base senza --openai lascia il traduttore disabilitato, il che si manifesta come un'esecuzione che analizza il PDF ma non traduce mai. Gli id di modello sono stringhe esatte contro l'elenco /v1/models dell'endpoint; un errore di battitura fa fallire la prima chiamata sul paragrafo con model-not-found. Un 401 significa che chiave e URL base non appartengono insieme. I problemi di layout non sono problemi di endpoint. Testo sovrapposto, formule perse, o tabelle rotte risalgono al lato dell'analisi PDF (prova --enhance-compatibility, --ocr-workaround per documenti scansionati, o il toggle rich-text), e cambiare modello non li risolverà. Vale anche il contrario: terminologia mal tradotta è un problema di modello o glossario, non del parser. La cache può mascherare i cambiamenti. Dopo aver cambiato modello, passa --ignore-cache se vuoi che il nuovo id ritraduca contenuti che il vecchio id aveva già coperto; altrimenti i paragrafi in cache restano come erano.

Chi instrada BabelDOC tramite un gateway.

• Ricercatori che traducono paper in massa, dove centinaia di piccole chiamate per documento rendono il prezzo di volume e la visibilità di utilizzo per chiave l'intera partita.
• Team che standardizzano documentazione bilingue, eseguendo un profilo veloce di default e un profilo premium contro lo stesso endpoint con stringhe di modello diverse.
• Utenti in mercati dove i modelli di traduzione più forti per la loro coppia linguistica appartengono a fornitori diversi: id GLM, DeepSeek, Claude e Gemini tutti dietro una chiave.
• Self-hoster che sostituiscono il servizio ospitato per documenti riservati, mantenendo l'analisi locale e inviando solo testo dei paragrafi a un unico endpoint verificabile.
• Sviluppatori senza accesso alla fatturazione di un dato fornitore. L'accesso basato su ricarica senza obbligo di carta rimuove la dipendenza dalla registrazione per provider.

Verifica l'endpoint e fai debug del primo documento.

Elenca i modelli che la tua chiave può indirizzare prima di avviare un'esecuzione lunga; --openai-model deve corrispondere esattamente a un id servito. Poi traduci qualcosa di minuscolo (un PDF di una pagina, o --pages 1 su uno più grande) dall'inizio alla fine. Un 401 sul primo paragrafo significa che la chiave non corrisponde all'URL base. Model-not-found è un errore di battitura nell'id. Un'esecuzione che analizza ma non chiama mai l'endpoint manca di --openai. Blocchi frequenti con messaggi di retry indicano un QPS impostato più alto di quanto l'endpoint sostenga; abbassalo e risali gradualmente. Una volta che i documenti fluiscono, la console di APIsRouter mostra il modello per richiesta, i conteggi dei token e la spesa. Il costo di traduzione scala con la lunghezza del documento in entrambe le direzioni (input e output), e il log di utilizzo per chiave è come impari il tuo costo reale per pagina per ogni modello invece di stimarlo.

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

Domande frequenti