ZeroGPU를 위한 배치 처리 (Batch Processing) 소개

한 번에 하나의 요청씩 AI 추론 (Inference)을 실행하는 것은 실시간 제품 경험에는 적합합니다. 하지만 많은 워크로드 (Workloads)는 즉각적인 응답을 필요로 하지 않습니다. 데이터 보강 (Data enrichment), 분류 (Classification), 추출 (Extraction), 콘텐츠 모더레이션 (Content moderation), 요약 (Summarization), 그리고 오프라인 분석 (Offline analytics)은 종종 비동기적 (Asynchronously)으로 처리될 수 있는 수백 또는 수천 개의 요청을 포함합니다.

그 지점에서 ZeroGPU 배치 API (Batch API)가 등장합니다.

배치 처리 (Batch Processing)를 통해 JSONL 파일을 업로드하고, 이를 배치 작업 (Batch job)으로 제출한 다음, 처리가 완료되면 결과를 가져올 수 있습니다. 이는 즉각적인 응답 시간보다 처리량 (Throughput), 신뢰성 (Reliability), 그리고 단순함 (Simplicity)이 더 중요한 대규모 비동기 워크로드 (Asynchronous workloads)를 위해 설계되었습니다.

왜 배치 처리 (Batch Processing)인가요?

많은 AI 워크플로 (Workflows)는 본질적으로 비동기적 (Asynchronous)입니다.
예를 들어, 다음과 같은 작업을 원할 수 있습니다:

• 수천 개의 문서 분류 (Classify).
• 고객 기록에서 구조화된 데이터 추출 (Extract).
• 과거의 사용자 생성 콘텐츠에 대해 콘텐츠 모더레이션 (Content moderation) 실행.
• 지원 티켓, 리뷰 또는 연구 노트 요약 (Summarize).
• 백필 (Backfills) 또는 반복적인 데이터 파이프라인 (Data pipelines) 처리.

각 요청을 개별적으로 보내는 것은 불필요한 오케스트레이션 (Orchestration) 복잡성을 더할 수 있습니다. 재시도 로직 (Retry logic), 요청 추적 (Request tracking), 출력 매칭 (Output matching), 속도 제한 관리 (Rate management), 그리고 실패 처리 (Failure handling)가 필요하기 때문입니다.

배치 API (Batch API)는 더 깔끔한 워크플로 (Workflow)를 제공합니다.

작동 방식
ZeroGPU의 배치 처리 (Batch Processing)는 간단한 파일 기반 흐름을 따릅니다:

1. JSONL 입력 파일을 생성합니다.
2. Files API를 사용하여 파일을 업로드합니다.
3. 반환된 파일 ID를 사용하여 배치를 생성합니다.
4. 배치가 완료될 때까지 폴링 (Poll)합니다.
5. 출력 파일과 에러 파일을 다운로드합니다.

JSONL 파일의 각 라인은 하나의 요청을 나타냅니다. ZeroGPU는 이러한 요청들을 비동기적 (Asynchronously)으로 처리하고 결과를 출력 파일에 다시 기록합니다.

최소한의 입력 라인은 다음과 같습니다:

{"custom_id":"request-1","method":"POST","url":"/v1/chat/completions","body":{"model":"your-model-id","messages":[{"role":"user","content":"Classify this text."}]}}

custom_id는 출력 결과에 포함되어 반환되므로, 모든 결과를 원래의 입력값과 매칭할 수 있습니다.

대규모 AI 워크로드(AI Workloads)를 위해 설계됨

Batch API는 클라이언트 연결을 계속 유지하거나 자체적인 작업 오케스트레이션 레이어 (Job Orchestration Layer)를 구축하지 않고도 대량의 데이터를 처리해야 할 때 특히 유용합니다.

ZeroGPU는 현재 /v1/chat/completions에 대한 배치 작업 (Batch Jobs)을 지원하며, JSONL 파일은 /v1/files를 통해 업로드합니다.

핵심 엔드포인트 (Endpoints)는 다음과 같습니다:

POST /v1/files: 입력 JSONL 업로드
POST /v1/batches: 배치 작업 생성
GET /v1/batches/{batch_id}: 상태 확인
...

이를 통해 배치 처리 (Batch Processing)를 기존 백엔드 시스템, 크론 잡 (Cron Jobs), 데이터 파이프라인 (Data Pipelines) 및 내부 도구에 쉽게 통합할 수 있습니다.

OpenAI 호환 구조 (OpenAI-Compatible Shape)
ZeroGPU의 Batch 및 Files API는 ZeroGPU 인증 헤더 (Authentication Headers)를 사용하면서도, OpenAI 스타일의 배치 워크플로 (Batch Workflow)와 와이어 호환성 (Wire-compatible)을 유지합니다:

x-api-key: your-api-key
x-project-id: your-project-id

즉, OpenAI 배치 작업에 익숙한 개발자라면 ZeroGPU의 라우팅 (Routing), 프로젝트 격리 (Project Isolation), 로깅 (Logging) 및 모델 인프라 (Model Infrastructure)를 그대로 활용하면서도 이질감 없이 사용할 수 있습니다.

언제 배치를 사용해야 하나요?
사용자가 응답을 기다리고 있는 경우에는 실시간 API (Real-time API)를 사용하세요.
작업이 백그라운드 (Background)에서 수행될 수 있는 경우에는 Batch API를 사용하세요.
다음과 같은 경우에 적합합니다:

• 야간 데이터 처리 (Nightly data processing)
• 대량 문서 분류 (Bulk document classification)
• 대규모 추출 작업 (Large-scale extraction jobs)
• 오프라인 분석 (Offline analytics)
• 백필 (Backfills)
• 평가 데이터셋 (Evaluation datasets)
• 과거 데이터 재처리 (Reprocessing historical data)

배치 작업은 각 요청이 안정적인 custom_id를 가지고 있고, 출력이 다운로드 가능한 파일로 작성되기 때문에 감사 (Audit)하기에도 더 쉽습니다.

시작하기

가장 빠르게 시도하는 방법:

1. JSONL 파일을 준비합니다.
2. POST /v1/files로 업로드합니다.
3. POST /v1/batches로 배치를 생성합니다.
4. 완료될 때까지 폴링 (Poll)합니다.
5. 출력 파일을 다운로드합니다.

ZeroGPU 문서에서 새로운 인터랙티브 플레이그라운드 (Interactive Playgrounds)를 체험해 볼 수 있습니다:

파일 업로드: /api-reference/batch/upload-file
배치 생성: /api-reference/batch/create-batch
배치 조회: /api-reference/batch/retrieve-batch
...

배치 처리 (Batch Processing)를 사용하면 큐 (Queues), 워커 (Workers), 재시도 (Retries) 또는 GPU 인프라를 관리할 필요 없이 대규모로 AI 워크로드 (AI workloads)를 실행하는 것이 더 쉬워집니다.

ZeroGPU가 실행을 처리합니다. 여러분은 데이터에만 집중하세요.