KO ▾

OpenAI 호환 LLM API를 위한 Python 배치 요청

Python에서 LLM API 배치 작업을 하려면 특별한 배치 엔드포인트가 필요한 것은 아닙니다. 속도 제한을 준수하는 워커 풀, HTTP 429용 재시도 규칙, 재개 가능한 결과 파일이 필요합니다. 이 가이드는 Base URL을 설정한 OpenAI SDK를 사용하여 이 세 가지를 모두 구현합니다.

업데이트됨

데이터 큐브를 처리 코어로 전달하는 병렬 파이프, Python에서의 동시 배치 요청을 나타냅니다.

주요 포인트

  • API에는 채팅 완성 및 모델 두 가지 메서드가 있으므로 배치는 동시 요청 풀을 사용하여 클라이언트 측에서 처리합니다.
  • 전체 키는 동시 요청 8개와 분당 300개의 요청을 허용합니다. 체험 키는 동시 2개와 분당 60개를 허용합니다. 풀 크기를 이에 맞게 조정하세요.
  • Retry-After 헤더를 사용하여 429 오류를 재시도하고, 속도 제한 오류와 동시성 오류를 구분하세요.
  • 각 결과가 완료될 때마다 JSONL 파일에 기록하여 충돌 시 전체 실행이 아닌 몇 분의 손실로 끝나도록 하세요.

여기서 배치가 작동하는 방식

엔드포인트는 OpenAI 호환이며 POST /v1/chat/completions과 GET /v1/models을 제공합니다. 파일을 받아 나중에 결과를 반환하는 별도의 작업 제출 엔드포인트는 없습니다. 따라서 배치는 제한 사항이 코드에 내장된 일반 요청의 루프이며, 병렬로 실행됩니다. 이는 생각보다 간단하며, 완료되는 대로 결과를 제공하므로 마지막에 한꺼번에 받는 것보다 낫습니다.

설계를 결정하는 수치는 제한 사항입니다. 전체 키는 동시 요청 8개와 분당 300개의 요청을 허용합니다. 체험 키는 동시 2개와 분당 60개의 요청을 허용합니다. 최대 요청 본문 크기는 8 MB입니다. 스트리밍 요청은 스트리밍이 끝날 때까지 동시성 슬롯을 점유하므로, 배치 작업의 경우 스트리밍을 끄세요.

모든 것을 한 번에 보내면 안 되는 이유는 무엇일까요? 배치 처리는 한계가 있는 처리량 문제이며, 그 한계를 준수해야 합니다. Python이 생성할 수 있는 속도로 5,000개의 요청을 보내는 루프는 429 응답의 벽에 부딪히고, 재시도에 시간을 낭비하며, 유용한 오류를 노이즈 속에 묻어버립니다. 최대 8개의 요청만 동시에 처리하는 풀은 서비스가 허용하는 속도로 진행을 유지하며, 50개의 행이든 500,000개의 행이든 동일한 코드를 사용합니다. 계획해야 할 세 가지 요소는 제한된 풀, 재시도 규칙 하나, 그리고 추가 전용 결과 파일입니다.

모델 ID는 uncensored이며, 인증은 Authorization: Bearer <key>, 베이스 URL은 https://api.unfilteredvideo.com/v1입니다. 아직 키가 없다면 API 키 페이지에서 $0.50 체험판을 한 번의 클릭으로 얻을 수 있습니다.

설치 및 설정

Python 3.9 이상이 필요하며 공식 openai 패키지가 필요합니다. 키를 스크립트 대신 환경 변수에 저장하세요.

pip install openai
export API_KEY="paste-your-key-here"

# quick check that the key and base URL work
curl https://api.unfilteredvideo.com/v1/models -H "Authorization: Bearer $API_KEY"

모델 목록에 uncensored가 표시되어야 합니다. 이제 입력을 JSONL 파일로 준비하세요. 각 줄에 id와 처리할 텍스트를 포함하는 객체를 하나씩 넣습니다. id는 나중에 재개할 수 있게 해줍니다.

{"id": "r001", "text": "Summarise this product review in one sentence: ..."}
{"id": "r002", "text": "Summarise this product review in one sentence: ..."}

한도 내에서 유지되는 스레드 풀

