> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-zh/mlops-yu-bu-shu/mlflow.md).

# MLflow

**MLflow** 是一个用于管理完整的 **机器学习生命周期** —— 从实验跟踪和模型版本控制到部署和监控。被全球成千上万的组织使用，MLflow 为机器学习工作流带来结构化和可复现性。在 Clore.ai 的 GPU 云上运行它，可以让你的训练任务旁边拥有一个集中式跟踪服务器。

***

## 什么是 MLflow？

MLflow 提供四个核心组件：

| 组件        | 描述                    |
| --------- | --------------------- |
| **跟踪**    | 记录 ML 运行中的参数、指标、产物和代码 |
| **项目**    | 将代码打包以实现可复现运行         |
| **模型**    | 用于跨框架部署的标准模型格式        |
| **模型注册表** | 带版本控制和生命周期管理的集中式模型存储  |

**支持的框架（内置自动日志记录）：**

* PyTorch、TensorFlow/Keras
* Scikit-learn、XGBoost、LightGBM
* HuggingFace Transformers
* Spark MLlib、statsmodels、Prophet

***

## 前提条件

| 要求     | 数值                      |
| ------ | ----------------------- |
| GPU 显存 | 任意（MLflow 服务器本身仅占用 CPU） |
| 存储     | 20 GB+（用于产物）            |
| 内存     | 服务器至少需要 4 GB            |
| 端口     | 22（SSH）、5000（MLflow UI） |

{% hint style="info" %}
MLflow 跟踪服务器非常轻量。你可以在小型 CPU 实例上运行它，并将你的 GPU 训练任务指向它。或者，也可以将它与你的训练 GPU 实例放在一起。
{% endhint %}

***

## 步骤 1 — 在 Clore.ai 上租用服务器

