API OpenAI para LLM local: execute localmente, migre para hospedado

O que a frase significa

As pessoas usam "API OpenAI para LLM local" para duas coisas relacionadas. A primeira é um modelo de linguagem que você executa sozinho, em um laptop ou servidor doméstico, que escuta em uma porta local e fala o formato de chat OpenAI. A segunda é o hábito de escrever seu app contra esse formato para que o modelo por trás possa ser substituído.

O formato é um contrato simples. Seu app envia um corpo JSON com um nome de model e uma lista de messages, cada uma com um role de system, user ou assistant. O servidor responde com um objeto JSON contendo a mensagem gerada, ou com um stream de pequenos chunks se você solicitar streaming. SDKs oficiais para Python e JavaScript envolvem isso, e permitem que você substitua a base URL, que é o truque principal.

Muitas ferramentas locais expõem esse contrato. Ollama, LM Studio, o servidor llama.cpp e vLLM oferecem cada um uma rota estilo OpenAI. Serviços hospedados também oferecem, por isso as mesmas vinte linhas de código do cliente podem falar com qualquer uma das duas opções. O endpoint deste site é um dos tipos hospedados. Ele aceita POST /v1/chat/completions e GET /v1/models, e é acessado em https://api.onekeyllmapi.com/v1.

Local versus hospedado em um relance

Nenhum é melhor em geral. Eles trocam controle por esforço. A tabela lista as diferenças que valem para a categoria, não para qualquer produto específico.

Se seus dados não devem sair jamais de uma máquina que você controla, o local vence e o hospedado é a ferramenta errada. Se você precisa de um modelo maior do que seu hardware suporta, ou de um bot que permaneça acessível de muitos lugares, o hospedado vence. Uma configuração comum mantém ambos e escolhe por tarefa.

Alternando um cliente de local para hospedado

Se seu código já fala com um executador local, a mudança são três valores. Tudo o resto, incluindo como você constrói mensagens e lê chunks em streaming, permanece igual.

1. Base URL. Use https://api.onekeyllmapi.com/v1 em vez do seu endereço local.
2. Chave de API. Servidores locais frequentemente ignoram a chave. Um serviço hospedado exige a chave como Authorization: Bearer <key>, e o SDK a envia para você.
3. ID do modelo. Nomes locais são o que você puxou. Aqui o ID é uncensored.

Uma maneira limpa de manter isso flexível é ler todos os três de variáveis de ambiente, para que um arquivo funcione em ambos os lugares.

Copyimport os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ.get("LLM_BASE_URL", "https://api.onekeyllmapi.com/v1"),
    api_key=os.environ.get("LLM_API_KEY", "YOUR_KEY"),
)
MODEL = os.environ.get("LLM_MODEL", "uncensored")

models = client.models.list()
print([m.id for m in models.data])

resp = client.chat.completions.create(
    model=MODEL,
    messages=[
        {"role": "system", "content": "Answer in two sentences."},
        {"role": "user", "content": "Why do OpenAI-style endpoints make switching models easy?"},
    ],
    temperature=0.5,
)
print(resp.choices[0].message.content)

A mesma chamada da linha de comando, útil para um teste rápido:

Copycurl https://api.onekeyllmapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "uncensored", "messages": [{"role": "user", "content": "ping"}], "max_tokens": 20}'

Com Node, o padrão é idêntico:

Copyimport OpenAI from "openai";

const client = new OpenAI({
  baseURL: process.env.LLM_BASE_URL ?? "https://api.onekeyllmapi.com/v1",
  apiKey: process.env.LLM_API_KEY,
});

const res = await client.chat.completions.create({
  model: process.env.LLM_MODEL ?? "uncensored",
  messages: [{ role: "user", content: "Name three uses for JSON mode." }],
});
console.log(res.choices[0].message.content);

O que a compatibilidade com OpenAI cobre e o que não cobre

Compatível significa que o formato de rede corresponde. Não garante que todas as funcionalidades que o serviço original oferece estejam presentes. Antes de migrar um aplicativo real, verifique cada uma destas contra o destino.

O que esta API suporta

• Completions de chat em POST /v1/chat/completions e uma lista de modelos em GET /v1/models.
• Streaming sobre eventos enviados pelo servidor com stream: true, com o uso reportado no final do streaming.
• Chamada de funções através de tools e tool_choice, streaming de tool_calls, e resultados enviados como mensagens de role: "tool".
• Modo JSON através de response_format: {"type": "json_object"}.
• Controles de amostragem: temperature, top_p, stop, seed e os parâmetros de penalidade são passados.

O que não faz

