Batch API + 비용 관측 파이프라인: 대규모 오프라인 추론의 실전 설계

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

Batch API는 동기 호출 대비 비용 50% 절감, 처리량 제한 완화(표준 RPM 한도 적용 제외)라는 두 가지 이점을 제공한다. 대신 결과 반환까지 최대 24시간 지연이 발생한다. 이 지연을 감수할 수 있는 유스케이스—대규모 문서 분류, 오프라인 평가, 데이터 증강—에서는 동기 호출보다 압도적으로 유리하다.

실패 모드 주의: 배치 내 일부 요청이 실패해도 전체 배치는 완료 상태로 반환된다. 개별 결과의 error 필드를 반드시 검사해야 한다. 실패율이 5%를 초과하면 배치 전략 자체를 재검토해야 한다.

비용 관측 파이프라인 설계

배치 작업에서 비용 추적이 어려운 이유는 결과가 비동기로 도착하고, 요청 단위 토큰 메타데이터가 응답 본문에 분산되기 때문이다. 아래 패턴은 배치 제출 시 메타데이터를 로컬에 저장하고, 결과 수집 시 비용을 재구성한다.

import anthropic
import json
from datetime import datetime

client = anthropic.Anthropic()

# 1. 배치 요청 구성 및 제출
requests = [
    {
        "custom_id": f"doc-{i}",
        "params": {
            "model": "claude-opus-4-5",
            "max_tokens": 512,
            "messages": [{"role": "user", "content": f"Classify: {doc}"}],
        },
    }
    for i, doc in enumerate(["doc_a", "doc_b", "doc_c"])
]

batch = client.messages.batches.create(requests=requests)
print(f"Batch ID: {batch.id} | 제출 시각: {datetime.utcnow().isoformat()}")

# 2. 메타데이터 로컬 저장 (DB or 파일)
job_meta = {
    "batch_id": batch.id,
    "submitted_at": datetime.utcnow().isoformat(),
    "request_count": len(requests),
    "model": "claude-opus-4-5",
}
with open(f"batch_{batch.id}.json", "w") as f:
    json.dump(job_meta, f)

# 3. 결과 수집 및 비용 집계 (폴링 또는 웹훅 트리거 후 실행)
def collect_and_observe(batch_id: str):
    total_input, total_output, errors = 0, 0, []
    # claude-opus-4-5 기준: input $15/MTok, output $75/MTok
    INPUT_PRICE = 15 / 1_000_000
    OUTPUT_PRICE = 75 / 1_000_000

    for result in client.messages.batches.results(batch_id):
        if result.result.type == "errored":
            errors.append(result.custom_id)
            continue
        usage = result.result.message.usage
        total_input += usage.input_tokens
        total_output += usage.output_tokens

    cost = total_input * INPUT_PRICE + total_output * OUTPUT_PRICE
    print(f"총 비용: ${cost:.4f} | 실패: {len(errors)}건")
    if len(errors) / max(total_input, 1) > 0.05:
        print("[경고] 실패율 5% 초과 — 배치 전략 재검토 필요")
    return cost, errors

운영 체크리스트

• 배치 크기: 단일 배치에 최대 10,000 요청 가능. 10,000건 초과 시 배치를 분할하고 batch_id를 그룹으로 묶어 관리.
• 만료 처리: 배치는 29일 후 자동 만료. 결과 수집 스케줄러가 이 기간 내에 실행되는지 모니터링.
• 비용 이상 탐지: 작업 유형별 평균 토큰 소비 기준선(baseline)을 수립하고, ±30% 편차 발생 시 알림.
• 재시도 전략: 개별 실패 요청만 추출해 동기 API로 재시도. 전체 배치 재제출은 비용 낭비.
• 캐시 연동: 반복 프롬프트가 많다면 cache_control 블록을 배치 요청에도 동일하게 적용해 추가 절감.