mlflow-3

MLflow 3

オープンソースの MLflow 3 を対象としたライブラリリファレンス用スキルです。6 カテゴリーにわたる 24 のルールで構成されています。MLflow 3 では、モデルを第一級のエンティティとしてライブラリが再構成され、レジストリのステージに関する用語が非推奨となり、サービングスタックが置き換えられ、ストレージとシリアライズのデフォルトが変更されました。膨大な MLflow 2 のコーパスで訓練されたモデルは、以前のイディオムを流暢に再現します。まさにそれが、これらのルールが存在する理由です。優れたモデルがすでに正しく扱える内容についてのルールはありません。

対象範囲は、セルフホスト型の OSS MLflow における従来型 ML の MLOps です。GenAI 機能（mlflow.genai、トレーシング、プロンプトレジストリ、AI Gateway）は、従来型 API と混同すること自体が落とし穴となる場合に限って取り上げます。Databricks／Unity Catalog 専用機能（Deployment Jobs）は、OSS 向けに誤ってひな形が作られる可能性がある場合、対象範囲外であることを明記しています。

mlflow 3.15.1（Python ≥ 3.10）に固定しています。API に関する記述は、展開した mlflow／mlflow-skinny 3.15.1 ホイールで検証済みです。

適用する場面

• MLflow でモデル、メトリクス、パラメーター、データセットをログに記録するトレーニングコードの作成またはレビュー
• モデルバージョンの登録と、開発／ステージング／本番環境をまたいだ昇格の設定（エイリアス、copy_model_version、タグ、Webhook）
• mlflow server の立ち上げまたは堅牢化 — バックエンドストア、アーティファクトストア、認証
• 候補モデルの評価と、しきい値に基づく昇格判定
• モデルのサービング — mlflow models serve、build-docker、/invocations クライアント、デプロイ前の検証
• MLflow 3 に移行する MLflow 2 時代のコードベース（ステージ、artifact_path、mlflow.evaluate、./mlruns）

ルールのカテゴリー

#	カテゴリー	プレフィックス	対象
1	モデルのログ記録と LoggedModel	log-	artifact_path ではなく name= を使用、モデルと実行を分離、入力例に基づくシグネチャ、ログ記録時の登録、skops／torch.export のシリアライズデフォルト、モデルに関連付けられたメトリクスと search_logged_models
2	モデルレジストリと昇格	reg-	ステージに代わるエイリアス、エイリアスに基づく検索、copy_model_version を用いた環境ごとの登録済みモデル、タグによるゲート状態の管理、OSS の Webhook と Databricks 専用の Deployment Jobs
3	トラッキングバックエンドとサーバー	track-	sqlite:///mlflow.db のデフォルト、データベースのみのサーバーバックエンドと migrate-filestore、プロキシされたアーティファクトのトポロジー、テレメトリーのオプトアウト、自動ログ記録における入力例のデフォルト
4	サービング	serve-	FastAPI スコアリングサーバー（MLServer は削除）、/invocations のペイロード仕様、デプロイ前検証のための mlflow.models.predict、クラスター向けの build-docker
5	評価とゲート	eval-	mlflow.genai.evaluate ではなく mlflow.models.evaluate、baseline_model の削除後に validate_evaluation_results を使ったしきい値ベースのゲート判定
6	環境と再現性	env-	サービングの信頼できる情報源となる生成済み環境ファイル、依存関係のピン留めと uv による記録、code_paths を使ったカスタムコードの同梱

クイックリファレンス

1. モデルのログ記録と LoggedModel

• log-name-not-artifact-path — name= は検索可能な LoggedModel を作成します。artifact_path は非推奨で、警告が表示されます
• log-models-are-not-run-artifacts — start_run は不要です。アーティファクトは models/<model_id>/ に保存され、model_uri で指定します
• log-input-example-infers-signature — input_example= はシグネチャを推論し、ログ記録時にサービング入力を検証します
• log-register-at-log-time — registered_model_name= または register_model(model_info.model_uri) を使用し、組み立てた runs:/ パスは使いません
• log-serialization-defaults-changed — sklearn／lightgbm は skops、pytorch は torch.export、xgboost は UBJSON を書き出します
• log-link-metrics-search-models — log_metric(model_id=, dataset=) と search_logged_models を使えば、実行の記録管理なしにモデルを順位付けできます

