배치 처리는 대량의 요청을 효율적으로 처리하기 위한 강력한 접근 방식입니다. 요청을 한 번에 하나씩 즉각적인 응답으로 처리하는 대신, 배치 처리를 통해 여러 요청을 함께 제출하여 비동기적으로 처리할 수 있습니다. 이 패턴은 다음과 같은 경우에 특히 유용합니다:

• 대용량 데이터를 처리해야 할 때
• 즉각적인 응답이 필요하지 않을 때
• 비용 효율성을 최적화하고 싶을 때
• 대규모 평가나 분석을 실행할 때

Message Batches API는 이 패턴의 첫 번째 구현입니다.

​

Message Batches API

Message Batches API는 대량의 Messages 요청을 비동기적으로 처리하는 강력하고 비용 효율적인 방법입니다. 이 접근 방식은 즉각적인 응답이 필요하지 않은 작업에 적합하며, 대부분의 배치는 1시간 이내에 완료되면서 비용을 50% 절감하고 처리량을 증가시킵니다.

이 가이드와 함께 API 참조를 직접 살펴볼 수 수 있습니다.

​

Message Batches API 작동 방식

Message Batches API에 요청을 보내면:

1. 시스템은 제공된 Messages 요청으로 새로운 Message Batch를 생성합니다.
2. 배치는 각 요청이 독립적으로 처리되면서 비동기적으로 처리됩니다.
3. 모든 요청의 처리가 완료되면 배치의 상태를 확인하고 결과를 검색할 수 있습니다.

이는 즉각적인 결과가 필요하지 않은 대량 작업에 특히 유용합니다:

• 대규모 평가: 수천 개의 테스트 케이스를 효율적으로 처리
• 콘텐츠 모더레이션: 대량의 사용자 생성 콘텐츠를 비동기적으로 분석
• 데이터 분석: 대규모 데이터셋에 대한 인사이트나 요약 생성
• 대량 콘텐츠 생성: 다양한 목적(예: 제품 설명, 기사 요약)을 위한 대량의 텍스트 생성

​

배치 제한사항

• Message Batch는 100,000개의 Message 요청 또는 256 MB 크기 중 먼저 도달하는 제한으로 제한됩니다.
• 각 배치를 가능한 한 빠르게 처리하며, 대부분의 배치는 1시간 이내에 완료됩니다. 모든 메시지가 완료되거나 24시간이 경과한 후 중 먼저 도달하는 시점에 배치 결과에 접근할 수 있습니다. 24시간 이내에 처리가 완료되지 않으면 배치는 만료됩니다.
• 배치 결과는 생성 후 29일 동안 사용할 수 있습니다. 그 이후에도 배치를 볼 수는 있지만, 결과는 더 이상 다운로드할 수 없습니다.
• 배치는 Workspace에 범위가 지정됩니다. API 키가 속한 Workspace 내에서 생성된 모든 배치와 그 결과를 볼 수 있습니다.
• Batches API HTTP 요청과 처리 대기 중인 배치 내 요청 수에 대해 속도 제한이 적용됩니다. Message Batches API 속도 제한을 참조하세요. 또한 현재 수요와 요청 볼륨에 따라 처리 속도가 늦춰질 수 있습니다. 이 경우 24시간 후에 더 많은 요청이 만료되는 것을 볼 수 있습니다.
• 높은 처리량과 동시 처리로 인해 배치가 Workspace의 구성된 지출 제한을 약간 초과할 수 있습니다.

​

지원되는 모델

Message Batches API는 현재 다음을 지원합니다:

• Claude 3.5 Sonnet (claude-3-5-sonnet-20240620 및 claude-3-5-sonnet-20241022)
• Claude 3.5 Haiku (claude-3-5-haiku-20241022)
• Claude 3 Haiku (claude-3-haiku-20240307)
• Claude 3 Opus (claude-3-opus-20240229)

​

배치 가능한 항목

Messages API에 할 수 있는 모든 요청을 배치에 포함할 수 있습니다. 여기에는 다음이 포함됩니다:

• Vision
• Tool 사용
• System 메시지
• 다중 턴 대화
• 모든 베타 기능

배치의 각 요청이 독립적으로 처리되므로 단일 배치 내에서 다른 유형의 요청을 혼합할 수 있습니다.

​

가격

Batches API는 상당한 비용 절감을 제공합니다. 모든 사용량은 표준 API 가격의 50%로 청구됩니다.

​

Message Batches API 사용 방법

​

배치 준비 및 생성

Message Batch는 Message를 생성하기 위한 요청 목록으로 구성됩니다. 개별 요청의 형태는 다음으로 구성됩니다:

• Messages 요청을 식별하기 위한 고유한 custom_id
• 표준 Messages API 매개변수가 있는 params 객체

이 목록을 requests 매개변수에 전달하여 배치를 생성할 수 있습니다:

이 예제에서는 두 개의 별도 요청이 비동기 처리를 위해 함께 배치됩니다. 각 요청에는 고유한 custom_id가 있으며 Messages API 호출에 사용할 표준 매개변수를 포함합니다.

배치가 처음 생성되면 응답의 처리 상태는 in_progress가 됩니다.