1. 登录到 [clore.ai](https://clore.ai).
2. 点击 **市场**.
3. 对于专用跟踪服务器：按 RAM ≥ 8 GB 过滤（GPU 可选）。
4. 对于共置部署：使用你现有的训练实例。
5. 设置 Docker 镜像： **`ghcr.io/mlflow/mlflow:latest`**
6. 设置开放端口： `22` （SSH）和 `5000` （MLflow UI）。
7. 点击 **租用**.

***

## 步骤 2 — 启动 MLflow 跟踪服务器

官方 `ghcr.io/mlflow/mlflow` 镜像需要覆盖启动命令。

### 在 Clore.ai Docker 配置中

将 **命令** （或 entrypoint 覆盖）设置为：

```bash
bash -c "apt-get update -q && apt-get install -y -q openssh-server && \\
    mkdir /var/run/sshd && \\
    echo 'root:clore123' | chpasswd && \
    sed -i 's/#PermitRootLogin prohibit-password/PermitRootLogin yes/' /etc/ssh/sshd_config && \\
    service ssh start && \\
    mlflow server \\
        --host 0.0.0.0 \\
        --port 5000 \\
        --default-artifact-root /mlflow/artifacts \\
        --backend-store-uri sqlite:////mlflow/mlflow.db"
```

### 替代方案：自定义 Dockerfile

```dockerfile
FROM ghcr.io/mlflow/mlflow:latest

RUN apt-get update && apt-get install -y \
    openssh-server \
    && rm -rf /var/lib/apt/lists/*

# 配置 SSH
RUN mkdir /var/run/sshd && \
    echo 'root:clore123' | chpasswd && \
    sed -i 's/#PermitRootLogin prohibit-password/PermitRootLogin yes/' /etc/ssh/sshd_config

# 额外的 Python 包
RUN pip install boto3 psycopg2-binary

RUN mkdir -p /mlflow/artifacts

EXPOSE 22 5000

CMD service ssh start && \\
    mlflow server \\
        --host 0.0.0.0 \\
        --port 5000 \\
        --default-artifact-root /mlflow/artifacts \\
        --backend-store-uri sqlite:////mlflow/mlflow.db
```

***

## 步骤 3 — 访问 MLflow UI

打开你的浏览器：

```
http://<clore-host>:<public-port-5000>
```

你应该会看到 MLflow Experiments 仪表板。

{% hint style="info" %}
默认的 SQLite 后端（`mlflow.db`）会将所有运行元数据保存在本地。对于生产环境或团队使用，请切换到 PostgreSQL——见下面的高级配置。
{% endhint %}

***

## 步骤 4 — 记录你的第一个实验

### 从远程训练任务连接

在你的训练机器（或另一台 Clore.ai 实例）上，设置跟踪 URI：

```bash
export MLFLOW_TRACKING_URI=http://<clore-host>:<public-port-5000>
```

### 基础 PyTorch 实验日志记录

```python
import mlflow
import mlflow.pytorch
import torch
import torch.nn as nn
import torch.optim as optim

# 连接到 MLflow 服务器
mlflow.set_tracking_uri("http://<clore-host>:<public-port-5000>")
mlflow.set_experiment("my-first-experiment")

# 定义一个简单模型
class SimpleNet(nn.Module):
    def __init__(self, input_size, hidden_size, output_size):
        super().__init__()
        self.fc1 = nn.Linear(input_size, hidden_size)
        self.relu = nn.ReLU()
        self.fc2 = nn.Linear(hidden_size, output_size)
    
    def forward(self, x):
        return self.fc2(self.relu(self.fc1(x)))

# 使用 MLflow 跟踪进行训练
with mlflow.start_run(run_name="training-run-001"):
    # 记录超参数
    params = {
        "learning_rate": 0.001,
        "batch_size": 64,
        "epochs": 100,
        "hidden_size": 256,
        "optimizer": "adam"
    }
    mlflow.log_params(params)
    
    # 初始化模型
    model = SimpleNet(784, 256, 10).cuda()
    optimizer = optim.Adam(model.parameters(), lr=params["learning_rate"])
    criterion = nn.CrossEntropyLoss()
    
    # 训练循环
    for epoch in range(params["epochs"]):
        loss = torch.tensor(0.5 / (epoch + 1))  # 模拟
        accuracy = 0.7 + epoch * 0.003
        
        # 在每个 epoch 记录指标
        mlflow.log_metrics({
            "train_loss": loss.item(),
            "train_accuracy": accuracy,
        }, step=epoch)
    
    # 记录最终模型
    mlflow.pytorch.log_model(model, "model")
    
    # 记录最终指标
    mlflow.log_metric("final_accuracy", accuracy)
    
    print(f"运行已记录到 MLflow。ID: {mlflow.active_run().info.run_id}")
```

### HuggingFace Transformers 自动日志记录

```python
import mlflow
from transformers import TrainingArguments, Trainer

mlflow.set_tracking_uri("http://<clore-host>:<public-port-5000>")
mlflow.set_experiment("llm-finetuning")

# 启用自动日志记录——自动记录参数、指标和模型
mlflow.transformers.autolog()

training_args = TrainingArguments(
    output_dir="./results",
    num_train_epochs=3,
    per_device_train_batch_size=16,
    per_device_eval_batch_size=64,
    learning_rate=2e-5,
    warmup_steps=500,
    weight_decay=0.01,
    logging_dir="./logs",
    logging_steps=10,
    evaluation_strategy="epoch",
)

trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=train_dataset,
    eval_dataset=eval_dataset,
)

with mlflow.start_run():
    trainer.train()
```

***

## 步骤 5 — 使用自动日志记录的 Scikit-learn

```python
import mlflow
import mlflow.sklearn
from sklearn.ensemble import RandomForestClassifier
from sklearn.model_selection import train_test_split
from sklearn.datasets import load_digits

mlflow.set_tracking_uri("http://<clore-host>:<public-port-5000>")
mlflow.set_experiment("sklearn-experiments")

# 自动记录所有内容
mlflow.sklearn.autolog()

X, y = load_digits(return_X_y=True)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)

with mlflow.start_run(run_name="random-forest-v1"):
    rf = RandomForestClassifier(n_estimators=100, max_depth=10, random_state=42)
    rf.fit(X_train, y_train)
    
    score = rf.score(X_test, y_test)
    print(f"测试准确率：{score:.4f}")
    # 所有参数、指标和模型都会自动记录！
```

***

## 步骤 6 — 模型注册表

通过 UI 或 API 注册和管理模型版本：

```python
import mlflow

client = mlflow.MlflowClient("http://<clore-host>:<public-port-5000>")

# 从运行中注册模型
run_id = "your-run-id-here"
model_uri = f"runs:/{run_id}/model"

registered = mlflow.register_model(
    model_uri=model_uri,
    name="production-classifier"
)

print(f"版本：{registered.version}")

# 切换模型阶段
client.transition_model_version_stage(
    name="production-classifier",
    version=registered.version,
    stage="Production"
)

# 在任何地方加载生产模型
model = mlflow.pyfunc.load_model(
    model_uri="models:/production-classifier/Production"
)
```

***

## 步骤 7 — 提供模型服务

MLflow 可以将任何已记录的模型作为 REST API 提供服务：

```bash
# 在 MLflow 服务器实例上
export MLFLOW_TRACKING_URI=http://localhost:5000

mlflow models serve \\
    --model-uri "models:/production-classifier/Production" \\
    --host 0.0.0.0 \\
    --port 5001 \\
    --no-conda
```

测试已提供服务的模型：

```bash
curl -X POST http://<clore-host>:5001/invocations \\
    -H "Content-Type: application/json" \\
    -d '{"inputs": [[1.0, 2.0, 3.0, ...]]}'
```

***

## 高级配置

### PostgreSQL 后端（生产环境）

```bash
# 使用 PostgreSQL 启动
mlflow server \\
    --host 0.0.0.0 \\
    --port 5000 \\
    --backend-store-uri postgresql://user:password@db-host/mlflow \\
    --default-artifact-root s3://my-bucket/mlflow-artifacts
```

### S3 产物存储

```bash
pip install boto3

export AWS_ACCESS_KEY_ID=your_key
export AWS_SECRET_ACCESS_KEY=your_secret

mlflow server \\
    --host 0.0.0.0 \\
    --port 5000 \\
    --default-artifact-root s3://my-mlflow-bucket/artifacts \\
    --backend-store-uri sqlite:////mlflow/mlflow.db
```

### 认证（企业版）

```bash
pip install mlflow[auth]

mlflow server \\
    --host 0.0.0.0 \\
    --port 5000 \\
    --app-name basic-auth \\
    --backend-store-uri sqlite:////mlflow/mlflow.db \\
    --default-artifact-root /mlflow/artifacts
```

***

## 在 UI 中比较运行

1. 在以下位置打开 MLflow UI： `http://<clore-host>:<port>`
2. 从左侧面板选择一个实验
3. 勾选多个运行旁边的复选框
4. 点击 **比较** 以并排查看指标和参数
5. 使用 **图表** 选项卡用于可视化比较

***

## 故障排查

### 无法连接到跟踪服务器

```
mlflow.exceptions.MlflowException: API 请求失败，状态码 503
```

**解决方案：**

* 检查端口 5000 是否已在 Clore.ai 中开放并转发
* 验证服务器是否正在运行： `ps aux | grep mlflow`
* 测试连通性： `curl http://<clore-host>:<port>/health`

### 产物上传失败

**解决方案：** 确保产物目录可写：

```bash
chmod 777 /mlflow/artifacts
```

### SQLite 锁定错误（并发写入）

**解决方案：** 对于多用户设置，切换到 PostgreSQL：

```bash
pip install psycopg2-binary
```

### 模型注册表未显示

**解决方案：** 请确认你使用的是一个 `--backend-store-uri` 支持注册表的后端（SQLite 或 PostgreSQL——而不是仅仅本地路径）。

***

## 成本估算

| 实例       | 使用场景       | 预估价格          | 备注          |
| -------- | ---------- | ------------- | ----------- |
| 4 核 CPU  | 仅跟踪服务器     | 约 $0.05/小时    | 非常轻量        |
| RTX 3080 | 共置训练       | $0.05–0.19/小时 | 训练 + MLflow |
| RTX 4090 | 高负载训练 + 跟踪 | $0.14–0.42/小时 | 最常见的设置      |

{% hint style="info" %}
在一台便宜的 CPU 实例上运行 MLflow，并将你所有的 GPU 训练任务指向它。这样跟踪服务器就能持续运行，而不会烧掉昂贵的 GPU 额度。
{% endhint %}

***

## 有用资源

* [MLflow 官方文档](https://mlflow.org/docs/latest/index.html)
* [MLflow GitHub](https://github.com/mlflow/mlflow)
* [MLflow Docker Hub](https://github.com/mlflow/mlflow/pkgs/container/mlflow)
* [MLflow 模型注册表指南](https://mlflow.org/docs/latest/model-registry.html)
* [MLflow 跟踪 API 参考](https://mlflow.org/docs/latest/python_api/mlflow.html)

***

## Clore.ai GPU 推荐

| 使用场景  | 推荐 GPU         | Clore.ai 预计成本                     |
| ----- | -------------- | --------------------------------- |
| 开发/测试 | RTX 3090（24GB） | $0.07–0.21/gpu/hr                 |
| 生产训练  | RTX 4090（24GB） | $0.14–0.42/gpu/hr                 |
| 大规模实验 | A100 80GB      | [裸机](https://clore.ai/bare-metal) |

> 💡 本指南中的所有示例都可以部署在 [Clore.ai](https://clore.ai/marketplace) GPU 服务器上。浏览可用 GPU 并按小时租用——无需承诺，拥有完整 root 访问权限。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-zh/mlops-yu-bu-shu/mlflow.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.