PT ▾

Requisições em lote em Python para uma API LLM compatível com OpenAI

Para trabalho de lote de API LLM em Python, você não precisa de um endpoint de lote especial: precisa de um pool de workers que respeite os limites de requisições, uma regra de retry para HTTP 429 e um arquivo de resultados do qual você possa retomar. Este guia constrói tudo isso com o SDK OpenAI apontado para o seu base URL.

Atualizado

Canais paralelos transportando cubos de dados para um núcleo de processamento, ilustrando requisições em lote concorrentes em Python

Pontos principais

  • A API tem dois métodos, chat completions e models, então o loteamento é feito do seu lado com um pool de requisições concorrentes.
  • Uma chave completa permite 8 requisições concorrentes e 300 por minuto; uma chave de teste permite 2 e 60. Dimensione seu conjunto para corresponder.
  • Faça retry no 429 usando o cabeçalho Retry-After, e diferencie o limite de taxa da simultaneidade.
  • Escreva cada resultado em um arquivo JSONL assim que terminar para que uma falha custe minutos, não a execução inteira.

Como o loteamento funciona aqui

O endpoint é compatível com OpenAI e expõe POST /v1/chat/completions e GET /v1/models. Não há um endpoint separado de submissão de jobs que aceite um arquivo e retorne depois. Um lote é portanto um loop sobre requisições normais, executadas em paralelo, com os limites embutidos no seu código. Isso é mais simples do que parece e fornece resultados conforme terminam em vez de no final.

Os números que moldam o design são os limites. Uma chave completa permite 8 requisições concorrentes e 300 requisições por minuto. Uma chave de teste permite 2 concorrentes e 60 por minuto. O corpo máximo da requisição é 8 MB. Uma requisição com streaming mantém seu slot de concorrência até o fim do stream, então para trabalho em lote, deixe o streaming desligado.

Por que não enviar tudo de uma vez? Porque um lote é um problema de vazão com um teto, e o teto é o limite que você deve respeitar. Um loop que envia 5.000 requisições na velocidade máxima que o Python consegue criar recebe uma parede de respostas 429, desperdiça tempo com retentativas e enterra os erros úteis no ruído. Um pool que mantém no máximo 8 requisições em execução mantém o fluxo na velocidade permitida pelo serviço, e é o mesmo código se você tiver 50 linhas ou 500.000. Planeje três componentes: um pool com limite, uma regra de retentativa e um arquivo de resultados append-only.

O ID do modelo é uncensored, a autenticação é Authorization: Bearer <key>, e a URL base é https://api.unfilteredvideo.com/v1. Se você ainda não tem uma chave, a página de chave de API tem uma oferta de teste de $0,50.

Instalar e configurar

Você precisa do Python 3.9 ou mais recente e do pacote oficial openai. Coloque a chave em uma variável de ambiente em vez de no script.

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"

A lista de modelos deve mostrar uncensored. Agora prepare sua entrada como um arquivo JSONL, um objeto por linha com um id e o texto para processar. O id é o que permite retomar depois.

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

Um pool de threads que fica dentro dos limites

Para a maioria dos scripts, um ThreadPoolExecutor é o caminho mais curto. O cliente OpenAI é seguro para compartilhar entre threads, e o trabalho é limitado pela rede, então as threads são adequadas. Defina o tamanho do pool para o seu limite de concorrência, não mais: trabalhadores extras apenas acumulam erros 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()

Esta versão não tem tentativa nem retomada, então é um ponto de partida. O cliente é criado com max_retries=0 no cliente porque o SDK tenta novamente por padrão, e você quer um lugar que possua a regra de tentativa. As duas próximas seções adicionam essa regra e a lógica de retomada.

Tratar 429 da maneira correta

Existem três tipos de 429 nesta API, e eles exigem reações ligeiramente diferentes:

  • rate_limited: você enviou muitas requisições em um minuto. Diminua o ritmo. Um pool com menos workers, ou uma pequena pausa, corrige isso.
  • concurrency: muitas requisições estavam em voo ao mesmo tempo. Seu pool é maior que seu limite, ou você tem streams abertos que esqueceu.
  • Sobrecarga temporária: um 429 com um cabeçalho Retry-After: 5. Nada está errado com o seu código. Aguarde o tempo indicado e tente novamente.

Um auxiliar de retry cobre todos os três. Ele aguarda Retry-After quando presente e, caso contrário, recua exponencialmente com um pouco de jitter. Requisições falhas e recusadas não são cobradas, então fazer retry é gratuito.

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)

Não faça retry cegamente em cada erro. Um 400 significa que sua requisição está errada, por exemplo um corpo acima de 8 MB ou uma mensagem malformada, e enviá-la novamente falhará da mesma forma. Registre com o id da linha e siga em frente.

Uma versão assíncrona com semáforo

Se o seu script já roda em um loop de eventos, ou se você quer alimentar um serviço web, use AsyncOpenAI e um asyncio.Semaphore que limite as requisições em execução. O semáforo desempenha o papel do tamanho do pool.

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())

Envolva a chamada na mesma lógica de retentativa acima, usando await asyncio.sleep em vez de time.sleep. Uma cautela: gather com dezenas de milhares de coroutines as cria todas de uma vez. Para entradas muito grandes, processe o arquivo em fatias de algumas mil linhas.

Tornar a execução retomável

