LangChain n'est pas un service de modèles : il relie prompts, modèles, outils et parseurs de sortie dans une application. Dès lors que le service cible expose une interface compatible OpenAI, ChatOpenAI du paquet langchain-openai peut s'y connecter en pointant la Base URL vers votre propre adresse. Ce qui bloque en pratique n'est souvent pas le framework, mais trois champs : jusqu'où remplir l'adresse, d'où lire la clé, et si le nom du modèle correspond à ce qui est disponible sur la passerelle.

Cet article suit l'ordre installation, exemple minimal, variables d'environnement, chaînes, streaming, agents, dépannage et migration. LangChain évolue vite : les noms de classes et les paramètres dépendent de la documentation de la version installée.

Remarque : LangChain est une marque de LangChain, Inc. et OpenAI une marque de son détenteur ; cet article est indépendant des éditeurs concernés. Les noms de modèles et les prix figurent sur la page Tarifs des modèles ; les détails d'interface sont dans la documentation officielle.

1. Installation : deux paquets principaux

Créez un environnement virtuel puis installez :

python -m venv .venv
source .venv/bin/activate
pip install -U langchain langchain-openai

langchain-openai est le paquet d'intégration pour OpenAI et les interfaces compatibles ; langchain fournit les chaînes, agents et autres couches supérieures ; langchain-core est installé comme dépendance. En production, fixez les versions dans requirements.txt pour éviter des API différentes selon les machines. L'ancien import langchain.chat_models.ChatOpenAI a migré : le nouveau chemin est langchain_openai.

2. Exemple minimal : ChatOpenAI vers une adresse personnalisée

Trois paramètres suffisent : model, base_url et api_key. base_url s'arrête généralement à /v1, sans /chat/completions, que le client ajoute lui-même.

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="votre-modele",
    base_url="https://votre-passerelle/v1",
    api_key="sk-votre-cle",
    temperature=0.3,
    timeout=60,
)

resp = llm.invoke("Explique en une phrase ce qu'est une interface compatible OpenAI.")
print(resp.content)

Faites d'abord fonctionner cet exemple, puis ajoutez prompts et outils. Validez dans cet ordre :

  1. Appelez base_url + /chat/completions avec curl pour confirmer adresse et clé.
  2. Créez ChatOpenAI en Python et appelez invoke une seule fois.
  3. Affichez resp.content et resp.response_metadata pour vérifier le modèle et les champs d'usage.
  4. Ajoutez ensuite modèles de prompt, parseurs de sortie et outils.

Si une 404 apparaît ici, vérifiez la structure de l'adresse ; une 401, la clé et l'en-tête d'authentification ; un modèle inexistant, interrogez /v1/models et comparez le nom. Le nom doit correspondre exactement à celui renvoyé par la passerelle : casse, suffixe de date et alias comptent.

3. Paramètres et variables d'environnement

Ne codez pas la clé en dur. Le SDK OpenAI lit OPENAI_API_KEY, et peut aussi lire OPENAI_BASE_URL ; certains anciens codes et documents utilisent OPENAI_API_BASE. Le comportement varie selon les versions : le plus sûr est de passer explicitement les paramètres, les variables ne servant que de valeurs par défaut.

Paramètre Rôle Usage courant
model Identifiant du modèle Identique à la réponse de /v1/models
base_url Racine de l'API https://hote/v1
api_key Clé d'authentification Passée explicitement ou lue dans OPENAI_API_KEY
temperature Aléa d'échantillonnage Selon la plage prise en charge par le modèle
timeout Délai d'une requête Ajusté à la longueur de la tâche
max_retries Nombre de relances client Environ 2 en général

En développement local, un fichier .env avec python-dotenv convient, mais .env doit figurer dans .gitignore. En équipe, séparez les clés par projet et par environnement, avec des quotas distincts entre test et production, afin de pouvoir désactiver un jeu de clés en cas de problème.

4. Chaînes : relier prompt et modèle avec LCEL

Le LangChain Expression Language (LCEL) compose les composants avec un opérateur de pipeline. La chaîne de base est « prompt → modèle → parseur de sortie » :

from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

prompt = ChatPromptTemplate.from_messages([
    ("system", "Tu es un assistant technique. Reponds de facon concrete, conclusion d'abord."),
    ("user", "{question}"),
])

chain = prompt | llm | StrOutputParser()
print(chain.invoke({"question": "Jusqu'a quel niveau faut-il remplir la Base URL ?"}))

invoke prend une entrée et renvoie un résultat, batch traite une liste par lots, stream renvoie par fragments. Le parseur de sortie convertit le message du modèle en chaîne ou en objet structuré ; pour du JSON, privilégiez la sortie structurée du modèle, puis ajoutez parsing et validation, sans vous fier uniquement au prompt.

5. Streaming et appels par lots

Le streaming convient aux interfaces de chat et aux réponses longues :

for chunk in chain.stream({"question": "Explique ce qu'est un appel d'outil"}):
    print(chunk, end="", flush=True)

Si invoke fonctionne mais que stream n'affiche rien progressivement, un proxy tamponne probablement le flux ou l'amont ne prend pas en charge le streaming. Vérifiez que la passerelle renvoie text/event-stream et que le reverse proxy désactive le buffering. Pour les appels par lots, surveillez la concurrence : batch peut envoyer en parallèle ; en cas de 429, réduisez la concurrence ou traitez par lots et conservez les éléments en échec pour une relance.

