Claude Platform Docs
Messages모델 기능

배치 처리

Message Batches API로 대량의 Messages 요청을 비동기적으로 처리하여 비용을 50퍼센트 절감하고 처리량을 높이세요.

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

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

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

Message Batches API

Message Batches API는 대량의 MessagesAPI 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요. 요청을 비동기적으로 처리하는 강력하고 비용 효율적인 방법입니다. 이 접근 방식은 즉각적인 응답이 필요하지 않은 작업에 적합하며, 대부분의 배치는 1시간 이내에 완료되면서 비용을 50퍼센트 절감하고 처리량을 높여 줍니다.

이 가이드 외에도 API 레퍼런스를 직접 살펴볼API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요. 수 있습니다.

Message Batches API 작동 방식

Message Batches API에 요청을 보내면:

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

이는 즉각적인 결과가 필요하지 않은 대량 작업에 특히 유용합니다. 예를 들면 다음과 같습니다:

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

배치 제한 사항

  • 메시지 배치는 100,000개의 Message 요청 또는 256 MB 크기 중 먼저 도달하는 쪽으로 제한됩니다.
  • 시스템은 각 배치를 최대한 빠르게 처리하며, 대부분의 배치는 1시간 이내에 완료됩니다. 배치 결과는 모든 메시지가 완료되었을 때 또는 24시간이 지난 후 중 먼저 도래하는 시점에 접근할 수 있습니다. 24시간 이내에 처리가 완료되지 않으면 배치는 만료됩니다.
  • 배치 결과는 생성 후 29일 동안 사용할 수 있습니다. 그 이후에도 배치를 볼 수는 있지만, 결과는 더 이상 다운로드할 수 없습니다.
  • 배치는 Claude Console의 워크스페이스에 범위가 지정됩니다. 요청이 실행되는 워크스페이스 내에서 생성된 모든 배치(및 그 결과)를 볼 수 있습니다.
  • “Rate limit”(속도 제한)은 Batches API HTTP 요청과 처리 대기 중인 배치 내 요청 수 모두에 적용됩니다. Message Batches API 속도 제한을 참조하세요. 또한 현재 수요와 요청량에 따라 처리 속도가 느려질 수 있습니다. 이 경우 24시간 후 만료되는 요청이 더 많아질 수 있습니다.
  • 높은 처리량과 동시 처리로 인해, 배치는 Claude Console에서 워크스페이스에 설정된 지출 한도를 약간 초과할 수 있습니다.
  • 배치에 포함된 각 요청의 max_tokensAPI 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요.는 최소 1 이상이어야 합니다. max_tokens: 0(캐시 사전 준비)은 배치 내에서 지원되지 않습니다. 배치 처리 중에 기록된 임시 캐시 항목은 후속 요청이 실행되기 전에 만료될 가능성이 높기 때문입니다.

지원 모델

모든 활성 모델이 Message Batches API를 지원합니다.

배치로 처리할 수 있는 항목

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

  • 비전
  • 도구 사용(모든 서버 도구 포함: 웹 검색, 웹 가져오기, 코드 실행, MCP 커넥터, 어드바이저, 도구 검색)
  • 시스템 메시지
  • 멀티턴 대화
  • 확장 사고
  • 대부분의 베타 기능

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

소수의 Messages API 매개변수는 배치 요청에서 지원되지 않습니다. 이 중 하나라도 포함하면 유효성 검사 오류가 반환됩니다:

매개변수이유
stream: true배치 결과는 스트림이 아닌 단일 파일로 반환됩니다.
speed (Fast mode)Fast mode는 동기식 지연 시간을 조정하는 기능으로, 비동기 배치 처리에는 적용되지 않습니다.
fallbacks (서버 측 폴백)서버 측 폴백은 배치에 적용되지 않습니다. 거부된 요청을 재시도하려면 Message Batches에서의 거부를 참조하세요.
max_tokens: 0배치 제한 사항을 참조하세요.

가격

Batches API는 상당한 비용 절감 효과를 제공합니다. 모든 사용량은 표준 API 가격의 50퍼센트로 청구됩니다.

