Os desenvolvedores frequentemente enfrentam tempos de resposta lentos e altos custos de rede ao enviar milhares de chamadas de API separadas. A API em Lote resolve isso ao combinar várias solicitações independentes em uma única operação, reduzindo a latência, o uso de largura de banda e a sobrecarga de conexão.
Este artigo explica o que é a API em Lote, como ela difere das APIs padrão e como a API em Lote da Novita AI permite inferência assíncrona em grande escala por meio de entrada JSONL estruturada, manipulação eficiente de arquivos e rastreamento confiável de erros. Ele também descreve os principais fatores de eficiência, como custo, latência e vazão, e fornece um guia conciso de implementação e monitoramento.
[Experimente a Inferência em Lote com 50% de Desconto
Execute previsões em grande escala mais rápido e mais barato com os modelos suportados:
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)
Experimente a Inferência em Lote com 50% de Desconto
Execute previsões em grande escala mais rápido e mais barato com os modelos suportados:
qwen/qwen3-vl-235b-a22b-instruct, openai/gpt-oss-120b, deepseek/deepseek-r1-0528, qwen/qwen3-4b-f
O que é a API em Lote？
API em Lote: Combina várias chamadas de API independentes (ex: GET, POST, PUT, DELETE) em uma única solicitação HTTP.
Estrutura de Resposta: O servidor retorna os resultados de todas as sub-solicitações em ordem, indicando sucesso ou falha para cada uma.
Diferença Principal entre API em Lote e API Padrão
Solicitações Normais
Client
├──► Request 1 (/user/1)
│ └──► Server Response 1
├──► Request 2 (/user/2)
│ └──► Server Response 2
└──► Request 3 (/order)
└──► Server Response 3
Solicitação em Lote
Client
└──► Single Request (/batch)
├─ Sub-request 1: GET /user/1
├─ Sub-request 2: GET /user/2
└─ Sub-request 3: POST /order
↓
Server processes all
↓
Combined Response:
[Result1, Result2, Result3]
A API em Lote pode ajudar:
Reduzir a latência de rede ao enviar uma solicitação combinada em vez de várias.
Diminuir a sobrecarga de largura de banda e conexão, já que cabeçalhos e handshakes são compartilhados.
Melhorar o desempenho do cliente, especialmente em dispositivos móveis ou redes lentas.
Simplificar a lógica transacional, permitindo tratamento de erros unificado ou reversão.
Otimizar a vazão do API Gateway, evitando inundação de solicitações.
Casos de Uso Típicos da API em Lote
| Cenário | Descrição |
|---|---|
| 1. Consultas de dados em massa | Recupere vários usuários, produtos ou publicações de uma só vez para evitar solicitações repetidas. |
| 2. Escrita ou atualização em massa | Crie ou atualize vários registros em uma única operação (ex: upload em lote, atualização de inventário). |
| 3. Otimização de desempenho front-end | Reduza o número de chamadas HTTP de navegadores ou aplicativos móveis para tempos de carregamento mais rápidos. |
| 4. Agregação de tarefas de backend | Em sistemas de microsserviços, combine várias chamadas de API internas em uma única chamada externa. |
| 5. Sincronização de dados | Sincronize vários estados de recursos ou execute operações em lote (ex: marcação, exclusão). |
| 6. Otimização de limite de taxa | Diminua a carga do API Gateway e economize largura de banda ao consolidar solicitações. |
Principais Fatores que Afetam a Eficiência da API em Lote
Quanto custo as APIs em Lote podem economizar em comparação com APIs em tempo real?
Análises de mercado (Growth-onomics) mostram reduções de custo de cerca de 20 a 45%, principalmente devido a menos viagens de ida e volta na rede, menor sobrecarga de conexão e processamento concentrado, embora a economia exata dependa da frequência de chamadas, tamanho do lote e design do sistema.
E a latência: as APIs em Lote realmente podem concluir as tarefas “em até 24 horas”?
As APIs em Lote geralmente são executadas de forma assíncrona com latência muito maior do que as APIs em tempo real; muitos sistemas executam tarefas de hora em hora ou diariamente, então “em até 24 horas” depende do SLA (Acordo de Nível de Serviço) e não é garantido.
O tamanho do lote ou do arquivo afeta a velocidade?
Sim. Lotes maiores (ex: mais linhas de JSONL) aumentam o tempo de transferência e análise quase linearmente; embora a vazão melhore, o tempo total de conclusão por lote aumenta.
Por que as APIs em Lote são melhores para cargas de trabalho de alto throughput?
Ao agregar milhares de solicitações em um único processo, as APIs em Lote reduzem a sobrecarga por chamada e permitem execução paralela ou reutilização de cache, geralmente melhorando a vazão em 17 a 92% em operações em grande escala, embora isso tenha como custo uma latência mais alta.
Como Usar a API em Lote？
A API em Lote da Novita é altamente compatível com a interface da OpenAI, suportando
/v1/chat/completionse/v1/completions, para que o código existente possa ser reutilizado com alterações mínimas. Ela aceita arquivos de entrada.jsonlem que cada linha representa uma solicitação individual para o mesmo modelo, identificada por umcustom_idexclusivo para facilitar o rastreamento. A saída também está no formato JSONL, tornando o pós-processamento em grande escala, a análise e a integração simples e eficientes.
1. Prepare o Seu Arquivo de Entrada de Lote
Crie um arquivo .jsonl, em que cada linha é uma solicitação de API no formato JSON.
Exemplo (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}}
Regras:
- Uma solicitação por linha.
- Todas as solicitações devem usar o mesmo modelo.
- Cada linha deve incluir um
custom_idexclusivo.
2. Faça Upload do Arquivo de Entrada e Crie um Lote
Use Python ou curl para fazer upload do arquivo e iniciar o trabalho de lote imediatamente.
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. Verifique o Status do Lote
Você pode verificar o progresso a qualquer momento usando o ID do lote.
batch = client.batches.retrieve("batch_xxx")
print(batch.status)
Os status incluem:
VALIDATING– arquivo de entrada sendo verificadoPROGRESS– em execuçãoCOMPLETED– concluído com sucessoFAILED– falhouEXPIRED– excedeu a janela de 48h
4. Recupere os Resultados
Depois de concluído, baixe o arquivo de resultados por meio do output_file_id:
output = client.files.content("file_xxx")
print(output.read().decode("utf-8"))
Cada linha na saída corresponde a uma entrada, correspondente ao custom_id.
Dicas:
suporta apenas
deepseek/deepseek-r1-0528Até 50 000 solicitações por lote
Arquivo de entrada ≤ 100 MB
Janela de conclusão fixa em 48 horas
Saída retida por 30 dias
Como as Solicitações com Falha Devem Ser Tratadas em uma API em Lote?
Erros encontrados durante o processamento em lote são registrados em um arquivo de erros separado, acessível por meio do campo error_file_id. Cada sub-solicitação com falha inclui um código de erro e uma descrição. Exemplos comuns:
| Código de Erro | Descrição | Solução |
|---|---|---|
| 400 | Formato de solicitação inválido | Verifique a sintaxe do JSONL e os campos obrigatórios |
| 401 | Falha na autenticação | Verifique a chave de API |
| 404 | Lote não encontrado | Verifique o ID do lote |
| 429 | Limite de taxa excedido | Reduza a frequência de solicitações |
| 500 | Erro no servidor | Entre em contato com o provedor ou tente novamente mais tarde |
Os desenvolvedores devem reprocessar apenas as entradas com falha usando uma fila de repetição ou um lote de acompanhamento menor, em vez de reenviar o arquivo original inteiro.
Quais Endpoints a Novita AI Disponibiliza para Operações de API em Lote?
| Endpoint | Propósito |
|---|---|
| Criar lote | Enviar um novo trabalho de lote contendo várias solicitações. |
| Recuperar lote | Obter o status ou os resultados de um lote específico por seu ID. |
| Cancelar lote | Interromper um trabalho de lote em execução antes da conclusão. |
| Listar lotes | Listar todos os trabalhos de lote enviados para a conta. |
| Fazer upload de arquivo | Fazer upload de arquivos de dados de entrada (ex: JSONL). |
| Listar arquivos | Visualizar todos os arquivos enviados. |
| Recuperar arquivo | Obter metadados do arquivo por ID do arquivo. |
| Excluir arquivo | Remover um arquivo enviado. |
| Recuperar conteúdo do arquivo | Baixar o conteúdo real de um arquivo (ex: resultados ou log de erros). |
A API em Lote consolida várias solicitações pequenas em um fluxo de trabalho eficiente. Ao usar a API em Lote da Novita AI, os desenvolvedores podem reduzir os custos de rede em até 45%, escalar a vazão para até 50 000 solicitações por lote e simplificar o tratamento de erros por meio de endpoints de registro e recuperação integrados. Embora sacrifique a velocidade em tempo real, ela oferece eficiência excepcional para cargas de trabalho de inferência em massa, sincronização e processamento de dados.
Novita AI é uma plataforma de nuvem de IA que oferece aos desenvolvedores uma maneira fácil de implantar modelos de IA usando nossa API simples, além de fornecer uma nuvem de GPU acessível e confiável para construção e escalonamento.
