生成AI アプリのトレース (IDE)

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

達成できること

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

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

trace

前提条件

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

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

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

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

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

MLflow エクスペリメントは、生成AI アプリケーションのコンテナです。エクスペリメントとその内容の詳細については、データモデルのセクションを参照してください。

Databricks ワークスペースを開く
左側のサイドバーの [Machine Learning ]の下にある [エクスペリメント ]に移動します
エクスペリメントページの上部にある 新規生成AIエクスペリメント をクリックします

エクスペリメントクリエーション

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

注記

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

Use environment variables
Use a .env file

[Generate API Key ] をクリックします

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

Bash
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>

[Generate API Key ] をクリックします

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

Bash
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 パッケージをインストールする
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: アプリケーションを作成して計測可能にする

ヒント

Databricks は、一般的なフロンティアおよびオープンソースの基礎 LLM へのアクセスをすぐに提供しました。このクイックスタートを実行するには、次の操作を行います。

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

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

がサポートする他の20+LLM SDK (Anthropic 、Bedrock など) または生成AI オーサリングフレームワーク (LangGraph など)MLflowMLflowのいずれかを使用する場合は、前の手順のエクスペリメント UI の指示に従ってください。

プロジェクトディレクトリに 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 デコレータを使用すると、OpenAI 自動インストルメンテーションと組み合わせた任意の Python アプリケーションを簡単にトレースして、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
```

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

MLflow エクスペリメント UI に戻る
生成されたトレースが [トレース ] タブに表示されます
トレースをクリックすると、その詳細が表示されます

トレースの詳細

トレースの理解

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

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

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

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

ヒント

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

次のステップ

これらの推奨アクションとチュートリアルで旅を続けてください。

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

リファレンスガイド

このガイドで説明されている概念と機能の詳細なドキュメントをご覧ください。

トレースの概念 - MLflow Tracingの基本を理解する
トレースデータモデル - トレース、スパン、MLflow が観測可能性データをどのように構造化するかについて学習します
手動トレースAPIs - カスタムインストゥルメンテーションの高度なトレース手法を探る

達成できること​

前提 条件​

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

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

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

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

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

トレースの理解​

次のステップ​

リファレンスガイド​