LangChain e LangGraph sem chave de API

O que "sem chave de API" pode significar realisticamente

Pesquisar por langchain e langraph sem chave de API geralmente significa uma de três coisas. Você pode querer evitar pagar antes de saber se a infraestrutura funciona. Você pode não querer passar um cartão de crédito para mais um fornecedor. Ou você pode querer executar um grafo de agentes sem nenhuma credencial.

O terceiro desejo não pode ser atendido por nenhum serviço hospedado: um servidor que faz o trabalho para você precisa saber quem está chamando. O que você pode obter é uma chave que não custa nada e não pede cartão. Novos usuários neste site podem obter $0,50 de crédito de teste com um clique na página da chave de API após entrar com Google ou com e-mail e senha. É uma por pessoa e válida por 7 dias.

A outra rota para "sem chave" é um modelo local servido por algo em sua própria máquina. Isso funciona, mas você assume o hardware, e um laptop não corresponderá a um endpoint hospedado para execuções longas de agente. Uma avaliação hospedada é a maneira mais rápida de descobrir se a lógica do seu grafo é sólida, e o código que você escreve é idêntico ao que você executará mais tarde com uma chave financiada.

Como o endpoint é compatível com OpenAI, o LangChain não precisa de integração especial. Você aponta sua classe de chat OpenAI para uma URL base diferente, fornece a chave e nomeia o modelo uncensored. Tudo abaixo assume essa configuração.

Passo 1: obter a chave de teste e configurar o ambiente

Registre-se, abra a página de chaves e pressione o botão de teste. Copie a chave e mantenha-a fora do seu repositório. Coloque-a em uma variável de ambiente para que o mesmo script funcione com uma chave de teste hoje e uma chave completa depois.

Copyexport UNCENSORED_API_KEY="paste-your-key-here"
pip install -U langchain-openai langgraph langchain-core

Antes de envolver qualquer framework, verifique a chave com uma requisição simples. Dois minutos aqui economizam uma hora de leitura de rastros de pilha que são realmente erros de autenticação.

Copycurl https://api.stableaudio.top/v1/chat/completions \
  -H "Authorization: Bearer $UNCENSORED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"uncensored","messages":[{"role":"user","content":"Reply with one word: ready"}]}'

Uma chamada GET /v1/models é a outra verificação rápida; deve listar uncensored. A chave de teste permite 2 requisições simultâneas e 60 requisições por minuto, o que é suficiente para desenvolver um grafo, mas vale lembrar ao adicionar nós paralelos.

Passo 2: apontar o LangChain para o endpoint

A classe a ser usada é ChatOpenAI de langchain-openai. Dois argumentos fazem o trabalho: base_url e api_key. O nome do modelo é uncensored, e as configurações habituais de amostragem são passadas.

Copyimport os
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="uncensored",
    base_url="https://api.stableaudio.top/v1",
    api_key=os.environ["UNCENSORED_API_KEY"],
    temperature=0.7,
    max_retries=3,
)

print(llm.invoke("Give me three titles for an ambient track about rain.").content)

Se isso imprimir texto, a conexão está boa. O streaming funciona da mesma forma: itere sobre llm.stream(...) e os fragmentos chegam via eventos enviados pelo servidor, com o uso reportado no final do stream.

Um erro comum é deixar a variável OPENAI_API_KEY definida de um projeto antigo. O LangChain enviará esse valor para sua URL base personalizada se você esquecer de passar api_key. Passe a chave explicitamente e você elimina as suposições.

Passo 3: um grafo LangGraph mínimo

LangGraph modela seu agente como estado movendo-se entre nós. O grafo útil mais simples tem um nó que chama o modelo e anexa a resposta a uma lista de mensagens. MessagesState dá essa lista de graça.

Copyfrom langgraph.graph import StateGraph, MessagesState, START, END

def call_model(state: MessagesState):
    reply = llm.invoke(state["messages"])
    return {"messages": [reply]}

builder = StateGraph(MessagesState)
builder.add_node("model", call_model)
builder.add_edge(START, "model")
builder.add_edge("model", END)
graph = builder.compile()

out = graph.invoke({"messages": [("user", "Outline a three-act short story about a lighthouse keeper.")]})
print(out["messages"][-1].content)

Isso é deliberadamente simples. O ponto é que nada no LangGraph sabe ou se importa com qual provedor está atrás de llm. Qualquer nó pode ter um objeto de modelo diferente, então você pode depois dar a uma etapa de planejamento barata e uma etapa de escrita mais longa suas próprias configurações, como uma temperatura menor para planejamento.

Passo 4: adicionar ferramentas e um loop

Os agentes ficam interessantes quando o modelo pode chamar funções. O endpoint suporta chamada de funções com tools e tool_choice, e os resultados das ferramentas retornam como mensagens role: "tool". O LangChain e o LangGraph cuidam dessa infraestrutura para você.

Copyfrom langchain_core.tools import tool
from langgraph.prebuilt import ToolNode, tools_condition

@tool
def word_count(text: str) -> int:
    'Count the words in a piece of text.'
    return len(text.split())

tools = [word_count]
llm_with_tools = llm.bind_tools(tools)

def agent(state: MessagesState):
    return {"messages": [llm_with_tools.invoke(state["messages"])]}

builder = StateGraph(MessagesState)
builder.add_node("agent", agent)
builder.add_node("tools", ToolNode(tools))
builder.add_edge(START, "agent")
builder.add_conditional_edges("agent", tools_condition)
builder.add_edge("tools", "agent")
graph = builder.compile()

result = graph.invoke({"messages": [("user", "Write a 40-word product blurb, then check its word count with the tool.")]})
print(result["messages"][-1].content)

