このガイドでは、サードパーティライブラリ (例: OpenAI) を Weave TypeScript SDK に統合する方法を説明します。Weave は自動インストルメンテーションをサポートしているため、セットアップが簡単になり、手動設定の必要性も減ります。
何が変わりましたか？
PR #4554 以降、OpenAI などのサポート対象ライブラリは、Weave の読み込み時に自動的にパッチされるようになりました。以前のように手動でラップする必要はありません。weave.wrapOpenAI(new OpenAI());
TypeScript プロジェクトで Weave インテグレーションを使用する
package.json と tsconfig.json を明示的に用意することを推奨します。
プロジェクトで CommonJS と ESM のどちらを使用しているかを判断するには、package.json の type フィールドを確認します。
type が "module" の場合、プロジェクトでは ESM が使用されます。type フィールドが存在しないか、"commonjs" に設定されている場合、プロジェクトではデフォルトで CommonJS が使用されます。
CommonJS プロジェクトでは、自動インストルメンテーションは追加の設定なしで動作します。
プロジェクトを CommonJS 用に設定するには、次の手順に従います。
-
package.json を作成または更新します。
-
CommonJS と互換性のある設定で
tsconfig.json を作成します。
{
"compilerOptions": {
"module": "CommonJS",
"target": "es2022",
"rootDir": ".",
"outDir": "dist"
}
}
-
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 を参照してください。
-
Weave と、必要なその他のライブラリをインストールします。
-
TypeScript ファイルをコンパイルします。
たとえば
test.ts というファイルの場合は、次を実行します。
これにより、ファイルは dist/test.js にコンパイルされます。
-
コンパイルしたファイルを Node.js で実行します。
CommonJS は Node.js の require モジュールローダーを使用するため、Weave は ESM プロジェクトで使用される --import フラグなしで、サポートされるライブラリを自動的にインストルメントできます。
ESM TypeScript プロジェクトで Weave を使用するには、プロジェクトを Node.js ESM 用に設定し、コードをコンパイルしたうえで、--import フラグ付きで Node.js を起動します。これにより、他のモジュールが読み込まれる前に Weave がインストルメンテーションを登録できます。
プロジェクトを ESM 向けに設定するには、次の手順に従います。
-
package.json を作成または更新します。
-
Node.js 互換の ESM 設定を含む
tsconfig.json を作成します。
{
"compilerOptions": {
"module": "nodenext",
"moduleResolution": "nodenext",
"target": "es2022",
"rootDir": ".",
"outDir": "dist"
}
}
-
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 を参照してください。
-
Weave と必要なライブラリをインストールします。
-
TypeScript ファイルをコンパイルします。
たとえば
test.ts というファイルの場合は、次のように実行します。
これにより、ファイルは dist/test.js にコンパイルされます。
-
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 プロセスに影響し、意図しない副作用を招く可能性があります。
NODE_OPTIONS 環境変数を設定してください：
export NODE_OPTIONS="--import=weave/instrument"
-
バンドラーの設定で、LLM ライブラリを外部として指定します。これによりそれらはバンドルされなくなるため、Weave が実行時に正しくパッチを適用できるようになります。
次の例は、
next.config.js の設定で openai パッケージを外部として指定する方法を示しています。これにより、openai はバンドルされません。モジュールは実行時に読み込まれるため、Weave が自動的にパッチを適用してトラッキングできます。Next.js のようなフレームワークを使用している場合は、自動インストルメンテーションを有効にするためにこの設定を使用してください。
externals: {
'openai': 'commonjs openai'
}
-
それでもパッチの適用に失敗する場合は、手動インストルメンテーション に切り替えてください。
手動パッチ適用は従来の方法です。自動パッチ適用が機能しない場合にのみ使用してください。
import { wrapOpenAI } from 'weave';
const client = wrapOpenAI(new OpenAI());
