はじめよう: 生成AI 向けMLflow Tracing (ローカル IDE)

このクイックスタートは、IDE (VS Code、PyCharm、Cursor など) やローカルでホストされているノートブック環境 (Jupyter など) などのローカル開発環境を使用する場合に、生成AI アプリをMLflow Tracingと統合するのに役立ちます。Databricksノートブックを使用している場合は、代わりにDatabricksノートブッククイックスタートを使用してください。

達成できること

このチュートリアルを終了すると、次のことができるようになります。

生成AI アプリのMLflowエクスペリメント
MLflow に接続されたローカル開発環境
MLflow Tracing でインストルメント化されたシンプルな生成AI アプリケーション
MLflowエクスペリメント内のそのアプリからのトレース

trace

前提条件

Databricks Workspace : Databricksワークスペースへのアクセス。

手順 1: MLflow をインストールする

ローカル IDE で作業する場合は、Databricks 接続を使用して MLflow をインストールする必要があります。

Bash
pip install --upgrade "mlflow[databricks]>=3.1" openai

ステップ 2: 新しいMLflowエクスペリメントを作成する

MLflowエクスペリメントは、生成AI アプリケーションのコンテナです。エクスペリメントの詳細については、概念セクションをご覧ください。

Databricks ワークスペースを開く
左側のサイドバーの AI / ML の下にある [エクスペリメント] をクリックします。
エクスペリメントページの上部で、 GenAI アプリとエージェント をクリックします。
情報アイコンをクリックしてエクスペリメント ID とパスを取得します。左上にあります。これらは後で使用します。

エクスペリメントを作成

手順 3: 環境を MLflow に接続する

以下のコードスニペットは、 Databricksパーソナルアクセストークンを使用して認証を設定する方法を示しています。 MLflow は、Databricks がサポートする他の認証方法でも動作します。

Use environment variables
Use a .env file

MLflowエクスペリメントで、Kebab メニューアイコンをクリックします。 > トレースをローカルに記録 > APIキーの生成 をクリックします。

生成されたコードをコピーしてターミナルで実行します。

Bash
export DATABRICKS_TOKEN=<databricks-personal-access-token>
export DATABRICKS_HOST=https://<workspace-name>.cloud.databricks.com
export MLFLOW_TRACKING_URI=databricks
export MLFLOW_REGISTRY_URI=databricks-uc
export MLFLOW_EXPERIMENT_ID=<experiment-id>

MLflowエクスペリメントで、Kebab メニューアイコンをクリックします。 > トレースをローカルに記録 > APIキーの生成 をクリックします。

生成されたコードをプロジェクトルートの .env ファイルにコピーします

Bash
DATABRICKS_TOKEN=<databricks-personal-access-token>
DATABRICKS_HOST=https://<workspace-name>.cloud.databricks.com
MLFLOW_TRACKING_URI=databricks
MLFLOW_REGISTRY_URI=databricks-uc
MLFLOW_EXPERIMENT_ID=<experiment-id>

python-dotenv パッケージをインストールする
Bash
```
pip install python-dotenv
```

コードに環境変数を読み込む

Python
# At the beginning of your Python script
from dotenv import load_dotenv

# Load environment variables from .env file
load_dotenv()

ステップ 4: アプリケーションを作成して計測可能にする

トレースを有効にして生成AI アプリを作成します。

プロジェクトディレクトリに app.py という名前のPythonファイルを作成します。
OpenAI クライアントを初期化して、Databricks でホストされている LLM または OpenAI でホストされている LLM に接続します。

Databricks-hosted LLMs
OpenAI-hosted LLMs

MLflow を使用して、Databricks でホストされている LLM に接続する OpenAI クライアントを取得します。利用可能な基盤モデルからモデルを選択します。

Python
import mlflow
from databricks.sdk import WorkspaceClient

# Enable MLflow's autologging to instrument your application with Tracing
mlflow.openai.autolog()

