mlflow-python

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MLflow Python Skill

Unified read/write MLflow operations via Python API with QuantStats integration for comprehensive trading metrics.

ADR: 2025-12-12-mlflow-python-skill

Note: This skill uses Pandas (MLflow API requires it). The
mlflow-python
path is auto-skipped by the Polars preference hook.

通过Python API实现MLflow统一读写操作，集成QuantStats以获取全面的交易指标。

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

注意：本Skill依赖Pandas（MLflow API要求）。Polars偏好钩子会自动跳过
mlflow-python
路径。

When to Use This Skill

适用场景

CAN Do:

Log backtest metrics (Sharpe, max_drawdown, total_return, etc.)
Log experiment parameters (strategy config, timeframes)
Create and manage experiments
Query runs with SQL-like filtering
Calculate 70+ trading metrics via QuantStats
Retrieve metric history (time-series data)

CANNOT Do:

Direct database access to MLflow backend
Artifact storage management (S3/GCS configuration)
MLflow server administration

支持的操作：

记录回测指标（夏普比率、最大回撤、总收益等）
记录实验参数（策略配置、时间周期）
创建和管理实验
使用类SQL过滤条件查询运行记录
通过QuantStats计算70+交易指标
获取指标历史数据（时间序列数据）

不支持的操作：

直接访问MLflow后端数据库
制品存储管理（S3/GCS配置）
MLflow服务器管理

Prerequisites

前置条件

Authentication Setup

认证设置

MLflow uses separate environment variables for credentials (NOT embedded in URI):

bash

undefined

MLflow使用独立的环境变量存储凭证（不嵌入URI）：

bash

undefined

Option 1: mise + .env.local (recommended)

选项1：mise + .env.local（推荐）

Create .env.local in skill directory with:

在Skill目录下创建.env.local文件，内容如下：

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

Option 2: Direct environment variables

选项2：直接设置环境变量

export MLFLOW_TRACKING_URI="http://mlflow.eonlabs.com:5000" export MLFLOW_TRACKING_USERNAME="eonlabs" export MLFLOW_TRACKING_PASSWORD="<password>"

undefined

export MLFLOW_TRACKING_URI="http://mlflow.eonlabs.com:5000" export MLFLOW_TRACKING_USERNAME="eonlabs" export MLFLOW_TRACKING_PASSWORD="<password>"

undefined

Verify Connection

验证连接

bash

/usr/bin/env bash << 'SKILL_SCRIPT_EOF'
cd ${CLAUDE_PLUGIN_ROOT}/skills/mlflow-python
uv run scripts/query_experiments.py experiments
SKILL_SCRIPT_EOF

bash

/usr/bin/env bash << 'SKILL_SCRIPT_EOF'
cd ${CLAUDE_PLUGIN_ROOT}/skills/mlflow-python
uv run scripts/query_experiments.py experiments
SKILL_SCRIPT_EOF

Quick Start Workflows

快速开始流程

A. Log Backtest Results (Primary Use Case)

A. 记录回测结果（主要使用场景）

bash

