PT ▾
Obter chave de API

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.

Atualizado

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.
Cadeia de nós conectados que se ligam a um servidor de modelo remoto através de um único endpoint

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ê passar api_key explicitamente, 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, como LLM_API_KEY.
  • Erros de não encontrado. A URL base deve terminar em /v1. LangChain anexa /chat/completions sozinho, então adicioná-lo à URL base produz um caminho duplicado.
  • Modelo desconhecido. Faça GET /v1/models com a mesma chave e copie o ID que ele imprime. Deve ser uncensored.
  • Bloqueios silenciosos em cadeias longas. Defina timeout no modelo e registre o cabeçalho de resposta X-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.

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.

Obter chave de API