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

Version Tracking API リファレンス

概要​

MLflow バージョン追跡を使用すると、 LoggedModel エンティティを使用して 生成AI アプリケーションのバージョン管理された表現を作成できます。このページでは、MLflow でアプリケーションのバージョンを追跡するための API リファレンスを提供します。

生成AIアプリケーションをバージョン管理する理由​

再現性 : 特定のバージョンで使用されている正確なコード (Git コミット ハッシュなど) と構成をキャプチャまたはリンクして、いつでも再構築できるようにします。

リグレッションのデバッグ : LoggedModel バージョンを追跡し、コード、構成、評価結果、トレースの違いを調べることで、問題のあるバージョンを既知の正常なバージョンと簡単に比較できます。

客観的な比較 : mlflow.genai.evaluate() を使用してバージョンを体系的に評価し、品質スコア、コスト、レイテンシなどのメトリクスを並べて比較します。

監査可能性 : 各 LoggedModel バージョンは監査可能なレコードとして機能し、コンプライアンスとインシデント調査のための特定のコードと構成にリンクします。

コアコンセプト​

LoggedModel​

MLflow の LoggedModel は、生成AI アプリケーションの特定のバージョンを表します。評価、デプロイ、または参照するアプリケーションの各個別の状態は、新しい LoggedModelとしてキャプチャできます。

主な特徴:

  • 生成AI アプリケーションの 中央バージョン管理されたエンティティ
  • アプリケーションの状態 (構成とパラメーターを含む) をキャプチャします
  • 外部コードへのリンク (通常は Git コミット ハッシュ経由)
  • 開発から本番運用までの ライフサイクルを追跡

バージョン追跡方法​

MLflow には、バージョン追跡のための 2 つのアプローチが用意されています。

  1. set_active_model : 必要に応じてLoggedModelを自動的に作成し、後続のトレースをリンクするシンプルなバージョン追跡
  2. create_external_model : 広範なメタデータ、パラメーター、タグを使用してバージョン作成を完全に制御

API リファレンス​

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"

ベストプラクティス​

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

一般的な問題​

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

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

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

次のステップ​

に最終更新