/usr/bin/env bash << 'SKILL_SCRIPT_EOF_2'
cd ${CLAUDE_PLUGIN_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

bash

/usr/bin/env bash << 'SKILL_SCRIPT_EOF_2'
cd ${CLAUDE_PLUGIN_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. Search Experiments

B. 搜索实验

bash

uv run scripts/query_experiments.py experiments

bash

uv run scripts/query_experiments.py experiments

C. Query Runs with Filter

C. 带过滤条件查询运行记录

bash

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

bash

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

D. Create New Experiment

D. 创建新实验

bash

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

bash

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

E. Get Metric History

E. 获取指标历史数据

bash

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

bash

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

QuantStats Metrics Available

可用的QuantStats指标

The

log_backtest.py

script calculates 70+ metrics via QuantStats, including:

Category	Metrics
Ratios	sharpe, sortino, calmar, omega, treynor
Returns	cagr, total_return, avg_return, best, worst
Drawdown	max_drawdown, avg_drawdown, drawdown_days
Trade	win_rate, profit_factor, payoff_ratio, consecutive_wins/losses
Risk	volatility, var, cvar, ulcer_index, serenity_index
Advanced	kelly_criterion, recovery_factor, risk_of_ruin, information_ratio

See quantstats-metrics.md for full list.

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。

Bundled Scripts

内置脚本

Script	Purpose
`log_backtest.py`	Log backtest returns with QuantStats metrics
`query_experiments.py`	Search experiments and runs (replaces CLI)
`create_experiment.py`	Create new experiment with metadata
`get_metric_history.py`	Retrieve metric time-series data

脚本名称	用途
`log_backtest.py`	记录回测收益及QuantStats指标
`query_experiments.py`	搜索实验和运行记录（替代CLI）
`create_experiment.py`	创建带元数据的新实验
`get_metric_history.py`	获取指标时间序列数据

Configuration

配置

The skill uses mise

[env]

pattern for configuration. See

.mise.toml

for defaults.

Create

.env.local

(gitignored) for credentials:

bash

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

本Skill使用mise

[env]

模式进行配置。默认配置请查看

.mise.toml

。

创建

.env.local

（已被Git忽略）存储凭证：

bash

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

Reference Documentation

参考文档

Authentication Patterns - Idiomatic MLflow auth
QuantStats Metrics - Full list of 70+ metrics
Query Patterns - DataFrame operations
Migration from CLI - CLI to Python API mapping

认证模式 - 标准MLflow认证方式
QuantStats指标 - 70+指标完整列表
查询模式 - DataFrame操作
从CLI迁移 - CLI到Python API的映射

Migration from mlflow-query

从mlflow-query迁移

This skill replaces the CLI-based

mlflow-query

skill. Key differences:

Feature	mlflow-query (old)	mlflow-python (new)
Log metrics	Not supported	`mlflow.log_metrics()`
Log params	Not supported	`mlflow.log_params()`
Query runs	CLI text parsing	DataFrame output
Metric history	Workaround only	Native support
Auth pattern	Embedded in URI	Separate env vars

See migration-from-cli.md for detailed mapping.

本Skill替代了基于CLI的

mlflow-query

Skill。主要差异：

功能特性	mlflow-query（旧版）	mlflow-python（新版）
记录指标	不支持	`mlflow.log_metrics()`
记录参数	不支持	`mlflow.log_params()`
查询运行记录	CLI文本解析	DataFrame输出
指标历史数据	仅支持临时方案	原生支持
认证模式	嵌入URI中	独立环境变量

详细映射请查看migration-from-cli.md。

Troubleshooting

故障排除

Issue	Cause	Solution
Connection refused	MLflow server not running	Verify MLFLOW_TRACKING_URI and server status
Authentication failed	Wrong credentials	Check MLFLOW_TRACKING_USERNAME and PASSWORD in .env
Experiment not found	Experiment name typo	Run `query_experiments.py experiments` to list all
QuantStats import error	Missing dependency	`uv add quantstats` in skill directory
Pandas import warning	Expected for this skill	Ignore - MLflow requires Pandas (hook-excluded)
Run creation fails	Experiment doesn't exist	Use `create_experiment.py` to create first
Metric history empty	Wrong run_id or metric name	Verify run_id with `query_experiments.py runs`
Returns CSV parse error	Wrong date format or columns	Check CSV has date index and returns column

问题现象	原因	解决方案
连接被拒绝	MLflow服务器未运行	验证MLFLOW_TRACKING_URI和服务器状态
认证失败	凭证错误	检查.env中的MLFLOW_TRACKING_USERNAME和PASSWORD
实验未找到	实验名称拼写错误	运行 `query_experiments.py experiments` 列出所有实验
QuantStats导入错误	缺少依赖	在Skill目录下执行 `uv add quantstats`
Pandas导入警告	属于正常现象	忽略 - MLflow要求依赖Pandas（已被钩子排除）
运行记录创建失败	实验不存在	先使用 `create_experiment.py` 创建实验
指标历史数据为空	run_id或指标名称错误	通过 `query_experiments.py runs` 验证run_id
收益CSV解析错误	日期格式或列错误	检查CSV是否包含日期索引和收益列