모델배치 토큰
이름입력출력
Claude Fable 5.2For demanding reasoning and long-horizon agentic work
US$4 /
US$20 / MTok
Claude Opus 5.5For long-running agentic coding and knowledge work
US$2 / MTok
US$10 / MTok
Claude Sonnet 5.5The best combination of speed and intelligence
US$1 / MTok
US$5 / MTok
Claude Haiku 5.5For high-volume, latency-sensitive tasks such as classification, extraction, and routing
US$0.05 / MTok100,000토큰 이하 프롬프트 기준
US$0.25 / MTok
US$0.25 / MTok100,000토큰을 초과하는 프롬프트의 경우
US$1.25 / MTok
US$4 / MTok
US$20 / MTok
US$5 / MTok
US$25 / MTok
US$5 / MTok
US$25 / MTok
US$5 / MTok
US$25 / MTok
US$5 / MTok
US$25 / MTok
US$2.50 / MTok
US$12.50 / MTok
US$2.50 / MTok
US$12.50 / MTok
US$2.50 / MTok
US$12.50 / MTok
US$2.50 / MTok
US$12.50 / MTok
US$2.50 / MTok
US$12.50 / MTok
Claude Opus 4.1
US$7.50 / MTok
US$37.50 / MTok
Claude Opus 4
US$7.50 / MTok
US$37.50 / MTok
US$1 / MTok
US$5 / MTok
US$1.50 / MTok
US$7.50 / MTok
US$1.50 / MTok
US$7.50 / MTok
Claude Sonnet 4
US$1.50 / MTok
US$7.50 / MTok
US$0.50 / MTok
US$2.50 / MTok

Message Batches API 사용 방법

배치 준비 및 생성

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

  • Messages 요청을 식별하기 위한 고유한 custom_idAPI 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요.. 1~64자여야 하며 영숫자, 하이픈, 밑줄만 포함해야 합니다(^[a-zA-Z0-9_-]{1,64}$와 일치).
  • 표준 Messages APIAPI 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요. 매개변수가 포함된 paramsAPI 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요. 객체

이 목록을 requests 매개변수에 전달하여 배치를 생성API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요.할 수 있습니다:

from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request

client = anthropic.Anthropic()

message_batch = client.messages.batches.create(
    requests=[
        Request(
            custom_id="my-first-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-5-5",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hello, world",
                    }
                ],
            ),
        ),
        Request(
            custom_id="my-second-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-5-5",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hi again, friend",
                    }
                ],
            ),
        ),
    ]
)

print(message_batch)

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

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

