LangChain 1.x réduit le namespace principal autour des briques essentielles des agents, messages, outils, modèles et embeddings. Plusieurs chaînes et retrievers historiques ont été déplacés vers langchain-classic. Une migration sûre commence donc par un inventaire des dépendances, pas par un remplacement global d’imports.
Cartographier l’existant
Relevez versions de langchain, langchain-core, langchain-community et intégrations fournisseurs. Cherchez chaînes anciennes, agents, retrievers, mémoire, callbacks et imports profonds. Pour chaque parcours, conservez des entrées et sorties de référence, ainsi que coût, nombre d’appels et sources récupérées.
Comprendre la séparation des packages
Dans 1.x, le package langchain se concentre notamment sur create_agent, AgentState, messages, outils et initialisation des modèles. Les chaînes historiques comme LLMChain, plusieurs retrievers et l’ancienne API d’indexation se trouvent dans langchain-classic. Ce package facilite une transition, mais ne doit pas devenir une excuse pour reporter indéfiniment la modernisation.
Migrer par tranche verticale
Choisissez un parcours utilisateur, mettez à jour ses imports, adaptez les types de messages et vérifiez ses callbacks ou événements. Pour un agent, comparez l’ancien comportement avec create_agent et son état. Exécutez les tests avant de passer au parcours suivant. Évitez une mise à jour simultanée du modèle, du prompt et du retriever : vous ne pourriez plus attribuer les régressions.
Tests indispensables
Vérifiez sorties structurées, appels et arguments d’outils, streaming, annulation, historique, erreurs et usage des tokens. Pour le RAG, mesurez les passages récupérés plutôt que seulement la réponse finale. Épinglez toutes les versions compatibles et déployez progressivement avec possibilité de retour.
Checklist
- Dépendances et imports inventoriés.
- Documentation 1.x officielle suivie.
- Usage de langchain-classic explicitement temporaire ou assumé.
- Tests de comportement avant et après.
- Modèle et prompts inchangés pendant la migration.
- Télémétrie et procédure de rollback prêtes.
FAQ
Peut-on tout migrer mécaniquement ?
Les imports, parfois ; le comportement des agents, messages et callbacks demande une validation.
Faut-il supprimer immédiatement langchain-classic ?
Non. Utilisez-le comme étape contrôlée, avec une décision documentée pour chaque composant.
Pourquoi migrer si 0.2 fonctionne ?
Pour suivre l’écosystème maintenu, les correctifs et nouvelles abstractions, à condition que le bénéfice justifie le risque.
Exemple de remplacement progressif
Avant, de nombreux projets importaient les intégrations depuis le paquet principal. En 1.x, utilisez les paquets fournisseurs et une chaîne explicite :
~~~python from langchain_core.prompts import ChatPromptTemplate from langchain_openai import ChatOpenAI
prompt = ChatPromptTemplate.from_template("Résume : {text}") chain = prompt | ChatOpenAI(model="gpt-4.1-mini") result = chain.invoke({"text": "Contenu à résumer"}) print(result.content) ~~~
Inventoriez d’abord les imports et composants réellement utilisés :
~~~bash rg "from langchain|import langchain" src tests python -m pip check pytest -q ~~~
Migrez un chemin fonctionnel à la fois. Remplacez les agents historiques par les API 1.x adaptées, et utilisez LangGraph pour les workflows à états. Vérifiez les changements de types de messages, d’invocation synchrone/asynchrone et de callbacks. Épinglez les versions de langchain-core et des paquets d’intégration compatibles : les mettre à jour séparément est une source fréquente d’erreurs.