MLflow Tracing で Node.js アプリケーションをインストルメントする

MLflowの TypeScript SDK 、 TypeScript および JavaScript アプリケーションにMLflow Tracing機能をもたらします。最小限のコード変更で本番運用に対応した可観測性を GenAI アプリケーションに追加し、 Databricksの強力なアナリティクスおよびモニタリングプラットフォームを活用します。

要件

ヒント

Databricks では、トレースを使用して Node.js アプリケーションを開発する場合、最新バージョンの MLflow Tracing TypeScript SDK をインストールすることをお勧めします。

MLflow Tracing を使用して Node.js アプリケーションをインストルメントするには、以下をインストールします。

mlflow-tracing npmレジストリから
Node.js 14以上
MLflowエクスペリメントにアクセスできるDatabricksワークスペース

OpenAI による自動トレースには、次のものも必要です。

mlflow-openai npmレジストリから

SDKをセットアップする

パッケージをインストールする

npm レジストリからパッケージをインストールします。

Bash
npm install mlflow-tracing

MLflowエクスペリメントを作成する

Databricks ワークスペースを開きます。
左側のサイドバーの AI / ML の下にある [エクスペリメント] をクリックします。
エクスペリメントページの上部にある GenAIアプリとエージェント をクリックします。
クリックエクスペリメント名の横にあるアイコンをクリックしてエクスペリメント ID を見つけ、メモします。

エクスペリメントを作成

認証を構成する

次のいずれかの認証方法を選択します。

Environment Variables
.env File

MLflowエクスペリメントで、アイコン > トレースをローカルに記録 > APIキーの生成を クリックします。
生成されたコードをコピーしてターミナルで実行します。

Bash
export DATABRICKS_TOKEN=<databricks-personal-access-token>
export DATABRICKS_HOST=https://<workspace-name>.cloud.databricks.com

MLflowエクスペリメントで、アイコン > トレースをローカルに記録 > APIキーの生成を クリックします。
生成されたコードをプロジェクトルートの.envファイルにコピーします。

Bash
DATABRICKS_TOKEN=<databricks-personal-access-token>
DATABRICKS_HOST=https://<workspace-name>.cloud.databricks.com

SDKを初期化する

Node.jsアプリケーションで、エクスペリメント ID を使用してSDKを初期化します。

TypeScript
import * as mlflow from 'mlflow-tracing';

mlflow.init({
  trackingUri: 'databricks',
  experimentId: '<your-experiment-id>',
});

自動トレース

サポートされているライブラリを自動的にトレースするには、コードを 1 行追加します。MLflow Tracing TypeScript SDK は現在、OpenAI SDK の自動トレースをサポートしています。

OpenAI の自動トレースを使用するには、 mlflow-openaiパッケージをインストールします。

Bash
npm install mlflow-openai

次に、OpenAI クライアントをtracedOpenAI関数でラップします。

TypeScript
import * as mlflow from 'mlflow-tracing';

// Initialize the tracing SDK
mlflow.init({
  trackingUri: 'databricks',
  experimentId: '<your-experiment-id>',
});

import { OpenAI } from 'openai';
import { tracedOpenAI } from 'mlflow-openai';

// Wrap the OpenAI client with the tracedOpenAI function
const client = tracedOpenAI(new OpenAI());

// Invoke the client as usual
const response = await client.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [
    { role: 'system', content: 'You are a helpful weather assistant.' },
    { role: 'user', content: "What's the weather like in Seattle?" },
  ],
});

手動トレース

`trace` API を使用して関数をトレースする

trace API は、関数をトレースする場合に便利です。

Named function
Anonymous function

TypeScript
import * as mlflow from 'mlflow-tracing';

const getWeather = async (city: string) => {
  return `The weather in ${city} is sunny`;
};

// Wrap the function with mlflow.trace to create a traced function
const tracedGetWeather = mlflow.trace(getWeather, { name: 'get-weather' });

// Invoke the traced function as usual
const result = await tracedGetWeather('San Francisco');

TypeScript
import * as mlflow from 'mlflow-tracing';

const getWeather = mlflow.trace(
  (city: string) => {
    return `The weather in ${city} is sunny`;
  },
  // When wrapping an anonymous function, specify the span name
  { name: 'get-weather' },
);

// Invoke the traced function as usual
const result = getWeather('San Francisco');