대부분의 스크립트에는 ThreadPoolExecutor이 가장 짧은 경로입니다. OpenAI 클라이언트는 스레드 간에 안전하게 공유할 수 있으며, 작업은 네트워크 종속적이므로 스레드가 적합합니다. 풀 크기를 동시성 제한에 맞게 설정하세요. 높게 설정하면 추가 워커가 429 오류만 수집합니다.

import json, os
from concurrent.futures import ThreadPoolExecutor, as_completed
from openai import OpenAI

client = OpenAI(api_key=os.environ["API_KEY"], base_url="https://api.unfilteredvideo.com/v1", max_retries=0)
MODEL = "uncensored"
WORKERS = 8          # use 2 on a trial key

def run_one(row):
    resp = client.chat.completions.create(
        model=MODEL,
        temperature=0.2,
        max_tokens=200,
        messages=[{"role": "user", "content": row["text"]}],
    )
    return {
        "id": row["id"],
        "output": resp.choices[0].message.content,
        "in": resp.usage.prompt_tokens,
        "out": resp.usage.completion_tokens,
    }

rows = [json.loads(line) for line in open("input.jsonl")]
with ThreadPoolExecutor(max_workers=WORKERS) as pool, open("output.jsonl", "a") as out:
    futures = [pool.submit(run_one, r) for r in rows]
    for f in as_completed(futures):
        out.write(json.dumps(f.result()) + "\n")
        out.flush()

이 버전에는 재시도 및 재개 기능이 없으므로 시작점입니다. SDK는 기본적으로 자체적으로 재시도하므로, 재시도 규칙을 관리할 단일 위치가 필요하여 클라이언트 생성 시 max_retries=0을 설정합니다. 다음 두 섹션에서는 해당 규칙과 재개 로직을 추가합니다.

429 오류를 올바르게 처리하기

이 API에는 세 가지 유형의 429 오류가 있으며 각각 약간 다른 대응이 필요합니다:

  • rate_limited: 분당 요청이 너무 많습니다. 속도를 줄이세요. 워커가 적은 풀이나 짧은 대기 시간이 이를 해결합니다.
  • concurrency: 동시에 처리 중인 요청이 너무 많습니다. 풀이 한도보다 크거나 잊고 있는 스트리밍 연결이 있을 수 있습니다.
  • 일시적 과부하: Retry-After: 5 헤더가 있는 429 오류입니다. 코드에 문제가 없습니다. 명시된 시간만큼 기다린 후 다시 시도하세요.

하나의 재시도 헬퍼가 세 가지 경우 모두를 처리합니다. Retry-After가 있는 경우 해당 시간만큼 대기하고, 그렇지 않으면 약간의 지터를 추가하여 지수 백오프를 수행합니다. 실패한 요청과 거부된 요청에는 요금이 부과되지 않으므로 재시도는 무료입니다.

import random, time
import openai
from openai import OpenAI

client = OpenAI(api_key=__import__("os").environ["API_KEY"], base_url="https://api.unfilteredvideo.com/v1", max_retries=0)
MODEL = "uncensored"

def call_with_retry(messages, attempts=6):
    for n in range(attempts):
        try:
            return client.chat.completions.create(model=MODEL, messages=messages, max_tokens=200)
        except openai.RateLimitError as e:
            wait = e.response.headers.get("Retry-After")
            delay = float(wait) if wait else min(60, 2 ** n) + random.random()
            print("429", getattr(e, "code", None), "waiting", round(delay, 1), "s")
            time.sleep(delay)
        except (openai.APIConnectionError, openai.APITimeoutError):
            time.sleep(min(30, 2 ** n))
    raise RuntimeError("gave up after %d attempts" % attempts)

모든 오류에 대해 무작정 재시도하지 마세요. 400 오류는 요청이 잘못되었음을 의미합니다. 예를 들어 본문이 8 MB를 초과하거나 메시지 형식이 잘못되었을 수 있으며, 다시 보내도 같은 방식으로 실패합니다. 행 id와 함께 로그에 기록하고 넘어가세요.

세마포어를 사용한 비동기 버전

이벤트 루프에서 이미 실행 중이거나 웹 서비스에 공급하려면 AsyncOpenAI와 실행 중 요청을 제한하는 asyncio.Semaphore를 사용하세요. 세마포어는 풀 크기의 역할을 합니다.

