mlflow-onboarding

MLflow のオンボーディング

ユーザーのプロジェクトに合ったオンボーディングの進め方を選択してください。

• GenAI アプリとエージェント — チャットボット、RAG パイプライン、ツール呼び出しエージェント向けのトレーシング、評価、プロンプト管理。
• 従来型 ML／ディープラーニング — scikit-learn、PyTorch、TensorFlow、XGBoost などのトレーニングフレームワーク向けの実験トラッキング、モデルのロギング、デプロイ。

既存の設定を再利用する

Databricks のツールによって提供された設定も含め、動作中のトラッキング URI と実験を再利用してください。不足している設定の解決、または要求されたバックエンドの変更のみを行い、提供済みのプロファイル、認証情報、実験を置き換えないでください。

ステップ 1：ユースケースを特定する

以下のシグナルを順番に確認してください。ユースケースがまだ不明な場合は、ユーザーに尋ねてください。

シグナル 1：コードベースを確認する

ユーザーのプロジェクトを検索し、ユースケースを示すインポートや使用パターンを確認します。

GenAI の指標：

• LLM クライアントライブラリからのインポート：openai、anthropic、google.generativeai、google.genai、langchain、langchain_openai、langgraph、llamaindex、litellm、autogen、crewai、dspy
• MLflow の GenAI モジュールからのインポート：mlflow.genai、mlflow.tracing、mlflow.openai、mlflow.langchain
• チャット補完、埋め込み、エージェントフレームワークの使用
• プロンプトテンプレート、またはプロンプトエンジニアリングのコード

従来型 ML の指標：

• ML フレームワークからのインポート：sklearn、torch、tensorflow、keras、xgboost、lightgbm、catboost、statsmodels、scipy
• MLflow の ML モジュールからのインポート：mlflow.sklearn、mlflow.pytorch、mlflow.tensorflow
• モデルのトレーニングループ、.fit() の呼び出し、ハイパーパラメーター調整のコード
• 表形式、画像、時系列データを含むデータセットの読み込み

# Search for GenAI indicators
grep -rl --include='*.py' -E '(import openai|import anthropic|from langchain|from langgraph|import litellm|from mlflow\.genai|from mlflow\.tracing|mlflow\.openai|mlflow\.langchain|ChatCompletion|chat\.completions)' .

# Search for ML indicators
grep -rl --include='*.py' -E '(from sklearn|import torch|import tensorflow|import keras|import xgboost|import lightgbm|mlflow\.sklearn|mlflow\.pytorch|mlflow\.tensorflow|\.fit\()' .

シグナル 2：実験タイプのタグを確認する

コードベースまたはプロジェクトディレクトリが MLflow リポジトリ自体である場合は、シグナル 3 に進んでください。MLflow リポジトリにはあらゆるユースケース向けのコードが含まれているため、ユーザーの意図を示すものではありません。

実験 ID が分かっている場合は、その mlflow.experimentKind タグを確認してください。

mlflow experiments get --experiment-id <EXPERIMENT_ID> --output json > /tmp/exp_detail.json
jq -r '.tags["mlflow.experimentKind"] // "not set"' /tmp/exp_detail.json

• genai_development → GenAI のユースケース
• custom_model_development → 従来型 ML のユースケース
• 未設定 → シグナル 3 に進む

実験 ID が分からない場合は、シグナル 3 に進んでください。

シグナル 3：ユーザーに尋ねる

コードベースと実験のシグナルから判断できない場合は、直接尋ねてください。

GenAI アプリケーション（例：LLM を活用したチャットボット、RAG パイプライン、ツール呼び出しエージェント）と、従来型の ML／ディープラーニングモデル（例：分類器、回帰モデル、ニューラルネットワークのトレーニング）のどちらを構築していますか？

ユースケースを推測しないでください。

ステップ 2：クイックスタートチュートリアルを推奨する

プロジェクトに適したクイックスタートを推奨してください。チュートリアル形式の案内と、直接の統合のどちらを希望するか、ユーザーに尋ねてください。

GenAI の進め方

MLflow GenAI のドキュメントはこちらです：https://mlflow.org/docs/latest/genai/getting-started/

該当するガイドを選択してください。

• トレーシングのクイックスタート（https://mlflow.org/docs/latest/genai/tracing/quickstart/） — LLM 呼び出しの自動トレーシングを有効にします。MLflow サーバーの起動、実験の作成、自動ロギングの有効化、UI でのトレースの表示について説明します。
  • Python + OpenAI 版：https://mlflow.org/docs/latest/genai/tracing/quickstart/python-openai/
  • TypeScript + OpenAI 版：https://mlflow.org/docs/latest/genai/tracing/quickstart/typescript-openai
  • OpenTelemetry（言語非依存）版：クイックスタートのページからもリンクされています
