4.5배치 처리

Message Batches API는 다수의 Messages API 요청을 하나의 배치(batch)로 묶어 비동기로 제출하는 방식입니다. 각 요청은 custom_id와 일반 Messages API 파라미터(params)로 구성되며, 배치는 생성 후 백그라운드에서 처리됩니다. 대부분의 배치는 1시간 이내에 완료되고, 처리 보장 시한은 24시간입니다. 대가로 입력·출력 토큰 모두 표준 가격의 50% 할인이 적용됩니다.

batch = client.messages.batches.create(
    requests=[
        {
            "custom_id": f"review-{r.id}",
            "params": {
                "model": "claude-haiku-4-5",
                "max_tokens": 512,
                "messages": [
                    {"role": "user", "content": f"리뷰 분류: {r.text}"}
                ],
            },
        }
        for r in reviews
    ]
)
print(batch.id, batch.processing_status)  # in_progress

제출 후에는 배치 상태를 폴링(polling)하다가 processing_status가 ended가 되면 결과 파일을 내려받습니다. 여기서 시험에 자주 나오는 특성 두 가지가 있습니다. 첫째, 결과 순서는 제출 순서와 무관합니다. 결과를 원본 요청과 짝지으려면 반드시 custom_id를 사용해야 합니다. 둘째, 배치 내 각 요청은 서로 독립적으로 성공하거나 실패합니다. 하나의 요청이 실패해도 배치 전체가 실패하지 않으며, 결과에는 요청별 result.type(succeeded, errored, canceled, expired)이 표시됩니다.

배치 처리를 선택하는 기준은 단 하나, 결과를 기다리는 주체가 사람인가 파이프라인인가입니다.

배치가 적합한 워크로드: 야간 로그 분류, 문서 아카이브 임베딩 전처리, 대량 콘텐츠 모더레이션, 평가 세트 일괄 실행, 데이터셋 라벨링. 공통점은 개별 결과의 지연이 사용자 경험에 영향을 주지 않는다는 것입니다.

실시간이 필요한 워크로드: 챗봇 응답, 에이전트의 툴 호출 루프, 사용자가 화면에서 기다리는 모든 작업. 에이전틱 루프는 이전 응답이 다음 요청의 입력이 되므로 배치로 처리할 수 없다는 점이 중요한 시험 포인트입니다. 배치 내 요청들은 서로의 결과를 참조할 수 없기 때문입니다.

비용 구조도 이해해야 합니다. 배치 할인 50%는 프롬프트 캐싱 할인과는 별개 메커니즘입니다. 대량 분류 작업이라면 "작은 모델 선택 + 배치 처리"의 조합이 비용 최적화의 기본형입니다. 최상위 모델의 실시간 호출과 비교하면 수십 배의 비용 차이가 납니다.

비용 비교 (동일 워크로드 1만 건 가정)
- Sonnet 실시간:        기준 비용 100%
- Sonnet 배치:          50%
- Haiku 실시간:         ~8%
- Haiku 배치:           ~4%

시험에서는 "지연에 민감하지 않은 대량 작업의 비용 최적화"를 묻고, 정답은 거의 항상 배치 API(+작은 모델 검토)입니다. 반대로 "대화형 에이전트에 배치를 적용한다"는 선택지는 오답입니다.

배치 파이프라인의 신뢰성은 결과 수집 단계에서 결정됩니다. 표준 패턴은 다음과 같습니다.

import time

def wait_and_collect(batch_id: str) -> tuple[dict, list]:
    while True:
        batch = client.messages.batches.retrieve(batch_id)
        if batch.processing_status == "ended":
            break
        time.sleep(60)

    succeeded, failed = {}, []
    for entry in client.messages.batches.results(batch_id):
        if entry.result.type == "succeeded":
            succeeded[entry.custom_id] = entry.result.message
        else:
            failed.append((entry.custom_id, entry.result.type))
    return succeeded, failed

부분 실패는 정상 상황으로 설계합니다. 실패 목록을 모아 새 배치로 재제출하는 '재배치(re-batch)' 패턴이 정석입니다. 이때 custom_id를 원본과 동일하게 유지하면 몇 번을 재배치해도 결과를 원본 데이터와 안전하게 짝지을 수 있습니다. custom_id를 멱등성(idempotency) 키로 쓰는 셈입니다.

결과 검증은 실시간과 동일하게 적용합니다. 배치로 받았다고 출력 품질이 보장되는 것은 아니므로, 4.3~4.4에서 배운 스키마 검증을 결과 수집 후에 일괄 실행하고, 검증 실패 건은 재배치 목록에 합류시킵니다.

운영 팁 세 가지: (1) 폴링 간격은 분 단위면 충분합니다. 초 단위 폴링은 의미 없는 API 호출만 늘립니다. (2) 거대한 단일 배치보다 수천 건 단위로 나눠 제출하면 진행 관찰과 부분 재처리가 쉬워집니다. (3) 24시간 시한이 지나 expired된 요청도 실패 목록에 넣어 재배치하면 됩니다.