배치 처리

배치 처리 (Batch)

배치 지원은 실험적 기능이며, API가 패치 릴리스에서 변경될 수 있습니다.

배치(batch)를 사용하면 여러 독립적인 요청을 비동기 처리용으로 한 번에 제출할 수 있습니다. 프로바이더가 백그라운드에서 배치를 처리하므로, 모델이 결과를 생성하는 동안 애플리케이션이 요청을 계속 열어둘 필요가 없습니다. 분류, 요약, 콘텐츠 생성처럼 즉각적인 응답이 필요 없는 워크로드에 유용합니다.

배치 API는 type: 'text' 텍스트 생성과 type: 'image' 이미지 생성을 지원합니다.

출처: 공식문서

본문

AI SDK는 배치 라이프사이클을 위한 다섯 가지 함수를 제공합니다:

다섯 함수 모두 ai에서 내보내집니다. 아래 예시는 애플리케이션 코드에서 더 짧은 이름을 쓰기 위해 별칭을 사용합니다:

import {
  experimental_cancelBatch as cancelBatch,
  experimental_getBatchResults as getBatchResults,
  experimental_getBatchStatus as getBatchStatus,
  experimental_listBatches as listBatches,
  experimental_startBatch as startBatch,
} from 'ai';

취소와 나열은 선택적인 프로바이더 기능입니다. 이를 구현하지 않은 프로바이더와 함께 호출하면 UnsupportedFunctionalityError가 던져집니다. 아래 취소·나열 예시에서 provider는 각 해당 기능을 구현한 배치 프로바이더를 나타냅니다.

지원 프로바이더

배치 처리는 배치 인터페이스를 구현한 프로바이더가 필요합니다. 지원 여부는 프로바이더와 모델별로 다릅니다. 지원하는 퍼스트파티 프로바이더는 다음과 같습니다:

프로바이더 프로바이더 값 요청 타입 프로바이더 API
Anthropic anthropic text Message Batches API
Google google text, image Gemini Batch API
OpenAI openai text Batch API
xAI xai text, image Batch API
AI Gateway 글로벌 기본값 text Batch processing

지원 모델, 한도, 네이티브 배치 동작에 대해서는 프로바이더 문서를 참고하세요. 예를 들어 OpenAI 배치 지원은 openai.chat()이 아니라 Responses API로 제공되고, xAI 배치 지원도 xai.chat()이 아니라 Responses API로 제공됩니다.

배치 시작하기

startBatch에 프로바이더와 하나 이상의 고유하게 식별된 요청을 전달합니다. 각 요청은 type: 'text', 모델 ID, 그리고 텍스트 prompt 또는 messages 배열 중 하나를 지정해야 합니다. 프로바이더가 지원하면 요청마다 서로 다른 모델 ID를 쓸 수 있습니다. 각 요청은 instructions, maxOutputTokens, temperature, topP, topK, presencePenalty, frequencyPenalty, stopSequences, seed, reasoning 같은 일반적인 텍스트 생성 설정도 사용할 수 있습니다.

툴 정의와 툴 설정은 개별 요청에 제공됩니다. 같은 이름의 툴은 그것을 사용하는 모든 요청에서 동일한 정의를 가져야 합니다.

import { anthropic } from '@ai-sdk/anthropic';
import { experimental_startBatch as startBatch } from 'ai';

const provider = anthropic;

const batch = await startBatch({
  provider,
  requests: [
    {
      id: 'capital-france',
      type: 'text',
      model: 'claude-haiku-4-5',
      prompt: 'What is the capital of France?',
    },
    {
      id: 'capital-germany',
      type: 'text',
      model: 'claude-haiku-4-5',
      prompt: 'What is the capital of Germany?',
    },
  ],
});

배치 상태 확인

getBatchStatus로 배치의 최신 상태를 확인할 수 있습니다. 반환되는 상태로는 제출·처리 중·완료 같은 배치 수준 상태와, 각 요청의 개수·완료·실패·취소·만료 건수가 있습니다.

배치 취소

cancelBatch는 프로바이더가 이미 제출된 배치의 처리를 중단하도록 요청합니다. 취소가 보장되는 것은 아니며, 프로바이더 구현에 따라 시점과 결과가 달라집니다.

배치 나열

listBatches는 배치와 각각의 최신 상태를 나열합니다.

결과 조회

getBatchResults는 각 입력 요청의 최종 결과를 비동기 이터러블로 순회합니다. 각 항목은 하나의 입력 요청에 대한 ID와 종료 상태를 담고 있습니다:

for await (const item of getBatchResults({ provider: anthropic, batch })) {
  if (item.status === 'succeeded') {
    console.log(item.id, item.text);
  } else {
    console.error(item.id, item.status, item.error);
  }
}

성공한 항목은 다음을 포함합니다:

  • text — 연결된 텍스트 콘텐츠. 결과에 텍스트 파트가 없으면 빈 문자열일 수 있습니다.
  • content — 정규화된 정렬 콘텐츠 파트. 지원되는 경우 text, reasoning, files, sources, tool calls, tool results, provider content를 포함합니다.
  • finishReason와 선택적 rawFinishReason.
  • usage와 선택적 response 메타데이터.
  • 선택적 providerMetadata.

실패·취소·만료된 항목은 id와 상태를 포함합니다. 실패한 항목은 error를 포함하며, 취소·만료 항목도 포함할 수 있습니다. 배치 안의 한 요청이 실패했다고 모든 요청이 실패한 것은 아니므로 각 항목을 독립적으로 처리하세요.

배치 조회는 AI SDK 툴 루프를 실행하지 않으며 클라이언트가 정의한 execute 함수도 호출하지 않습니다. 프로바이더 정의 툴은 배치 처리의 일부로 프로바이더 측에서 실행될 수 있습니다. 결과 콘텐츠와 프로바이더 메타데이터는 신뢰할 수 없는 모델 출력으로 취급하고, 민감한 데이터를 포함할 수 있으므로 무분별하게 로깅하지 마세요.

요청 컨트롤

모든 배치 라이프사이클 함수는 현재 작업에 대해 providerOptions, headers, timeout, abortSignal을 받습니다. getBatchStatus, getBatchResults, listBatches는 maxRetries도 받습니다:

  • maxRetries는 상태·결과 조회·나열의 재시도를 제어합니다. 배치 생성이나 취소는 재시도하지 않습니다. 기본값은 2이며, 0으로 두면 재시도를 끕니다.
  • abortSignal은 현재 API 요청을 취소합니다.
  • timeout은 현재 HTTP 작업의 시간을 제한합니다.

이 컨트롤은 프로바이더와의 통신에 영향을 줍니다. 프로바이더의 처리 마감일을 바꾸거나 이미 제출된 배치를 취소하지는 않습니다.

더 알아보기