Batch API 비용 절감 50%: 처리량·지연 트레이드오프 실전 설계

왜 Batch API인가: 수치로 보는 트레이드오프

Batch API는 비동기 처리로 요청당 비용 50% 절감을 제공하지만 결과 반환까지 최대 24시간이 소요된다. 실시간 응답이 불필요한 워크로드, 예를 들어 대규모 문서 분류, 오프라인 임베딩 생성, 야간 보고서 요약에 적합하다.

핵심 제약:

• 배치당 최대 10,000 요청 또는 32MB
• 결과는 .jsonl 형식으로 일괄 반환
• 부분 실패 시 성공 요청 결과는 그대로 사용 가능

동기 API 대비 지연 허용 기준: SLA가 1분 이상인 파이프라인에서만 적용을 권장한다. 그 이하면 스트리밍 동기 호출이 총 비용 관점에서 유리할 수 있다.

실전 배치 구성 코드

import anthropic
import json
from pathlib import Path

client = anthropic.Anthropic()

# 요청 목록 구성 (custom_id는 후속 매핑에 필수)
requests = [
    {
        "custom_id": f"doc-{i}",
        "params": {
            "model": "claude-opus-4-5",
            "max_tokens": 256,
            "messages": [{"role": "user", "content": f"Classify sentiment: {text}"}]
        }
    }
    for i, text in enumerate(documents)  # documents: List[str]
]

# 배치 제출
batch = client.messages.batches.create(requests=requests)
print(f"Batch ID: {batch.id}, Status: {batch.processing_status}")

# 지수 백오프 폴링 (초기 30초, 최대 5분 간격)
import time
delay = 30
while True:
    result = client.messages.batches.retrieve(batch.id)
    if result.processing_status == "ended":
        break
    time.sleep(min(delay, 300))
    delay *= 1.5

# 결과 파싱 및 실패 분리
successes, failures = {}, []
for item in client.messages.batches.results(batch.id):
    if item.result.type == "succeeded":
        successes[item.custom_id] = item.result.message.content[0].text
    else:
        failures.append({"id": item.custom_id, "error": item.result.error})

print(f"성공: {len(successes)}, 실패: {len(failures)}")

실패 모드와 운영 체크리스트

주요 실패 모드:

1. custom_id 중복: 배치 내 중복 ID는 전체 배치 거부로 이어진다. 제출 전 len(set(ids)) == len(ids) 검증 필수.
2. 32MB 초과: 대형 문서는 청크 분할 후 여러 배치로 나눠야 한다. 목표 배치 크기는 20MB 이하 권장.
3. 24시간 타임아웃: expired 상태가 되면 재제출 필요. 크리티컬 파이프라인은 12시간 시점에 상태 알람 설정.
4. 부분 실패 미처리: 실패 항목을 별도 큐에 저장해 동기 API로 재처리하는 fallback 경로 필수.

운영 체크리스트:

• [ ] custom_id를 원본 데이터 DB PK와 1:1 매핑, 결과 저장 시 트랜잭션 처리
• [ ] 배치 제출 후 ID를 영속 저장소(Redis/DB)에 기록 — 프로세스 재시작 대비
• [ ] 실패율 > 5% 시 알람, > 20% 시 자동 동기 fallback 전환
• [ ] 월간 비용 리포트에 Batch vs 동기 비율 추적 (목표: 비실시간 워크로드의 70% 이상 배치화)