# Set up MLflow tracking to Databricks
mlflow.set_tracking_uri("databricks")
mlflow.set_experiment("/Shared/docs-demo")

# Create an OpenAI client that is connected to Databricks-hosted LLMs
w = WorkspaceClient()
client = w.serving_endpoints.get_open_ai_client()

# Select an LLM
model_name = "databricks-claude-sonnet-4"

ネイティブの OpenAI SDK を使用して、OpenAI でホストされるモデルに接続します。利用可能なOpenAIモデルからモデルを選択します。

Python
import mlflow
import os
import openai

# Ensure your OPENAI_API_KEY is set in your environment
# os.environ["OPENAI_API_KEY"] = "<YOUR_API_KEY>" # Uncomment and set if not globally configured

# Enable auto-tracing for OpenAI
mlflow.openai.autolog()

# Set up MLflow tracking to Databricks
mlflow.set_tracking_uri("databricks")
mlflow.set_experiment("/Shared/docs-demo")

# Create an OpenAI client connected to OpenAI SDKs
client = openai.OpenAI()

# Select an LLM
model_name = "gpt-4o-mini"

アプリケーションを定義して実行します。

@mlflow.traceデコレータを使用すると、任意の Python 関数を簡単にトレースでき、 OpenAI 自動インストルメンテーションと組み合わせて、OpenAI SDK への呼び出しの詳細をキャプチャできます。

Python
# Use the trace decorator to capture the application's entry point
@mlflow.trace
def my_app(input: str):
    # This call is automatically instrumented by `mlflow.openai.autolog()`
    response = client.chat.completions.create(
        model=model_name,  # This example uses a Databricks hosted LLM - you can replace this with any AI Gateway or Model Serving endpoint. If you provide your own OpenAI credentials, replace with a valid OpenAI model e.g., gpt-4o, etc.
        messages=[
            {
                "role": "system",
                "content": "You are a helpful assistant.",
            },
            {
                "role": "user",
                "content": input,
            },
        ],
    )
    return response.choices[0].message.content

result = my_app(input="What is MLflow?")
print(result)

アプリケーションを実行する
Bash
```
python app.py
```

アプリにトレースを追加する方法の詳細については、トレースインストルメンテーションガイドと20 を超えるライブラリ統合を参照してください。

ステップ 5: MLflowでトレースを表示する

MLflowエクスペリメント UI に戻ります。
生成されたトレースが 「トレース」 タブに表示されます。
トレースをクリックすると詳細が表示されます。

トレースの詳細

トレースを理解する

作成したトレースには、次の情報が表示されます。

ルートスパン : my_app(...)関数への入力を表します
- 子スパン : OpenAI完了リクエストを表す
属性 : モデル名、トークン数、タイミング情報などのメタデータが含まれます
入力 : モデルに送信されたメッセージ
出力 : モデルから受信した応答

この単純なトレースは、次のようなアプリケーションの動作に関する貴重な知見をすでに提供しています。

質問されたこと
どのようなレスポンスが生成されたか
リクエストにかかった時間
使用されたトークンの数 (コストに影響)

RAGシステムやマルチステップエージェントのようなより複雑なアプリケーションの場合、 MLflow Tracing は各コンポーネントとステップの内部動作を明らかにすることで、さらに多くの価値を提供します。

ガイドと参考資料

このガイドの概念と機能の詳細については、以下を参照してください。

MLflow Tracingガイド- MLflow Tracingについてさらに詳しく知りたい場合は、ここから始めてください。
MLflow Tracing統合- 自動トレース統合を備えた 20 以上のライブラリ
トレースの概念 - MLflow Tracingの基本を理解する

達成できること​

前提 条件​

手順 1: MLflow をインストールする​

ステップ 2: 新しいMLflowエクスペリメントを作成する​

手順 3: 環境を MLflow に接続する​

ステップ 4: アプリケーションを作成して計測可能にする​

ステップ 5: MLflowでトレースを表示する​

トレースを理解する​

ガイドと参考資料​