메시지 배치 (베타)

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

이 가이드와 함께 API 레퍼런스를 직접 살펴볼 수 수 있습니다.

​

메시지 배치 API 작동 방식

메시지 배치 API에 요청을 보낼 때:

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

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

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

​

배치 제한사항

• 메시지 배치는 10,000개의 메시지 요청 또는 32MB 크기 중 먼저 도달하는 제한으로 제한됩니다.
• 배치는 응답 생성에 최대 24시간이 걸리지만, 처리는 이보다 일찍 끝날 수 있습니다. 전체 배치의 처리가 끝날 때까지 배치 결과를 사용할 수 없습니다. 24시간 내에 처리가 완료되지 않으면 배치가 만료됩니다.
• 배치 결과는 생성 후 29일 동안 사용할 수 있습니다. 그 이후에도 배치를 볼 수는 있지만, 결과는 더 이상 다운로드할 수 없습니다.
• 배치는 Workspace에 범위가 지정됩니다. API 키가 속한 Workspace 내에서 생성된 모든 배치와 그 결과를 볼 수 있습니다.
• 속도 제한은 배치 내 요청 수가 아닌 Batches API HTTP 요청에 적용됩니다. 또한 현재 수요와 요청 볼륨에 따라 처리 속도가 늦춰질 수 있습니다. 이 경우 24시간 후에 더 많은 요청이 만료되는 것을 볼 수 있습니다.
• 높은 처리량과 동시 처리로 인해 배치가 Workspace의 구성된 지출 한도를 약간 초과할 수 있습니다.

​

지원되는 모델

메시지 배치 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
• 도구 사용
• 시스템 메시지
• 다중 턴 대화
• 모든 베타 기능

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

​

가격

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

​

메시지 배치 API 사용 방법

​

배치 준비 및 생성

메시지 배치는 메시지를 생성하기 위한 요청 목록으로 구성됩니다. 개별 요청의 형태는 다음으로 구성됩니다:

• 메시지 요청을 식별하기 위한 고유한 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
}

​

배치 추적

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

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

​

배치 결과 검색

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

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

배치의 결과는 Console과 메시지 배치의 results_url에서 다운로드할 수 있습니다. 결과의 크기가 잠재적으로 클 수 있기 때문에, 한 번에 모두 다운로드하는 대신 결과를 스트리밍하는 것이 좋습니다.

결과는 .jsonl 형식이며, 각 줄은 메시지 배치의 단일 요청 결과를 나타내는 유효한 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":"안녕하세요! 다시 만나서 반갑습니다. 오늘 어떻게 도와드릴까요? 특별히 이야기하고 싶은 주제나 질문이 있으신가요?"}],"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":"안녕하세요! 오늘 어떻게 도와드릴까요? 질문이 있으시거나 이야기하고 싶은 주제가 있다면 말씀해 주세요."}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":10,"output_tokens":34}}}}

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

​

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

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

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

​

일반적인 문제 해결

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

• 전체 배치 요청 크기가 32MB를 초과하지 않는지 확인하세요. 요청 크기가 너무 큰 경우 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"],
    ...
)