{
  "id": "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
  "type": "message_batch",
  "processing_status": "in_progress",
  "request_counts": {
    "processing": 2,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2024-09-24T18:37:24.100435Z",
  "expires_at": "2024-09-25T18:37:24.100435Z",
  "cancel_initiated_at": null,
  "results_url": null
}

​

배치 추적

Message Batch의 processing_status 필드는 배치가 처리 중인 단계를 나타냅니다. in_progress로 시작하여 배치의 모든 요청 처리가 완료되고 결과가 준비되면 ended로 업데이트됩니다. Console을 방문하거나 검색 엔드포인트를 사용하여 배치의 상태를 모니터링할 수 있습니다:

처리가 완료되었는지 알기 위해 이 엔드포인트를 폴링할 수 있습니다.

​

배치 결과 검색

배치 처리가 완료되면 배치의 각 Messages 요청에 결과가 있습니다. 4가지 결과 유형이 있습니다:

배치의 request_counts에서 이러한 네 가지 상태에 도달한 요청 수를 보여주는 결과 개요를 볼 수 있습니다.

배치의 결과는 Console과 Message Batch의 results_url에서 다운로드할 수 있습니다. 결과의 잠재적인 큰 크기 때문에 모두 한 번에 다운로드하는 대신 결과를 스트리밍하는 것이 좋습니다.

결과는 .jsonl 형식이며, 각 줄은 Message Batch의 단일 요청 결과를 나타내는 유효한 JSON 객체입니다. 스트리밍된 각 결과에 대해 custom_id와 결과 유형에 따라 다른 작업을 수행할 수 있습니다. 다음은 결과 예시입니다:

{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-3-5-sonnet-20241022","content":[{"type":"text","text":"Hello again! It's nice to see you. How can I assist you today? Is there anything specific you'd like to chat about or any questions you have?"}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":11,"output_tokens":36}}}}
{"custom_id":"my-first-request","result":{"type":"succeeded","message":{"id":"msg_01FqfsLoHwgeFbguDgpz48m7","type":"message","role":"assistant","model":"claude-3-5-sonnet-20241022","content":[{"type":"text","text":"Hello! How can I assist you today? Feel free to ask me any questions or let me know if there's anything you'd like to chat about."}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":10,"output_tokens":34}}}}

결과에 오류가 있는 경우 result.error가 표준 오류 형태로 설정됩니다.

​

Message Batches에서 프롬프트 캐싱 사용

Message Batches API는 프롬프트 캐싱을 지원하여 배치 요청의 비용과 처리 시간을 잠재적으로 줄일 수 있습니다. 프롬프트 캐싱과 Message Batches의 가격 할인은 함께 적용되어 두 기능을 모두 사용할 때 더 큰 비용 절감을 제공할 수 있습니다. 그러나 배치 요청이 비동기적으로 동시에 처리되기 때문에 캐시 히트는 최선의 노력으로 제공됩니다. 사용자는 일반적으로 트래픽 패턴에 따라 30%에서 98%의 캐시 히트율을 경험합니다.

배치 요청에서 캐시 히트 가능성을 최대화하려면:

1. 배치 내의 모든 Message 요청에 동일한 cache_control 블록을 포함합니다
2. 캐시 항목이 5분의 수명 후에 만료되는 것을 방지하기 위해 꾸준한 요청 스트림을 유지합니다
3. 가능한 한 많은 캐시된 콘텐츠를 공유하도록 요청을 구성합니다

배치에서 프롬프트 캐싱을 구현하는 예:

이 예제에서는 배치의 두 요청 모두 동일한 시스템 메시지와 cache_control로 표시된 Pride and Prejudice의 전체 텍스트를 포함하여 캐시 히트 가능성을 높입니다.

​

효과적인 배치를 위한 모범 사례

Batches API를 최대한 활용하려면:

• 배치 처리 상태를 정기적으로 모니터링하고 실패한 요청에 대한 적절한 재시도 로직을 구현합니다.
• 순서가 보장되지 않으므로 결과를 요청과 쉽게 매칭할 수 있도록 의미 있는 custom_id 값을 사용합니다.
• 더 나은 관리를 위해 매우 큰 데이터셋을 여러 배치로 나누는 것을 고려합니다.
• 유효성 검사 오류를 피하기 위해 Messages API로 단일 요청 형태를 테스트합니다.

​

일반적인 문제 해결

예상치 못한 동작이 발생하는 경우:

• 전체 배치 요청 크기가 256 MB를 초과하지 않는지 확인합니다. 요청 크기가 너무 큰 경우 413 request_too_large 오류가 발생할 수 있습니다.
• 배치의 모든 요청에 지원되는 모델을 사용하고 있는지 확인합니다.
• 배치의 각 요청에 고유한 custom_id가 있는지 확인합니다.
• 배치 created_at(처리 ended_at가 아님) 시간으로부터 29일이 지나지 않았는지 확인합니다. 29일이 지나면 결과를 더 이상 볼 수 없습니다.
• 배치가 취소되지 않았는지 확인합니다.

배치의 한 요청 실패가 다른 요청의 처리에 영향을 미치지 않습니다.

​

배치 저장 및 개인정보 보호

• Workspace 격리: 배치는 생성된 Workspace 내에서 격리됩니다. 해당 Workspace와 연결된 API 키나 Console에서 Workspace 배치를 볼 수 있는 권한이 있는 사용자만 접근할 수 있습니다.

• 결과 가용성: 배치 결과는 배치가 생성된 후 29일 동안 사용할 수 있어 검색 및 처리에 충분한 시간을 제공합니다.

​

FAQ

import anthropic

client = anthropic.Anthropic()

message_batch = client.beta.messages.batches.create(
    betas: ["max-tokens-3-5-sonnet-2024-07-15"],
    ...
)