Passer au contenu principal
Ce guide explique comment intégrer des bibliothèques tierces (par exemple OpenAI) au SDK TypeScript de Weave. Il s’adresse aux développeurs TypeScript qui souhaitent que Weave trace automatiquement les appels aux bibliothèques prises en charge dans leur application. Weave prend en charge l’instrumentation automatique, ce qui simplifie la configuration et réduit le besoin de configuration manuelle.
Qu’est-ce qui a changé ? Depuis la PR #4554, Weave effectue automatiquement le patching des bibliothèques prises en charge, comme OpenAI, lors de son chargement. Vous n’avez donc plus besoin de les encapsuler manuellement :
weave.wrapOpenAI(new OpenAI());
Weave s’en charge automatiquement dans la plupart des cas. Cependant, des cas limites peuvent survenir.

​
Utilisez les intégrations Weave avec votre projet TypeScript

Les sections suivantes expliquent comment déterminer le système de modules utilisé par votre projet, puis configurer ce projet afin que Weave puisse instrumenter automatiquement les bibliothèques tierces prises en charge. Les projets TypeScript peuvent utiliser le système de modules CommonJS ou ESM, et la configuration requise diffère légèrement selon le système utilisé.

​
Si vous ne savez pas quel type de projet vous avez

Si vous exécutez directement un fichier TypeScript avec un outil tel que : 
npx tsx test.ts
le système de modules peut être déterminé implicitement par votre environnement. Pour garantir un comportement cohérent, définissez explicitement les fichiers package.json et tsconfig.json. Pour déterminer si un projet utilise CommonJS ou ESM, vérifiez le champ type dans package.json : 
"type": "module"
  • Si type vaut "module", le projet utilise ESM.
  • Si le champ type est absent ou défini sur "commonjs", le projet utilise CommonJS par défaut.

​
Configurer un projet CommonJS

Pour les projets CommonJS, l’instrumentation automatique fonctionne sans configuration supplémentaire. Pour configurer votre projet en CommonJS :
  1. Créez ou mettez à jour votre package.json : 
    {
  "type": "commonjs"
}
  2. Créez un tsconfig.json avec des paramètres compatibles avec CommonJS : 
    {
  "compilerOptions": {
    "module": "CommonJS",
    "target": "es2022",
    "rootDir": ".",
    "outDir": "dist"
  }
}
    Ces paramètres configurent TypeScript pour compiler en CommonJS :
    • module: "CommonJS". Compile les modules au format CommonJS (require ou module.exports). Pour plus de détails sur cette option du compilateur, voir TypeScript - Module.
    • target: "es2022" (recommandé). Génère du JavaScript moderne compatible avec les versions récentes de Node.js. Pour plus de détails sur cette option du compilateur, voir TypeScript - Target.
    • rootDir: ".". Considère le répertoire contenant tsconfig.json comme la racine de vos fichiers d’entrée. TypeScript l’utilise avec outDir pour reproduire la structure de votre dossier source dans le résultat généré. Pour plus de détails sur cette option du compilateur, voir TypeScript - Root Dir.
    • outDir: "dist". Écrit le JavaScript généré et les autres sorties du compilateur dans le dossier dist. Pour plus de détails sur cette option du compilateur, voir TypeScript - Out Dir.
  3. Installez Weave et toutes les autres bibliothèques requises : 
    npm install weave
  4. Compilez votre fichier TypeScript. Pour un fichier d’exemple test.ts : 
    npx tsc
    Cela compile le fichier en dist/test.js.
  5. Exécutez le fichier compilé avec Node.js : 
    node dist/test.js
Votre projet CommonJS est maintenant configuré pour que Weave instrumente automatiquement les bibliothèques prises en charge lors de l’exécution de votre code. Comme CommonJS utilise le chargeur de modules require de Node.js, Weave peut instrumenter automatiquement les bibliothèques prises en charge sans nécessiter l’option --import utilisée dans les projets ESM.

​
Configurer un projet ESM

