バージョン追跡と `LoggedModel`

MLflow バージョントラッキングを使用すると、GenAI アプリケーションのバージョン管理された表現を作成できます。バージョン管理には次のような利点があります。

再現性と監査可能性。各アプリまたはモデルバージョンは、Git コミットハッシュなどの特定のコードとその構成にリンクします。
デバッグのお手伝い。モデルバージョン間でコード、構成、評価結果、トレースを比較します。
体系的な評価。mlflow.genai.evaluate()を使用して、品質スコア、コスト、レイテンシなどのメトリクスを並べて比較します。

アプリまたはモデルのバージョンを作成するには、 LoggedModelを使用します。MLflow では、 LoggedModel GenAI アプリケーションの特定のバージョンを表します。評価、デプロイ、または参照するアプリケーションのそれぞれの個別の状態は、新しいLoggedModelとしてキャプチャできます。

このページは、MLflow バージョン追跡の紹介です。ステップバイステップのチュートリアルについては、「MLflow を使用して Git ベースのアプリケーションのバージョンを追跡する」を参照してください。

バージョン追跡の方法

MLflow はバージョン追跡に 2 つの方法を提供します。

mlflow.set_active_model() : シンプルなバージョン追跡。必要に応じてLoggedModel自動的に作成し、後続のトレースをリンクします。
mlflow.create_external_model() : バージョン作成に対する完全な制御。広範なメタデータ、問題、タグを提供できます。

`set_active_model`

トレースを特定の LoggedModel バージョンにリンクします。指定した名前のモデルが存在しない場合は、自動的に作成されます。

Python
def set_active_model(
    name: Optional[str] = None,
    model_id: Optional[str] = None
) -> ActiveModel:

パラメーター

パラメーター	Type	必須	説明
`name`	`str \| None`	いいえ*	モデルの名前。モデルが存在しない場合は、新しいモデルを作成します
`model_id`	`str \| None`	いいえ*	既存の LoggedModel の ID

※ name または model_id のいずれかのご用意が必要です。

戻り値

コンテキストマネージャとして使用できる ActiveModel オブジェクト( LoggedModelのサブクラス)を返します。

使用例

Python
import mlflow

# Simple usage - creates model if it doesn't exist
mlflow.set_active_model(name="my-agent-v1.0")

# Use as context manager
with mlflow.set_active_model(name="my-agent-v2.0") as model:
    print(f"Model ID: {model.model_id}")
    # Traces within this context are linked to this model

# Use with existing model ID
mlflow.set_active_model(model_id="existing-model-id")

`create_external_model`

コードとアーティファクトがMLflow外部(Gitなど)に保存されているアプリケーションに対して、新しいLoggedModelを作成します。

Python
def create_external_model(
    name: Optional[str] = None,
    source_run_id: Optional[str] = None,
    tags: Optional[dict[str, str]] = None,
    params: Optional[dict[str, str]] = None,
    model_type: Optional[str] = None,
    experiment_id: Optional[str] = None,
) -> LoggedModel:

パラメーター

パラメーター	Type	必須	説明
`name`	`str \| None`	No	モデル名。指定しない場合は、ランダムな名前が生成されます
`source_run_id`	`str \| None`	No	関連付けられたランの ID。デフォルトは、実行コンテキスト内にある場合はアクティブなランのID です
`tags`	`dict[str, str] \| None`	No	整理とフィルタリングのためのキーと値のペア
`params`	`dict[str, str] \| None`	No	モデルのパラメーターと構成 (文字列である必要があります)
`model_type`	`str \| None`	No	分類のためのユーザー定義のタイプ (例: "agent"、"rag-system")
`experiment_id`	`str \| None`	No	に関連付けるエクスペリメント。指定されていない場合は、アクティブなエクスペリメントを使用します

戻り値

次の LoggedModel オブジェクトを返します。

model_id: モデルの一意の識別子
name: 割り当てられたモデル名
experiment_id: 関連付けられたエクスペリメント ID
creation_timestamp: モデルが作成されたとき
status:モデルのステータス(外部モデルの場合は常に「READY」)
tags: タグの辞書
params: パラメーターの辞書

使用例

Python
import mlflow

# Basic usage
model = mlflow.create_external_model(
    name="customer-support-agent-v1.0"
)

