O que você precisa antes de começar
O LangChain se conecta a qualquer servidor que implemente o protocolo de chat completions da OpenAI, então não há integração especial para instalar. Seu ponto de partida é o mesmo pacote que você usaria para a OpenAI: langchain-openai para Python ou @langchain/openai para Node. Apenas três valores mudam.
- Base URL:
https://api.deepseekapipricing.com/v1 - Modelo:
uncensored - Chave: enviada como
Authorization: Bearer <key>, que o cliente faz para você
Um esclarecimento sobre nomenclatura. Este endpoint é um serviço independente executando um modelo de pesos abertos ajustado para responder sem recusas de conteúdo para uso adulto legal. Não é a API oficial da DeepSeek nem um roteador entre fornecedores, então o nome do modelo é sempre uncensored, não um ID de modelo de fornecedor. Se você precisa de uma chave, a página da chave de API mostra os passos de cadastro e o teste de $0,50 com um clique.
Instale e faça a primeira chamada em Python
Instale os pacotes:
pip install -U langchain-openai langchain-core
# then use base_url https://api.deepseekapipricing.com/v1 and model "uncensored"
Depois crie o objeto do modelo. Passe a chave explicitamente em vez de confiar na variável de ambiente OPENAI_API_KEY, que pode conter uma chave real da OpenAI que você não quer enviar para um host diferente.
import os
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.deepseekapipricing.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
temperature=0.7,
max_retries=2,
)
print(llm.invoke("Say hello in five words.").content)
Se isso imprimir uma saudação, a conexão, a chave e o nome do modelo estão corretos. O erro mais comum nesta etapa é omitir /v1 na base URL, o que geralmente gera um erro not-found.
Prompts, chains e streaming
A partir daqui, o LangChain funciona como de costume. Um template de prompt, o modelo e um parser de saída são combinados em uma cadeia com o operador pipe:
# llm = ChatOpenAI(model="uncensored", base_url="https://api.deepseekapipricing.com/v1", ...)
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
prompt = ChatPromptTemplate.from_messages([
("system", "You write tight, vivid scene descriptions for adult fiction."),
("human", "Describe this setting in under 80 words: {setting}"),
])
chain = prompt | llm | StrOutputParser()
print(chain.invoke({"setting": "a flooded subway station at night"}))
O streaming ocorre via eventos enviados pelo servidor. No LangChain você chama stream, e cada chunk carrega um pedaço de texto. Defina stream_usage=True no modelo se quiser contagem de tokens no final do stream; a API envia o uso no evento final.
llm_stream = ChatOpenAI(
model="uncensored",
base_url="https://api.deepseekapipricing.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
stream_usage=True,
)
for chunk in llm_stream.stream("Write a four-line poem about a night train."):
print(chunk.content, end="", flush=True)
Uma requisição em streaming mantém seu slot de concorrência até que o streaming termine, então, se você interromper um streaming sem fechá-lo, esse slot fica ocupado por mais tempo do que o esperado.
Node e TypeScript
O pacote JavaScript recebe a base URL dentro de um objeto configuration:
import { ChatOpenAI } from "@langchain/openai";
const llm = new ChatOpenAI({
model: "uncensored",
apiKey: process.env.UNCENSORED_API_KEY,
configuration: { baseURL: "https://api.deepseekapipricing.com/v1" },
maxRetries: 2,
});
const res = await llm.invoke("Say hello in five words.");
console.log(res.content);
const stream = await llm.stream("Write a four-line poem about a night train.");
for await (const chunk of stream) {
process.stdout.write(chunk.content);
}
Execute-o como um módulo ES ("type": "module" em package.json, ou um arquivo .mjs). Tudo o mais na API Node, incluindo prompt templates e runnables, comporta-se como faz com qualquer outro modelo de chat.
Chamada de funções e agentes
A API suporta o formato de ferramentas da OpenAI: os parâmetros tools e tool_choice, streaming de tool_calls, e resultados de ferramentas retornados como mensagens com role: "tool". No LangChain você declara ferramentas com um decorator e as anexa com bind_tools:
# llm = ChatOpenAI(model="uncensored", base_url="https://api.deepseekapipricing.com/v1", ...)
from langchain_core.tools import tool
from langchain_core.messages import HumanMessage, ToolMessage
@tool
def order_status(order_id: str) -> str:
"""Return the shipping status of an order."""
return f"Order {order_id} left the warehouse yesterday."
llm_tools = llm.bind_tools([order_status])
messages = [HumanMessage("Where is order 1042?")]
ai = llm_tools.invoke(messages)
messages.append(ai)
for call in ai.tool_calls:
result = order_status.invoke(call["args"])
messages.append(ToolMessage(content=result, tool_call_id=call["id"]))
print(llm_tools.invoke(messages).content)
Escrever o loop à mão uma vez vale os dez minutos. Isso mostra exatamente o que o modelo retornou, quais argumentos ele escolheu para cada chamada e onde uma descrição ruim de ferramenta leva a um palpite errado. Uma vez que isso esteja claro, mude para um agente pré-construído e mantenha a versão escrita à mão como referência de depuração.
Esse é o loop manual: o modelo pede uma ferramenta, você a executa, retorna o resultado e o modelo gera a resposta final. Se preferir um loop de agente pronto, o pacote langgraph oferece create_react_agent(llm, [order_status]), e você o invoca com {"messages": [("user", "Where is order 1042?")]}.
O quão bem um modelo escolhe ferramentas depende do modelo, então teste com seus próprios esquemas de ferramentas. Descrições de ferramentas curtas e específicas e uma temperatura baixa ajudam. Um agente que faz seis chamadas com um histórico crescente de cerca de 27.000 tokens de entrada no total e 1.800 tokens de saída custa aproximadamente $0,00405 mais $0,0009, ou cerca de meio centavo.
Saída estruturada com modo JSON
O modo JSON é suportado através de response_format. Vincule-o ao modelo e também diga no prompt que você quer JSON com chaves específicas, já que o parâmetro de formato controla a sintaxe, não seu esquema:
# llm = ChatOpenAI(model="uncensored", base_url="https://api.deepseekapipricing.com/v1", ...)
import json
json_llm = llm.bind(response_format={"type": "json_object"})
msg = json_llm.invoke(
"Return a JSON object with keys title (string) and tags (list of 3 strings) "
"for a short story about a lighthouse keeper."
)
data = json.loads(msg.content)
print(data["title"], data["tags"])
Valide o resultado analisado com Pydantic ou suas próprias verificações antes de confiar nele, e trate json.JSONDecodeError com uma nova tentativa. Para trabalhos de extração grandes, analise cada resposta de forma defensiva em vez de assumir que a primeira é limpa.
Recuperação, memória e callbacks
Esta API não possui endpoint de embeddings, então um pipeline de recuperação precisa de uma fonte separada de embeddings. Tudo após a recuperação é chat simples. Uma cadeia de recuperação típica extrai os melhores trechos do seu repositório de vetores, os insere no prompt e pede ao modelo para responder com base nesse texto. Como a janela de contexto é de 100.000 tokens, você pode usar trechos generosos, mas lembre-se da conta: cada token de contexto recuperado é processado como entrada a $0,15 por milhão, então 20.000 tokens de contexto custam $0,003 por pergunta.
Para memória de chat, a abordagem mais simples é uma lista de mensagens que você corta por contagem de tokens antes de cada chamada. O LangChain oferece auxiliares como trim_messages para isso. Mantenha a mensagem do sistema e as rodadas mais recentes, e descarte ou resuma o meio quando o histórico atingir um limite que você escolher. Um histórico menor também mantém as respostas focadas, e reduz o custo de cada rodada, porque todo o histórico é reenviado como entrada toda vez.
Callbacks são o local para registrar o custo de uma chamada. Cada resposta inclui um bloco de uso com tokens de prompt e conclusão, e no LangChain a mensagem retornada o carrega em usage_metadata:
# llm = ChatOpenAI(model="uncensored", base_url="https://api.deepseekapipricing.com/v1", ...)
msg = llm.invoke("Name three rivers.")
u = msg.usage_metadata
cost = u["input_tokens"] * 0.15 / 1_000_000 + u["output_tokens"] * 0.50 / 1_000_000
print(u, f"${cost:.6f}")
Registre o custo com o ID da requisição para que uma conta surpreendente possa ser rastreada até uma cadeia.
Prompts de sistema e tom
O modelo não possui recusas de conteúdo embutidas, então a mensagem do sistema é onde você define o comportamento do seu produto: a persona, o tom, os tópicos que deve evitar e o formato da resposta. Escreva-a como faria um briefing para um novo colega. Curto e específico funciona melhor do que longo e vago. Conteúdo envolvendo menores de idade é um limite rígido neste serviço, então não construa prompts que se aproximem disso.
Uma lista de verificação curta antes de enviar
- A chave vive em uma variável de ambiente ou secret store, nunca no repositório.
max_concurrencyestá definido para o limite da sua chave, ou abaixo dele se outros serviços compartilharem a chave.- As retentativas usam um back-off curto, e as respostas 429 com
Retry-After: 5são respeitadas. - Streams são fechados quando o cliente desconecta para liberar slots.
- Saídas JSON são analisadas de forma defensiva e validadas.
- Os custos são registrados por cadeia a partir do bloco de uso.
- Existe um fallback para o caso em que o endpoint está inacessível, mesmo que o fallback seja uma mensagem de erro.
Siga essa lista e a integração se comportará como qualquer outro modelo de chat do LangChain. A diferença está no lado do conteúdo, onde requisições que outros modelos recusam para uso adulto legal são respondidas.
Limites de taxa, concorrência e erros comuns
Uma chave completa permite 8 requisições simultâneas e 300 requisições por minuto. Uma chave de trial permite 2 requisições simultâneas e 60 por minuto. O corpo da requisição pode ter até 8 MB, e a janela de contexto é de 100.000 tokens cobrindo prompt e completion juntos.
Os helpers de batch do LangChain distribuem requisições, então defina um teto que corresponda à sua chave:
# llm = ChatOpenAI(model="uncensored", base_url="https://api.deepseekapipricing.com/v1", ...)
inputs = [{"setting": s} for s in ["a rooftop garden", "a desert diner", "a quiet harbor"]]
results = chain.batch(inputs, config={"max_concurrency": 8})
Use 2 em vez de 8 em uma chave de trial. Quando você excede um limite, a API retorna HTTP 429 com o código de erro rate_limited (muitas requisições por minuto) ou concurrency (muitas de uma vez). Em sobrecarga temporária também retorna 429, com um cabeçalho Retry-After: 5. A configuração max_retries no cliente lida com casos transitórios, mas se você vir o código de erro concurrency repetidamente, reduza max_concurrency em vez de adicionar retries.
- Erros not-found em todas as chamadas: verifique se a base URL termina em
/v1. - Erro de autenticação: a chave está faltando ou tem um erro de digitação; confirme que é passada através de
api_key. - Erros de modelo: o nome do modelo deve ser exatamente
uncensored. - Execuções em batch lentas: streams travados seguram slots de concurrency, então feche-os ou defina um timeout.
O preço é $0,15 por milhão de tokens de entrada e $0,50 por milhão de tokens de saída, e requisições falhas ou recusadas não são cobradas. A página de preços lista recargas, e a documentação abrange todos os parâmetros e os cabeçalhos de resposta, incluindo X-Request-Id e X-Balance-USD, úteis para registrar em um callback do LangChain.
