개발자들은 수천 개의 개별 API 호출을 보낼 때 느린 응답 시간과 높은 네트워크 비용으로 어려움을 겪습니다. 배치 API는 여러 개의 독립적인 요청을 하나의 작업으로 결합하여 지연 시간, 대역폭 사용량 및 연결 오버헤드를 줄여 이 문제를 해결합니다.
이 글에서는 배치 API가 무엇인지, 표준 API와 어떻게 다른지, 그리고 Novita AI의 배치 API가 구조화된 JSONL 입력, 효율적인 파일 처리, 신뢰할 수 있는 오류 추적을 통해 대규모 비동기 추론을 가능하게 하는 방법을 설명합니다. 또한 비용, 지연 시간, 처리량과 같은 주요 효율성 요소를 설명하고 구현 및 모니터링에 대한 간결한 가이드를 제공합니다.
[50% 할인으로 배치 추론 사용해보기
지원 모델로 더 빠르고 저렴하게 대규모 예측 실행:
qwen/qwen3-vl-235b-a22b-instruct, openai/gpt-oss-120b, deepseek/deepseek-r1-0528, qwen/qwen3-4b-fp8.](https://novita.ai/docs/guides/llm-batch-api)
50% 할인으로 배치 추론 사용해보기
지원 모델로 더 빠르고 저렴하게 대규모 예측 실행:
qwen/qwen3-vl-235b-a22b-instruct, openai/gpt-oss-120b, deepseek/deepseek-r1-0528, qwen/qwen3-4b-f
배치 API란?
배치 API: 여러 개의 독립적인 API 호출(예: GET, POST, PUT, DELETE)을 단일 HTTP 요청으로 결합합니다.
응답 구조: 서버는 모든 하위 요청의 결과를 순서대로 반환하며, 각각의 성공 또는 실패를 나타냅니다.
배치 API와 표준 API의 주요 차이점
일반 요청
클라이언트
├──► 요청 1 (/user/1)
│ └──► 서버 응답 1
├──► 요청 2 (/user/2)
│ └──► 서버 응답 2
└──► 요청 3 (/order)
└──► 서버 응답 3
배치 요청
클라이언트
└──► 단일 요청 (/batch)
├─ 하위 요청 1: GET /user/1
├─ 하위 요청 2: GET /user/2
└─ 하위 요청 3: POST /order
↓
서버가 모두 처리
↓
결합된 응답:
[결과1, 결과2, 결과3]
배치 API가 도움이 되는 경우:
네트워크 지연 시간 감소 – 여러 요청 대신 하나의 결합된 요청을 전송합니다.
대역폭 및 연결 오버헤드 절감 – 헤더와 핸드셰이크를 공유합니다.
클라이언트 성능 향상 – 특히 모바일 또는 느린 네트워크에서 유용합니다.
트랜잭션 로직 단순화 – 통합 오류 처리 또는 롤백이 가능합니다.
API 게이트웨이 처리량 최적화 – 요청 플러딩을 방지합니다.
배치 API의 대표적인 사용 사례
| 시나리오 | 설명 |
|---|---|
| 1. 대량 데이터 조회 | 여러 사용자, 제품 또는 게시물을 한 번에 검색하여 반복 요청을 방지합니다. |
| 2. 대량 쓰기 또는 업데이트 | 한 번의 작업으로 여러 레코드를 생성하거나 업데이트합니다(예: 대량 업로드, 재고 업데이트). |
| 3. 프론트엔드 성능 최적화 | 브라우저나 모바일 앱의 HTTP 호출 수를 줄여 로딩 시간을 단축합니다. |
| 4. 백엔드 작업 집계 | 마이크로서비스 시스템에서 여러 내부 API 호출을 하나의 외부 호출로 병합합니다. |
| 5. 데이터 동기화 | 여러 리소스 상태를 동기화하거나 일괄 작업(예: 태깅, 삭제)을 실행합니다. |
| 6. 속도 제한 최적화 | 요청을 통합하여 API 게이트웨이 부하를 줄이고 대역폭을 절약합니다. |
배치 API 효율성에 영향을 미치는 주요 요인
실시간 API에 비해 배치 API가 얼마나 비용을 절약할 수 있나요?
업계 분석(Growth-onomics)에 따르면 네트워크 왕복 횟수 감소, 연결 오버헤드 절감, 집중 처리 덕분에 약 20~45%의 비용 절감 효과를 보이지만, 정확한 절감액은 호출 빈도, 배치 크기, 시스템 설계에 따라 달라집니다.
지연 시간은 어떤가요? 배치 API가 정말 "24시간 이내"에 완료될 수 있나요?
배치 API는 일반적으로 비동기적으로 실행되며 실시간 API보다 지연 시간이 훨씬 깁니다. 많은 시스템이 시간별 또는 일별로 실행되므로 "24시간 이내"는 보장된 SLA라기보다는 조건에 따라 달라집니다.
배치 크기나 파일 크기가 속도에 영향을 미치나요?
네. 배치가 클수록(예: 더 많은 JSONL 라인) 전송 및 구문 분석 시간이 거의 선형적으로 증가합니다. 처리량은 향상되지만 배치당 총 완료 시간은 늘어납니다.
왜 배치 API가 높은 처리량 워크로드에 더 적합한가요?
수천 개의 요청을 하나의 프로세스로 집계함으로써 배치 API는 호출당 오버헤드를 줄이고 병렬 실행 또는 캐싱 재사용을 가능하게 합니다. 대규모 운영에서는 처리량이 17~92% 향상될 수 있지만, 지연 시간이 증가하는 대가가 따릅니다.
배치 API 사용 방법
Novita의 배치 API는 OpenAI의 인터페이스와 높은 호환성을 가지며
/v1/chat/completions및/v1/completions를 지원하므로 기존 코드를 최소한의 변경으로 재사용할 수 있습니다. 입력 파일로.jsonl을 사용하며, 각 라인은 동일한 모델에 대한 개별 요청을 나타내고 고유한custom_id로 식별됩니다. 출력도 JSONL 형식이므로 대규모 후처리, 분석 및 통합이 간단하고 효율적입니다.
1. 배치 입력 파일 준비
.jsonl 파일을 생성합니다. 각 라인은 하나의 API 요청을 JSON 형식으로 나타냅니다.
예시 (batch_input.jsonl):
{"custom_id": "req-1", "body": {"model": "deepseek/deepseek-v3-0324", "messages": [{"role": "user", "content": "Summarize: batch API basics"}], "max_tokens": 200}}
{"custom_id": "req-2", "body": {"model": "deepseek/deepseek-v3-0324", "messages": [{"role": "system", "content": "You are concise."},{"role": "user", "content": "List 3 batch API use cases"}], "max_tokens": 150}}
규칙:
- 한 줄에 하나의 요청.
- 모든 요청은 동일한 모델을 사용해야 함.
- 각 라인에는 고유한
custom_id가 포함되어야 함.
2. 입력 파일 업로드 및 배치 생성
Python 또는 curl을 사용하여 파일을 업로드하고 즉시 배치 작업을 시작합니다.
Python
from openai import OpenAI
client = OpenAI(base_url="https://api.novita.ai/openai/v1", api_key="YOUR_API_KEY")
# Upload + create batch
uploaded = client.files.create(file=open("batch_input.jsonl", "rb"), purpose="batch")
batch = client.batches.create(
input_file_id=uploaded.id,
endpoint="/v1/chat/completions",
completion_window="48h"
)
print("file_id:", uploaded.id)
print("batch_id:", batch.id)
curl
export API_KEY="YOUR_API_KEY"
# Upload file
upload_response=$(curl -s -X POST \
-H "Authorization: Bearer ${API_KEY}" \
-F 'file=@batch_input.jsonl' -F 'purpose=batch' \
https://api.novita.ai/openai/v1/files)
# Extract file_id and start batch
file_id=$(echo $upload_response | jq -r '.id')
curl -X POST https://api.novita.ai/openai/v1/batches \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d "{\"input_file_id\": \"$file_id\", \"endpoint\": \"/v1/chat/completions\", \"completion_window\": \"48h\"}"
3. 배치 상태 확인
배치 ID를 사용하여 언제든지 진행 상황을 확인할 수 있습니다.
batch = client.batches.retrieve("batch_xxx")
print(batch.status)
상태는 다음과 같습니다:
VALIDATING– 입력 파일 검사 중PROGRESS– 실행 중COMPLETED– 성공적으로 완료됨FAILED– 실패EXPIRED– 48시간 창 초과
4. 결과 검색
완료되면 output_file_id를 통해 결과 파일을 다운로드합니다:
output = client.files.content("file_xxx")
print(output.read().decode("utf-8"))
출력의 각 라인은 custom_id로 매칭된 하나의 입력에 해당합니다.
팁:
deepseek/deepseek-r1-0528만 지원배치당 최대 50,000개 요청
입력 파일 ≤ 100MB
완료 창은 48시간 고정
출력은 30일 동안 보관
배치 API에서 실패한 요청은 어떻게 처리해야 하나요?
배치 처리 중 발생한 오류는 별도의 오류 파일에 기록되며, error_file_id 필드를 통해 접근할 수 있습니다. 각 실패한 하위 요청에는 오류 코드와 설명이 포함됩니다. 일반적인 예:
| 오류 코드 | 설명 | 해결 방법 |
|---|---|---|
| 400 | 잘못된 요청 형식 | JSONL 구문 및 필수 필드 확인 |
| 401 | 인증 실패 | API 키 확인 |
| 404 | 배치를 찾을 수 없음 | 배치 ID 확인 |
| 429 | 속도 제한 초과 | 요청 빈도 줄이기 |
| 500 | 서버 오류 | 제공업체에 문의하거나 나중에 재시도 |
개발자는 전체 원본 파일을 다시 제출하는 대신 재시도 큐나 소규모 후속 배치를 사용하여 실패한 항목만 다시 처리해야 합니다.
Novita AI는 배치 API 작업을 위해 어떤 엔드포인트를 제공하나요?
| 엔드포인트 | 목적 |
|---|---|
| 배치 생성 | 여러 요청이 포함된 새 배치 작업을 제출합니다. |
| 배치 검색 | 특정 배치의 상태 또는 결과를 ID로 조회합니다. |
| 배치 취소 | 실행 중인 배치 작업을 완료 전에 중지합니다. |
| 배치 목록 | 계정에 제출된 모든 배치 작업을 나열합니다. |
| 파일 업로드 | 입력 데이터 파일(예: JSONL)을 업로드합니다. |
| 파일 목록 | 업로드된 모든 파일을 조회합니다. |
| 파일 검색 | 파일 ID로 파일 메타데이터를 가져옵니다. |
| 파일 삭제 | 업로드된 파일을 제거합니다. |
| 파일 내용 검색 | 파일의 실제 내용(예: 결과 또는 오류 로그)을 다운로드합니다. |
배치 API는 많은 소규모 요청을 하나의 효율적인 워크플로우로 통합합니다. Novita AI의 배치 API를 사용하면 개발자는 네트워크 비용을 최대 45% 절감하고, 배치당 최대 50,000개 요청까지 처리량을 확장하며, 기본 제공 로깅 및 검색 엔드포인트를 통해 오류 처리를 간소화할 수 있습니다. 실시간 속도를 희생하지만, 대량 추론, 동기화 및 데이터 처리 워크로드에서 뛰어난 효율성을 제공합니다.
Novita AI는 개발자가 간단한 API를 사용하여 AI 모델을 손쉽게 배포할 수 있도록 지원하는 AI 클라우드 플랫폼이며, 합리적인 가격의 신뢰할 수 있는 GPU 클라우드도 제공합니다.