Output
{
  "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_statusAPI 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요. 필드는 배치가 현재 어떤 처리 단계에 있는지를 나타냅니다. 처음에는 in_progress로 시작하며, 배치의 모든 요청 처리가 완료되고 결과가 준비되면 ended로 업데이트됩니다. Console을 방문하거나 조회 엔드포인트를 사용하여 배치 상태를 모니터링할 수 있습니다.

Retrieve a Message Batch

GET/v1/messages/batches/{message_batch_id}

This endpoint is idempotent and can be used to poll for Message Batch completion. To access the results of a Message Batch, make a request to the results_url field in the response.

메시지 배치 완료 폴링

메시지 배치를 폴링하려면 해당 id가 필요하며, 이는 배치를 생성할 때의 응답이나 배치 목록 조회를 통해 제공됩니다. 처리가 끝날 때까지 주기적으로 배치 상태를 확인하는 폴링 루프를 구현할 수 있습니다:

import time

client = anthropic.Anthropic()

MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"

message_batch = None
while True:
    message_batch = client.messages.batches.retrieve(MESSAGE_BATCH_ID)
    if message_batch.processing_status == "ended":
        break

    print(f"Batch {MESSAGE_BATCH_ID} is still processing...")
    time.sleep(60)
print(message_batch)

모든 메시지 배치 나열

목록 엔드포인트API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요.를 사용하여 워크스페이스의 모든 메시지 배치를 나열할 수 있습니다. API는 페이지네이션을 지원하며, 필요에 따라 추가 페이지를 자동으로 가져옵니다:

client = anthropic.Anthropic()

# 필요에 따라 다음 페이지를 자동으로 가져옵니다.
for message_batch in client.messages.batches.list(limit=20):
    print(message_batch)

배치 결과 가져오기

배치 처리가 끝나면 배치의 각 Messages 요청에는 결과가 있습니다. 결과 유형은 네 가지입니다:

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

배치의 request_counts 객체는 아직 처리 중인 요청 수와 각 결과 유형별 요청 수를 집계합니다.

request_counts: MessageBatchRequestCounts { canceled, errored, expired, 2 more }

Tallies requests within the Message Batch, categorized by their status.

Requests start as processing and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch.

canceled: number

Number of requests in the Message Batch that have been canceled.

This is zero until processing of the entire Message Batch has ended.

default0
errored: number

Number of requests in the Message Batch that encountered an error.

This is zero until processing of the entire Message Batch has ended.

default0
expired: number

Number of requests in the Message Batch that have expired.

This is zero until processing of the entire Message Batch has ended.

default0
processing: number

Number of requests in the Message Batch that are processing.

default0
succeeded: number

Number of requests in the Message Batch that have completed successfully.

This is zero until processing of the entire Message Batch has ended.

default0

배치 결과는 메시지 배치의 results_urlAPI 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요. 속성에서 다운로드할 수 있으며, 조직 권한이 허용하는 경우 Console에서도 다운로드할 수 있습니다. 결과의 크기가 클 수 있으므로, 한 번에 모두 다운로드하기보다는 결과를 스트리밍API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요.하는 것이 좋습니다.

client = anthropic.Anthropic()

# 결과 파일을 메모리 효율적인 청크 단위로 스트리밍하여 한 번에 하나씩 처리합니다
for result in client.messages.batches.results(
    "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
):
    outcome = result.result
    match outcome.type:
        case "succeeded":
            print(f"Success! {result.custom_id}")
        case "errored":
            if outcome.error.error.type == "invalid_request_error":
                # 요청을 다시 보내기 전에 요청 본문을 수정해야 합니다
                print(f"Validation error {result.custom_id}")
            else:
                # 요청을 바로 재시도할 수 있습니다
                print(f"Server error {result.custom_id}")
        case "expired":
            print(f"Request expired {result.custom_id}")

결과는 .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-5-5","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-5-5","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는 표준 오류 형태로 설정됩니다.

배치 결과는 배치를 생성한 요청의 API 버전을 사용합니다.

메시지 배치 취소

취소 엔드포인트API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요.를 사용하여 현재 처리 중인 메시지 배치를 취소할 수 있습니다. 취소 직후 배치의 processing_status는 canceling이 됩니다. 앞서 설명한 것과 동일한 폴링 기법을 사용하여 취소가 완료될 때까지 기다릴 수 있습니다. 취소된 배치는 최종적으로 ended 상태가 되며, 취소 전에 처리된 요청에 대한 부분 결과가 포함될 수 있습니다.

client = anthropic.Anthropic()

MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"

message_batch = client.messages.batches.cancel(
    MESSAGE_BATCH_ID,
)
print(message_batch)

응답은 canceling 상태의 배치를 보여줍니다:

Output
{
  "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message_batch",
  "processing_status": "canceling",
  "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": "2024-09-24T18:39:03.114875Z",
  "results_url": null
}

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

Message Batches API는 “prompt caching”(프롬프트 캐싱)을 지원하므로, 배치 요청의 비용과 처리 시간을 줄일 수 있습니다. 프롬프트 캐싱과 Message Batches의 가격 할인은 중첩될 수 있어, 두 기능을 함께 사용하면 더 큰 비용 절감 효과를 얻을 수 있습니다. 다만 배치 요청은 비동기적이고 동시에 처리되므로, 캐시 적중은 최선의 노력 기준으로 제공됩니다. 사용자는 트래픽 패턴에 따라 일반적으로 30퍼센트에서 98퍼센트 범위의 캐시 적중률을 경험합니다.

배치 요청에서 캐시 적중 가능성을 극대화하려면:

  1. 배치 내 모든 Message 요청에 동일한 cache_control 블록을 포함하세요.
  2. 캐시 항목이 5분의 수명 후 만료되지 않도록 요청을 꾸준히 이어서 보내세요.
  3. 캐시된 콘텐츠를 최대한 많이 공유하도록 요청을 구성하세요.

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

from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request

client = anthropic.Anthropic()

message_batch = client.messages.batches.create(
    requests=[
        Request(
            custom_id="my-first-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-5-5",
                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.",
                    }
                ],
            ),
        ),
        Request(
            custom_id="my-second-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-5-5",
                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로 표시된 동일한 시스템 메시지와 오만과 편견 전문을 포함합니다.

서버 도구와 에이전트 루프

모든 서버 도구(웹 검색, 웹 가져오기, 코드 실행, MCP 커넥터, 어드바이저, 도구 검색)는 배치 요청에서 작동합니다. 배치 워커는 동기식 Messages API와 동일한 서버 측 에이전트 루프를 실행합니다.

유지해야 할 열린 연결이 없으므로, 배치 루프는 stop_reason: "pause_turn"을 반환하기 전에 동기식 요청보다 한 턴에서 더 많은 반복을 실행할 수 있습니다. 배치 결과가 pause_turn으로 반환되면 해당 턴은 완료되지 않은 것입니다. pause_turn 연속 패턴에 나온 대로 일시 중지된 어시스턴트 콘텐츠를 후속 요청(배치 또는 동기식)으로 제출하여 계속할 수 있습니다.

배치 워커는 또한 각 조직에 대해 web_search를 조절하여, 동시성이 높은 배치 처리가 조직의 웹 검색 속도 제한을 소진하지 않도록 합니다. 배치는 조절된 요청을 자동으로 재시도하므로 직접 처리할 필요는 없지만, 매우 큰 웹 검색 배치는 완료하는 데 더 오래 걸릴 수 있습니다.

확장 출력 (베타)

output-300k-2026-03-24 베타 헤더는 Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5.5, Claude Sonnet 5, Claude Sonnet 4.6 또는 Claude Haiku 5.5를 사용하는 배치 요청의 max_tokens 상한을 300,000으로 높입니다. 이 헤더를 포함하면 단일 턴에서 표준 128k max_tokens 제한보다 훨씬 긴 출력을 생성할 수 있습니다.

확장 출력은 책 분량의 초안 및 기술 문서와 같은 장문 생성, 포괄적인 구조화 데이터 추출, 대규모 코드 생성 스캐폴드, 긴 추론 체인에 사용하세요.

300k 토큰 단일 생성은 완료하는 데 1시간 이상 걸릴 수 있으므로, 24시간 처리 기간을 염두에 두고 배치 제출을 계획하세요. 표준 배치 가격(표준 API 가격의 50퍼센트)이 적용됩니다.

from anthropic.types.beta.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.beta.messages.batch_create_params import Request

client = anthropic.Anthropic()

message_batch = client.beta.messages.batches.create(
    betas=["output-300k-2026-03-24"],
    requests=[
        Request(
            custom_id="long-form-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-5-5",
                max_tokens=300_000,
                messages=[
                    {
                        "role": "user",
                        "content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices.",
                    }
                ],
            ),
        ),
    ],
)

