メインコンテンツまでスキップ

アプリをインストルメント化する

MLflow Tracingを使用してGenAIアプリケーションをインストルメント化し、アプリケーションの実行フローをキャプチャして視覚化する方法を学びます。MLflow には、トレースを実装するための 2 つの主要なアプローチが用意されています。

前提 条件​

このガイドには、次のパッケージが必要です。

  • mlflow[databricks]>=3.1 : GenAI 機能と Databricks 接続を備えたコア MLflow 機能。
  • openai>=1.0.0: 以下の クイックスタート例 を実行する場合にのみ必要です(他のLLMプロバイダーを使用している場合は、代わりにそれぞれのSDKをインストールしてください)

必要なパッケージをインストールします。

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

MLflow バージョンの推奨事項

MLflow 2.15.0+ ではトレース機能を使用できますが、拡張されたトレース機能や堅牢なサポートなど、最新の GenAI 機能を利用するには、 MLflow 3 ( mlflow[databricks]を使用している場合は 3.1 以降) をインストールすることを強くお勧めします 。

ヒント

Databricks ノートブックで実行していますか? MLflow は Databricks ランタイムにプレインストールされています。外部の LLM プロバイダーを使用する場合は、 openai などの追加のパッケージのみをインストールする必要があります。

ローカルで実行していますか? 上記のすべてのパッケージをインストールする必要があります。

環境設定​

以下の例を実行する前に、環境を構成してください。

Databricks 認証を構成する​

注記

このコードを Databricks ノートブック内で 実行している場合は、この認証設定をスキップできます。MLflow では、ノートブックの認証コンテキストが自動的に使用されます。

このコードを Databricks の外部 (ローカル IDE など) で実行している場合は、認証を設定する必要があります。

Python
import os

# Set Databricks authentication (only needed when running outside Databricks)
os.environ["DATABRICKS_HOST"] = "https://your-workspace.databricks.com"  # Your workspace URL
os.environ["DATABRICKS_TOKEN"] = "your-databricks-token"  # Your access token

API キーの設定​

LLM プロバイダー API キーを環境変数として設定します。

Python
import os

# Set your OpenAI API key (if using OpenAI models)
os.environ["OPENAI_API_KEY"] = "your-api-key-here"

# Set other provider keys as needed
# os.environ["ANTHROPIC_API_KEY"] = "your-anthropic-key"
# os.environ["GOOGLE_API_KEY"] = "your-google-key"
ヒント

スクリプトを実行する前に、シェルで次の環境変数を設定することもできます。

Bash
# For Databricks authentication (if running outside Databricks)
export DATABRICKS_HOST="https://your-workspace.databricks.com"
export DATABRICKS_TOKEN="your-databricks-token"

# For LLM providers
export OPENAI_API_KEY="your-api-key-here"

トレーシングアプローチ​

  1. 自動トレース : 1 行のコード mlflow.<library>.autolog() を追加するだけで、アプリのロジックを自動的にキャプチャできます。自動トレースは、20+ のサポートされているライブラリとフレームワーク ですぐに機能します
  2. 手動トレース : カスタムロジックと複雑なワークフロー用に設計された手動トレースでは、 高レベルの APIs (デコレーターと流暢なコンテキストマネージャー) または 低レベルの APIsを使用して、トレースの内容とトレース方法を完全に制御できます。
注記

自動トレースと手動トレースを併用できます。たとえば、OpenAI の SDK の自動トレースと手動トレースを使用して、複数の LLM 呼び出しを、アプリケーションのエンドツーエンド ロジックを表す 1 つのトレースに結合できます。

クイックスタートの例​

自動トレースの例​

お気に入りのライブラリの自動トレースを 1 行のコードで有効にします。

Python
import mlflow
from openai import OpenAI
import os

# Set up environment (if not already configured)
os.environ["OPENAI_API_KEY"] = "your-api-key-here"  # Replace with your actual API key

# Set up MLflow tracking
mlflow.set_tracking_uri("databricks")
mlflow.set_experiment("/Shared/auto-tracing-demo")

# Enable automatic tracing for OpenAI
mlflow.openai.autolog()

# Your existing code works unchanged
client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "What is MLflow?"}],
    max_tokens=100
)

print(response.choices[0].message.content)
# Traces are automatically captured and logged!

手動トレースの例​

@mlflow.traceデコレータを使用して、カスタム関数をインストゥルメントします。

Python
import mlflow
from mlflow.entities import SpanType
from openai import OpenAI
import os

# Set up environment (if not already configured)
os.environ["OPENAI_API_KEY"] = "your-api-key-here"  # Replace with your actual API key

# Set up MLflow tracking
mlflow.set_tracking_uri("databricks")
mlflow.set_experiment("/Shared/manual-tracing-demo")

# Enable automatic tracing for OpenAI
mlflow.openai.autolog()

@mlflow.trace(name="RAG Pipeline", span_type=SpanType.CHAIN)
def answer_question(question: str) -> str:
    """A simple RAG pipeline with manual tracing."""

    # Step 1: Retrieve context (manually traced)
    context = retrieve_context(question)

    # Step 2: Generate answer (automatically traced by OpenAI autolog)
    client = OpenAI()
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {"role": "system", "content": f"Context: {context}"},
            {"role": "user", "content": question}
        ],
        max_tokens=150
    )

    return response.choices[0].message.content

@mlflow.trace(span_type=SpanType.RETRIEVER)
def retrieve_context(question: str) -> str:
    """Simulate context retrieval."""
    # Simulate retrieval logic
    return f"Relevant context for: {question}"

# Execute the traced pipeline
result = answer_question("What is MLflow Tracing?")
print(result)

私のユースケースに適したアプローチは何ですか?​

一般に、 自動トレース から始めて、アプリケーションのロジックが正確にキャプチャされていない場合、またはより詳細に制御する必要がある場合にのみ 手動トレース に移行することをお勧めします。

ユースケースに最適なトレースアプローチを決定するには、アプリケーションのコードをどのように記述しているかに基づいてください。

  1. 単一のGenAIオーサリングライブラリ (LangGraph、CrewAI、OpenAIエージェント、Bedrockエージェントなど)を使用

    • auotomaticトレーシング を使用するには、選択したライブラリの統合ページから1行の統合を追加します。 mlflow.<library>.autolog()

  2. LLM プロバイダーの SDK を直接使用する (OpenAI SDK、Anthropic SDK、Bedrock SDK など)

    • API ライブラリ の自動トレース を有効にする
    • 手動トレース デコレーターを追加して、複数の LLM 呼び出しを 1 つのトレース に結合 します

  3. 複数のオーサリングフレームワークを使用するか、オーサリングフレームワークをLLMプロバイダーのSDK (LangGraphやOpenAI SDKなど)と組み合わせる

    • 各フレームワーク/SDK の自動トレース を有効にする
    • 手動トレースデコレータを追加して、複数のフレームワークまたは SDK への呼び出しを 1 つのトレース に結合 します

  4. 他のすべてのアプローチ、またはきめ細かな制御が必要な場合

ログに記録されたトレースの表示​

トレースの概要

ヒント

自動トレースから始めてすばやく成功させ、次に、より制御が必要な場所に手動トレースを追加します。両方のアプローチを組み合わせることで、GenAIアプリケーションの包括的な可観測性が得られます。

次のステップ​

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

リファレンスガイド​

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

に最終更新