배치 작업 관리

비동기 대량 요청을 제출하고 배치 실행 상태를 확인합니다.

OpenAI 호환 Batch API를 통해 지원되는 모델 엔드포인트 전반에 걸쳐 비동기 일괄 처리 요청을 제출합니다.

POST/openai/v1/batches

요청 본문

필드타입필수 여부설명
input_file_idstring예목적이 batch로 설정된 업로드된 파일의 고유 식별자.
endpointstring예대상 엔드포인트(/v1/chat/completions, /v1/completions, /v1/responses 또는 /v1/embeddings).
completion_windowstring예완료 기간(현재 24h로 고정됨).
metadataobject아니요추적 및 감사를 위한 선택적 키-값 메타데이터 쌍.

입력 파일은 최대 50,000개 항목 및 200 MiB 크기 제한을 준수하는 UTF-8 JSONL 형식이어야 합니다. 각 줄은 고유하고 비어있지 않은 custom_id, POST 방식의 method, 배치의 endpoint와 일치하는 url, 객체 형태의 body(엄격한 선불 배치의 경우 body 내 model 필수)를 포함하는 유효한 JSON 객체여야 합니다. 네이티브 선불 배치는 자금 승인 전 저장된 파일 체크섬 및 실행 정책을 검증하며, 공급자 전송 전 모든 항목의 예약금이 원자적으로 확정됩니다. 총 잔액이 부족하면 부분 처리 없이 HTTP 402를 반환합니다. 호환되지 않는 공급자 설정은 동일 배치 내에서 분할될 수 없으며 항목 수준의 공급자 간 장애 조치는 수행되지 않습니다.

배치 수명 주기

GET/openai/v1/batches/{batch_id}
POST/openai/v1/batches/{batch_id}/cancel
  • validating: 입력 파일 형식, JSONL 구문 및 항목 스키마 준수를 검증합니다.
  • in_progress: 지정된 공급자 자격 증명으로 배치 추론 작업을 실행합니다.
  • finalizing: 추론 결과를 집계하고 사용량 결제를 기록합니다.
  • completed: 처리가 성공적으로 완료되어 output_file_id 및 선택적 error_file_id를 생성합니다.
  • failed: 파일 유효성 검사 또는 배치 오케스트레이션이 완전히 실패한 종료 상태입니다.
  • cancelling: 요청에 따라 처리를 안전하게 중지하고 취소 상태로 전환합니다.
  • cancelled: 일괄 처리가 최종 완료 전에 중지된 상태입니다. 실패, 취소 또는 누락된 항목 결과가 공급자 비용 0을 증명하지 않으며, 결제는 공급자 기록과의 대조 조정을 위해 예약 자금을 보존합니다. AnyInt의 표준 상태는 cancelled입니다.
  • expired: 24시간 완료 기간을 초과했을 때 발생합니다. 확인되지 않은 실행은 대조 작업이 필요하며 공급자 비용 0원을 보장하지 않습니다.

배치 작업 및 결과 다운로드

GET/openai/v1/batches
  • 배치 목록 조회: GET /openai/v1/batches를 통해 인증된 조직 또는 프로젝트의 활성 및 과거 배치 작업을 조회합니다.
  • 객체 스토리지 및 다운로드: purpose: "batch" 파일 접수 및 배치 작업 실행은 공유 객체 스토리지(OBJECT_STORE_MODE)를 필요로 합니다. 작업 완료 후 결과 및 오류 JSONL 파일은 GET /openai/v1/files/{file_id}/content를 통해 다운로드할 수 있습니다.

호환 별칭

  • 게이트웨이는 호환성을 위해 /v1/batches를 허용하며, 새 통합에는 /openai/v1/batches 사용을 권장합니다.