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

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

메시지 배치 API는 이 패턴의 첫 번째 구현입니다.

​
메시지 배치 API

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

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

​
메시지 배치 API 작동 방식

메시지 배치 API에 요청을 보내면:

  1. 시스템은 제공된 메시지 요청으로 새 메시지 배치를 생성합니다.
  2. 그런 다음 배치는 비동기적으로 처리되며, 각 요청은 독립적으로 처리됩니다.
  3. 배치의 상태를 폴링하고 모든 요청에 대한 처리가 끝나면 결과를 검색할 수 있습니다.

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

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

​
배치 제한사항

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

​
지원되는 모델

메시지 배치 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)

​
배치 처리 가능한 항목

메시지 API에 할 수 있는 모든 요청은 배치에 포함될 수 있습니다. 여기에는 다음이 포함됩니다:

  • 비전
  • 도구 사용
  • 시스템 메시지
  • 다중 턴 대화
  • 모든 베타 기능

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

​
가격 책정

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

ModelBatch inputBatch output
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$1.50 / MTok$7.50 / MTok
Claude Haiku 3.5$0.40 / MTok$2 / MTok
Claude Opus 3$7.50 / MTok$37.50 / MTok
Claude Haiku 3$0.125 / MTok$0.625 / MTok

​
메시지 배치 API 사용 방법

​
배치 준비 및 생성

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

  • 메시지 요청을 식별하기 위한 고유한 custom_id
  • 표준 메시지 API 매개변수가 포함된 params 객체

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

curl https://api.anthropic.com/v1/messages/batches \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "requests": [
        {
            "custom_id": "my-first-request",
            "params": {
                "model": "claude-opus-4-20250514",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hello, world"}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-4-20250514",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hi again, friend"}
                ]
            }
        }
    ]
}'

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

메시지 API로 배치 요청 테스트하기

각 메시지 요청에 대한 params 객체의 유효성 검사는 비동기적으로 수행되며, 유효성 검사 오류는 전체 배치 처리가 끝날 때 반환됩니다. 먼저 메시지 API로 요청 형태를 확인하여 입력을 올바르게 구성하고 있는지 확인할 수 있습니다.

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

JSON
{
  "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로 업데이트됩니다. 콘솔을 방문하거나 검색 엔드포인트를 사용하여 배치 상태를 모니터링할 수 있습니다:

curl https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d \
 --header "x-api-key: $ANTHROPIC_API_KEY" \
 --header "anthropic-version: 2023-06-01" \
 | sed -E 's/.*"id":"([^"]+)".*"processing_status":"([^"]+)".*/Batch \1 processing status is \2/'

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

​
배치 결과 검색

배치 처리가 종료되면 배치의 각 메시지 요청에 결과가 생깁니다. 결과 유형은 4가지입니다:

결과 유형설명
succeeded요청이 성공했습니다. 메시지 결과를 포함합니다.
errored요청에 오류가 발생하여 메시지가 생성되지 않았습니다. 가능한 오류에는 잘못된 요청과 내부 서버 오류가 포함됩니다. 이러한 요청에 대해서는 요금이 청구되지 않습니다.
canceled이 요청이 모델로 전송되기 전에 사용자가 배치를 취소했습니다. 이러한 요청에 대해서는 요금이 청구되지 않습니다.
expired이 요청이 모델로 전송되기 전에 배치가 24시간 만료 시간에 도달했습니다. 이러한 요청에 대해서는 요금이 청구되지 않습니다.

배치의 request_counts에서 결과 개요를 볼 수 있으며, 이는 각 상태에 도달한 요청 수를 보여줍니다.

배치 결과는 메시지 배치의 results_url 속성에서 다운로드할 수 있으며, 조직 권한이 허용하는 경우 콘솔에서도 다운로드할 수 있습니다. 결과의 크기가 잠재적으로 클 수 있기 때문에, 모든 결과를 한 번에 다운로드하기보다는 결과를 스트리밍하는 것이 좋습니다.

#!/bin/sh
curl "https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  | grep -o '"results_url":[[:space:]]*"[^"]*"' \
  | cut -d'"' -f4 \
  | while read -r url; do
    curl -s "$url" \
      --header "anthropic-version: 2023-06-01" \
      --header "x-api-key: $ANTHROPIC_API_KEY" \
      | sed 's/}{/}\n{/g' \
      | while IFS= read -r line
    do
      result_type=$(echo "$line" | sed -n 's/.*"result":[[:space:]]*{[[:space:]]*"type":[[:space:]]*"\([^"]*\)".*/\1/p')
      custom_id=$(echo "$line" | sed -n 's/.*"custom_id":[[:space:]]*"\([^"]*\)".*/\1/p')
      error_type=$(echo "$line" | sed -n 's/.*"error":[[:space:]]*{[[:space:]]*"type":[[:space:]]*"\([^"]*\)".*/\1/p')

      case "$result_type" in
        "succeeded")
          echo "Success! $custom_id"
          ;;
        "errored")
          if [ "$error_type" = "invalid_request" ]; then
            # Request body must be fixed before re-sending request
            echo "Validation error: $custom_id"
          else
            # Request can be retried directly
            echo "Server error: $custom_id"
          fi
          ;;
        "expired")
          echo "Expired: $line"
          ;;
      esac
    done
  done

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

.jsonl file
{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-4-20250514","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-opus-4-20250514","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가 표준 오류 형태로 설정됩니다.

배치 결과는 입력 순서와 일치하지 않을 수 있습니다

배치 결과는 어떤 순서로든 반환될 수 있으며, 배치가 생성될 때 요청 순서와 일치하지 않을 수 있습니다. 위 예제에서는 두 번째 배치 요청에 대한 결과가 첫 번째 요청보다 먼저 반환됩니다. 결과를 해당 요청과 올바르게 일치시키려면 항상 custom_id 필드를 사용하세요.

​
메시지 배치와 함께 프롬프트 캐싱 사용하기

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

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

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

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

curl https://api.anthropic.com/v1/messages/batches \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "requests": [
        {
            "custom_id": "my-first-request",
            "params": {
                "model": "claude-opus-4-20250514",
                "max_tokens": 1024,
                "system": [
                    {
                        "type": "text",
                        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
                    },
                    {
                        "type": "text",
                        "text": "<the entire contents of Pride and Prejudice>",
                        "cache_control": {"type": "ephemeral"}
                    }
                ],
                "messages": [
                    {"role": "user", "content": "Analyze the major themes in Pride and Prejudice."}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-4-20250514",
                "max_tokens": 1024,
                "system": [
                    {
                        "type": "text",
                        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
                    },
                    {
                        "type": "text",
                        "text": "<the entire contents of Pride and Prejudice>",
                        "cache_control": {"type": "ephemeral"}
                    }
                ],
                "messages": [
                    {"role": "user", "content": "Write a summary of Pride and Prejudice."}
                ]
            }
        }
    ]
}'

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

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

배치 API를 최대한 활용하려면:

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

​
일반적인 문제 해결

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

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

배치의 한 요청 실패가 다른 요청의 처리에 영향을 미치지 않는다는 점에 유의하세요.

​
배치 저장 및 개인정보 보호

  • 워크스페이스 격리: 배치는 생성된 워크스페이스 내에서 격리됩니다. 해당 워크스페이스와 연결된 API 키 또는 콘솔에서 워크스페이스 배치를 볼 수 있는 권한이 있는 사용자만 액세스할 수 있습니다.

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

​
FAQ