BabelDOC으로 커스텀 OpenAI base URL에서 PDF 번역하기.

빠른 답: 세 플래그가 모든 번역 호출을 라우팅합니다.

BabelDOC의 명령줄은 엔드포인트를 직접 받습니다: --openai는 LLM 번역기를 활성화하고, --openai-base-url은 요청이 향할 곳을 설정하고, --openai-api-key는 인증하고, --openai-model은 모델 id를 고릅니다. README의 예제 자체가 정확히 이 플래그 조합을 보여주며, 번역 서비스에 대한 안내는 OpenAI 호환 LLM만 지원된다고 명시하는데, 이는 멀티벤더 OpenAI 호환 게이트웨이를 우회책이 아니라 자연스러운 선택으로 만듭니다. 모델 id가 그냥 문자열로 전달되므로, 엔드포인트가 서빙하는 어떤 것이든 작동합니다: 업스트림 문서 자체가 GLM과 DeepSeek 계열의 OpenAI 호환 친화적인 모델을 권장하는데, APIsRouter를 통하면 그것들이 같은 base 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, Immersive Translate 팀 작품, 약 9천 스타)은 레이아웃을 보존하는 PDF 문서 번역기입니다: 문서 구조를 파싱하고, 수식과 그림을 보호하고, 문단을 찾아 LLM으로 번역한 다음, 번역된 단일본과 좌우 대조 이중본으로 PDF를 재조립합니다. CLI와 Python API로 제공되며, 호스팅형 BabelDOC 서비스에 대응하는 셀프 호스팅 버전입니다. 엔드포인트가 중요해지는 곳은 번역 단계입니다. 문서 하나가 문단 크기의 채팅-완성 요청 여러 개가 되고, --qps 플래그(기본값 초당 4쿼리)로 스로틀링되며, 워커 풀(pool-max-workers, 기본값은 QPS 값)로 처리됩니다. 이 형태에는 두 가지 결과가 따릅니다. 첫째, 번역은 물량 워크로드입니다: 긴 PDF는 수백 개의 작은 호출이므로 토큰당 가격이 빠르게 누적됩니다. 둘째, 모델이 주로 읽기만 하는 검색 워크로드와 달리, 번역은 읽는 만큼 대략 써내기도 하므로, id를 비교할 때 입력 가격만큼 출력 토큰 가격도 중요합니다. BabelDOC은 번역도 캐싱하므로, --ignore-cache를 넘기지 않는 한 문서를 다시 실행하면 이전 결과를 재사용합니다. 용어집 CSV(--glossary-files)는 실행 전체에 걸쳐 용어를 고정하며, --max-pages-per-part는 매우 큰 문서를 여러 부분으로 나눠 번역한 뒤 자동으로 병합합니다.

전체 설정: CLI 플래그 또는 TOML 설정 파일.

반복 사용을 위해서는 같은 설정을 --config로 넘기는 TOML 파일에 둘 수 있습니다. [babeldoc] 테이블은 kebab-case로 동일한 키를 받습니다: 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"

번역 모델 선택하기.

비교 워크플로우는 구체적입니다: 같은 열 페이지를 두 id로 번역하고(실행마다 키가 붙는 캐시가 둘을 분리해 줍니다), 이중본을 나란히 읽고, 각 실행에 무엇이 들었는지 키별 사용량 로그를 확인하세요. 대부분의 팀은 빠른 기본값과 그럴 가치가 있는 문서를 위한 프리미엄 프로필, 둘 다 TOML 파일로 정착합니다.

• 물량 문서(매뉴얼, 한 번 읽는 논문)에는 deepseek-v4-flash가 맞습니다: 기술적 산문에 대한 번역 품질을 유지하면서 페이지당 비용은 거의 무시할 만한 수준입니다.
• 중국어 대상 번역은 glm-5.2와 DeepSeek 계열의 홈그라운드입니다; 업스트림 문서 자체가 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 없이 base URL만 넘기면 번역기가 비활성 상태로 남고, 이는 PDF는 파싱하지만 번역은 전혀 하지 않는 실행으로 나타납니다. 모델 id는 엔드포인트의 /v1/models 목록에 대한 정확한 문자열입니다; 오타는 첫 문단 호출에서 model-not-found로 실패합니다. 401은 키와 base URL이 짝이 맞지 않는다는 뜻입니다. 레이아웃 문제는 엔드포인트 문제가 아닙니다. 텍스트 겹침, 수식 손실, 표 깨짐은 PDF 파싱 쪽(--enhance-compatibility, 스캔 문서를 위한 --ocr-workaround, 또는 rich-text 토글을 시도해 보세요)에서 비롯되며, 모델을 바꿔도 고쳐지지 않습니다. 반대도 마찬가지입니다: 잘못 번역된 용어는 파서 문제가 아니라 모델이나 용어집 문제입니다. 캐시가 변경을 가릴 수 있습니다. 모델을 바꾼 뒤 예전 id가 이미 처리한 내용을 새 id가 다시 번역하길 원한다면 --ignore-cache를 넘기세요; 그렇지 않으면 캐시된 문단은 예전 그대로 남습니다.

어떤 사람들이 게이트웨이를 통해 BabelDOC을 쓰는가.

• 논문을 대량으로 번역하는 연구자 — 문서당 수백 개의 작은 호출이 물량 가격과 키별 사용량 가시성을 게임의 전부로 만듭니다.
• 이중 언어 문서를 표준화하는 팀 — 같은 엔드포인트에 대해 서로 다른 모델 문자열로 빠른 기본 프로필과 프리미엄 프로필을 함께 운영합니다.
• 해당 언어 쌍에서 가장 강한 번역 모델이 서로 다른 벤더에 있는 시장의 사용자: GLM, DeepSeek, Claude, Gemini id 모두 키 하나 뒤에.
• 기밀 문서를 위해 호스팅형 서비스를 셀프 호스팅으로 대체하는 사람들 — 파싱은 로컬에 두고 문단 텍스트만 감사 가능한 엔드포인트 하나로 보냅니다.
• 특정 벤더의 결제 수단에 접근할 수 없는 개발자. 카드 없이 충전만으로 사용할 수 있어 프로바이더별 가입 의존성이 사라집니다.

엔드포인트 검증 및 첫 문서 디버깅.

긴 실행을 시작하기 전에 여러분의 키로 접근 가능한 모델을 나열하세요; --openai-model은 서빙되는 id와 정확히 일치해야 합니다. 그런 다음 아주 작은 것(한 페이지짜리 PDF, 또는 더 큰 문서에 --pages 1)을 처음부터 끝까지 번역해 보세요. 첫 문단에서 401이 나오면 키가 base 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

자주 묻는 질문