Une migration majeure ne se résume pas à mettre à jour un numéro de paquet. LangChain répartit ses fonctions entre langchain, langchain-core, intégrations fournisseurs, langchain-community et, pour plusieurs API historiques, langchain-classic. L’objectif est de préserver le comportement utilisateur tout en modernisant une tranche à la fois.
Établir une référence
Verrouillez les versions actuelles et capturez des scénarios représentatifs : réponses, outils appelés, documents récupérés, événements de streaming, tokens, latence et erreurs. Inventoriez imports profonds, classes dépréciées, callbacks et dépendances qui imposent leur propre plage de versions.
Lire les guides dans l’ordre
Consultez le guide officiel de la version cible et ceux des intégrations utilisées. Dans LangChain 1.x, le namespace principal est recentré sur agents, messages, outils, modèles et embeddings ; plusieurs chaînes et retrievers historiques passent par langchain-classic. Décidez consciemment quels éléments migrer maintenant et lesquels isoler temporairement.
Migrer verticalement
Choisissez un parcours complet, mettez à jour ses imports et types, puis exécutez ses tests avant de continuer. Ne changez pas simultanément modèle, prompt, embedding et base vectorielle. Pour un agent, contrôlez état, conditions d’arrêt et outils ; pour un RAG, comparez les passages récupérés avant la réponse finale.
Déployer sans pari unique
Épinglez toutes les dépendances, activez la nouvelle version sur une fraction du trafic et comparez erreurs, qualité, coût et latence. Préparez un retour à la version précédente et conservez les formats persistés compatibles. Les avertissements de dépréciation doivent devenir des tâches datées, pas être masqués.
FAQ
langchain-classic est-il une mauvaise pratique ?
Non, c’est un pont de compatibilité. Documentez toutefois pourquoi chaque usage reste nécessaire.
Un codemod suffit-il ?
Il aide pour les imports, mais ne valide pas comportement, streaming, état ni outils.
Quand la migration est-elle terminée ?
Quand les scénarios de référence passent, la télémétrie est stable et le rollback n’est plus nécessaire.
Procédure de migration reproductible
Créez une branche dédiée et capturez l’état de départ :
~~~bash python -m pip freeze > requirements.before.txt pytest -q python -W error::DeprecationWarning -m pytest -q ~~~
Mettez à jour les paquets LangChain ensemble dans un environnement propre, puis recherchez les imports obsolètes :
~~~bash python -m pip install -U langchain langchain-core langchain-community python -m pip check rg "from langchain\.(chat_models|embeddings|vectorstores)" . ~~~
Ajoutez un test contractuel sur chaque parcours critique : même type de sortie, mêmes sources, même politique d’erreur et budget de latence acceptable. Les tests de snapshots textuels sont fragiles ; validez plutôt le schéma, les citations et les invariants métier. Déployez progressivement et conservez un verrou de dépendances permettant le rollback. Une migration réussie ne signifie pas seulement « les imports passent », mais « le comportement observé reste maîtrisé ».