トレースされた関数の呼び出し時に、MLflow は次のものをキャプチャするスパンを自動的に作成します。

入力引数
戻り値
例外情報（スローされた場合）
レイテンシー

ネストされた関数呼び出しのキャプチャ

ネストされた関数をトレースする場合、MLflow は複数のスパンを含むトレースを生成し、スパン構造によってネストされた関数の呼び出しがキャプチャされます。

TypeScript
const sum = mlflow.trace(
  (a: number, b: number) => {
    return a + b;
  },
  { name: 'sum' },
);

const multiply = mlflow.trace(
  (a: number, b: number) => {
    return a * b;
  },
  { name: 'multiply' },
);

const computeArea = mlflow.trace(
  (a: number, b: number, h: number) => {
    const sumOfBase = sum(a, b);
    const area = multiply(sumOfBase, h);
    return multiply(area, 0.5);
  },
  { name: 'compute-area' },
);

computeArea(1, 2, 3);

トレースは次のようになります。

- compute-area
  - sum (a=1, b=2)
  - multiply (a=3, b=3)
  - multiply (a=9, b=0.5)

`@trace` API を使用してクラスメソッドをトレースする

TypeScript バージョン 5.0 以降ではデコレータがサポートされています。MLflow Tracing は、クラスメソッドを簡単にトレースするためにこの構文をサポートしています。MLflow は以下をキャプチャするスパンを自動的に作成します。

入力引数
戻り値
例外情報（スローされた場合）
レイテンシー

TypeScript
import * as mlflow from 'mlflow-tracing';

class MyClass {
  @mlflow.trace({ spanType: mlflow.SpanType.LLM })
  generateText(prompt: string) {
    return "It's sunny in Seattle!";
  }
}

const myClass = new MyClass();
myClass.generateText("What's the weather like in Seattle?");

`withSpan` API を使用してコードブロックをトレースする

withSpan API は、関数ではなくコードブロックをトレースする場合に便利です。

TypeScript
import * as mlflow from 'mlflow-tracing';

const question = "What's the weather like in Seattle?";

const result = await mlflow.withSpan(
  async (span: mlflow.Span) => {
    return "It's sunny in Seattle!";
  },
  // Pass name, span type, and inputs as options.
  {
    name: 'generateText',
    spanType: mlflow.SpanType.TOOL,
    inputs: { prompt: question },
  },
);

明示的にスパンを作成して終了する

スパンのライフサイクルをより細かく制御するには、スパンを明示的に作成および終了することができます。

TypeScript
import * as mlflow from 'mlflow-tracing';

const span = mlflow.startSpan({
  name: 'generateText',
  spanType: mlflow.SpanType.LLM,
  inputs: { prompt: question },
});

span.end({
  outputs: { answer: "It's sunny in Seattle!" },
  status: 'OK',
});

ユーザーとセッションによるトレースのグループ化

多くの実際のアプリケーションでは、複数ターンのユーザーインタラクションを維持するためにセッションを使用します。一方、トレースはリクエストごとに生成されることがよくあります。MLflow は、ユーザーセッションごとにトレースをグループ化することをサポートしており、エンドユーザーの行動を理解して問題を特定するのに役立ちます。詳細については、「ユーザーとセッションの追跡」ガイドを参照してください。

フルスタックのサンプルアプリケーション

Node.js アプリケーションで MLflow Tracing TypeScript SDK を使用する方法の完全な例については、フルスタックの例を確認してください。

次のステップ

次のページを参照してください。

アプリをデバッグして観察する- Trace UI を使用してアプリケーションの動作とパフォーマンスを分析します
アプリの品質を評価する- トレースを活用して、アプリケーションの品質を体系的に評価し、改善します
本番運用モニタリング- 本番運用での品質メトリクスの追跡

要件​

SDKをセットアップする​

パッケージをインストールする​

MLflowエクスペリメントを作成する​

認証を構成する​

SDKを初期化する​

自動トレース​

手動トレース​

trace API を使用して関数をトレースする​

ネストされた関数呼び出しのキャプチャ​

@trace API を使用してクラスメソッドをトレースする​

withSpan API を使用してコードブロックをトレースする​

明示的にスパンを作成して終了する​

ユーザーとセッションによるトレースのグループ化​

フルスタックのサンプルアプリケーション​

次のステップ​

要件