2. モデルレジストリと昇格

• reg-aliases-not-stages — set_registered_model_alias と models:/name@alias を使い、非推奨のステージ API を置き換えます
• reg-resolve-by-alias-not-latest-versions — デプロイコードでは割り当て済みのエイリアスを解決し、get_latest_versions や /latest は使用しません
• reg-per-environment-registered-models — dev.*／staging.*／prod.* モデルを使用し、昇格の基本操作には copy_model_version を使います
• reg-gate-state-in-tags — validation_status タグで、以前はステージが担っていたレビュー状態を保持します
• reg-webhooks-oss-deployment-jobs-not — レジストリの Webhook は OSS で利用できますが、Deployment Jobs は Databricks 専用です

3. トラッキングバックエンドとサーバー

• track-default-is-sqlite-not-mlruns — ローカルのデフォルトは sqlite:///mlflow.db であり、./mlruns ではありません
• track-server-needs-database-backend — 3.13 以降、ファイルストアではサーバー起動時にエラーが発生します。migrate-filestore と db upgrade を実行してください
• track-proxied-artifacts-one-credential — サーバーはデフォルトでアーティファクトをプロキシするため、クライアントに必要なのは MLFLOW_TRACKING_URI だけです
• track-telemetry-on-by-default — 匿名化されたテレメトリはデフォルトで有効です。本番用イメージでは明示的に無効にしてください
• track-autolog-input-examples-off — デプロイ候補モデルには autolog(log_input_examples=True) を使用します

4. サービング

• serve-fastapi-scoring-server-only — スコアリングサーバーは FastAPI／uvicorn のみです。MLServer と Flask／gunicorn は廃止されています
• serve-invocations-payload-keys — /invocations では dataframe_split／dataframe_records／inputs／instances（およびシグネチャで宣言された params）を受け付けます
• serve-predict-before-deploy — mlflow.models.predict は実際の環境を再構築します。validate_serving_input は非推奨です
• serve-build-docker-for-clusters — コンテナには build-docker を使用します。Helm チャートがデプロイするのはトラッキングサーバーであり、モデルではありません

5. 評価とゲート

• eval-models-evaluate-split — 従来型 ML では mlflow.models.evaluate を使用します。mlflow.genai.evaluate は別の API です
• eval-gate-with-validate-evaluation-results — baseline_model は削除されています。validate_evaluation_results と MetricThreshold でゲートを設けます

6. 環境と再現性

• env-generated-files-drive-serving — サービング環境は生成されたファイルから再構築します。pip_requirements／extra_pip_requirements／uv でバージョンを固定してください
• env-bundle-custom-code-paths — code_paths／infer_code_paths により、モデルとともにインポートグラフをパッケージ化します

使い方

該当する判断が必要になったら、リファレンスファイルを読んでください。各ルールでは、修正対象となる誤ったデフォルトを示したうえで、標準的な方法を説明します（誤った方法が実際の落とし穴となる場合に限り、誤りと正解を対比します）。

• セクションの定義 — カテゴリー構成
• ルールのテンプレート — 新しいルールの追加に使用します
• AGENTS.md — すべてのルールを横断した目次を自動生成します

関連スキル

• mlflow-mlops-migration — 関連する一連のワークフローです。任意の ML コードベースを評価・再構成し、dev／staging／prod 環境で MLflow 3 をセットアップします。各フェーズでこれらのルールを参照します

参考ファイル

ファイル	説明
references/_sections.md	カテゴリの定義と順序
assets/templates/_template.md	新しいルール用のテンプレート
metadata.json	バージョンとソースの参照