import asyncio, json, os
from openai import AsyncOpenAI

client = AsyncOpenAI(api_key=os.environ["API_KEY"], base_url="https://api.unfilteredvideo.com/v1", max_retries=0)
MODEL = "uncensored"
sem = asyncio.Semaphore(8)

async def run_one(row, out):
    async with sem:
        resp = await client.chat.completions.create(
            model=MODEL,
            max_tokens=200,
            messages=[{"role": "user", "content": row["text"]}],
        )
    out.write(json.dumps({"id": row["id"], "output": resp.choices[0].message.content}) + "\n")
    out.flush()

async def main():
    rows = [json.loads(l) for l in open("input.jsonl")]
    with open("output.jsonl", "a") as out:
        await asyncio.gather(*(run_one(r, out) for r in rows))

asyncio.run(main())

await asyncio.sleep을 사용하여 time.sleep 대신 위의 재시도 로직을 호출에 적용하세요. 주의할 점: 수만 개의 코루틴을 사용하는 gather은 모든 코루틴을 한 번에 예약합니다. 매우 큰 입력의 경우, 파일의 행을 몇 천 개씩 슬라이스하여 처리하세요.

실행 재개 기능 구현하기

긴 작업은 지루한 방식으로 실패합니다: 노트북이 절전 모드로 전환되거나 연결이 끊기거나 Ctrl+C를 누르는 경우. 각 완료된 행은 id와 함께 output.jsonl에 추가되므로 재개는 이미 있는 id를 건너뛰는 것을 의미합니다.

import json, os
from openai import OpenAI

client = OpenAI(api_key=os.environ["API_KEY"], base_url="https://api.unfilteredvideo.com/v1")
MODEL = "uncensored"

def done_ids(path="output.jsonl"):
    if not os.path.exists(path):
        return set()
    return {json.loads(line)["id"] for line in open(path) if line.strip()}

finished = done_ids()
todo = [r for r in map(json.loads, open("input.jsonl")) if r["id"] not in finished]
print(len(finished), "done,", len(todo), "to go")

todo를 위의 두 풀 중 하나에 전달하세요. 출력 파일을 추가 모드로 열고, 쓰기 모드로 열면 재시작 시 진행 상황이 지워집니다. 또한 오류를 errors.jsonl이라는 두 번째 파일에 기록하여 실패 원인을 파악한 후 실패한 행만 다시 실행할 수 있게 하세요.

재실행 간 일관된 출력을 위해 고정 seed과 낮은 temperature을 전달하세요. 시드는 top_p, stop 및 페널티와 함께 모델에 전달됩니다.

작은 샘플로 테스트하기

20,000개를 실행하기 전에 20개 행으로 테스트하세요. 가장 나쁜 케이스를 포함하는 행을 선택하세요: 가장 긴 입력, 이상한 문자가 포함된 입력, 빈 입력. 출력을 눈으로 확인하고, usage가 비용 추정치와 일치하는지 확인하세요. 또한 작업자 수를 제한보다 높게 설정하여 재시도 헬퍼가 올바르게 동작하는지 확인하세요. 로그에 concurrency 코드가 있는 429 응답, 대기 시간, 그리고 성공적인 재시도가 표시되어야 합니다. 9,000번째 행에서 이를 발견하는 것보다 20개 행에서 확인하는 것이 낫습니다.

작업에 구조화된 출력이 필요한 경우, response_format={"type": "json_object"}으로 JSON 모드를 추가하고 프롬프트에 키를 설명한 후 try 블록 내에서 각 응답을 구문 분석하세요. 테스트 슬라이스에서 구문 분석 실패 횟수를 세세요. 실패율이 1% 또는 2%를 초과하면 프롬프트가 더 명확한 스키마를 필요로 한다는 의미이며, 이는 나중에 다시 실행하는 것보다 지금 수정하는 것이 저렴합니다. 구문 분석에 실패한 행은 id와 함께 errors.jsonl에 기록되며, 재개 로직은 이를 완료되지 않은 것으로 처리합니다.

마지막으로, 예상되는 가장 긴 출력에 맞는 클라이언트 시간 제한을 설정하세요. SDK는 클라이언트 또는 요청별로 timeout=60을 허용합니다. 응답이 늦거나 멈춘 요청은 그렇지 않을 경우 대기 중인 8개의 슬롯 중 하나를 점유 상태로 유지합니다.

