TypeScript SDK: サードパーティインテグレーションガイド

サードパーティライブラリを Weave TypeScript SDK に統合する

このガイドでは、サードパーティライブラリ (例: OpenAI) を Weave TypeScript SDK に統合する方法を説明します。Weave は自動インストルメンテーションをサポートしているため、セットアップが簡単になり、手動設定の必要性も減ります。

何が変わりましたか？ PR #4554 以降、OpenAI などのサポート対象ライブラリは、Weave の読み込み時に自動的にパッチされるようになりました。以前のように手動でラップする必要はありません。

weave.wrapOpenAI(new OpenAI());

通常、これは Weave が自動的に処理します。ただし、エッジケース が発生する場合があります。

​

TypeScript プロジェクトで Weave インテグレーションを使用する

TypeScript プロジェクトでは、CommonJS または ESM のいずれかのモジュールシステムを使用できます。

​

どのタイプのプロジェクトかわからない場合

次のようなツールでTypeScriptファイルを直接実行している場合:

npx tsx test.ts

モジュールシステムは、環境に応じて暗黙的に決まる場合があります。動作を一貫させるため、package.json と tsconfig.json を明示的に用意することを推奨します。

プロジェクトで CommonJS と ESM のどちらを使用しているかを判断するには、package.json の type フィールドを確認します。

"type": "module"

• type が "module" の場合、プロジェクトでは ESM が使用されます。
• type フィールドが存在しないか、"commonjs" に設定されている場合、プロジェクトではデフォルトで CommonJS が使用されます。

​

CommonJS プロジェクトを設定する

CommonJS プロジェクトでは、自動インストルメンテーションは追加の設定なしで動作します。

プロジェクトを CommonJS 用に設定するには、次の手順に従います。

1. package.json を作成または更新します。

   {
     "type": "commonjs"
   }
   

2. CommonJS と互換性のある設定で tsconfig.json を作成します。

   {
     "compilerOptions": {
       "module": "CommonJS",
       "target": "es2022",
       "rootDir": ".",
       "outDir": "dist"
     }
   }
   

   これらの設定により、TypeScript は CommonJS 向けにコンパイルされます。

   • module: "CommonJS" — モジュールを CommonJS 形式 (require/module.exports) にコンパイルします。 このコンパイラオプションの詳細については、TypeScript - Module を参照してください。

   • target: "es2022" (推奨) — 最近の Node.js バージョンと互換性のあるモダンな JavaScript を出力します。 このコンパイラオプションの詳細については、TypeScript - Target を参照してください。

   • rootDir: "." — tsconfig.json を含むディレクトリを入力ファイルのルートとして扱います。TypeScript はこれを outDir と組み合わせて使用し、出力先でソースフォルダーの Layout を反映します。 このコンパイラオプションの詳細については、TypeScript - Root Dir を参照してください。

   • outDir: "dist" — 生成された JavaScript (およびその他のコンパイラ出力) を dist フォルダーに書き込みます。 このコンパイラオプションの詳細については、TypeScript - Out Dir を参照してください。

3. Weave と、必要なその他のライブラリをインストールします。

   npm install weave
   

4. TypeScript ファイルをコンパイルします。

   たとえば test.ts というファイルの場合は、次を実行します。

   npx tsc
   

   これにより、ファイルは dist/test.js にコンパイルされます。

5. コンパイルしたファイルを Node.js で実行します。

   node dist/test.js
   

CommonJS は Node.js の require モジュールローダーを使用するため、Weave は ESM プロジェクトで使用される --import フラグなしで、サポートされるライブラリを自動的にインストルメントできます。

​

ESM プロジェクトを設定する

ESM TypeScript プロジェクトで Weave を使用するには、プロジェクトを Node.js ESM 用に設定し、コードをコンパイルしたうえで、--import フラグ付きで Node.js を起動します。これにより、他のモジュールが読み込まれる前に Weave がインストルメンテーションを登録できます。

プロジェクトを ESM 向けに設定するには、次の手順に従います。

1. package.json を作成または更新します。

   {
     "type": "module"
   }
   