Trabalhos longos falham de maneiras chatas: um laptop entra em suspensão, uma conexão cai, você pressiona Ctrl+C. Como cada linha concluída é anexada a output.jsonl com seu id, retomar significa pular ids que você já tem.

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")

Alimente todo a qualquer um dos pools acima. Abra o arquivo de saída no modo append, nunca no modo write, ou uma reinicialização apagará seu progresso. Escreva também os erros em um segundo arquivo, errors.jsonl, para que você possa reexecutar apenas as falhas após ler o motivo do erro.

Para saída repetível entre reexecuções, passe um seed fixo junto com um temperature baixo. O seed é passado para o modelo junto com top_p, stop e as penalidades.

Testar em uma pequena fatia primeiro

Execute 20 linhas antes de executar 20.000. Escolha linhas que incluam seus piores casos: a entrada mais longa, uma com caracteres estranhos, uma que está vazia. Leia as saídas a olho nu, verifique se o usage corresponde à sua estimativa de custo e confirme que o auxiliar de retentativa se comporta aumentando temporariamente a contagem de trabalhadores acima do seu limite. Você deve ver um 429 com o código concurrency no log, uma espera e uma retentativa bem-sucedida. É melhor ver isso em 20 linhas do que descobrir na linha 9.000.

Se o trabalho precisar de saída estruturada, adicione o modo JSON com response_format={"type": "json_object"}, descreva as chaves no prompt e analise cada resposta dentro de um bloco try. Conte falhas de análise durante a fatia de teste. Uma taxa acima de um ou dois por cento geralmente significa que o prompt precisa de um esquema mais claro, e isso é mais barato de corrigir agora do que reexecutar depois. Linhas que falham na análise vão para errors.jsonl com seu id, e a lógica de retomada as trata como não concluídas.

Finalmente, defina um timeout do cliente que se encaixe na sua saída máxima esperada. O SDK aceita timeout=60 no cliente ou por requisição; uma requisição presa que nunca retorna manterá uma de suas 8 slots pelo tempo que ficar lá.

Dimensionar o pool e estimar tempo

O throughput é limitado por duas coisas: a concurrency dividida pelo tempo que uma requisição leva, e o limite de requests por minuto. Com uma chave completa, o limite é 300 por minuto, que é 5 por segundo. Se uma requisição típica leva 2 segundos, 8 workers produzem 8 / 2 = 4 requests por segundo, ou 240 por minuto, que está abaixo do limite. Se as requisições levam 1 segundo, 8 workers tentariam 8 por segundo e atingiriam o limite, então adicione um pequeno atraso ou aceite 429s ocasionais que seu helper de retry absorve.

A 4 por segundo, 10.000 linhas levam 2.500 segundos, cerca de 42 minutos. Em uma chave de teste, com 2 requisições simultâneas e 60 por minuto, o limite é de 1 por segundo, então as mesmas 10.000 linhas levariam 10.000 segundos, quase 2 horas e 47 minutos. Na prática, o crédito de teste de $0,50 acabará antes disso, o que o torna um bom lugar para testar o script em algumas centenas de linhas e não um lugar para executar produção.

Quanto um grande lote custa

O preço é $0,15 por 1M de tokens de entrada e $0,50 por 1M de tokens de saída. Pegue um trabalho de estilo classificação: 50.000 linhas, cada uma com cerca de 200 tokens de entrada e 100 tokens de saída.

  • Input: 50.000 × 200 = 10.000.000 tokens, que é 10 × $0,15 = $1,50.
  • Output: 50.000 × 100 = 5.000.000 tokens, que é 5 × $0,50 = $2,50.
  • Total: $4,00, ou $0,00008 por linha.

O script acima registra in e out para cada linha, então você pode calcular a mesma figura a partir da sua execução real. O cabeçalho de resposta X-Balance-USD também mostra o crédito restante, e X-Request-Id é o que você deve citar se pedir ajuda nas páginas de documentação ou suporte.

O crédito é pré-pago em recargas em dólares inteiros de $20 a $500, com +5% de $50, +10% de $100 e +15% de $200, pago em cripto (USDT na TRC20 ou USDC na Base). Ele nunca expira. A página de preços tem todos os detalhes. Uma nota para conjuntos de dados sensíveis: os prompts não são usados para treinamento.

Perguntas e respostas

A API tem um endpoint de lote?

Não. Ela expede chat completions e uma lista de modelos. Você faz o lote executando muitas requisições normais em paralelo a partir do seu próprio código, dentro de 8 simultâneas e 300 por minuto em uma chave completa.

Quantas threads devo usar?

Use 8 workers em uma chave completa e 2 em uma chave de teste, correspondendo aos limites de concorrência. Mais workers apenas produzem erros 429 com o código concurrency.

O que devo fazer quando receber HTTP 429?

Aguarde o valor Retry-After se a resposta tiver um, caso contrário, faça backoff por alguns segundos e tente novamente. As requisições falhas não são cobradas, então tentar novamente não custa nada.

Posso fazer streaming de respostas em um trabalho de lote?

Você pode, mas não deveria. Uma solicitação de streaming mantém sua slot de concorrência até o fim do streaming, o que reduz o throughput. Deixe o streaming desativado para trabalho em lote.

Sua chave está a um clique de formulário

Crie uma conta, copie a chave e altere a URL base. Essa é toda a configuração.

Obter chave de API