블로그 목록
ai

Claude Message Batches로 토큰 비용 절반 줄이기 — 급하지 않은 작업은 배치로

사이드 프로젝트에서 블로그 글 수백 개를 한 번에 요약해야 할 일이 생겼다. 그냥 messages.create()를 루프로 돌리면 되긴 하는데, 두 가지가 걸렸다. 토큰 비용이 글 개수만큼 그대로 나간다는 거, 그리고 실시간으로 받을 이유가 전혀 없는 작업이라는 거.

요약 결과는 나중에 한꺼번에 DB에 넣을 거라 몇 초 안에 응답이 올 필요가 없다. 이렇게 지연에 민감하지 않은 대량 작업이라면 Message Batches API가 딱이다. 같은 요청을 배치로 묶어 보내면 모든 토큰 비용이 50% 깎인다. 실시간 응답을 포기하는 대가로 가격을 절반으로 받는 구조다.

배치 만들기

핵심은 요청마다 custom_id를 붙여서 배열로 넘기는 것이다. 각 요청의 params는 평소 messages.create()에 넣던 것과 똑같다.

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();

const batch = await client.messages.batches.create({
  requests: posts.map((post) => ({
    custom_id: post.id, // 결과를 다시 매칭할 키
    params: {
      model: 'claude-opus-4-8',
      max_tokens: 1024,
      messages: [
        { role: 'user', content: `다음 글을 세 문장으로 요약해줘:\n\n${post.body}` },
      ],
    },
  })),
});

console.log(batch.id, batch.processing_status); // msgbatch_..., "in_progress"

배치 하나에 최대 10만 건, 256MB까지 넣을 수 있다. 대부분 1시간 안에 끝나고, 최대 24시간 안에는 무조건 처리된다.

폴링하고 결과 받기

배치는 비동기라 바로 결과가 안 온다. processing_status가 ended가 될 때까지 기다린 다음 결과를 스트림으로 읽는다.

let result = await client.messages.batches.retrieve(batch.id);
while (result.processing_status !== 'ended') {
  await new Promise((r) => setTimeout(r, 60_000)); // 1분마다 확인
  result = await client.messages.batches.retrieve(batch.id);
}

for await (const item of await client.messages.batches.results(batch.id)) {
  if (item.result.type === 'succeeded') {
    const text = item.result.message.content[0];
    if (text.type === 'text') {
      await saveSummary(item.custom_id, text.text);
    }
  }
}

여기서 한 가지 꼭 기억할 점. 결과는 보낸 순서대로 오지 않는다. 그래서 배열 인덱스가 아니라 반드시 custom_id로 매칭해야 한다. 처음에 이걸 모르고 순서를 믿었다가 요약이 엉뚱한 글에 붙는 버그를 만들었다.

item.result.type은 succeeded 외에 errored, canceled, expired도 있으니 분기 처리를 해두는 게 안전하다. 한 건이 실패해도 나머지는 정상적으로 처리된다.

정리하면

프롬프트 캐싱이 "같은 컨텍스트를 반복해서 보낼 때" 비용을 줄이는 도구라면, 배치는 "급하지 않은 대량 작업"의 비용을 줄이는 도구다. 둘은 겹치지 않으니 같이 써도 된다. 스트리밍 챗봇처럼 실시간 응답이 필요한 곳엔 당연히 맞지 않지만, 분류·요약·임베딩 전처리·평가셋 돌리기 같은 백그라운드 작업이라면 그냥 배치로 넘기는 게 이득이다. 코드를 거의 안 바꾸고 비용만 절반으로 떨어뜨릴 수 있는 몇 안 되는 선택지다.

목록으로 돌아가기