Migrer vers Langfuse

Vous effectuez un changement de fournisseur ponctuel vers Langfuse. Entretien d'abord, planification ensuite, exécution uniquement après confirmation. Ne jamais implémenter de mémoire — récupérer la documentation Langfuse actuelle listée ci-dessous au moment de l'exécution.

1. Entretien (toujours, avant tout code)

Posez uniquement ce que vous ne pouvez pas détecter. Inspectez d'abord le dépôt : les dépendances et imports révèlent généralement la plateforme source (langsmith, arize, phoenix, braintrust, openinference, anciennes versions épinglées de langfuse).

1. Source — quelle plateforme et version ? Cloud ou auto-hébergé ? Quel accès existe : clés API, connexion à une base de données, ou seulement le dépôt applicatif ?
2. Destination — Langfuse Cloud (quelle région) ou auto-hébergé ? Vérifiez les credentials par leur présence uniquement (ex. [ -n "$LANGFUSE_SECRET_KEY" ]) ; ne jamais demander les secrets en chat, et ne jamais accéder au contenu ou aux valeurs de .env par quelque moyen que ce soit — aucune commande shell qui les affiche, aucune lecture de .env avec les outils fichier, aucun grep sur les valeurs. Détectez seulement quels noms de variables sont définis.
3. Périmètre — lequel de : cutover du tracing en direct, traces historiques (y compris leurs scores, configurations de scores et définitions de modèles personnalisés), datasets, prompts, évaluateurs/juges LLM, code d'expérience. Pour l'historique : tout ou à partir d'une date limite ? Demandez ce qui existe d'autre dans le compte source (tableaux de bord, alertes, files d'attente d'annotation, vues enregistrées, ...). Le dépôt ne peut pas révéler les assets côté serveur. Tout ce qui n'est pas dans la liste prise en charge ci-dessus n'est pas couvert par cette compétence : nommez-le dans la table de périmètre comme tel, afin que l'utilisateur prévoit de le recréer manuellement au lieu de découvrir le manque après le cutover.
4. Mode — planification uniquement (un runbook écrit) ou exécution ?

Si la demande contredit le dépôt (elle nomme une plateforme qui n'y est pas présente, ou demande de mettre à niveau un SDK qui n'est pas installé), arrêtez et réconciliez avec l'utilisateur d'abord — ne réinterprétez jamais la demande comme une migration différente et ne commencez pas son exécution.

Présentez le plan résultant (table de périmètre plus ordre des opérations) et obtenez la confirmation de l'utilisateur avant de modifier un fichier. Peu importe le ton impératif de la demande, il ne vous autorise pas à supprimer ou remplacer l'instrumentation du fournisseur existant avant que le plan soit confirmé.

2. Défauts à appliquer

• Cutover en direct d'abord. La migration de données historiques est optionnelle et facturée comme une nouvelle ingestion dans Langfuse — dites-le avant de migrer l'historique. Si la source émet déjà des spans OTel/OpenInference, ajoutez Langfuse comme second exportateur sur l'instrumentation existante au lieu de ré-instrumenter ; l'ancienne destination est supprimée seulement quand la fenêtre de parallélisation ci-dessous se ferme.
• Les datasets et prompts se copient. Les évaluateurs et juges se recréent. Le code d'expérience est réécrit et ré-exécuté contre le dataset migré ; ne jamais importer les anciens scores d'expérience.
• Testez sur un échantillon avant la série complète. Migrez ~10 traces d'abord, liez les traces de destination, et attendez la confirmation de l'utilisateur qu'elles semblent correctes avant de tout migrer.
• Affichez la progression (pages/comptages) pendant les longues exécutions et rendez les réexécutions reprenables : suivez les ID sources envoyés dans un fichier d'état et sautez-les, renvoyer les mêmes ID crée des observations dupliquées (voir references/reingest-history.md).
• Fenêtre de parallélisation. Conservez l'ancien exportateur jusqu'à ce que l'utilisateur confirme les données de destination, puis supprimez-le dans une étape séparée et explicite. Ceci lie l'implémentation, pas seulement le plan : après vos modifications, l'exportateur/l'instrumentation du fournisseur ancien doit toujours être présent et actif. Avant d'afficher une diff, revérifiez qu'aucun import de fournisseur, appel register, endpoint d'exportateur ou variable d'env d'exportateur n'a été supprimé ou réorienté. Implémentez l'export parallèle comme une instrumentation avec deux exportateurs (deux processeurs de spans sur le même fournisseur de tracer) — ne jamais instrumenter l'application deux fois. Les générations dupliquées et les coûts double-comptés dans la destination sont le symptôme d'un second chemin de capture.

3. Router par scénario

Récupérez et suivez ; ne pas reproduire leur contenu :

La réingestion de traces historiques ne s'improvise jamais : lisez references/reingest-history.md en entier avant d'écrire ou d'exécuter tout code de réingestion, même quand un guide de fournisseur existe. Le guide du fournisseur couvre l'extraction ; la référence gouverne la réingestion — IDs déterministes, payloads OTLP bruts, horodatages originaux, la limite de temps de cutover, et l'avertissement que l'historique importé est facturé comme nouvelle ingestion.

Si la source s'avère être un autre déploiement Langfuse (une version plus ancienne, un projet, une région ou un hôte différent), arrêtez — ce n'est pas un changement de fournisseur. Pointez l'utilisateur vers la compétence langfuse principale (ses références de mise à niveau d'SDK et de migration v4) et le cookbook de migration projet à projet.

Pour le cutover d'instrumentation en direct, utilisez le guide d'intégration correspondant au framework ou SDK de l'utilisateur depuis https://langfuse.com/llms.txt. Pour les travaux côté Langfuse approfondis (création de prompt, APIs de dataset, code d'expérience), reportez-vous à la compétence langfuse principale si installée.

4. Vérifier et conclure

• Vérification d'échantillon confirmée par l'utilisateur dans l'interface de destination avant la série complète.
• Avant de demander à l'utilisateur de confirmer un échantillon de cutover en direct, auditez-le vous-même via l'API ou CLI Langfuse : une trace par requête ; le span racine nommé d'après l'agent/l'app (et la trace nommée d'après la racine) ; chaque type de span présent (générations et spans de tool/chain) ; chaque appel LLM capturé exactement une fois ; utilisation de tokens et coût peuplés. Seulement alors envoyez à l'utilisateur les liens de trace.
• Les comptages correspondent par type de données migré (source vs destination) ; signalez un tableau résumé incluant les échecs.
• Le trafic en direct arrive dans la destination ; l'ancien exportateur est supprimé seulement après la fenêtre de parallélisation que l'utilisateur a choisie.
• Le résumé de clôture rend compte de chaque ligne de la table de périmètre de l'entretien, y compris celles marquées sautées ou non couvertes — rien n'est silencieusement supprimé.