2. Node.js 互換の ESM 設定を含む tsconfig.json を作成します。

   {
     "compilerOptions": {
       "module": "nodenext",
       "moduleResolution": "nodenext",
       "target": "es2022",
       "rootDir": ".",
       "outDir": "dist"
     }
   }
   

   これらの設定により、TypeScript はモダンな Node.js ESM 向けにコンパイルされます。

   • module: "nodenext" — Node.js ESM のセマンティクスを使用してモジュールをコンパイルします。 このコンパイラオプションの詳細は、TypeScript - Module を参照してください。

   • moduleResolution: "nodenext" — モジュール解決が Node.js ESM のルールに従うようにします。 このコンパイラオプションの詳細は、TypeScript - Module Resolution を参照してください。

   • target: "es2022" (推奨) — 新しい Node.js バージョンと互換性のあるモダンな JavaScript を出力します。 このコンパイラオプションの詳細は、TypeScript - Target を参照してください。

   • rootDir: "." — tsconfig.json を含むディレクトリを入力ファイルのルートとして扱います。TypeScript はこれを outDir と組み合わせて使用し、出力先でもソースフォルダの Layout を反映します。 このコンパイラオプションの詳細は、TypeScript - Root Dir を参照してください。

   • outDir: "dist" — 出力された JavaScript (およびその他のコンパイラ出力) を dist フォルダに書き込みます。 このコンパイラオプションの詳細は、TypeScript - Out Dir を参照してください。

3. Weave と必要なライブラリをインストールします。

   npm install weave
   

4. TypeScript ファイルをコンパイルします。

   たとえば test.ts というファイルの場合は、次のように実行します。

   npx tsc
   

   これにより、ファイルは dist/test.js にコンパイルされます。

5. Node.js でコンパイル済みファイルを実行し、Weave のインストルメンテーションを事前に読み込みます。

   node --import=weave/instrument dist/test.js
   

--import フラグにより、weave/instrument モジュールが他のモジュールより先に読み込まれるため、Weave はサポートされるライブラリやインテグレーションに自動でインストルメンテーションを適用できます。

Weave は、実行するプロジェクトにローカルインストールされている必要があります。

​

高度な使い方とトラブルシューティング

このセクションでは、TypeScript SDK の自動パッチ適用が期待どおりに動作しない場合のエッジケースと回避策を説明します。たとえば、ESM 専用の環境、Next.js のようなバンドラー構成、または制約のあるランタイム環境では、想定外の問題が発生することがあります。トレースが欠落している場合やインテグレーションに問題がある場合は、まずこのセクションを確認してください。

​

NODE_OPTIONS を使用する (ESM の場合のみ)

NODE_OPTIONS の使用には注意してください。環境内のすべての Node.js プロセスに影響し、意図しない副作用を招く可能性があります。

ESM のプロジェクトを使用していて、CLI フラグを渡せない場合 (たとえば、CLI ツールやフレームワークの制約がある場合) は、NODE_OPTIONS 環境変数を設定してください：

export NODE_OPTIONS="--import=weave/instrument"

​

バンドラーの互換性

Next.js などの一部のフレームワークやバンドラーでは、Node.js が実行時にパッチを適用できない形でサードパーティライブラリがバンドルされることがあります。

これが現在の設定に当てはまる場合は、次の手順を試してください。

1. バンドラーの設定で、LLM ライブラリを外部として指定します。これによりそれらはバンドルされなくなるため、Weave が実行時に正しくパッチを適用できるようになります。

   次の例は、next.config.js の設定で openai パッケージを外部として指定する方法を示しています。これにより、openai はバンドルされません。モジュールは実行時に読み込まれるため、Weave が自動的にパッチを適用してトラッキングできます。Next.js のようなフレームワークを使用している場合は、自動インストルメンテーションを有効にするためにこの設定を使用してください。

   externals: {
   'openai': 'commonjs openai'
   }
   

2. それでもパッチの適用に失敗する場合は、手動インストルメンテーション に切り替えてください。

​

手動パッチ適用 (フォールバックオプション)

手動パッチ適用は従来の方法です。自動パッチ適用が機能しない場合にのみ使用してください。

場合によっては、引き続き手動インストルメンテーションが必要になることがあります：

import { wrapOpenAI } from 'weave';
const client = wrapOpenAI(new OpenAI());