API LLM personalizzata LangChain: puntala a qualsiasi Base URL
Per usare un'API LLM personalizzata LangChain non devi scrivere una classe personalizzata: il wrapper chat compatibile con OpenAI accetta un base URL, una chiave e un nome del modello. Ecco la configurazione esatta, più streaming, strumenti, output JSON e gestione dei limiti.
Punti chiave
- ChatOpenAI accetta base_url, api_key e model, quindi non serve la sottoclasse.
- Usa il modello uncensored e il base URL https://api.llmapistatus.com/v1.
- Chiamate di funzioni, streaming e modalità JSON passano tutti attraverso l'endpoint.
- Limita le catene parallele a 8 per restare sotto il limite di concorrenza; gli embedding non sono offerti.

La risposta breve: ChatOpenAI con un diverso base URL
LangChain parla con server in stile OpenAI tramite il pacchetto langchain-openai. La sua classe ChatOpenAI ti permette di sovrascrivere dove vanno le richieste, che è esattamente ciò di cui ha bisogno un endpoint personalizzato. Installa il pacchetto, poi passa tre valori: il base URL https://api.llmapistatus.com/v1, la tua chiave e l'ID del modello uncensored.
Installa con 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 questo stampa una risposta, il collegamento è corretto. Ottieni una chiave dalla pagina chiave API; la guida quickstart mostra lo stesso switch per gli utenti SDK semplici. L'endpoint serve POST /v1/chat/completions e GET /v1/models, e questi due metodi sono tutto ciò di cui ha bisogno il wrapper OpenAI per la chat.
Una nota sul termine "LLM personalizzato". LangChain documenta anche un modo per scrivere il tuo modello di chat personalizzato ereditando da una classe base, il che ha senso per le API che non supportano il formato OpenAI. Questo endpoint lo supporta, quindi l'ereditarietà aggiungerebbe solo codice da mantenere. Usalo solo se hai bisogno di un comportamento che il wrapper non può esprimere.
Costruire una catena con prompt e parsing dell'output
Con l'oggetto modello pronto, tutto il resto in LangChain funziona come con qualsiasi modello di chat. Ecco una piccola catena scritta nello stile del linguaggio di espressione: un modello di prompt, il modello e un analizzatore di stringhe.
# 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.",
}))
Nulla in questa catena sa o gli importa che il modello si trovi dietro un dominio diverso. Questo è il vantaggio dell'API compatibile: prompt, classi di memoria, retriever e agent scritti per l'interfaccia di chat standard continuano a funzionare. Quello che dovresti verificare dal tuo lato è il prompt stesso. Un modello ottimizzato per rispondere senza rifiuti di contenuti segue le istruzioni alla lettera, quindi prompt di sistema vaghi producono comportamenti vaghi. Specifica il ruolo, il formato e la lunghezza.
Un limite vale la pena di conoscerlo prima di progettare una pipeline di retrieval. Questo servizio è solo per testo. Non ci sono embedding, quindi OpenAIEmbeddings puntato a questo URL base fallirà. Usa un modello di embedding locale o un altro provider per il vector store, e usa questo endpoint solo per la generazione.
Token di streaming in arrivo
L'endpoint supporta gli eventi server-sent quando invii stream: true, e LangChain lo trasforma in un iteratore. Non imposti il flag tu stesso; chiamare .stream() lo fa.
# 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()
Per server asincroni usa astream. La stessa chiamata esiste nella libreria 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);
}
Ricorda che una richiesta in streaming mantiene il suo slot di concorrenza fino all'arrivo dell'ultimo evento. Se un utente chiude la scheda del browser e il tuo server continua a leggere lo streaming, quello slot rimane occupato. Annulla la richiesta upstream quando il client si disconnette. I numeri di utilizzo arrivano alla fine dello streaming, che è dove leggi i conteggi finali dei token per i log di fatturazione.
Chiamata di funzioni e agenti
La chiamata di funzioni è disponibile: l'endpoint accetta tools e tool_choice, restituisce in streaming tool_calls, e prende i tuoi risultati come messaggi con role: "tool". In LangChain attacchi gli strumenti con bind_tools e lasci che il framework costruisca i messaggi.
# 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)
Eseguire la chiamata e restituire il risultato è la seconda metà del 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)
I modelli a pesi aperti variano in quanto bene scelgono gli strumenti e riempiono gli argomenti. Mantieni le descrizioni degli strumenti brevi e concrete, usa pochi strumenti per chiamata e valida gli argomenti nella tua funzione invece di fidarti di loro. Se un agent fa un loop, abbassa la temperatura e imposta un numero massimo di passaggi nel tuo agent executor.
Output strutturato e JSON
La modalità JSON è supportata tramite response_format: {"type": "json_object"}. In LangChain la strada più semplice è with_structured_output usando il metodo modalità JSON, che convalida anche il risultato contro uno schema.
# 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)
La modalità JSON garantisce che l'output sia un oggetto JSON, non che abbia i campi che volevi. Due abitudini aiutano. Primo, nomina le chiavi nel prompt, come sopra; l'istruzione per produrre JSON dovrebbe essere esplicita. Secondo, avvolgi la chiamata in un retry che rielabora l'output in caso di errore. Il controllo pydantic cattura campi mancanti e tipi errati, e un singolo retry con il messaggio di errore allegato di solito lo risolve.
Puoi anche impostare response_format direttamente quando costruisci il modello con model_kwargs={"response_format": {"type": "json_object"}}, che è utile per catene semplici che terminano in un parser JSON.
Limiti di richieste, retry e catene parallele
Lavori batch e agent fanno molte chiamate contemporaneamente, ed è qui che un endpoint personalizzato differisce da un modello locale. Una chiave completa permette 8 richieste parallele e 300 richieste al minuto. Una chiave di prova permette 2 parallele e 60 al minuto. Superato un limite, l'API risponde con HTTP 429 e il codice di errore rate_limited o concurrency; in caso di sovraccarico temporaneo risponde 429 con Retry-After: 5.
Due impostazioni LangChain gestiscono la maggior parte. Il modello accetta max_retries, che riprova i fallimenti transitori con backoff, e i runnables accettano un valore max_concurrency nella loro configurazione per il lavoro batch:
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})
Impostare il cap a 6 su una chiave completa lascia spazio per altre due richieste, come una chiamata visibile all'utente dalla stessa app. Su una chiave di prova usa 1 o 2. Non fare affidamento solo sui retry per un problema di concorrenza: se il cap è sopra il limite, i retry ricreano semplicemente la stessa collisione. Leggere X-RateLimit-Limit-Requests e X-RateLimit-Limit-Concurrency dalle intestazioni di risposta ti dice cosa è permesso alla tua chiave.
Gli input lunghi vanno bene fino alla finestra da 100.000 token, condivisa tra prompt e completion, e il corpo della richiesta è limitato a 8 MB. I text splitters di LangChain impostati su poche migliaia di token per chunk ti tengono lontano da entrambi.
Risoluzione dei problemi di un endpoint personalizzato
La maggior parte dei problemi con un base URL personalizzato rientra in un elenco breve e ciascuno ha un test rapido.
- Errori di autenticazione. LangChain legge anche la variabile d'ambiente
OPENAI_API_KEY. Se passiapi_keyesplicitamente, quel valore vince, ma una variabile obsoleta può ancora confondere un secondo oggetto modello che hai dimenticato di configurare. Passa la chiave ogni volta e dai alla variabile un altro nome comeLLM_API_KEY. - Errori non trovato. Il base URL deve terminare con
/v1. LangChain aggiunge/chat/completionsda solo, quindi aggiungerlo al base URL produce un percorso duplicato. - Modello sconosciuto. Chiedi
GET /v1/modelscon la stessa chiave e copia l'ID che stampa. Dovrebbe essereuncensored. - Blocchi silenziosi in catene lunghe. Imposta
timeoutsul modello e registra l'intestazione di rispostaX-Request-Id. Se contatti il supporto, quell'ID permette loro di trovare la richiesta esatta. - Output sorprendente. Stampa il prompt finale prima che venga inviato. La maggior parte delle risposte strane in LangChain provengono da un template che ha riempito una variabile con qualcosa di inaspettato, non dal modello.
In caso di dubbio, riproduci la chiamata fallita con curl semplice contro lo stesso URL. Se curl funziona e LangChain no, la colpa è nella tua catena; se entrambi falliscono, controlla la chiave e il saldo.
Verifica dei costi mentre costruisci
Le catene nascondono i conteggi dei token, quindi misura presto. Ogni risposta include l'utilizzo e le intestazioni di risposta includono X-Balance-USD. Il prezzo è $0,15 per 1M token di input e $0,50 per 1M token di output, fatturati dal credito prepagato.
Un esempio pratico: una catena di retrieval che invia 6.000 token di contesto e domanda e riceve 400 token indietro costa 6.000 x $0,15 / 1M = $0,0009 per l'input più 400 x $0,50 / 1M = $0,0002 per l'output, quindi $0,0011 per chiamata. Eseguire 5.000 di queste chiamate in una scansione di test costa $5,50. È utile saperlo prima di lasciare un loop di agent in esecuzione tutta la notte.
Le richieste fallite o rifiutate non vengono addebitate. La pagina prezzi elenca gli importi per ricaricare da $20 a $500 con bonus, e i nuovi account possono richiedere un credito di prova gratuito di $0,50 con un solo clic, sufficiente per alcune centinaia di piccole chiamate di test mentre configuri l'integrazione.
Altre guide
Domande e risposte
Devo creare una sottoclasse della classe base del modello chat di LangChain?
No. L'endpoint è compatibile con OpenAI, quindi ChatOpenAI con un base_url personalizzato, api_key e model funziona. La sottoclasse è necessaria solo per le API che utilizzano un formato diverso.
Posso usare OpenAIEmbeddings con questo endpoint?
No. Il servizio è solo testuale e non ha embedding. Usa un modello di embedding locale o un altro provider per i vettori e usa questo endpoint per la generazione.
Quale nome del modello devo passare?
Passa uncensored come modello. GET /v1/models restituisce lo stesso ID.
Perché ottengo errori 429 in un lavoro batch?
Hai superato il limite di richieste al minuto o di richieste parallele. Riduci max_concurrency a meno di 8 su una chiave completa, o a 2 su una chiave di prova, e mantieni abilitati i tentativi di ripetizione.
Lo streaming di LangChain funziona qui?
Sì. Chiamare stream o astream utilizza gli eventi inviati dal server e l'utilizzo viene inviato alla fine dello streaming.
La tua chiave è a un modulo di distanza
Crea un account, copia la chiave, modifica il base URL. È tutta la configurazione.