はじめに — つまずきに寄り添う一言
モデルが増えてくると、「どのモデルが何をしているか」「どのデータで学習したか」「どこで使われているか」が曖昧になりがちです。監査や切替が必要になったときに手が止まる、という経験をされた読者も多いでしょう。本記事では、小規模チームでもすぐに使える最小限の設計とPythonで動く実装例を示し、まずは手を動かして運用を回せる状態を目指します。
問題定義と要件
実務で必要な観点を整理します。後回しにされやすいポイントを意識して要件化します。
- 再現性：モデルバージョンと訓練データ参照が追えること
- 検索性：オーナーや性能、デプロイ先で絞り込みできること
- 依存関係：前処理や他モデルとの依存を明確化すること
- 監査・変更履歴：誰がいつ何を更新したか追跡できること
- 軽量運用：最初はSQLiteやファイルベースで始め、必要に応じてElasticsearch/Postgresに移行
メタデータ設計の実務ガイド
まずは必須フィールドと任意フィールドを分け、メタデータ肥大化を防ぎます。下表は最小限で運用に必要なスキーマ例です。
| フィールド | 型（例） | 説明 | 必須 |
|---|---|---|---|
| model_id | 文字列（UUID） | 一意の識別子 | はい |
| name | 文字列 | 人間が読めるモデル名 | はい |
| version | 文字列（semver推奨） | モデルバージョン | はい |
| training_data_ref | 文字列／URI | 訓練データの参照（S3パスやデータセットID） | はい |
| metrics | JSONオブジェクト | 評価指標（例：accuracy, f1） | 条件付き |
| deploy_targets | 配列 | デプロイ先（例：prod/service-a, staging） | いいえ |
| dependencies | 配列（他モデルIDや処理名） | 依存する前処理・他モデルの参照 | いいえ |
| artifacts_location | URI | モデルアーティファクトの場所（S3等） | はい |
| owner | 文字列（ユーザー名／チーム） | 所有者（問い合わせ先） | はい |
| created_at / updated_at | timestamp | 登録・更新日時 | はい |
| events | 配列（ログ） | 変更履歴のイベントログ（誰が何をしたか） | はい |
軽量カタログの最小実装（SQLite + FastAPI例）
最初はSQLiteのテーブルにJSONカラムを置く構成がおすすめです。運用が大きくなればPostgresやOpenSearchにスケールアウトします。
| 目的 | 例（説明） |
|---|---|
| DBスキーマ（代表例） |
CREATE TABLE models (id TEXT PRIMARY KEY, name TEXT, version TEXT, metadata JSON, created_at TEXT, updated_at TEXT); |
| 登録API（エンドポイント） |
POST /models で model_id, name, version, metadata(JSON) を受け取り INSERT する。metadata に metrics, dependencies, artifacts_location などを含める。 |
| 検索API |
GET /models?owner=alice&min_f1=0.8 のようにクエリパラメータで絞り込み。SQLite では JSON_EXTRACT を使って JSON カラムを検索する。 |
検索・フィルタ・依存管理の実装手順（Pythonサンプル）
ここでは手順と簡潔な例を示します。詳しいコードはテンプレート配布を参照してください。
- 1) 基本的な検索：SQLite の JSON_EXTRACT を使う
用途 SQL例 ownerで絞る SELECT * FROM models WHERE json_extract(metadata, ‘$.owner’) = ‘alice’; 評価指標で閾値フィルタ SELECT * FROM models WHERE json_extract(metadata, ‘$.metrics.f1’) >= 0.8; - 2) 依存関係グラフの作り方
依存は metadata.dependencies に配列で保持します。Pythonで読み出して NetworkX 等で有向グラフを作ると可視化やサイクル検出が容易です。
手順 例（擬似コード） データ取得 rows = db.execute(‘SELECT id, json_extract(metadata, “$.dependencies”) FROM models’) グラフ構築 for id, deps in rows: for d in deps: G.add_edge(d, id) サイクル検出 cycles = list(nx.simple_cycles(G)) - 3) 変更履歴（イベントログ）設計
events 配列に {timestamp, user, action, details} を追加して都度更新します。重要な操作（登録、更新、デプロイ）は必ずイベントを残す運用ルールにします。
オーケストレーションとCI/CDとの連携ポイント
モデル登録はトレーニングパイプラインの最後に自動化します。以下は連携例です。
| ツール | フック／実装例 |
|---|---|
| Airflow | トレーニングタスクの最後にPythonOperatorで登録APIを呼ぶ。登録成功で次のデプロイタスクを進める。 |
| Prefect | Flowの最後で登録タスクを配置。登録時に自動でイベントログを追加。 |
| CI/CD（GitHub Actions 等） | モデル更新時に自動検査（性能閾値・互換性チェック）を入れ、合格時のみカタログに登録・タグ付けする。 |
運用チェックリストとよくある失敗例
導入直後に確認すべき項目と、避けるべき落とし穴をまとめます。
| チェック項目 | 確認ポイント |
|---|---|
| 登録数 | 期待通りの件数が登録されているか（トレーニング終了時に自動登録されているか） |
| 検索成功率 | 典型的なクエリ（owner, f1, deploy_target）で結果が返るか |
| 参照整合性 | dependencies が存在するモデルIDを参照しているか |
| バックアップ | メタデータの定期的なバックアップ・エクスポートがあるか |
よくある失敗例：
- 必須でないフィールドを増やしすぎて検索が重くなる
- 所有者が明確でなく、更新時の責任があいまいになる
- イベントログを残さず、誰が何をしたか追えない
次の一歩（導入テンプレートと30日チェックリスト）
短時間で動くカタログ立ち上げの手順例：
- 1. SQLiteテーブル作成スクリプトを配置する
- 2. FastAPIで最低限の登録・検索APIを実装する
- 3. トレーニングパイプラインの最後に登録API呼び出しを追加する
- 4. 30日後のチェック（登録数、検索成功率、参照整合性）を運用ルールにする
導入テンプレート（コマンド／スニペット）は Manage AI の配布リポジトリで提供予定です。まずは「1モデルを完全に登録・検索・参照できる」フローを一つ作ることを優先してください。
まとめ
モデルカタログは完璧を目指すより、まずは「再現性」「検索性」「追跡性」を満たす小さな仕組みから始めることが重要です。SQLiteやJSONベースのメタデータ、FastAPIにより短期間で動く実装が可能です。依存関係の可視化やイベントログの運用ルールを定めることで、監査対応や迅速なモデル切替えが現実的になります。まずはテンプレートを使って1つのモデルでワークフローを動かし、30日チェックで改善点を見つけてください。