6. Agents : modèle, outils et boucle

Un agent est essentiellement une boucle : le modèle décide d'appeler un outil, l'exécution lance l'outil et renvoie le résultat, puis le modèle décide de l'étape suivante jusqu'à la réponse finale. LangChain 1.x propose des interfaces de haut niveau comme create_agent ; les versions 0.3 et antérieures utilisaient souvent AgentExecutor. Les écritures diffèrent : copier un ancien tutoriel mène facilement à une erreur d'import.

Les outils se définissent avec un décorateur ; le nom de fonction, les types de paramètres et la docstring influencent le choix du modèle :

from langchain_core.tools import tool

@tool
def get_order_status(order_id: str) -> str:
    """Consulte le statut logistique a partir du numero de commande."""
    return "Expediee, livraison prevue sous trois jours"

Avec une passerelle personnalisée, l'appel d'outils exige que l'amont prenne complètement en charge tools, tool_choice et le format de retour des résultats. Certains services compatibles n'implémentent que le dialogue de base et ignorent les paramètres ou renvoient une erreur. Validez avec un seul outil et une question simple avant d'augmenter le nombre d'outils et les appels parallèles.

7. Erreurs courantes et diagnostic

Symptôme Cause possible Traitement
401 Unauthorized Clé invalide, absente ou avec des espaces Passer api_key explicitement, vérifier les variables
404 model_not_found Nom de modèle différent ou chemin en trop Interroger /v1/models, limiter base_url à /v1
429 Too Many Requests Concurrence élevée ou quota épuisé Réduire la concurrence, lotir, relancer avec backoff
400 context_length_exceeded Entrée au-delà de la fenêtre de contexte Tronquer l'historique, découper les documents, résumer
OutputParserException Sortie du modèle non conforme Contraindre le format, valider, réessayer une fois
APIConnectionError / délai Réseau, proxy, certificat ou panne amont Vérifier proxy, DNS et délais
Aucune réaction à l'appel d'outil L'amont ne gère pas le protocole tools Changer de modèle ou revenir à une chaîne simple

Pour diagnostiquer, contournez d'abord LangChain et appelez la même adresse avec curl ou le SDK OpenAI. Si l'appel direct réussit mais LangChain échoue, le problème vient souvent des noms de paramètres, des variables ou de la version ; si les deux échouent, il vient de la passerelle, de la clé ou du réseau.

8. Migrer depuis les anciennes écritures

  • Import : langchain.chat_models.ChatOpenAI devient langchain_openai.ChatOpenAI.
  • Paramètres : model_name devient model, openai_api_base devient base_url.
  • L'ancienne classe OpenAI de complétion cède la place aux modèles de chat ; les nouveaux projets utilisent directement ChatOpenAI.
  • Les anciennes chaînes et anciens agents sont partiellement déplacés dans des paquets de compatibilité en 1.x ; lisez les notes de migration et ne mélangez pas plusieurs versions majeures.
  • Dépendances : verrouillez les versions avant mise à jour et testez le chemin critique en environnement de test, en particulier streaming, outils et sortie structurée.

FAQ

Faut-il inclure /v1 dans base_url ?

La plupart des services compatibles OpenAI attendent /v1, le client ajoutant ensuite /chat/completions. Certaines passerelles placent le préfixe de version ailleurs : suivez leur documentation. Le critère est simple : base_url + /chat/completions doit répondre à un appel curl.

Peut-on utiliser la variable OPENAI_BASE_URL ?

Oui, le SDK OpenAI la lit ; certains anciens documents parlent de OPENAI_API_BASE. Le support varie selon les versions : en production, passez base_url explicitement pour éviter qu'une différence d'environnement envoie la requête à la mauvaise adresse.

Pourquoi invoke fonctionne-t-il mais stream n'affiche rien ?

Cause fréquente : buffering du proxy, amont sans streaming, ou code qui traite le flux comme une chaîne complète. Vérifiez d'abord que la réponse est bien un flux d'événements, puis la configuration du reverse proxy et la méthode de lecture.

LangChain peut-il utiliser Claude, DeepSeek ou d'autres modèles non OpenAI ?

Oui. Si le service expose une interface compatible OpenAI, ChatOpenAI suffit en changeant l'adresse et le nom du modèle ; avec un protocole natif, utilisez le paquet d'intégration correspondant. Les paramètres et les capacités d'outils diffèrent : validez chaque cas.

Que faire en cas d'erreur de paramètres lors d'un appel d'outil par un agent ?

Vérifiez d'abord que la structure d'appel renvoyée respecte le protocole, puis les types et champs obligatoires de la fonction. Certaines passerelles compatibles gèrent imparfaitement les appels parallèles : désactivez le parallélisme, ne donnez qu'un outil à la fois et progressez pas à pas.

Pour aller plus loin

La clé de l'intégration d'une API personnalisée à LangChain est de fixer trois éléments — adresse, clé, nom de modèle — puis de valider avec une requête minimale avant d'ajouter chaînes et outils. Pour une entrée compatible OpenAI unifiée, des clés virtuelles et un journal d'usage, vous pouvez créer un compte sur la passerelle AI de ZSQH ; les modèles et les prix sont sur la page Tarifs des modèles.

Lectures associées :