mlflow-python

MLflow Python 技能

通过 Python API 统一执行 MLflow 读写操作，并集成 QuantStats，全面计算交易指标。

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）存放凭据，并通过以下命令为每次运行加载：

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，避免下次调用时重复采用相同的变通方案。

仅在问题真实且可复现时更新，不要基于猜测更新。