모든 LLM 작업이 채팅은 아닙니다. 라벨을 붙일 지원 티켓 5만 건, 번역할 상품 설명 20만 건, 점수를 매길 리뷰 100만 건이 있을 수 있습니다. OpenAI와 Anthropic 같은 제공업체는 이런 용도로 Batch API를 판매합니다. BroadNet Inference를 포함한 많은 OpenAI 호환 API에는 없습니다. 이 글은 작업을 직접 돌리는 방법을 보여 줍니다. 얼마나 걸릴지 계산하고, 한도를 지키는 실행기를 작성하고, 멈췄다가 다시 시작해도 안전하게 만드는 방법입니다.
BroadRouter는 BroadNet의 자체 사이트이므로, 예시 수치는 BroadNet이 공개한 한도를 씁니다. 이 방법은 어떤 채팅 완성 API에서도 통하니, 사용하는 제공업체의 수치로 바꿔 넣으세요.
BroadNet Inference에 Batch API가 있나요?
없습니다. 2026년 11월 15일에 확인한 API 레퍼런스는 POST /v1/chat/completions, POST /v1/audio/transcriptions, GET /v1/models(모델 목록)와 /portal/ 아래의 계정 엔드포인트를 문서화합니다. 배치나 파일 업로드 엔드포인트도, 일괄 할인도 없습니다. 대량 작업은 일반 요청을 반복하는 루프입니다.
무엇을 다시 만드는 것인지 알 수 있도록, 호스팅되는 Batch API가 제공하는 것을 정리하면 다음과 같습니다.
| OpenAI Batch API | Anthropic Message Batches | 직접 만든 실행기 | |
|---|---|---|---|
| 가격 | 동기 호출 대비 50% 할인 | 50% 할인 | 일반 가격 |
| 처리 시간 | 24시간 이내 | 대부분 1시간 이내, 24시간 후 만료 | 속도 제한이 결정 |
| 배치당 크기 | 요청 50,000개 또는 200 MB | 요청 100,000개 또는 256 MB | 제한 없음 |
| 속도 제한 | 모델별 한도와 별도 | 대기 중인 요청에 적용 | 키의 한도 |
| 결과 순서 | 다를 수 있음, custom_id로 대조 |
custom_id로 대조 |
결과를 ID로 관리 |
여기서 가져올 교훈이 두 가지 있습니다. 두 제공업체 모두 결과가 순서대로 돌아오지 않기 때문에 요청마다 ID를 붙이게 합니다. 그리고 둘 다 몇 초 안에 답이 온다고 약속하지 않습니다. 직접 만든 실행기도 똑같이 동작해야 합니다. 모든 것에 ID를 붙이고, 계획은 시간 단위로 세우세요.
처리 시간보다 50% 할인이 더 중요하고 필요한 모델이 거기 있다면, 호스팅되는 Batch API가 더 저렴한 도구일 수 있습니다. 만들기 전에 LLM API 비용 계산기로 둘 다 가격을 따져 보세요.
작업에 얼마나 걸리나요?
코드를 쓰기 전에 계산하세요. 처리량을 제한하는 한도는 두 가지이며, 더 느린 쪽이 이깁니다.
- 동시 요청 한도 ÷ 지연 시간. 동시 요청 4개, 요청당 2초라면 초당 2건을 끝낼 수 있습니다.
- 분당 요청 수. 분당 30회라면 모델이 아무리 빨라도 초당 0.5건만 시작할 수 있습니다.
BroadNet 종량제 키는 동시 요청 4개, 분당 30회까지 허용합니다. 저희가 확인했을 때 API 레퍼런스의 값(분당 30회, 동시 요청 4개, 2026-11-15)에서는 요청 하나가 8초 넘게 걸리지 않는 한 속도 제한이 병목이며, 아래 표는 분당 30회를 기준으로 합니다.
| 항목 수 | 요청당 항목 1개 | 요청당 항목 20개 |
|---|---|---|
| 10,000 | 5.6시간 | 17분 |
| 100,000 | 2.3일 | 2.8시간 |
| 1,000,000 | 23일 | 28시간 |
분당 30회라면 키 하나로 시간당 1,800회, 하루 43,200회의 요청을 보냅니다. 재시도도 포함됩니다. 429를 일으킬 때마다 슬롯 하나를 씁니다.
가장 큰 지렛대는 두 번째 열입니다. 리뷰나 티켓 제목처럼 짧은 항목은 번호를 붙인 목록으로 요청당 10~50개를 보내고 JSON 배열로 받을 수 있습니다. 배열에 입력마다 항목이 하나씩 있고 각 항목에 번호가 붙어 있는지 확인하세요. 아랍어 텍스트 분류 글에 이 패턴이 나옵니다. 긴 항목은 묶을 수 없습니다. 각 요청은 여전히 모델의 컨텍스트 창에 들어가야 하고, 목록이 길어지면 품질이 떨어질 수 있습니다. 믿기 전에 200개 항목으로 묶음 처리를 테스트하세요.
키당 한도를 넘기려고 문의 없이 한 작업을 여러 키로 나누지 마세요. BroadNet의 허용 사용 정책은 속도, 동시성, 예산 한도의 우회를 금지합니다. 더 필요하다면 BroadNet에 문의하거나, 아래의 플랜 세션을 쓰세요. 배치 작업 플래너가 항목 수, 지연 시간, 한도에 맞춰 이 계산을 해 줍니다.
재개 가능한 실행기는 어떻게 생겼나요?
이 실행기는 items.jsonl(한 줄에 {"id", "text"} 객체 하나)을 읽고, 항목마다 결과 한 줄을 results.jsonl에 추가합니다. OpenAI Python SDK만 있으면 됩니다.
import asyncio, json, os, random, time
from openai import AsyncOpenAI, APIStatusError, APIConnectionError, APITimeoutError
client = AsyncOpenAI(base_url=os.environ.get("BASE_URL", "https://inference.broadnet.ai/v1"),
api_key=os.environ["BROADNET_API_KEY"],
max_retries=0, # we retry ourselves, with a cap we can see
timeout=120)
MODEL = os.environ.get("MODEL", "broadnet/deepseek-v4.1-flash")
IN_FLIGHT = int(os.environ.get("IN_FLIGHT", "4")) # PAYG key: 4 in flight. Plan: 1 per session.
RPM = int(os.environ.get("RPM", "30")) # PAYG key: 30 requests a minute
MAX_ATTEMPTS = 6
class Pacer:
"""Spaces request starts at least 60/RPM seconds apart, across all workers."""
def __init__(self, rpm):
self.gap, self.next, self.lock = 60 / rpm, 0.0, asyncio.Lock()
async def wait(self):
async with self.lock:
now = time.monotonic()
delay = max(0.0, self.next - now)
self.next = max(now, self.next) + self.gap
await asyncio.sleep(delay)
def retryable(e):
if isinstance(e, (APIConnectionError, APITimeoutError)):
return True
return isinstance(e, APIStatusError) and e.status_code in (429, 500, 502, 503, 504)
async def call(item, pacer):
for attempt in range(MAX_ATTEMPTS):
await pacer.wait() # every attempt counts against the rate limit
try:
r = await client.chat.completions.create(
model=MODEL, max_tokens=1500, reasoning_effort="low",
messages=[{"role": "system", "content": "Classify the review as positive, negative or mixed. Reply with one word."},
{"role": "user", "content": item["text"]}])
c = r.choices[0]
return {"id": item["id"], "ok": True, "finish_reason": c.finish_reason,
"output": c.message.content, "usage": r.usage.model_dump() if r.usage else None}
except Exception as e:
if not retryable(e) or attempt == MAX_ATTEMPTS - 1:
return {"id": item["id"], "ok": False, "error": repr(e)[:300]}
await asyncio.sleep(random.uniform(0, min(60, 2 ** attempt))) # full jitter, capped
async def run(in_path, out_path):
done = set()
if os.path.exists(out_path): # resume: skip ids that already succeeded
with open(out_path) as f:
done = {json.loads(l)["id"] for l in f if l.strip() and json.loads(l).get("ok")}
todo = [it for it in map(json.loads, open(in_path)) if it["id"] not in done]
print(f"{len(done)} done, {len(todo)} to go")
pacer, queue = Pacer(RPM), asyncio.Queue()
for it in todo:
queue.put_nowait(it)
with open(out_path, "a") as out:
async def worker():
while True:
try:
it = queue.get_nowait()
except asyncio.QueueEmpty:
return
res = await call(it, pacer)
out.write(json.dumps(res, ensure_ascii=False) + "\n")
out.flush() # one line per finished item = the checkpoint
await asyncio.gather(*(worker() for _ in range(IN_FLIGHT)))
if __name__ == "__main__":
import sys
asyncio.run(run(sys.argv[1], sys.argv[2]))
python batch_run.py items.jsonl results.jsonl로 실행하세요. 우리는 이 파일을 그대로, 무작위로 429(8%)와 500(5%)을 반환하고 동시 요청 4개 초과나 분당 30회 초과 시작을 거부하는 로컬 모의 서버에서 테스트했습니다. 항목 25개가 요청 28회(재시도 3회)로 55초 만에 끝났고, 어느 60초 구간에서도 시작이 30회를 넘지 않았습니다. 시간을 아끼려고 모의 서버의 한도를 분당 300회로 올린 상태에서, 10초 후 강제 종료한 120개 항목 실행은 저장된 결과 39개부터 재개해 중복 없이 고유 ID 120개로 끝났습니다.
왜 asyncio.gather가 아니라 워커 풀인가요?
429 가이드는 asyncio.gather를 세마포어로 감싸 씁니다. 호출 수백 번이라면 괜찮습니다. 큰 작업에는 큐에서 항목을 꺼내는 고정 크기 워커 풀이 더 낫습니다.
- 메모리.
gather는 처음에 항목마다 태스크를 하나씩 만듭니다. 풀은 진행 중인 항목만 들고 있습니다. - 동시성은 곧 풀 크기입니다. 워커 4개는 절대 요청 5개를 열 수 없습니다.
- 결과는 끝나는 대로 디스크로 흘러갑니다. 순서와 상관없이 ID별로 기록됩니다.
두 번째 한도는 Pacer가 처리합니다. 세마포어만으로는 동시 요청 4개를 넘지 않게 할 수 있지만, 요청이 1초씩 걸리면 워커 4개가 분당 240회를 시작해 대부분 429를 맞습니다. Pacer는 재시도를 포함해 모든 워커에 걸쳐 시작 간격을 2초로 벌립니다.
재시도는 어떻게 안전하게 유지하나요?
두 번째 시도에서 성공할 수 있는 것만 재시도하세요.
| 응답 | 조치 |
|---|---|
| 429 | 백오프 후 재시도. BroadNet 문서: “use response details and bounded backoff”(번역: 응답 세부 정보와 상한 있는 백오프를 사용하세요) |
| 500, 502, 503, 504, 타임아웃, 끊긴 연결 | 상한 있는 지수 백오프로 재시도 |
| 400, 422 | 요청을 고치세요. 재시도하면 같은 오류가 납니다 |
| 401, 402, 403 | 작업을 멈추세요. 키, 잔액 또는 정책을 확인해야 합니다 |
| 413 | 항목을 줄이세요 |
실행기는 SDK 자체 재시도를 끄므로(max_retries=0) 재시도 정책은 상한이 눈에 보이는 하나뿐입니다. 백오프는 완전 지터(full jitter)를 넣은 지수 백오프이며 60초가 상한이라, 함께 실패한 워커들이 함께 재시도하지 않습니다. 여섯 번 시도한 뒤에는 항목을 "ok": false로 기록하고 다음으로 넘어갑니다. 잘못된 항목 하나가 100만 건을 멈추게 하지 않습니다.
모델 호출에는 부수 효과가 없으므로 여기서의 전달은 최소 1회(at least once)입니다. 요청 도중 프로세스가 죽으면 그 항목은 재시작할 때 다시 전송되고, 비용을 두 번 냅니다. 낭비는 그것뿐입니다. 작업이 티켓이나 이메일 같은 다른 시스템에도 쓴다면, 그 쓰기를 항목 ID 기준으로 멱등적으로 만들고 results.jsonl을 대상으로 별도 패스에서 처리하세요. 멱등적인 부수 효과는 장시간 실행 에이전트 글에서 자세히 다룹니다.
체크포인트는 어떻게 작동하나요?
출력 파일이 곧 체크포인트입니다. 끝난 항목마다 flush된 한 줄이므로, 장애나 배포나 Ctrl-C 이후 다음 실행은 파일을 읽고 "ok": true인 ID를 모은 다음 나머지만 큐에 넣습니다. 앞서 실패한 항목은 다음 실행에서 재시도되고 새 줄이 추가됩니다. 결과를 읽을 때는 ID마다 마지막 줄을 쓰세요.
며칠 동안 버티게 하는 습관 세 가지:
- 안정적인 ID. 데이터베이스 키나 입력의 해시를 쓰고, 입력 파일이 바뀌면 달라지는 줄 번호는 절대 쓰지 마세요.
finish_reason확인.max_tokens에서 잘린 답변은"ok": true이지만 쓸모가 없습니다. DeepSeek V4.1 Flash, GLM 5.3, Qwen3.8 27B는 답하기 전에 추론하며, 추론은 max_tokens에 포함됩니다. 실행기는 BroadNet이 문서화한reasoning_effort="low"를 설정하고 1,500 토큰을 남겨 둡니다.- 줄마다 사용량 기록.
results.jsonl의usage를 합산하면 추정치와 비교할 실제 토큰 비용이 나옵니다.
비용은 얼마인가요: 종량제인가요, 플랜 세션인가요?
종량제에서 비용은 토큰입니다. 리뷰 10만 건, 시스템 프롬프트 150 토큰, 리뷰 150 토큰, 낮은 추론 수준의 출력 100 토큰을 가정해 봅시다. 입력 3,000만 토큰, 출력 1,000만 토큰입니다. DeepSeek V4.1 Flash에서는 30 × $0.175 + 10 × $0.52 금액이 듭니다. 시스템 프롬프트를 맨 앞에 바이트 단위까지 동일하게 두면, 그 1,500만 토큰은 캐시가 적중하는 경우 100만 토큰당 $0.0055 요금인 캐시된 입력 가격으로 과금될 수 있습니다. 얼마나 자주 적중했는지는 usage 줄에 나옵니다.
플랜에서는 토큰이 무료이고 비용은 시간입니다. DeepSeek V4.1 Flash 플랜 세션은 “runs one request at a time”(번역: 한 번에 요청 하나를 실행)하므로 세션마다 IN_FLIGHT=1로 설정하세요. 세션당 처리량은 하루 86,400 ÷ 항목당 초입니다. BroadNet은 일반적인 속도를 초당 약 100토큰 수준으로 제시하지만, 실제 지연 시간은 프롬프트 길이와 추론에 따라 달라지므로 항목 50개로 측정하세요. 항목당 3초로 측정되면 세션 하나가 하루 28,800건을 처리합니다.
| 작업 | 세션 | 항목당 3초 기준 시간 | 플랜 |
|---|---|---|---|
| 항목 100,000개 | 1 | 약 3.5일 | Orbit 1주권 1개, 세션당 $15 요금 |
| 항목 100,000개 | 4 | 약 21시간 | Orbit 1주권 4개(세션당 1개), 또는 각 $1 요금의 Meteor 시간권을 세션당 약 21개 |
| 항목 1,000,000개 | 6 | 약 6일 | Orbit 1주권 6개 |
플랜은 “best effort under fair use”(번역: 공정 사용 범위 내 최선 노력)로 제공되며, BroadNet은 플랜 키의 분당 요청 한도를 공개하지 않습니다. 적용되는 한도는 계정에 표시됩니다. RPM은 추측이 아니라 그 값으로 설정하세요. 세션을 여러 키에 나누는 방법은 세션 플래너 가이드에서 설명합니다.
BroadNet Inference의 역할
BroadNet Inference에는 Batch API가 없으므로, 실행기를 직접 통제하며 일반 토큰당 가격을 내거나 DeepSeek V4.1 Flash 플랜 세션으로 비용을 고정하고 싶을 때 대량 작업에 적합합니다. 예산이 적은 작은 작업이라면 100만 토큰당 입력 $0.10, 출력 $0.22 요금의 Gemma 4 VL 26B를 $5 상당의 초기 크레딧으로 돌릴 수 있습니다. 프롬프트와 출력은 요청 후 보관되지 않습니다. 작업이 하루를 기다릴 수 있고 필요한 모델이 50% 일괄 할인을 주는 제공업체에 있다면 그쪽이 더 저렴할 수 있으니, 확정하기 전에 비교하세요. 플랜과 한도는 inference.broadnet.ai/plans에 있습니다.
