mlflow-python

MLflow Python スキル

QuantStats と連携し、包括的なトレーディング指標を扱う、Python API による統一された MLflow の読み書き操作です。

ADR： 2025-12-12-mlflow-python-skill

注：このスキルでは Pandas を使用します（MLflow API で必要です）。Polars 優先フックにより、mlflow-python パスは自動的にスキップされます。

進化するスキル：このスキルは使用を通じて改善されます。手順が間違っている、パラメーターが変化している、または回避策が必要だった場合は、先送りせず、すぐにこのファイルを修正してください。実際に再現可能な問題がある場合にのみ更新してください。

このスキルを使用する場面

できること：

• バックテスト指標（Sharpe、max_drawdown、total_return など）を記録する
• 実験パラメーター（ストラテジー設定、時間足）を記録する
• 実験を作成して管理する
• SQL のようなフィルタリングでランをクエリする
• QuantStats を使用して 70 以上のトレーディング指標を計算する
• 指標の履歴（時系列データ）を取得する

できないこと：

• MLflow バックエンドへのデータベースの直接アクセス
• アーティファクトストレージの管理（S3/GCS の設定）
• MLflow サーバーの管理

前提条件

認証の設定

MLflow では認証情報に個別の環境変数を使用します（URI に埋め込みません）。

# Option 1: .env.local + uv --env-file (recommended)
# Create .env.local (gitignored) in the skill directory with the lines below,
# then run scripts as: uv run --env-file .env.local scripts/<script>.py
MLFLOW_TRACKING_URI=http://mlflow.example.com:5000
MLFLOW_TRACKING_USERNAME=<user>
MLFLOW_TRACKING_PASSWORD=<password>

# Option 2: Direct environment variables
export MLFLOW_TRACKING_URI="http://mlflow.example.com:5000"
export MLFLOW_TRACKING_USERNAME="<user>"
export MLFLOW_TRACKING_PASSWORD="<password>"

接続の確認

/usr/bin/env bash << 'SKILL_SCRIPT_EOF'
ROOT="$(cc-plugin-root devops-tools)"
cd "$ROOT/skills/mlflow-python"
uv run scripts/query_experiments.py experiments
SKILL_SCRIPT_EOF

クイックスタートのワークフロー

A. バックテスト結果の記録（主な用途）

/usr/bin/env bash << 'SKILL_SCRIPT_EOF_2'
ROOT="$(cc-plugin-root devops-tools)"
cd "$ROOT/skills/mlflow-python"
uv run scripts/log_backtest.py \
  --experiment "crypto-backtests" \
  --run-name "btc_momentum_v2" \
  --returns path/to/returns.csv \
  --params '{"strategy": "momentum", "timeframe": "1h"}'
SKILL_SCRIPT_EOF_2

B. 実験の検索

uv run scripts/query_experiments.py experiments

C. フィルターを使用したランのクエリ

uv run scripts/query_experiments.py runs \
  --experiment "crypto-backtests" \
  --filter "metrics.sharpe_ratio > 1.5" \
  --order-by "metrics.sharpe_ratio DESC"

D. 新しい実験の作成

uv run scripts/create_experiment.py \
  --name "crypto-backtests-2025" \
  --description "Q1 2025 cryptocurrency trading strategy backtests"

E. 指標の履歴の取得

uv run scripts/get_metric_history.py \
  --run-id abc123 \
  --metrics sharpe_ratio,cumulative_return

利用可能な QuantStats 指標

log_backtest.py スクリプトは QuantStats を使用して 70 以上の指標を計算します。以下はその一部です。

カテゴリー	指標
比率	sharpe, sortino, calmar, omega, treynor
リターン	cagr, total_return, avg_return, best, worst
ドローダウン	max_drawdown, avg_drawdown, drawdown_days
トレード	win_rate, profit_factor, payoff_ratio, consecutive_wins/losses
リスク	volatility, var, cvar, ulcer_index, serenity_index
高度な指標	kelly_criterion, recovery_factor, risk_of_ruin, information_ratio

全一覧は quantstats-metrics.md を参照してください。

同梱スクリプト

スクリプト	用途
log_backtest.py	QuantStats 指標とともにバックテストのリターンを記録する
query_experiments.py	実験とランを検索する（CLI を置き換えます）
create_experiment.py	メタデータ付きで新しい実験を作成する
get_metric_history.py	指標の時系列データを取得する

設定

設定には MLFLOW_* 環境変数を使用します。認証情報用に .env.local（gitignore 対象）を作成し、各コマンドで uv run --env-file .env.local scripts/<script>.py を使って読み込みます。

MLFLOW_TRACKING_URI=http://mlflow.example.com:5000
MLFLOW_TRACKING_USERNAME=<user>
MLFLOW_TRACKING_PASSWORD=<password>

リファレンスドキュメント

• 認証パターン - MLflow の標準的な認証方法
• QuantStats 指標 - 70 以上の指標の全一覧
• クエリパターン - DataFrame 操作
• CLI からの移行 - CLI と Python API の対応関係

mlflow-query からの移行

このスキルは、CLI ベースの mlflow-query スキルに代わるものです。主な違いは次のとおりです。

機能	mlflow-query（旧）	mlflow-python（新）
メトリクスの記録	非対応	mlflow.log_metrics()
パラメーターの記録	非対応	mlflow.log_params()
実行のクエリ	CLI のテキスト解析	DataFrame 出力
メトリクス履歴	回避策のみ	ネイティブ対応
認証パターン	URI に埋め込み	個別の環境変数

詳しい対応関係については、migration-from-cli.md を参照してください。

---

トラブルシューティング

問題	原因	解決策
接続が拒否される	MLflow サーバーが起動していない	MLFLOW_TRACKING_URI とサーバーの状態を確認してください
認証に失敗する	認証情報が間違っている	.env 内の MLFLOW_TRACKING_USERNAME と PASSWORD を確認してください
実験が見つからない	実験名の入力ミス	query_experiments.py experiments を実行してすべての実験を一覧表示してください
QuantStats のインポートエラー	依存関係が不足している	スキルのディレクトリで uv add quantstats を実行してください
Pandas のインポート警告	このスキルでは想定内	無視してください — MLflow には Pandas が必要です（フック対象外）
実行の作成に失敗する	実験が存在しない	まず create_experiment.py を使って作成してください
メトリクス履歴が空	run_id またはメトリクス名が間違っている	query_experiments.py runs を使って run_id を確認してください
戻り値の CSV 解析エラー	日付形式または列が間違っている	CSV に日付インデックスと returns 列があることを確認してください

実行後の振り返り

このスキルの実行後、終了する前に次の点を確認してください。

1. コマンドは成功しましたか？ — 失敗した場合は、失敗の原因となった手順またはエラー一覧を修正してください。
2. パラメーターまたは出力は変わりましたか？ — 基盤となるツールのインターフェースに変更があった場合は、使用例とパラメーター一覧を実際の内容に合わせて更新してください。
3. 回避策が必要でしたか？ — 臨機応変な対応（異なるフラグ、追加の手順など）が必要だった場合は、次回同じ回避策が不要になるよう、この SKILL.md を更新してください。

実際に再現できる問題がある場合のみ更新してください。憶測に基づく更新は避けてください。