Batch API로 LLM 비용 50% 절감: 처리량·지연·실패 복구 설계

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

Batch API는 요청을 모아 24시간 이내 비동기 처리하는 방식이다. 동기 Messages API 대비 입력·출력 토큰 모두 50% 할인이 적용된다. 단, 평균 완료 시간은 1~4시간이므로 실시간 응답이 필요한 워크플로에는 적합하지 않다.

| 항목 | 동기 API | Batch API | |------|----------|-----------| | 가격 | 기준 100% | 50% | | 평균 지연 | ~2초 | 1~4시간 | | 최대 요청/배치 | N/A | 10,000건 | | 실패 단위 | 요청 단위 | 요청 단위 |

적합한 워크플로: 오프라인 데이터 파이프라인, 야간 문서 분류, 대규모 평가(eval) 실행, 주기적 임베딩 갱신.

설계 핵심: 멱등성과 부분 실패 처리

배치 내 개별 요청은 독립적으로 성공·실패한다. 배치 전체가 실패하는 경우는 드물고, 일부 요청만 errored 상태로 반환되는 것이 일반적이다. 따라서 다음 세 가지 설계 원칙이 필수다.

1. custom_id에 멱등 키 부여: {job_id}-{record_id}-{attempt} 형태로 재시도 시 중복 처리를 방지한다.
2. 결과 스트리밍 파싱: 결과 파일은 JSONL로 제공되며, 수천 건을 메모리에 전부 올리지 말고 라인 단위로 스트리밍 처리한다.
3. 실패 건만 재배치: errored 결과만 골라 새 배치로 재제출한다. 전체 재실행은 비용 낭비다.

import anthropic
import json
from pathlib import Path

client = anthropic.Anthropic()

# 1. 배치 생성
records = [{"id": f"rec-{i}", "text": f"문서 {i}"} for i in range(100)]
requests = [
    {
        "custom_id": f"job-001-{r['id']}-v1",
        "params": {
            "model": "claude-opus-4-5",
            "max_tokens": 256,
            "messages": [{"role": "user", "content": f"다음을 한 줄 요약: {r['text']}"}],
        },
    }
    for r in records
]

batch = client.messages.batches.create(requests=requests)
print(f"배치 ID: {batch.id}, 상태: {batch.processing_status}")

# 2. 완료 폴링 (지수 백오프)
import time
for wait in [60, 120, 240, 480, 960]:
    time.sleep(wait)
    batch = client.messages.batches.retrieve(batch.id)
    if batch.processing_status == "ended":
        break

# 3. 결과 파싱 + 실패 건 수집
failed = []
for result in client.messages.batches.results(batch.id):
    if result.result.type == "succeeded":
        text = result.result.message.content[0].text
        print(f"{result.custom_id}: {text[:60]}")
    elif result.result.type == "errored":
        failed.append(result.custom_id)

print(f"실패 건수: {len(failed)} / {len(requests)}")

운영 체크리스트

• [ ] 배치 크기: 단일 배치 10,000건 상한 확인. 초과 시 청크 분할 로직 구현
• [ ] 폴링 주기: 분당 1회 이하 권장. request_counts 필드로 진행률 모니터링
• [ ] 결과 파일 보존: 결과는 29일 후 자동 삭제됨. S3/GCS로 즉시 백업
• [ ] 비용 알람: input_tokens + output_tokens 합계를 CloudWatch / Datadog로 추적
• [ ] 타임아웃 SLA: 24시간 초과 시 자동 취소(batches.cancel()) 후 동기 폴백 전환
• [ ] 모델 버전 고정: 배치 제출 시점과 결과 소비 시점 사이 모델 업데이트 가능성 고려