• Sem geração de imagens, áudio ou vídeo. É apenas texto.
• Sem endpoint de embeddings e sem ajuste fino. Se seu app constrói um índice vetorial, você precisa de uma fonte de embedding separada.
• Apenas um modelo. O modelo é um modelo de pesos abertos executado por um provedor independente. Não é a API oficial de nenhum grande fornecedor, e não é um roteador entre fornecedores, então você não pode escolher entre famílias de modelos alterando o ID.

Runners locais às vezes diferem da outra forma: um servidor local pode oferecer uma rota de embeddings ou permitir carregar vários modelos, e o tamanho da janela de contexto é o que você configura. Leia a documentação do alvo para cada um, e mantenha uma lista curta dos recursos que seu app realmente usa. A documentação de início rápido mostra os campos de solicitação em detalhes.

Contexto, limites e diferenças de custo

Três números mudam quando você deixa um servidor local. O primeiro é a janela. O comprimento de contexto de um executor local é uma configuração ligada à sua memória. Aqui é fixo em 100.000 tokens, compartilhado pelo prompt e pela conclusão, e max_tokens é opcional. O segundo é a concorrência. Sua própria máquina pode ser enfileirada tanto quanto você quiser, mas uma chave completa aqui permite 8 requisições simultâneas e 300 por minuto, e uma chave de teste 2 e 60. O terceiro é a conta.

O uso hospedado custa $0,15 por 1M de tokens de entrada e $0,50 por 1M de tokens de saída, pagamento por uso a partir de crédito pré-pago. Execute um trabalho diário como exemplo: um sistema de resumo processa 400 documentos por dia, cada um com 3.000 tokens de entrada e 300 tokens de saída. A entrada é 400 x 3.000 = 1.200.000 tokens, que custam 1,2 x $0,15 = $0,18. A saída é 400 x 300 = 120.000 tokens, que custam 0,12 x $0,50 = $0,06. O dia totaliza $0,24, e um mês de 30 dias é $7,20. Compare isso com o custo de manter uma GPU ligada e do próprio cartão antes de decidir.

Quando você excede um limite, a API responde HTTP 429 com o código rate_limited ou concurrency. Para sobrecarga breve, adiciona Retry-After: 5. Mantenha a lógica de nova tentativa que espera e tenta novamente. Solicitações que falham ou são recusadas não são cobradas. O crédito nunca expira, então um mês ocioso não custa nada.

Uma solicitação em streaming mantém sua vaga de concorrência até o stream terminar, então feche streams que você parar de ler. Recargas começam em $20; os níveis e bônus estão na página de preços.

Depuração quando a alternância falha

A maioria das migrações com falha se resume a um pequeno número de causas. Verifique-as nesta ordem.

• Erros 404 ou de conexão. A base URL provavelmente não tem o sufixo /v1 ou tem um caminho extra. Use-o exatamente como https://api.onekeyllmapi.com/v1.
• Erros de autenticação. A chave está ausente ou enviada no cabeçalho errado. O formato é Authorization: Bearer <key>. Usuários de SDK devem confirmar se a variável de ambiente foi carregada corretamente.
• Modelo não encontrado. O nome antigo do modelo local ainda está na sua configuração. Chame GET /v1/models e use o ID listado, que é uncensored.
• 429 sob carga. Você ultrapassou 8 requisições simultâneas ou 300 por minuto com uma chave completa. Adicione uma fila ou semáforo.
• Um parâmetro parece ser ignorado. Verifique se ele está entre os campos passados listados acima e compare o comportamento com um seed fixo e temperatura baixa.

Cada resposta inclui o cabeçalho X-Request-Id. Registre-o ao lado do seu próprio ID de requisição para rastrear uma resposta ruim posteriormente. Se você executa tráfego de produção e quer medir a qualidade ao longo do tempo, o artigo do site LLM Observability: Myths vs Facts é uma boa leitura seguinte. Os cabeçalhos de resposta X-Balance-USD, X-RateLimit-Limit-Requests e X-RateLimit-Limit-Concurrency também valem a pena ser capturados.

Experimente sem compromisso

A maneira mais barata de testar se seu código migra limpo é executá-lo uma vez. Crie uma conta com Google ou e-mail e senha, depois resgate o crédito de teste de $0,50 na página da chave. Leva um clique, não precisa de cartão, é limitado a um por pessoa e é válido por 7 dias. Obtenha sua chave na página da chave de API, defina as três variáveis de ambiente acima e execute seu conjunto de testes existente.

Se os testes passarem e o uso se encaixar no seu orçamento, recarregue a partir de $20, por cartão (Visa, Mastercard, Apple Pay, Google Pay) ou cripto (USDT na TRC20, USDC na Base). Os prompts não são usados para treinamento. O modelo é ajustado para responder sem recusas de conteúdo para uso adulto legal, com uma regra fixa: sem conteúdo sexual envolvendo menores de idade.

Mais guias

• Observabilidade de LLM: Mitos vs Fatos