print(message_batch)

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

Batches API를 효과적으로 사용하려면:

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

일반적인 문제 해결

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

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

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

배치 저장 및 개인정보 보호

  • 워크스페이스 격리: 배치는 생성된 워크스페이스 내에서 격리됩니다. 동일한 워크스페이스의 API 요청 또는 Console에서 워크스페이스 배치를 볼 수 있는 권한이 있는 사용자만 접근할 수 있습니다.

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

FAQ

제공 여부

배치 처리
Availability requirements for 배치 처리 are the same across all supported platforms.
API
  • Messages API
  • Managed Agents 지원되지 않음
모델
  • 모든 모델

데이터 처리

데이터 처리 개요

적용 엔드포인트

  • /v1/messages/batches
제로 데이터 보존적격 아님

29일 보존. 비동기 저장소 필요. 자세히 알아보기

HIPAA적격 아님

배치 처리는 배치 생성 후 최대 29일 동안 요청 및 응답 데이터를 저장합니다. 처리 후 언제든지 DELETE /v1/messages/batches/{batch_id}API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요. 엔드포인트를 사용하여 메시지 배치를 삭제할 수 있습니다. 진행 중인 배치를 삭제하려면 먼저 취소하세요. 비동기 처리를 위해서는 배치 완료 및 결과 조회 시까지 입력과 출력 모두를 서버 측에 저장해야 합니다.

다음 단계

출처 표시가 포함된 검색 결과를 제공하여 RAG 애플리케이션에서 자연스러운 인용을 얻으세요.

배치 내 요청 간에 공유되는 프롬프트 접두사를 캐싱하여 비용과 지연 시간을 줄이세요.

이 페이지가 도움이 되었나요?