O loop é a ideia inteira: o nó do agente responde, tools_condition verifica se a resposta pediu uma ferramenta, o nó da ferramenta a executa, e o controle retorna ao agente. Quando uma resposta não tem chamada de ferramenta, o grafo termina.

Modelos de pesos abertos variam em quão organizados são seus argumentos de ferramenta. Se uma chamada retornar malformada, ajuste a docstring da ferramenta, diminua a temperatura e mantenha o esquema de argumento pequeno. Esquemas curtos e tipados falham menos frequentemente do que longos com muitos campos opcionais.

Limites de requisições, tentativas e ramificações paralelas

O lugar onde grafos de agente mais tropeçam é a concorrência. Uma chave completa permite 8 requisições simultâneas e 300 requisições por minuto; uma chave de teste permite 2 e 60. Se seu grafo ramifica em cinco nós paralelos em uma chave de teste, três deles serão rejeitados com HTTP 429 e o código de erro concurrency. Ultrapassar o orçamento por minuto retorna rate_limited. Sobrecarga temporária também dá 429, com um cabeçalho Retry-After: 5.

Três hábitos mantêm isso gerenciável:

• Mantenha max_retries em 2 ou 3 no ChatOpenAI para que erros 429 breves sejam tentados novamente com backoff.
• Limite ramificações no seu limite de concorrência. No LangGraph você pode passar config={"max_concurrency": 2} ao invocar o grafo.
• Lembre-se de que uma requisição streaming mantém seu slot até o fim do streaming, então um consumidor lento mantém um slot ocupado.

Copyout = graph.invoke(
    {"messages": [("user", "Draft five taglines in parallel.")]},
    config={"max_concurrency": 2},
)

Os cabeçalhos de resposta ajudam na depuração. X-Request-Id identifica uma chamada se você precisar perguntar ao suporte sobre ela, e X-Balance-USD mostra seu crédito restante após cada solicitação.

Lista de verificação de depuração quando o grafo se comporta mal

A maioria das falhas em um primeiro projeto LangGraph não é sobre o modelo. Elas vêm de configuração, e uma lista de verificação curta captura quase todas elas.

1. 401 ou erros de autenticação. A chave está faltando, digitada incorreta ou um OPENAI_API_KEY antigo está sendo lido em vez disso. Imprima os primeiros quatro caracteres do valor que seu script realmente usa.
2. 404 ou modelo não encontrado. O nome do modelo deve ser uncensored. Chame GET /v1/models se não tiver certeza do que o endpoint lista.
3. Erros de conexão. A URL base deve terminar em /v1 e não deve incluir /chat/completions; o cliente adiciona essa parte.
4. Loops infinitos. Se o agente continua chamando uma ferramenta, o valor de retorno da ferramenta pode não responder à pergunta. Retorne strings simples e curtas e defina um limite de recursão através da configuração do grafo para que um loop ruim pare cedo.
5. Respostas vazias ou estranhas. Imprima a lista completa de mensagens após uma execução. Frequentemente um nó anterior escreveu uma mensagem de sistema que contradiz a posterior.

Quando uma solicitação falha no lado do servidor, cote o cabeçalho X-Request-Id em sua mensagem para suporte. Isso permite que eles encontrem essa chamada exata sem adivinhações. Tenha em mente também que solicitações falhas ou recusadas não são cobradas, então uma sessão de depuração cheia de erros não consome seu crédito de teste.

Mais um ponto de design. Dê a cada nó um trabalho estreito e um prompt curto. Um grafo com um planejador, um escritor e um verificador, cada um com sua própria mensagem de sistema pequena, é mais fácil de testar do que um único nó com uma página de instruções, e cada peça pode ser testada sozinha com uma chamada direta llm.invoke antes de conectá-la.

Quanto uma execução de teste realmente custa

O preço é $0.15 por 1M de tokens de entrada e $0.50 por 1M de tokens de saída, descontados do crédito pré-pago. Requisições falhas ou recusadas não são cobradas. Grafos de agentes chamam o modelo várias vezes por tarefa, e cada chamada reenvia a lista de mensagens crescente, então os tokens de entrada dominam.

Faça uma execução com seis chamadas de modelo. Digamos que cada chamada envie 3.000 tokens e retorne 400 tokens. Isso são 18.000 tokens de entrada e 2.400 tokens de saída.

• Entrada: 18.000 / 1.000.000 x $0,15 = $0,0027
• Saída: 2.400 / 1.000.000 x $0,50 = $0,0012
• Total: $0.0039 por execução

Os $0,50 de teste divididos por $0,0039 resultam em cerca de 128 execuções desse tamanho, suficientes para construir e testar um grafo adequadamente. Quando você ultrapassar esse limite, as recargas variam de $20 a $500 em valores inteiros, com bônus de 5% a partir de $50, 10% a partir de $100 e 15% a partir de $200; a página de preços tem os detalhes. Você pode pagar com cartão (Visa, Mastercard, Apple Pay, Google Pay) ou com cripto (USDT na TRC20, USDC na Base). O crédito nunca expira e os prompts não são usados para treinamento.

A janela de contexto é de 100.000 tokens para prompt mais conclusão, então históricos longos de agentes cabem, mas você paga por cada token que reenvia. Remover mensagens antigas com as utilidades de mensagem do LangGraph mantém o custo e a latência baixos. Para o formato de requisição bruto por trás de tudo isso, consulte a documentação da API.

Mais guias

• LLM de Texto para Áudio: O Que Ele Pode e Não Pode Fazer
• API de Texto Sem Censura para Prompts de Vídeo