mado ML Tracking

実験、モデル、実行コード、データセットを同じRunに結び付ける実験管理アプリです。mado S3 Data Catalogとは別に動作し、Mado連携を標準搭載しています。連携は初期状態では無効です。

利用者向けのドキュメント（インストール、使い方、管理）はhttps://aida0710.github.io/mado-ml-tracking/にあります。ソースはpages/です。

GitHub Releasesでは、ビルド済みコンテナから起動するComposeと設定例を配布します。配布物を展開し、同梱のREADMEに従って設定・DB更新・初期管理者の作成を行ってください。コンテナはGHCRで配布し、配布用Composeは内容をdigestで固定します。公開の手順はリリース手順にあります。

React/Viteの画面、TypeScript/HonoのAPI、PostgreSQL、Python SDKとSSH workerで構成します。学習・fine-tuning・推論・評価・データ加工を扱います。ArtifactsはファイルシステムまたはS3互換ストレージをProjectごとに選びます。公式MLflow 3 SDKからも記録できます。

タスクとコード編集では、リポジトリまたは単体コードをMonaco Editorで編集し、通常実行・テストのコマンドを登録できます。Taskのrevisionと実行内容を固定し、Jobごとのコードsnapshotと結果を追跡します。Computeとpluginも画面から追加・編集できます。

ローカルで起動する

Node.js 22.12以降、PostgreSQL 16以降、Python 3.11以降が必要です。workerにはOpenSSH clientも必要です。

npm ci
cp .env.example .env
chmod 600 .env

開発用DBを新規に用意する場合は次を使えます。既に同名のcontainerがあれば起動だけ行ってください。trust認証はlocalhostの開発fixture専用です。

docker run -d --name mmt-dev-postgres \
  -e POSTGRES_HOST_AUTH_METHOD=trust -e POSTGRES_USER=mmt -e POSTGRES_DB=mmt \
  -p 127.0.0.1:55483:5432 -v mmt-dev-postgres:/var/lib/postgresql/data postgres:16-alpine
docker exec mmt-dev-postgres createdb -U mmt mmt_test
npm run db:migrate:dev
npm run dev

http://127.0.0.1:5182を開き、開発ログインします。初期状態は空です。ProjectとExperimentを登録して使い始めます。確認用データを入れる場合だけ.envにMMT_ALLOW_SEED=trueを設定してnpm run db:seedを実行します。開発ログイン・seed・local executorは本番で無効です。

画面は日本語と英語に対応しています。右上の地球アイコンから切り替えられます。ログイン画面と初回パスワード変更画面では、ロゴの右側にあります。選択はブラウザに保存し、別タブにも反映します。未選択ならブラウザの優先言語を使い、対応する言語がなければ英語を表示します。切り替えても入力内容や開いている画面を保ちます。

LANからはhttp://<このマシンのprivate IP>:5182を開けます。.env.exampleはMMT_ALLOW_PRIVATE_ORIGINS=trueを設定しています。既存の.envにも追加し、APIを再起動してください。許可範囲とSSOの固定URLは運用手順にあります。

CPUだけで実行を試す場合はMMT_ALLOW_LOCAL_EXECUTOR=trueにし、local targetを登録します。workerの手順に従ってProject用Service Account tokenでworkerを起動します。実際のGPU実行ではSSH target、GPU ID、秘密鍵とknown_hostsをworker側に用意します。

管理するもの

• Run: パラメータ、タグ、時系列メトリクス、ログ、GPU使用率、実行環境。Run比較とメディアのArtifactプレビュー。
• ModelVersion: 重み、親モデル、生成元Run、モデル系列、既定CodeVersion。aliasを解決して実際のバージョンをRunへ保存。
• CodeVersion: 固定Git commit、inlineのソース、保存したzip/tar、またはコンテナ内のコード。Python・Docker・Singularity・Apptainerの実行環境、起動コマンド、対応モデル系列、実行種別。
• DatasetVersion: URI、digest、schema、加工元のバージョン、生成元Run。外部DatasetVersionのIDも保持。
• Job: SSH接続先、GPU予約、キュー、ログ、停止、再実行。再実行は新しいRunを作り、元の記録を保持。
• モデルの自動実行: モデルバージョンの登録完了後、系列に合うルールで推論・評価をキューへ登録。コード・データセット・コンテナのバージョンを固定し、同じ登録イベントの重複を防止。
• 認証: Authentik OIDC、Projectのviewer/editor/admin、期限・scope・失効を持つ個人tokenとService Account token。
• Plugin: 別サービスのHTTP契約。データセット検索・取り込み、Run lifecycleのlineage送信、Mado容量metricsの参照。

モデル系列とCodeVersionの対応はAPIとworkerで検証します。モデルバージョンとデータセットバージョンは不変です。ジョブは起動時のコード・モデル・データセットをsnapshotとして使います。

設定と検証

運用・Authentik・保存先、コンテナ・モデルの自動実行、API契約、Mado連携の仕様、検証手順、Webの実装規約、Sweepの探索アルゴリズムを参照してください。Python SDKの使用例はpython/examples/にあります。

MLflow 3の接続先・API token・Runとモデルの記録・autolog・workerでの使用方法はMLflow 3の手順を参照してください。

npm run typecheck
npm run build
MMT_TEST_DATABASE_URL=postgresql://[email protected]:55483/mmt_test npm test
cd python
uv sync --extra test --extra telemetry
uv run pytest

実際のAuthentik client、SSH GPU接続先、S3保存先は環境に合わせて設定します。外部サービスに接続していないテスト結果を、本番接続の確認として扱わないでください。

License

mado ML Tracking is licensed under the Apache License 2.0.