API LLM personalizada do LangChain: aponte para qualquer URL base
Para usar uma API LLM personalizada do LangChain, você não precisa escrever uma classe personalizada: o wrapper de chat compatível com OpenAI aceita uma URL base, uma chave e um nome de modelo. Aqui está a configuração exata, além de streaming, ferramentas, saída JSON e tratamento de limites.
Pontos principais
- ChatOpenAI aceita base_url, api_key e model, então não é necessária subclassificação.
- Use o modelo uncensored e a URL base https://api.llmapistatus.com/v1.
- Chamada de ferramentas, streaming e modo JSON passam todos pelo endpoint.
- Limite as cadeias paralelas a 8 para ficar abaixo do limite de concorrência; embeddings não são oferecidos.

A resposta curta: ChatOpenAI com uma URL base diferente
LangChain se comunica com servidores estilo OpenAI através do pacote langchain-openai. Sua classe ChatOpenAI permite substituir para onde as requisições vão, o que é exatamente o que um endpoint personalizado precisa. Instale o pacote e, em seguida, passe três valores: a URL base https://api.llmapistatus.com/v1, sua chave e o ID do modelo uncensored.
Instale com pip install -U langchain-openai langchain-core.
import os
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.llmapistatus.com/v1",
api_key=os.environ["LLM_API_KEY"],
temperature=0.7,
)
print(llm.invoke("Reply with the single word: ready").content)
Se isso imprimir uma resposta, a conexão está correta. Você obtém uma chave na página da chave de API; o início rápido mostra a mesma configuração para usuários de SDK puro. O endpoint serve POST /v1/chat/completions e GET /v1/models, e esses dois métodos são tudo que o wrapper OpenAI precisa para chat.
Uma palavra sobre o termo "LLM personalizada". LangChain também documenta uma maneira de escrever seu próprio modelo de chat subclassificando uma classe base, o que faz sentido para APIs que não falam o formato OpenAI. Este endpoint fala, então a subclassificação adicionaria apenas código para manter. Recorra a isso apenas se precisar de comportamento que o wrapper não possa expressar.
Construindo uma cadeia com prompts e análise de saída
Com o objeto de modelo no lugar, todo o resto no LangChain funciona da maneira que funciona com qualquer modelo de chat. Aqui está uma pequena cadeia escrita no estilo de linguagem de expressão: um modelo de prompt, o modelo e um analisador de string.
# reuses llm from the first example: base_url https://api.llmapistatus.com/v1, model uncensored
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
prompt = ChatPromptTemplate.from_messages([
("system", "You are a blunt technical editor. Answer in at most {limit} words."),
("human", "Rewrite this for clarity:\n\n{text}"),
])
chain = prompt | llm | StrOutputParser()
print(chain.invoke({
"limit": 60,
"text": "The thing that we did was basically to make the cache be invalidated on write.",
}))
Nada nesta cadeia sabe ou se importa que o modelo esteja atrás de um domínio diferente. Esse é o benefício da API compatível: prompts, classes de memória, recuperadores e agentes escritos contra a interface de chat padrão continuam funcionando. O que você deve verificar do seu lado é o próprio prompt. Um modelo ajustado para responder sem recusas de conteúdo segue instruções literalmente, então prompts de sistema vagos produzem comportamento vago. Declare o papel, o formato e o comprimento.
Vale a pena conhecer um limite antes de projetar um pipeline de recuperação. Este serviço é apenas de texto. Não há embeddings, então OpenAIEmbeddings apontado para esta URL base falhará. Use um modelo de embedding local ou outro provedor para o armazenamento de vetores e use este endpoint apenas para geração.
Streaming de tokens conforme chegam
O endpoint suporta eventos enviados pelo servidor quando você envia stream: true, e LangChain converte isso em um iterador. Você não define a flag você mesmo; chamar .stream() faz isso.
# reuses llm from the first example: base_url https://api.llmapistatus.com/v1, model uncensored
for chunk in llm.stream("Write a four-line poem about a failing cron job."):
print(chunk.content, end="", flush=True)
print()
Para servidores assíncronos use astream. A mesma chamada existe na biblioteca JavaScript:
import { ChatOpenAI } from "@langchain/openai";
const llm = new ChatOpenAI({
model: "uncensored",
apiKey: process.env.LLM_API_KEY,
configuration: { baseURL: "https://api.llmapistatus.com/v1" },
});
const stream = await llm.stream("Write a four-line poem about a failing cron job.");
for await (const chunk of stream) {
process.stdout.write(chunk.content);
}
Lembre-se de que uma solicitação de streaming mantém seu slot de concorrência até que o último evento chegue. Se um usuário fechar a aba do navegador e seu servidor continuar lendo o streaming, esse slot permanece ocupado. Cancele a solicitação upstream quando o cliente se desconectar. Os números de uso chegam ao final do streaming, que é onde você lê as contagens finais de tokens para logs de faturamento.
Chamada de funções e agentes
A chamada de ferramentas está disponível: o endpoint aceita tools e tool_choice, transmite tool_calls de volta e aceita seus resultados como mensagens com role: "tool". No LangChain, você anexa ferramentas com bind_tools e deixa o framework construir as mensagens.
# reuses llm from the first example: base_url https://api.llmapistatus.com/v1, model uncensored
from langchain_core.tools import tool
@tool
def get_order_status(order_id: str) -> str:
'Look up the status of an order by its id.'
return f"Order {order_id} shipped yesterday."
llm_tools = llm.bind_tools([get_order_status])
ai = llm_tools.invoke("Where is order A-1042?")
print(ai.tool_calls)
Executar a chamada e retornar o resultado é a segunda metade do loop:
# reuses llm from the first example: base_url https://api.llmapistatus.com/v1, model uncensored
# llm_tools comes from the previous snippet
from langchain_core.messages import HumanMessage, ToolMessage
messages = [HumanMessage("Where is order A-1042?")]
ai = llm_tools.invoke(messages)
messages.append(ai)
for call in ai.tool_calls:
result = get_order_status.invoke(call["args"])
messages.append(ToolMessage(content=result, tool_call_id=call["id"]))
print(llm_tools.invoke(messages).content)
Modelos de pesos abertos variam em quão bem eles selecionam ferramentas e preenchem argumentos. Mantenha as descrições das ferramentas curtas e concretas, use poucas ferramentas por chamada e valide argumentos na sua função em vez de confiar neles. Se um agente entrar em loop, reduza a temperatura e defina um número máximo de etapas no executor do seu agente.
Saída estruturada e JSON
O modo JSON é suportado através de response_format: {"type": "json_object"}. No LangChain, a rota mais fácil é with_structured_output usando o método de modo JSON, que também valida o resultado contra um esquema.
# reuses llm from the first example: base_url https://api.llmapistatus.com/v1, model uncensored
from pydantic import BaseModel
class Ticket(BaseModel):
title: str
priority: str
tags: list[str]
structured = llm.with_structured_output(Ticket, method="json_mode")
result = structured.invoke(
"Return JSON with keys title, priority and tags for this report: "
"login page times out on mobile, affects many users."
)
print(result)
O modo JSON garante que a saída seja um objeto JSON, não que tenha os campos que você queria. Dois hábitos ajudam. Primeiro, nomeie as chaves no prompt, como acima; a instrução para produzir JSON deve ser explícita. Segundo, envolva a chamada em uma nova tentativa que refaça a análise em caso de falha. A verificação pydantic captura campos ausentes e tipos errados, e uma única tentativa com a mensagem de erro anexada geralmente corrige isso.
Você também pode definir response_format diretamente quando construir o modelo com model_kwargs={"response_format": {"type": "json_object"}}, o que é útil para cadeias simples que terminam em um analisador JSON.
Limites de requisições, tentativas e cadeias paralelas
Trabalhos em lote e agentes fazem muitas chamadas ao mesmo tempo, e é aqui que um endpoint personalizado difere de um modelo local. Uma chave completa permite 8 requisições simultâneas e 300 requisições por minuto. Uma chave de teste permite 2 simultâneas e 60 por minuto. Ao ultrapassar um limite, a API responde com HTTP 429 e o código de erro rate_limited ou concurrency; em sobrecarga temporária, responde 429 com Retry-After: 5.
Duas configurações do LangChain lidam com a maioria disso. O modelo aceita max_retries, que repete a tentativa em falhas transitórias com backoff, e runnables aceitam um valor max_concurrency em sua configuração para trabalho em lote:
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.llmapistatus.com/v1",
api_key=os.environ["LLM_API_KEY"],
max_retries=4,
timeout=120,
)
questions = [f"Summarise item {i} in one sentence." for i in range(40)]
answers = llm.batch(questions, config={"max_concurrency": 6})
Definir o limite para 6 em uma chave completa deixa espaço para outras duas requisições, como uma chamada voltada ao usuário do mesmo aplicativo. Em uma chave de teste, use 1 ou 2. Não confie apenas nas tentativas para resolver um problema de concorrência: se o limite estiver acima do máximo, as tentativas apenas recriam a mesma colisão. Ler X-RateLimit-Limit-Requests e X-RateLimit-Limit-Concurrency nos cabeçalhos de resposta mostra o que sua chave permite.
Entradas longas são válidas até a janela de 100.000 tokens, compartilhada entre prompt e conclusão, e o corpo da requisição é limitado a 8 MB. Os splitters de texto do LangChain definidos para alguns milhares de tokens por chunk mantêm você longe de ambos.
Solução de problemas de um endpoint personalizado
A maioria dos problemas com uma URL base personalizada se enquadra em uma lista curta, e cada um tem um teste rápido.
- Erros de autenticação. O LangChain também lê a variável de ambiente
OPENAI_API_KEY. Se você passarapi_keyexplicitamente, esse valor prevalece, mas uma variável desatualizada ainda pode confundir um segundo objeto de modelo que você esqueceu de configurar. Passe a chave sempre e dê à variável outro nome, comoLLM_API_KEY. - Erros de não encontrado. A URL base deve terminar em
/v1. LangChain anexa/chat/completionssozinho, então adicioná-lo à URL base produz um caminho duplicado. - Modelo desconhecido. Faça
GET /v1/modelscom a mesma chave e copie o ID que ele imprime. Deve seruncensored. - Bloqueios silenciosos em cadeias longas. Defina
timeoutno modelo e registre o cabeçalho de respostaX-Request-Id. Se você entrar em contato com o suporte, esse ID permite que eles localizem a requisição exata. - Saídas surpreendentes. Imprima o prompt final antes de ser enviado. A maioria das respostas estranhas no LangChain vem de um template que preencheu uma variável com algo inesperado, não do modelo.
Em caso de dúvida, reproduza a chamada falha com curl simples contra a mesma URL. Se curl funcionar e LangChain não, a falha está na sua cadeia; se ambos falharem, verifique a chave e o saldo.
Verificando o custo enquanto você desenvolve
Cadeias ocultam contagens de tokens, então meça cedo. Cada resposta inclui uso, e os cabeçalhos de resposta incluem X-Balance-USD. O preço é $0,15 por 1M tokens de entrada e $0,50 por 1M tokens de saída, cobrados do crédito pré-pago.
Um exemplo prático: uma cadeia de recuperação que envia 6.000 tokens de contexto e pergunta e recebe 400 tokens de volta custa 6.000 x $0,15 / 1M = $0,0009 para entrada mais 400 x $0,50 / 1M = $0,0002 para saída, totalizando $0,0011 por chamada. Executar 5.000 dessas chamadas em uma varredura de teste custa $5,50. Isso é útil saber antes de deixar um loop de agente rodando a noite toda.
Requisições falhas ou recusadas não são cobradas. A página de preços lista valores de recarga de $20 a $500 com bônus, e novas contas podem obter um crédito de teste de $0,50 com um clique, suficiente para algumas centenas de chamadas de teste pequenas enquanto você configura as coisas.
Mais guias
Perguntas e respostas
Preciso subclassificar a classe base de modelo de chat do LangChain?
Não. O endpoint é compatível com OpenAI, então ChatOpenAI com base_url, api_key e modelo personalizados funciona. A subclassificação só é necessária para APIs que usam um formato diferente.
Posso usar OpenAIEmbeddings com este endpoint?
Não. O serviço é apenas de texto e não possui embeddings. Use um modelo de embedding local ou outro provedor para vetores e use este endpoint para geração.
Qual nome de modelo devo passar?
Passe uncensored como o modelo. GET /v1/models retorna o mesmo ID.
Por que obtenho erros 429 em um trabalho em lote?
Você excedeu as requisições por minuto ou as requisições simultâneas. Reduza o max_concurrency para abaixo de 8 em uma chave completa, ou 2 em uma chave de teste, e mantenha as tentativas ativadas.
O streaming do LangChain funciona aqui?
Sim. Chamar stream ou astream usa eventos SSE, e o uso é enviado no final do stream.
Sua chave está a um formulário de distância
Crie uma conta, copie a chave e altere a URL base. Essa é toda a configuração.