풀 크기 조정 및 시간 추정

처리량은 두 가지 요소로 제한됩니다: 동시성 수를 단일 요청 소요 시간으로 나눈 값과 분당 요청 수 제한입니다. 전체 키의 제한은 분당 300개(초당 5개)입니다. 일반적인 요청에 2초가 걸리면 8개의 워커는 초당 8 / 2 = 4개 요청, 분당 240개 요청을 생성하며 이는 제한 내에 있습니다. 요청에 1초가 걸리면 8개의 워커는 초당 8개를 시도하여 제한에 도달하므로 작은 지연을 추가하거나 재시도 헬퍼가 처리하는 간헐적인 429 오류를 수용하세요.

초당 4개의 속도로 10,000개의 행을 처리하려면 2,500초, 약 42분이 걸립니다. 체험용 키의 경우 동시 요청 2개와 분당 60개의 제한이 있으므로 처리량 한도는 초당 1개로, 동일한 10,000개의 행을 처리하는 데 10,000초, 거의 2시간 47분이 걸립니다. 실제로 $0.50 체험 크레딧은 그 전에 소진되므로, 이는 스크립트를 몇 백 개의 행으로 테스트하기에 좋은 장소이지만 프로덕션에서 실행하기에는 적합하지 않습니다.

대규모 배치 비용

가격은 입력 토큰 100만 개당 $0.15, 출력 토큰 100만 개당 $0.50입니다. 분류 스타일의 작업을 예로 들어보겠습니다: 50,000개 행, 각 행당 약 200 입력 토큰 및 100 출력 토큰.

  • 입력: 50,000 × 200 = 10,000,000 토큰, 이는 10 × $0.15 = $1.50입니다.
  • 출력: 50,000 × 100 = 5,000,000 토큰, 이는 5 × $0.50 = $2.50입니다.
  • 총계: $4.00, 행당 $0.00008입니다.

위 스크립트는 각 행에 대해 in과 out을 기록하므로 실제 실행에서 동일한 값을 계산할 수 있습니다. X-Balance-USD 응답 헤더는 남은 크레딧을 표시하며, X-Request-Id는 docs 또는 지원 페이지에서 도움을 요청할 때 인용해야 합니다.

크레딧은 $20부터 $500까지 전액 선불로 충전되며, $50 이상은 +5%, $100 이상은 +10%, $200 이상은 +15%의 보너스가 제공됩니다. 암호화폐(TRC20의 USDT 또는 Base의 USDC)로 결제합니다. 크레딧은 만료되지 않습니다. 가격 책정 페이지에 전체 세부 정보가 있습니다. 민감한 데이터 세트의 경우 한 가지 참고 사항: 프롬프트는 학습에 사용되지 않습니다.

질문과 답변

API에 배치 엔드포인트가 있나요?

아니요. 채팅 완료 엔드포인트와 모델 목록만 제공합니다. 자체 코드에서 여러 일반 요청을 동시에 실행하여 배치를 처리합니다. 전체 키의 경우 동시 요청 수는 8개, 분당 요청 수는 300개로 제한됩니다.

얼마나 많은 스레드를 사용해야 하나요?

전체 키에는 8개의 워커를, 체험 키에는 2개의 워커를 사용하세요. 이는 동시성 제한과 일치합니다. 워커를 더 많이 사용하면 코드 concurrency의 429 오류만 발생합니다.

HTTP 429 오류가 발생하면 어떻게 해야 하나요?

응답에 Retry-After 헤더가 있으면 해당 값을 기다렸다가, 없으면 몇 초 동안 대기 후 다시 시도하세요. 실패한 요청은 요금이 부과되지 않으므로 다시 시도해도 비용이 들지 않습니다.

배치 작업 중 응답을 스트리밍할 수 있나요?

스트리밍할 수는 있지만 권장하지 않습니다. 스트리밍 요청은 스트림이 종료될 때까지 동시성 슬롯을 점유하므로 처리량이 낮아집니다. 배치 작업에는 스트리밍을 사용하지 마세요.

키는 양식 하나만 작성하면 받을 수 있습니다

계정을 생성하고 키를 복사한 후 기본 URL을 변경하세요. 설정은 이것으로 끝입니다.

API 키 받기