Cosa ti serve prima di iniziare
LangChain comunica con qualsiasi server che implementa il protocollo di chat completions di OpenAI, quindi non c'è un'integrazione speciale da installare. Il tuo punto di partenza è lo stesso pacchetto che useresti per OpenAI stesso: langchain-openai per Python o @langchain/openai per Node. Solo tre valori cambiano.
- Base URL:
https://api.deepseekapipricing.com/v1 - Modello:
uncensored - Chiave: inviata come
Authorization: Bearer <key>, che il client fa per te
Un chiarimento sulla denominazione. Questo endpoint è un servizio indipendente che esegue un modello a pesi aperti ottimizzato per rispondere senza rifiuti di contenuto per l'uso adulto legale. Non è l'API ufficiale di DeepSeek e non è un router tra fornitori, quindi il nome del modello è sempre uncensored, non un ID modello di un fornitore. Se hai bisogno di una chiave, la pagina chiave API mostra i passaggi di registrazione e la prova da $0,50 con un solo clic.
Installa e fai la prima chiamata in Python
Installa i pacchetti:
pip install -U langchain-openai langchain-core
# then use base_url https://api.deepseekapipricing.com/v1 and model "uncensored"
Poi crea l'oggetto modello. Passa la chiave esplicitamente invece di affidarti alla variabile d'ambiente OPENAI_API_KEY, che potrebbe contenere una vera chiave OpenAI che non vuoi inviare a un host diverso.
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 questo stampa un saluto, la connessione, la chiave e il nome del modello sono tutti corretti. L'errore più comune in questa fase è dimenticare /v1 nel base URL, che di solito produce un errore not-found.
Prompt, catene e streaming
Da qui, LangChain funziona come al solito. Un prompt template, il modello e un output parser si compongono in una catena con l'operatore 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"}))
Lo streaming avviene tramite eventi inviati dal server. In LangChain chiami stream, e ogni chunk trasporta un pezzo di testo. Imposta stream_usage=True sul modello se vuoi i conteggi dei token alla fine dello stream; l'API invia i dati di utilizzo nell'evento finale.
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)
Una richiesta in streaming mantiene il suo slot di concurrency fino al termine dello stream, quindi se abbandoni uno stream senza chiuderlo, quello slot rimarrà occupato più a lungo del previsto.
Node e TypeScript
Il pacchetto JavaScript accetta il base URL all'interno di un oggetto 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);
}
Eseguilo come modulo ES ("type": "module" in package.json, o un file .mjs). Tutto il resto nell'API Node, inclusi i prompt template e i runnables, si comporta come con qualsiasi altro modello di chat.
Chiamata di funzioni e agenti
L'API supporta il formato degli strumenti OpenAI: i parametri tools e tool_choice, tool_calls in streaming, e i risultati degli strumenti restituiti come messaggi con role: "tool". In LangChain dichiari gli strumenti con un decorator e li attacchi con 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)
Scrivere il loop a mano una volta vale i dieci minuti. Ti mostra esattamente cosa ha restituito il modello, quali argomenti ha scelto per ogni chiamata e dove una descrizione errata dello strumento porta a un'ipotesi sbagliata. Una volta che è chiaro, passa a un agente precostruito e mantieni la versione scritta a mano come riferimento per il debug.
Questo è il ciclo completo eseguito manualmente: il modello richiede uno strumento, la esegui, restituisci il risultato e il modello scrive la risposta finale. Se preferisci un ciclo agente pronto all’uso, il pacchetto langgraph offre create_react_agent(llm, [order_status]), e lo invochi con {"messages": [("user", "Where is order 1042?")]}.
La capacità di un modello di scegliere gli strumenti dipende dal modello, quindi testa con i tuoi schemi di strumenti reali. Descrizioni di strumenti brevi e specifiche e una temperatura bassa aiutano. Un agente che effettua sei chiamate con una cronologia in crescita di circa 27.000 token di input in totale e 1.800 token di output costa circa $0,00405 più $0,0009, ovvero circa mezzo centesimo.
Output strutturato con modalità JSON
La modalità JSON è supportata tramite response_format. Associala al modello e dì anche nel prompt che vuoi JSON con chiavi specifiche, poiché il flag del formato controlla la sintassi, non il tuo schema:
# 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"])
Convalida il risultato analizzato con Pydantic o i tuoi controlli prima di fidarti, e gestisci json.JSONDecodeError con un nuovo tentativo. Per lavori di estrazione di grandi dimensioni, analizza ogni risposta in modo difensivo invece di assumere che la prima sia pulita.
Retrieval, memoria e callback
Questa API non ha un endpoint per gli embedding, quindi una pipeline di recupero necessita di una fonte separata di embedding. Tutto ciò che segue il recupero è una chat semplice. Una catena di recupero tipica estrae i passaggi migliori dal tuo vector store, li incolla nel prompt e chiede al modello di rispondere basandosi su quel testo. Poiché la finestra di contesto è di 100.000 token, puoi permetterti passaggi generosi, ma ricorda il costo: ogni token di contesto recuperato è input a $0,15 per milione, quindi 20.000 token di contesto costano $0,003 per domanda.
Per la memoria di chat, l'approccio più semplice è un elenco di messaggi che riduci per conteggio dei token prima di ogni chiamata. LangChain offre helper come trim_messages per questo. Mantieni il messaggio di sistema e gli ultimi turni, e scarta o riassumi il mezzo una volta che la cronologia raggiunge un limite che scegli. Una cronologia più piccola mantiene anche le risposte focalizzate e abbassa il costo di ogni turno, perché l'intera cronologia viene rispedita come input ogni volta.
Le callback sono il posto dove registrare quanto è costata una chiamata. Ogni risposta include un blocco di utilizzo con token di prompt e completamento, e in LangChain il messaggio restituito lo trasporta in 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}")
Registra il costo con l'ID della richiesta così una sorpresa in fattura può essere tracciata a una catena.
Prompt di sistema e tono
Il modello non ha rifiuti di contenuto integrati, quindi il messaggio di sistema è dove imposti il comportamento del tuo prodotto: la persona, il tono, gli argomenti che dovrebbe evitare e il formato della risposta. Scrivilo come faresti per una breve descrizione di un nuovo collega. Breve e specifico funziona meglio di lungo e vago. Il contenuto che coinvolge minorenni è un limite rigido su questo servizio, quindi non costruire prompt che vi si avvicinano.
Una breve checklist prima di spedire
- La chiave vive in una variabile d'ambiente o in un archivio di segreti, mai nel repository.
max_concurrencyè impostato al limite della tua chiave, o al di sotto se altri servizi condividono la chiave.- I tentativi usano un back-off breve, e le risposte 429 con
Retry-After: 5vengono rispettate. - Gli stream sono chiusi alla disconnessione del client così gli slot sono liberati.
- Gli output JSON sono analizzati in modo difensivo e convalidati.
- I costi sono registrati per catena dal blocco di utilizzo.
- Esiste un fallback per il caso in cui l'endpoint è irraggiungibile, anche se il fallback è un messaggio di errore.
Segui quell'elenco e l'integrazione si comporterà come qualsiasi altro modello di chat LangChain. La differenza è sul lato contenuto, dove le richieste che altri modelli rifiutano per uso adulto legale ricevono risposta.
Limiti di richiesta, concurrency ed errori comuni
Una chiave completa permette 8 richieste concorrenti e 300 richieste al minuto. Una chiave di prova permette 2 richieste concorrenti e 60 al minuto. Il corpo della richiesta può arrivare fino a 8 MB, e la finestra di contesto è di 100.000 token che coprono prompt e completamento insieme.
Gli helper batch di LangChain distribuiscono le richieste, quindi imposta un limite che corrisponda alla tua chiave:
# 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})
Usa 2 invece di 8 su una chiave di prova. Quando superi un limite, l'API restituisce HTTP 429 con il codice errore rate_limited (troppe richieste al minuto) o concurrency (troppe simultaneamente). In caso di sovraccarico temporaneo restituisce anche 429, con un'intestazione Retry-After: 5. L'impostazione max_retries nel client gestisce i casi transitori, ma se vedi il codice errore concurrency ripetutamente, riduci max_concurrency invece di aggiungere tentativi.
- Errori not-found su ogni chiamata: controlla che il base URL finisca con
/v1. - Errore di autenticazione: la chiave manca o ha un errore di battitura; conferma che sia passata tramite
api_key. - Errori del modello: il nome del modello deve essere esattamente
uncensored. - Esecuzioni batch lente: gli stream bloccati tengono gli slot di concurrency, quindi chiudili o imposta un timeout.
I prezzi sono $0,15 per milione di token di input e $0,50 per milione di token di output, e le richieste fallite o rifiutate non vengono addebitate. La pagina prezzi elenca le ricariche, e la documentazione copre ogni parametro e le intestazioni di risposta, inclusi X-Request-Id e X-Balance-USD, utili per il logging in un callback LangChain.