# With full metadata
model = mlflow.create_external_model(
    name="recommendation-engine-v2.1",
    model_type="rag-agent",
    params={
        "llm_model": "gpt-4",
        "temperature": "0.7",
        "max_tokens": "1000",
        "retrieval_k": "5"
    },
    tags={
        "team": "ml-platform",
        "environment": "staging",
        "git_commit": "abc123def"
    }
)

# Within a run context
with mlflow.start_run() as run:
    model = mlflow.create_external_model(
        name="my-agent-v3.0",
        source_run_id=run.info.run_id
    )

LoggedModel クラス

LoggedModel クラスは、MLflow のバージョン管理されたモデルを表します。

プロパティ

属性	Type	説明
`model_id`	`str`	モデルの一意の識別子
`name`	`str`	モデル名
`experiment_id`	`str`	関連付けられたエクスペリメント ID
`creation_timestamp`	`int`	作成時間 (エポックからのミリ秒)
`last_updated_timestamp`	`int`	最終更新時刻 (エポックからのミリ秒)
`model_type`	`str \| None`	ユーザー定義のモデルの種類
`source_run_id`	`str \| None`	このモデルを作成した実行の ID
`status`	`LoggedModelStatus`	モデルのステータス(READY、FAILED_REGISTRATIONなど)
`tags`	`dict[str, str]`	タグの辞書
`params`	`dict[str, str]`	パラメーターのディクショナリ
`model_uri`	`str`	モデルを参照するためのURI(例:"models:/model_id")

一般的なパターン

Git 統合によるバージョン管理

Python
import mlflow
import subprocess

# Get current git commit
git_commit = subprocess.check_output(["git", "rev-parse", "HEAD"]).decode().strip()[:8]

# Create versioned model name
model_name = f"my-app-git-{git_commit}"

# Track the version
model = mlflow.create_external_model(
    name=model_name,
    tags={"git_commit": git_commit}
)

トレースのバージョンへのリンク

Python
import mlflow

# Set active model - all subsequent traces will be linked
mlflow.set_active_model(name="my-agent-v1.0")

# Your application code with tracing
@mlflow.trace
def process_request(query: str):
    # This trace will be automatically linked to my-agent-v1.0
    return f"Processing: {query}"

# Run the application
result = process_request("Hello world")

本番運用でのデプロイメント

本番運用では、 set_active_model()を呼び出す代わりに環境変数を使用します。

Bash
# Set the model ID that traces should be linked to
export MLFLOW_ACTIVE_MODEL_ID="my-agent-v1.0"

ベストプラクティス

モデル名に セマンティックバージョニングを使用する (例: "app-v1.2.3")
追跡可能性のために タグに git コミットを含める
パラメーターは文字列である必要があります : - 数字やブール値を変換します
model_typeを使用して 類似のアプリケーションを分類する
トレースする前にアクティブモデルを設定して 、適切なリンケージを確保します

一般的な問題

無効なパラメーターの種類 :

Python
# Error: Parameters must be strings
# Wrong:
params = {"temperature": 0.7, "max_tokens": 1000}

# Correct:
params = {"temperature": "0.7", "max_tokens": "1000"}

次のステップ

アプリケーションのバージョンを追跡する - 生成AI アプリのバージョン管理のステップバイステップガイド
本番運用トレースのリンク - 本番運用データをアプリのバージョンに接続する
デプロイ用パッケージ - バージョン管理されたアプリをモデルサービングにデプロイする

バージョン追跡の方法​

set_active_model​

パラメーター​

戻り値​

使用例​

create_external_model​

パラメーター​

戻り値​

使用例​

LoggedModel クラス​

プロパティ​

一般的なパターン​

Git 統合によるバージョン管理​

トレースのバージョンへのリンク​

本番運用 でのデプロイメント​

ベストプラクティス​

一般的な問題​

次のステップ​

バージョン追跡の方法

`set_active_model`

パラメーター

戻り値

使用例

`create_external_model`

パラメーター

戻り値

使用例

LoggedModel クラス

プロパティ

一般的なパターン

Git 統合によるバージョン管理

トレースのバージョンへのリンク

本番運用でのデプロイメント

ベストプラクティス

一般的な問題

次のステップ