Pour utiliser Weave avec un projet TypeScript ESM, configurez votre projet pour le mode ESM de Node.js, compilez votre code, puis démarrez Node.js avec l’option --import afin que Weave puisse enregistrer son instrumentation avant le chargement des autres modules. Pour configurer votre projet pour ESM :
  1. Créez ou mettez à jour votre package.json : 
    {
  "type": "module"
}
  2. Créez un tsconfig.json avec des paramètres ESM compatibles avec Node.js : 
    {
  "compilerOptions": {
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "target": "es2022",
    "rootDir": ".",
    "outDir": "dist"
  }
}
    Ces paramètres configurent TypeScript pour compiler vers un ESM Node.js moderne :
    • module: "nodenext" — Compile les modules selon la sémantique ESM de Node.js. Pour plus de détails sur cette option du compilateur, voir TypeScript - Module.
    • moduleResolution: "nodenext" — Garantit que la résolution des modules suit les règles ESM de Node.js. Pour plus de détails sur cette option du compilateur, voir TypeScript - Module Resolution.
    • target: "es2022" (Recommandé) — Génère un code JavaScript moderne compatible avec les versions récentes de Node.js. Pour plus de détails sur cette option du compilateur, voir TypeScript - Target.
    • rootDir: "." — Traite le répertoire qui contient tsconfig.json comme la racine de vos fichiers d’entrée. TypeScript l’utilise avec outDir pour reproduire la structure de votre dossier source dans le dossier de sortie. Pour plus de détails sur cette option du compilateur, voir TypeScript - Root Dir.
    • outDir: "dist" — Écrit le code JavaScript généré (et les autres sorties du compilateur) dans le dossier dist. Pour plus de détails sur cette option du compilateur, voir TypeScript - Out Dir.
  3. Installez Weave et toute autre bibliothèque requise : 
    npm install weave
  4. Compilez votre fichier TypeScript. Pour un fichier d’exemple test.ts : 
    npx tsc
    Cette commande compile le fichier en dist/test.js.
  5. Exécutez le fichier compilé avec Node.js et préchargez l’instrumentation Weave : 
    node --import=weave/instrument dist/test.js
L’option --import garantit que le module weave/instrument est chargé avant les autres modules afin que Weave puisse automatiquement instrumenter les bibliothèques et intégrations prises en charge. Weave doit être installé localement dans le projet que vous exécutez. Votre projet ESM est maintenant configuré pour que Weave précharge son instrumentation avant les autres modules et trace automatiquement les appels aux bibliothèques prises en charge.

​
Utilisation avancée et dépannage

Les sections suivantes couvrent les cas limites et les solutions de contournement lorsque le patching automatique du SDK TypeScript ne fonctionne pas comme prévu. Par exemple, des environnements ESM uniquement, des configurations de bundler comme Next.js ou des environnements d’exécution contraints peuvent entraîner des problèmes. Si vous constatez des traces manquantes ou des problèmes d’intégration, commencez ici.

​
Utiliser NODE_OPTIONS (uniquement pour ESM)

Utilisez NODE_OPTIONS avec prudence, car cela s’applique à tous les processus Node.js de l’environnement et peut entraîner des effets de bord.
Si vous utilisez un projet ESM et que vous ne pouvez pas passer d’options CLI (par exemple, en raison de contraintes liées aux outils CLI ou aux frameworks), définissez la variable d’environnement NODE_OPTIONS : 
export NODE_OPTIONS="--import=weave/instrument"

​
Compatibilité des bundlers

Certains frameworks et bundlers, comme Next.js, peuvent intégrer des bibliothèques tierces au bundle d’une manière qui empêche Node.js d’effectuer leur patching à l’exécution. Si cela correspond à votre configuration, essayez les étapes suivantes :
  1. Marquez les bibliothèques LLM comme externes dans la configuration de votre bundler. Cela évite que le bundler les intègre au bundle, afin que Weave puisse effectuer correctement leur patching à l’exécution. L’exemple suivant montre comment marquer le package openai comme externe dans une configuration next.config.js, ce qui évite que le bundler l’intègre au bundle. Le module se charge à l’exécution, ce qui permet à Weave d’effectuer automatiquement son patching et de le suivre. Utilisez cette configuration lorsque vous travaillez avec des frameworks comme Next.js pour activer l’instrumentation automatique. 
    externals: {
'openai': 'commonjs openai'
}
  2. Si le patching échoue toujours, utilisez l’instrumentation manuelle.

​
Patching manuel (option de repli)

Le patching manuel est l’approche historique. Utilisez-le uniquement lorsque le patching automatique ne fonctionne pas.
Parfois, vous devrez peut-être encore utiliser l’instrumentation manuelle : 
import {  } from 'weave';
const  = (new OpenAI());