배치 처리
배치 처리는 대량의 요청을 효율적으로 처리하는 강력한 접근 방식입니다. 즉시 응답과 함께 요청을 하나씩 처리하는 대신, 배치 처리를 통해 여러 요청을 함께 제출하여 비동기적으로 처리할 수 있습니다. 이 패턴은 다음과 같은 경우에 특히 유용합니다:
- 대량의 데이터를 처리해야 하는 경우
- 즉시 응답이 필요하지 않은 경우
- 비용 효율성을 최적화하고자 하는 경우
- 대규모 평가나 분석을 실행하는 경우
Message Batches API는 이 패턴의 첫 번째 구현입니다.
Message Batches API
Message Batches API는 대량의 Messages 요청을 비동기적으로 처리하는 강력하고 비용 효율적인 방법입니다. 이 접근 방식은 즉시 응답이 필요하지 않은 작업에 적합하며, 대부분의 배치는 1시간 이내에 완료되면서 비용을 50% 절감하고 처리량을 증가시킵니다.
이 가이드 외에도 API 레퍼런스를 직접 탐색할 수 있습니다.
Message Batches API 작동 방식
Message Batches API에 요청을 보낼 때:
- 시스템은 제공된 Messages 요청으로 새로운 Message Batch를 생성합니다.
- 배치는 각 요청이 독립적으로 처리되면서 비동기적으로 처리됩니다.
- 배치의 상태를 폴링하고 모든 요청의 처리가 완료되면 결과를 검색할 수 있습니다.
이는 즉시 결과가 필요하지 않은 대량 작업에 특히 유용합니다:
- 대규모 평가: 수천 개의 테스트 케이스를 효율적으로 처리합니다.
- 콘텐츠 조정: 대량의 사용자 생성 콘텐츠를 비동기적으로 분석합니다.
- 데이터 분석: 대규모 데이터셋에 대한 인사이트나 요약을 생성합니다.
- 대량 콘텐츠 생성: 다양한 목적(예: 제품 설명, 기사 요약)을 위한 대량의 텍스트를 생성합니다.
배치 제한사항
- Message Batch는 100,000개의 Message 요청 또는 256MB 크기 중 먼저 도달하는 것으로 제한됩니다.
- 각 배치를 가능한 한 빠르게 처리하며, 대부분의 배치는 1시간 이내에 완료됩니다. 모든 메시지가 완료되거나 24시간 후 중 먼저 도달하는 시점에 배치 결과에 액세스할 수 있습니다. 24시간 이내에 처리가 완료되지 않으면 배치가 만료됩니다.
- 배치 결과는 생성 후 29일 동안 사용할 수 있습니다. 그 이후에도 배치를 볼 수는 있지만 결과를 더 이상 다운로드할 수 없습니다.
- 배치는 Workspace로 범위가 지정됩니다. API 키가 속한 Workspace 내에서 생성된 모든 배치와 그 결과를 볼 수 있습니다.
- 속도 제한은 Batches API HTTP 요청과 처리 대기 중인 배치 내 요청 수 모두에 적용됩니다. Message Batches API 속도 제한을 참조하세요. 또한 현재 수요와 요청 볼륨에 따라 처리 속도를 늦출 수 있습니다. 이 경우 24시간 후 더 많은 요청이 만료되는 것을 볼 수 있습니다.
- 높은 처리량과 동시 처리로 인해 배치가 Workspace의 구성된 지출 한도를 약간 초과할 수 있습니다.
지원되는 모델
Message Batches API는 현재 다음을 지원합니다:
- Claude Opus 4 (
claude-opus-4-20250514
) - Claude Sonnet 4 (
claude-sonnet-4-20250514
) - Claude Sonnet 3.7 (
claude-3-7-sonnet-20250219
) - Claude Sonnet 3.5 (
claude-3-5-sonnet-20240620
및claude-3-5-sonnet-20241022
) - Claude Haiku 3.5 (
claude-3-5-haiku-20241022
) - Claude Haiku 3 (
claude-3-haiku-20240307
) - Claude Opus 3 (
claude-3-opus-20240229
)
배치 처리 가능한 항목
Messages API에 만들 수 있는 모든 요청을 배치에 포함할 수 있습니다. 여기에는 다음이 포함됩니다:
- 비전
- 도구 사용
- 시스템 메시지
- 다중 턴 대화
- 모든 베타 기능
배치의 각 요청은 독립적으로 처리되므로 단일 배치 내에서 다양한 유형의 요청을 혼합할 수 있습니다.
배치는 처리하는 데 5분 이상 걸릴 수 있으므로, 공유 컨텍스트가 있는 배치를 처리할 때 더 나은 캐시 적중률을 위해 프롬프트 캐싱과 함께 1시간 캐시 지속 시간을 사용하는 것을 고려하세요.
가격
Batches API는 상당한 비용 절감을 제공합니다. 모든 사용량은 표준 API 가격의 50%로 청구됩니다.
Model | Batch input | Batch output |
---|---|---|
Claude Opus 4.1 | $7.50 / MTok | $37.50 / MTok |
Claude Opus 4 | $7.50 / MTok | $37.50 / MTok |
Claude Sonnet 4 | $1.50 / MTok | $7.50 / MTok |
Claude Sonnet 3.7 | $1.50 / MTok | $7.50 / MTok |
Claude Sonnet 3.5 (deprecated) | $1.50 / MTok | $7.50 / MTok |
Claude Haiku 3.5 | $0.40 / MTok | $2 / MTok |
Claude Opus 3 (deprecated) | $7.50 / MTok | $37.50 / MTok |
Claude Haiku 3 | $0.125 / MTok | $0.625 / MTok |
Message Batches API 사용 방법
배치 준비 및 생성
Message Batch는 Message를 생성하기 위한 요청 목록으로 구성됩니다. 개별 요청의 형태는 다음으로 구성됩니다:
- Messages 요청을 식별하기 위한 고유한
custom_id
- 표준 Messages API 매개변수가 포함된
params
객체
이 목록을 requests
매개변수에 전달하여 배치를 생성할 수 있습니다:
이 예제에서는 두 개의 별도 요청이 비동기 처리를 위해 함께 배치됩니다. 각 요청에는 고유한 custom_id
가 있고 Messages API 호출에 사용할 표준 매개변수가 포함되어 있습니다.
Messages API로 배치 요청 테스트
각 메시지 요청에 대한 params
객체의 유효성 검사는 비동기적으로 수행되며, 유효성 검사 오류는 전체 배치 처리가 완료될 때 반환됩니다. 먼저 Messages API로 요청 형태를 확인하여 입력을 올바르게 구성하고 있는지 확인할 수 있습니다.
배치가 처음 생성될 때 응답의 처리 상태는 in_progress
입니다.
배치 추적
Message Batch의 processing_status
필드는 배치가 처리 중인 단계를 나타냅니다. in_progress
로 시작하여 배치의 모든 요청이 처리를 완료하고 결과가 준비되면 ended
로 업데이트됩니다. Console을 방문하거나 검색 엔드포인트를 사용하여 배치 상태를 모니터링할 수 있습니다:
이 엔드포인트를 폴링하여 처리가 완료되었는지 알 수 있습니다.
배치 결과 검색
배치 처리가 완료되면 배치의 각 Messages 요청에 결과가 있습니다. 4가지 결과 유형이 있습니다:
결과 유형 | 설명 |
---|---|
succeeded | 요청이 성공했습니다. 메시지 결과를 포함합니다. |
errored | 요청에서 오류가 발생했고 메시지가 생성되지 않았습니다. 가능한 오류에는 잘못된 요청과 내부 서버 오류가 포함됩니다. 이러한 요청에 대해서는 청구되지 않습니다. |
canceled | 이 요청이 모델로 전송되기 전에 사용자가 배치를 취소했습니다. 이러한 요청에 대해서는 청구되지 않습니다. |
expired | 이 요청이 모델로 전송되기 전에 배치가 24시간 만료에 도달했습니다. 이러한 요청에 대해서는 청구되지 않습니다. |
배치의 request_counts
로 결과 개요를 볼 수 있으며, 이는 이 네 가지 상태에 도달한 요청 수를 보여줍니다.
배치 결과는 Message Batch의 results_url
속성에서 다운로드할 수 있으며, 조직 권한이 허용하는 경우 Console에서도 사용할 수 있습니다. 결과의 잠재적으로 큰 크기 때문에 모든 결과를 한 번에 다운로드하는 대신 결과를 스트리밍하는 것이 권장됩니다.
결과는 .jsonl
형식이며, 각 줄은 Message Batch의 단일 요청 결과를 나타내는 유효한 JSON 객체입니다. 각 스트리밍된 결과에 대해 custom_id
와 결과 유형에 따라 다른 작업을 수행할 수 있습니다. 다음은 결과 세트의 예입니다:
결과에 오류가 있는 경우 result.error
가 표준 오류 형태로 설정됩니다.
배치 결과가 입력 순서와 일치하지 않을 수 있습니다
배치 결과는 임의의 순서로 반환될 수 있으며 배치가 생성될 때의 요청 순서와 일치하지 않을 수 있습니다. 위 예제에서는 두 번째 배치 요청의 결과가 첫 번째보다 먼저 반환됩니다. 결과를 해당 요청과 올바르게 일치시키려면 항상 custom_id
필드를 사용하세요.
Message Batches에서 프롬프트 캐싱 사용
Message Batches API는 프롬프트 캐싱을 지원하여 배치 요청의 비용과 처리 시간을 잠재적으로 줄일 수 있습니다. 프롬프트 캐싱과 Message Batches의 가격 할인은 누적될 수 있어 두 기능을 함께 사용할 때 더 큰 비용 절감을 제공합니다. 그러나 배치 요청은 비동기적이고 동시에 처리되므로 캐시 적중은 최선의 노력 기반으로 제공됩니다. 사용자는 일반적으로 트래픽 패턴에 따라 30%에서 98% 범위의 캐시 적중률을 경험합니다.
배치 요청에서 캐시 적중 가능성을 최대화하려면:
- 배치 내의 모든 Message 요청에 동일한
cache_control
블록을 포함합니다 - 캐시 항목이 5분 수명 후 만료되는 것을 방지하기 위해 꾸준한 요청 스트림을 유지합니다
- 가능한 한 많은 캐시된 콘텐츠를 공유하도록 요청을 구조화합니다
배치에서 프롬프트 캐싱을 구현하는 예:
이 예제에서 배치의 두 요청 모두 동일한 시스템 메시지와 캐시 적중 가능성을 높이기 위해 cache_control
로 표시된 Pride and Prejudice의 전체 텍스트를 포함합니다.
효과적인 배치 처리를 위한 모범 사례
Batches API를 최대한 활용하려면:
- 배치 처리 상태를 정기적으로 모니터링하고 실패한 요청에 대한 적절한 재시도 로직을 구현합니다.
- 순서가 보장되지 않으므로 결과를 요청과 쉽게 일치시키기 위해 의미 있는
custom_id
값을 사용합니다. - 더 나은 관리 가능성을 위해 매우 큰 데이터셋을 여러 배치로 나누는 것을 고려합니다.
- 유효성 검사 오류를 피하기 위해 Messages API로 단일 요청 형태를 드라이 런합니다.
일반적인 문제 해결
예상치 못한 동작이 발생하는 경우:
- 총 배치 요청 크기가 256MB를 초과하지 않는지 확인합니다. 요청 크기가 너무 크면 413
request_too_large
오류가 발생할 수 있습니다. - 배치의 모든 요청에 대해 지원되는 모델을 사용하고 있는지 확인합니다.
- 배치의 각 요청에 고유한
custom_id
가 있는지 확인합니다. - 배치
created_at
(처리ended_at
이 아님) 시간으로부터 29일이 지나지 않았는지 확인합니다. 29일이 지나면 결과를 더 이상 볼 수 없습니다. - 배치가 취소되지 않았는지 확인합니다.
배치의 한 요청이 실패해도 다른 요청의 처리에는 영향을 주지 않습니다.
배치 저장 및 개인정보 보호
-
Workspace 격리: 배치는 생성된 Workspace 내에서 격리됩니다. 해당 Workspace와 연결된 API 키 또는 Console에서 Workspace 배치를 볼 수 있는 권한이 있는 사용자만 액세스할 수 있습니다.
-
결과 가용성: 배치 결과는 배치 생성 후 29일 동안 사용할 수 있어 검색 및 처리를 위한 충분한 시간을 제공합니다.