프로덕션의 Batch API 워크플로우

~14 min · batch-api, async, evaluation

Level 0Observer

0 XP0/64 lessons0/13 achievements

0/150 XP to next level150 XP to go0% complete

Batch가 진짜 무엇을 위한 것

Batch API가 옳은 도구 — 야간 분류, 주기적 backfill, 큰 평가 run, 데이터셋 annotation, 콘텐츠 audit. '답이 24시간 안 land 가능' 진실인 어떤 거. 거래는 그 유연성에 ~50% per-token 가격 할인.

Custom ID로 결과 re-key

각 batch 요청이 custom_id 받음. 결과가 그 id로 키된 채 임의 순서로 stream back. Position이 아니라 custom_id로 도메인 row에 매핑. Batch input list와 output stream을 id로 join된 두 독립 collection처럼 다뤄.

Polling, webhook, idempotent retry

가벼운 워크로드면 30-60초마다 polling OK. 프로덕션이면 webhook(제공될 때) 또는 scheduled check 선호. 결과 처리 단계 항상 idempotent — 끝난 batch 다시 pull해도 downstream store 더블 쓰지 마.

원칙: Batch는 'slow API' 아니야. 'wait 가능한 작업에 더 싼 API'. 차이 사용, Messages와 같은 척 X.

Code

Submit, poll, idempotent write·python

from anthropic import Anthropic
import time, json

client = Anthropic()

batch = client.messages.batches.create(
    requests=[
        {
            "custom_id": row["id"],
            "params": {
                "model": "claude-haiku-4-5-20251001",
                "max_tokens": 64,
                "system": "Reply with one word: positive, negative, or neutral.",
                "messages": [{"role": "user", "content": row["text"]}],
            },
        }
        for row in rows
    ]
)

while True:
    b = client.messages.batches.retrieve(batch.id)
    if b.processing_status == "ended":
        break
    time.sleep(60)

# Idempotent write: custom_id로 upsert
for item in client.messages.batches.results(batch.id):
    label = item.result.message.content[0].text.strip()
    db.upsert("sentiment", {"id": item.custom_id, "label": label})

Per-row 에러 처리·python

for item in client.messages.batches.results(batch.id):
    if item.result.type == "succeeded":
        save(item.custom_id, item.result.message)
    elif item.result.type == "errored":
        log.warning("batch row failed", id=item.custom_id, error=item.result.error)
        retry_queue.add(item.custom_id)

External links

Exercise

야간 작업 하나를 Batch API로 옮겨. 결과 측에 idempotent upsert 추가. 같은 batch id에서 두 번 row 안 더블 확인.

Hint

Downstream store에 custom_id unique constraint 있으면 upsert 그냥 떨어져 — 그렇게 디자인.

Progress

Progress is local-only — sign in to sync across devices.

← Previous깊이 있는 prompt caching 전략 Next →Retry 자세와 신뢰성 패턴

이 페이지에서 버그를 발견하셨거나 피드백이 있으세요?문제 신고

🔔 답글 알림 (로그인 필요)

로그인 — 댓글을 남기려면 로그인해 주세요.

아직 댓글이 없어요. 첫 댓글을 남겨보세요.