mlflow-mlops-migration

MLflow MLOps 移行

構造化されていないものも含め、あらゆる ML コードベースを、MLOps サイクル全体をカバーする本番環境対応のオープンソース MLflow 3構成へ移行する、段階的なゲート付きワークフローです。追跡された実験、ドメインモデルに基づくレジストリ、dev/staging/prod の分離、評価をゲートとする昇格、モデルのサービングを実現します。MLflow 3 の経験がない開発者と一緒に進めることを想定しており、変更を加える前に各フェーズでレビュー可能な成果物を作成します。また、API に関する判断はすべて、MLflow 3.15.1 に固定され、この移行で取り除くべき MLflow 2 時代の慣習を明示した、同階層のmlflow-3ルールパックに委ねます。

適用する場合

次の場合にこのスキルを使用してください。

• チームが MLflow を導入したい（または整理されていない／部分的な MLflow 2 構成を使用している）ときに、単なる API の修正ではなく、本番環境対応の MLflow 3 デプロイメントへの道筋が必要な場合。
• トレーニングコードはあるものの、実験が追跡されていない、ファイルのコピーでモデルを配布している、または「デプロイ」がバケット内の pickle を指している場合。
• dev/staging/prod でのモデル昇格の仕組みを設計またはレビューするよう依頼された場合。
• MLflow 2 → 3 の移行で、クライアントコードだけでなくインフラストラクチャ（ステージ、./mlruns ファイルストア、MLServer）も変更する場合。

単一の API に関する質問には使用せず、該当するmlflow-3ルールを直接参照してください。

ワークフローの概要

0 assess ─▶ 1 domain-model ─▶ 2 environments ─▶ 3 instrument ─▶ 4 promote ─▶ 5 serve ─▶ 6 operate
  audit        registry           tracking per      training code    eval-gated    validate,     retrain loop,
  report       naming, alias      env (dev local,   → MLflow 3       copy_model_   serve,        challenger,
  (script,     + gate design      stg/prod DB+S3    idioms (rule     version +     smoke-test    maintenance
  read-only)   (interview)        + auth)           pack)            alias flip    /invocations  (gated)

フェーズ	アクション	成果物	リスク
0	scripts/00-assess.sh <codebase> を実行 — 読み取り専用の監査	mlflow-assessment.md レポート	読み取り専用
1	ヒアリング + ドメインモデリング	レジストリのドメイン文書（名前、エイリアス、ゲート）	読み取り専用
2	環境に従ってトラッキングを構築し、dev では scripts/scaffold-dev-tracking.sh を使用	アクセス可能なトラッキングサーバー、入力済みの config.json	書き込み
3	トレーニングコードを MLflow 3 の慣習に合わせて再構成（同階層のルールパック）	リファクタリング済みコード、最初に登録された LoggedModels	書き込み
4	昇格を接続 — 評価ゲート、タグ、copy_model_version、エイリアスの切り替え	昇格スクリプト／CI ジョブ	書き込み
5	サービング — mlflow.models.predict、続いて serve／build-docker、/invocations のスモークテスト	各環境でサービングされるモデル	書き込み
6	運用 — 再トレーニング、チャレンジャー評価、メンテナンス（ワークフローを参照）	ランブックの運用手順、スケジュール済みジョブ	書き込み
✓	フェーズ 2～5 の後に scripts/verify.sh を実行	合否の検証レポート	読み取り専用

各フェーズは順番に進めます。references/workflow.mdに各フェーズの開始／終了条件が記載されており、scripts/verify.sh はインフラストラクチャ関連フェーズの終了ゲートです。どのフェーズも安全に再実行できます。00-assess.sh は自身のレポートのみを再生成し（それ以外のものを上書きしません）、scaffold-dev-tracking.sh は上書きを拒否し（終了コード 2 は作成済みを示します）、verify.sh は読み取りのみを行います。冪等でない唯一の手順は、昇格時の copy_model_version です。再コピーせずに再開する方法については、references/promotion.mdを参照してください。

リスクレベル：書き込み

このワークフローでは、トレーニングコードを編集し、インフラストラクチャファイルを書き込み、サービスを立ち上げます。安全策は次のとおりです。

• フェーズ 0～1 では何も変更しません。コードやインフラストラクチャに手を加える前に、必ず両方を完了してください。
• 次の操作を始める前に、ユーザーの確認を得てください。トラッキングサーバーの起動または置き換え、トレーニングのエントリポイントの書き換え、prod の @champion エイリアスの切り替え（dev/staging の切り替えはフェーズ 4 のパイプラインで自動化できます）、および localhost の範囲を超えてサービングエンドポイントを公開すること。
• メンテナンス用コマンドのうち 2 つは破壊的操作であり、明示的なユーザー確認と理由の提示がある場合に限り実行してください。mlflow gc（論理削除された run と experiment を完全に削除します。レジストリのエンティティには影響しません）と mlflow db upgrade（元に戻せないスキーマ移行です。事前にデータベースのスナップショットを取得してください）が該当します。hooks/hooks.jsonの PreToolUse フックは、そのコマンドに対して MLFLOW_MAINTENANCE_ACK=yes が設定されていない限り、どちらのコマンドもブロックするため、誤って未確認のまま実行されることはありません。

要件

• Python ≥ 3.10。プロジェクト環境に mlflow==3.15.1 がインストールされていること
• bash、curl、jq — スクリプトで使用します
• uv — サービングフェーズでは高速な分離環境の再構築のために --env-manager uv を使用します （uv を利用できない場合は、すべての箇所で virtualenv に置き換えてください）
• Docker + docker-compose — 開発用トラッキングスタックと build-docker サービングイメージに必要です
• 共有環境（ステージング／本番）ごとにデータベースとオブジェクトストア — PostgreSQL／MySQL と S3／GCS／Azure。開発環境では、スキャフォールド済みのローカルスタックを使用します
• 兄弟スキルの mlflow-3 — フェーズ 3 でそのルールを参照します。インストールされていない場合は、 代わりに MLflow 3 移行ガイドを読んでください（ワークフローは引き続き動作しますが、手動での確認が増えます）

セットアップ

config.json は空の状態で始まります。フェーズ 2 でこのファイルを埋めます（環境ごとのトラッキング URI、レジストリの名前空間、 モデル名、サービング URL）。スクリプトで必要なフィールドが空の場合、スクリプトが必要な項目を示します — ファイル内の _setup_instructions に従って入力してください。

クイックリファレンス

作業内容	参照先
現在のコードベースの動作を監査する	scripts/00-assess.sh <dir> + references/assessment.md
モデル名／エイリアス／ゲートを決める	references/domain-modelling.md
コマンド 1 つで開発用トラッキングを立ち上げる	scripts/scaffold-dev-tracking.sh <dir>
ステージング／本番のトラッキング構成を設計する	references/environments.md
log_model／ステージ／evaluate 呼び出しを書き換える	兄弟スキル mlflow-3 のルール（log-*、reg-*、eval-*）
昇格パイプラインを構築する	references/promotion.md
モデルをサービングしてスモークテストする	references/serving.md
セットアップが実際に動作することを確認する	scripts/verify.sh
各フェーズの開始／終了条件をすべて確認する	references/workflow.md

注意点

gotchas.md を参照してください — このワークフローの実行中に見つかった失敗要因を記載しています。migrate-filestore の SQLite 専用ターゲットや、基本認証のブートストラップ認証情報などが含まれます。

関連スキル

• mlflow-3 — このワークフローが API の判断ごとに参照する、兄弟のライブラリリファレンス用ルールパック