GenAI アプリのトレース (IDE)

2025-06-11

このクイックスタートは、開発環境としてローカル IDE を使用する場合に、GenAI アプリを MLflow Tracing と統合するのに役立ちます。 Databricks Notebook を使用する場合は、代わりに Databricks Notebook クイックスタートを使用してください。

達成する内容

このチュートリアルの最後には、次の内容が含まれます。

GenAI アプリの MLflow 実験
MLflow に接続されているローカル開発環境
MLflow トレースを使用してインストルメント化されたシンプルな GenAI アプリケーション
MLflow 実験におけるそのアプリからの痕跡

[前提条件]

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

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

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

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

手順 2: 新しい MLflow 実験を作成する

MLflow 実験は、GenAI アプリケーションのコンテナーです。実験の詳細と、データモデルセクションに含まれる内容について説明します。

Databricks ワークスペースを開く
左側のサイドバーの [Machine Learning] の下にある [実験] に移動します
[実験] ページの上部にある [新しい GenAI 実験] をクリックします。

実験の作成

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

注

このクイックスタートでは、Databricks 個人用アクセストークンの使用について説明します。 MLflow は、 Databricks でサポートされている他の認証方法でも機能します。

環境変数を使用する

[API キーの生成] をクリックする

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

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

.env ファイルを使用する

[API キーの生成] をクリックする

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

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

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

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

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

# Load environment variables from .env file
load_dotenv()

手順 4: アプリケーションを作成してインストルメント化する

ヒント

Databricks は、人気のあるフロンティアとオープンソースの基本 LLM へのすぐに使用できるアクセスを提供しました。このクイックスタートを実行するには、次の操作を行います。

Databricks でホストされる LLM を使用する
LLM プロバイダーから独自の API キーを直接使用する
LLM プロバイダーの API キーへの管理アクセスを有効にする外部モデルを作成する

次のクイックスタート例では、OpenAI SDK を使用して Databricks でホストされている LLM に接続します。独自の OpenAI キーを使用する場合は、 client = OpenAI(...) 行を更新します。

MLflow でサポートされている他の 20 以上の LLM SDK (Anthropic、Bedrock など) または GenAI オーサリングフレームワーク (LangGraph など) のいずれかを使用する場合は、前の手順の MLflow 実験 UI の指示に従います。

プロジェクトディレクトリに app.py という名前の Python ファイルを作成します。

ここでは、@mlflow.traceと組み合わせて Python アプリケーションを簡単にトレースできるデコレーターを使用して、OpenAI SDK への呼び出しの詳細をキャプチャします。

次のコードスニペットでは、Anthropic の Claude Sonnet LLM を使用しています。サポートされている基本モデルの一覧から別の LLM を選択できます。

import mlflow
from openai import OpenAI

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

# Connect to a Databricks LLM via OpenAI using the same credentials as MLflow
# Alternatively, you can use your own OpenAI credentials here
mlflow_creds = mlflow.utils.databricks_utils.get_databricks_host_creds()
client = OpenAI(
    api_key=mlflow_creds.token,
    base_url=f"{mlflow_creds.host}/serving-endpoints"
)

# 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="databricks-claude-sonnet-4",  # 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)

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

手順 5: MLflow でトレースを表示する

MLflow 実験 UI に戻る
生成されたトレースが [ トレース ] タブに表示されます
トレースをクリックして詳細を表示します

トレースの詳細

トレースの理解

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

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

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

質問された内容
どのような応答が生成されましたか？
要求にかかった時間
使用されたトークンの数 (コストに影響)

ヒント

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

次のステップ

これらの推奨されるアクションとチュートリアルを使用して、体験を続けます。

アプリの品質を評価する - MLflow の評価機能を使用して GenAI アプリの品質を測定して改善する
人間のフィードバックを収集する - ユーザーとドメインの専門家からフィードバックを収集する方法について説明します
ユーザーとセッションを追跡する - トレースにユーザーと会話のコンテキストを追加する

リファレンスガイド

このガイドで説明されている概念と機能の詳細なドキュメントを確認します。

トレースの概念 - MLflow トレースの基礎を理解する
トレースデータモデル - トレース、スパン、および MLflow 構造体による可観測データの構造について説明します
手動トレース API - カスタムインストルメンテーションの高度なトレース手法を調べる