• 評価のクイックスタート（https://mlflow.org/docs/latest/genai/eval-monitor/quickstart/） — LLM ジャッジ（スコアラー）を使って GenAI アプリケーションの品質を評価します。データセット、予測関数、組み込みスコアラーとカスタムスコアラーの定義について説明します。
• バージョントラッキングのクイックスタート（https://mlflow.org/docs/latest/genai/version-tracking/quickstart/） — プロンプト管理、アプリケーションのバージョニング、トレーシングとバージョン管理されたプロンプトの接続について説明します。

いずれもユーザーのニーズに合わない場合は、MLflow GenAI のドキュメントを調べて、より適切なガイドを探してください。

従来型 ML の手順

MLflow の ML ドキュメントはこちらです：https://mlflow.org/docs/latest/ml/getting-started/

該当するガイドを選んでください。

• トラッキングのクイックスタート (https://mlflow.org/docs/latest/ml/tracking/quickstart/) — scikit-learn を使った実験トラッキング：自動ログ記録、パラメーター／メトリクス／モデルの手動ログ記録、MLflow UI での結果の確認。
• ディープラーニングのチュートリアル (https://mlflow.org/docs/latest/ml/getting-started/deep-learning/) — MLflow のログ記録を使った PyTorch モデルのトレーニング：パラメーター、メトリクス、チェックポイント、システムメトリクス（GPU 使用率、メモリ）。
• ハイパーパラメーター調整のチュートリアル (https://mlflow.org/docs/latest/ml/getting-started/hyperparameter-tuning/) — Optuna + MLflow を使ったハイパーパラメーター探索の実行、結果の比較、最適なモデルの選択。

これらがユーザーのニーズに合わない場合は、MLflow の ML ドキュメントを調べて、より適したガイドを探してください。

ステップ 3：MLflow を統合する

チュートリアルの後、またはユーザーがチュートリアルをスキップした場合は、直接統合する方法を提案してください。ユーザーのコードを変更する前に、必ずユーザーの同意を得てください。

GenAI の統合

GenAI アプリの中核となる統合機能はトレーシングです。LLM の呼び出し、ツールの実行、エージェントのステップを自動的に記録します。

サンプルプロジェクトの作成を依頼された場合： ユーザーが LLM API キー（OpenAI、Anthropic など）を持っていると決めつけないでください。代わりに、@mlflow.trace と mlflow.start_span() を使ってモックデータのトレースを作成し、外部 API にアクセスせずにトレーシングを実演してください。例：

import mlflow

mlflow.set_experiment("example-genai-app")

@mlflow.trace
def mock_chat(query: str) -> str:
    with mlflow.start_span(name="retrieve_context") as span:
        context = "Mock retrieved context for: " + query
        span.set_inputs({"query": query})
        span.set_outputs({"context": context})
    with mlflow.start_span(name="generate_response") as span:
        response = "Mock response based on: " + context
        span.set_inputs({"context": context, "query": query})
        span.set_outputs({"response": response})
    return response

mock_chat("What is MLflow?")

設定する内容（既存のプロジェクトの場合）：

1. 自動ログ記録 — ユーザーのコードがサポート対象のフレームワークを使用している場合、1 行追加するだけで、LLM プロバイダーへのすべての呼び出しを自動的にトレースできます。サポート対象のプロバイダーの一覧は https://mlflow.org/docs/latest/genai/tracing/ を参照してください。プロバイダーがサポート対象の場合：

   import mlflow
   
   # Pick the one that matches the user's LLM provider:
   mlflow.openai.autolog()       # OpenAI SDK
   mlflow.anthropic.autolog()    # Anthropic SDK
   mlflow.gemini.autolog()       # Google Gemini (google-genai SDK)
   mlflow.langchain.autolog()    # LangChain / LangGraph
   mlflow.litellm.autolog()      # LiteLLM
   

   この呼び出しを、アプリケーションの起動時に一度だけ追加してください（例：main.py、app.py、またはエントリーポイントモジュールの先頭）。LLM の呼び出しが行われる前に実行される必要があります。

   プロバイダーが自動ログ記録でサポートされていない場合は、ステップ 3（カスタムトレーシング）に進み、@mlflow.trace を使って該当する関数を手動で計測してください。

2. 実験の設定 — トレースが整理されるように実験を設定します。

   mlflow.set_experiment("my-genai-app")
   

   または、環境変数で設定します：export MLFLOW_EXPERIMENT_NAME="my-genai-app"

3. カスタムトレーシング（任意）— 自動的にトレースされない関数（カスタムツール、ビジネスロジック）には、@mlflow.trace デコレーターを使用します。

   @mlflow.trace
   def my_custom_tool(query: str) -> str:
       # ... tool logic ...
       return result
   

追加する場所： アプリケーションのエントリーポイントまたは初期化モジュールを見つけ、そこに自動ログ記録の呼び出しを追加してください。メインの LLM クライアントのインスタンス化（例：openai.OpenAI()、ChatOpenAI()）を検索すると、適切な場所を見つけられます。

4. プロンプトレジストリ（任意）— MLflow ではプロンプトのバージョン管理、保存、読み込みができます。これにより、アプリケーションのコードでテンプレートをハードコードする代わりに、URI を指定してプロンプトを読み込めます。

   import mlflow
   
   # Register a prompt version
   prompt_version = mlflow.genai.register_prompt(
       name="my_prompt",
       template="Answer the user's question: {{question}}",
   )
   print(prompt_version.uri)  # prompts:/my_prompt/1
   
   # Load it back in application code
   prompt = mlflow.genai.load_prompt("prompts:/my_prompt/1")
   

   Databricks（Unity Catalog）の場合： プロンプトは UC の catalog.schema 配下に保存されるため、name は catalog.schema.my_prompt のような 3 つの要素で構成され、ワークスペースで Prompt Registry のプレビューが有効になっている必要があります（アカウント管理者 -> Previews -> "Prompt Registry"）。成功すると、register_prompt はワークスペース UI のリンクをログに記録し、アクティブな実験の Prompts タブを catalog.schema に自動的にリンクします。登録後にそのタブが空の場合、アクティブな実験は自動的にリンクされていません（古い mlflow バージョンでは、このタグは自動的に設定されません）。手動で設定してください。

   mlflow.set_experiment_tag(
       "mlflow.promptRegistryLocation",
       "catalog.schema",  # two-part: catalog.schema (no prompt name)
   )
   

従来型 ML の統合

ML の中核となる統合は実験の追跡です。トレーニング実行時のパラメーター、メトリクス、モデルを記録します。

設定する項目：

1. 自動ログ記録 — ユーザーのコードがサポート対象のフレームワークを使用している場合、1 行追加するだけで、トレーニング中のパラメーター、メトリクス、モデルが自動的に記録されます。サポート対象のフレームワークの一覧は https://mlflow.org/docs/latest/ml/ をご覧ください。フレームワークがサポート対象の場合：

   import mlflow
   
   # Pick the one that matches the user's ML framework:
   mlflow.sklearn.autolog()      # scikit-learn
   mlflow.pytorch.autolog()      # PyTorch / PyTorch Lightning
   mlflow.tensorflow.autolog()   # TensorFlow / Keras
   mlflow.xgboost.autolog()      # XGBoost
   mlflow.lightgbm.autolog()     # LightGBM
   

   トレーニング開始前に、この呼び出しを一度追加します。model.fit() の呼び出し、記録されたメトリクス、モデルのアーティファクトが自動的に取得されます。

   フレームワークが自動ログ記録に対応していない場合は、手順 3（手動ログ記録）に進み、mlflow.log_param()、mlflow.log_metric()、mlflow.log_artifact() を使ってデータを明示的に記録します。

2. 実験の設定 — 実行を整理できるよう、実験を設定します。

   mlflow.set_experiment("my-ml-experiment")
   

   または、環境変数で設定します：export MLFLOW_EXPERIMENT_NAME="my-ml-experiment"

3. 手動ログ記録（任意）— 自動ログ記録では取得されないメトリクスやパラメーターを記録します。

   with mlflow.start_run():
       mlflow.log_param("custom_param", value)
       mlflow.log_metric("custom_metric", value)
   

追加する場所： model.fit()（または同等の処理）を呼び出しているトレーニングスクリプトまたはモジュールを探します。トレーニングループの開始前に、自動ログ記録の呼び出しを追加します。

検証

GenAI の検証

mlflow-trace-instrumentation の検証ワークフローに従います。計装済みのアプリケーションを一度実行し、その後、読み戻しに対して実時間で 60 秒の期限を設定します。取得したトレース ID を使って読み込むか、実行開始時刻を trace.timestamp_ms の境界値として指定し、max_results=1 で検索します。MLflow の呼び出しが待機中または内部で再試行中であっても、期限が切れたら検証コマンドをキャンセルします。元の時間枠内に、具体的かつ迅速に実行できる修正が見つかった場合に限り、再試行は一度までにします。トレースと想定されるスパンが確認できた時点で終了します。追加の目視確認は不要です。

API キーの欠落、認証、権限、または SQL ウェアハウスの低速・利用不可によって実行や読み戻しが妨げられた場合は、検証済みの手順、未検証の結果、確認されたエラー、必要な具体的なユーザー操作を伝えます。検証を完了するために、アプリケーションを繰り返し実行したり、SQL、直接の REST 呼び出し、別の認証方法を試したりしないでください。

ML の検証

1. トレーニングスクリプトを実行します
2. 実行があるか確認します：

   mlflow runs search \
     --experiment-id <EXPERIMENT_ID> \
     --max-results 5 \
     --output json > /tmp/verify_runs.json
   jq '.runs | length' /tmp/verify_runs.json
   

3. 実行が表示されたら、MLflow UI を開き、記録されたパラメーター、メトリクス、アーティファクトを確認します