mlflow/mlflow · 上手攻略

• 仓库：mlflow/mlflow
• 链接：https://github.com/mlflow/mlflow
• 分类：ai
• 作者：Jay
• 更新：2026-07-12

是什么

MLflow 是全球规模最大的开源 AI 工程平台，服务于 agents、LLM 和传统 ML 模型的全生命周期。每月下载量超过 6000 万次，数千家企业将其用于生产级 AI 部署。

在 2026 年的 MLflow 3.x 版本中，它已演化为真正统一的平台，同时覆盖传统 ML、深度学习和生成式 AI 应用。核心四大能力：

• Tracing（追踪）：基于 OpenTelemetry 的端到端可观测性，捕获 LLM 应用和 Agent 的完整执行轨迹
• Evaluation（评估）：50+ 内置指标 + LLM Judge，支持自动化质量回归测试
• Prompt Registry（提示词注册表）：版本化管理提示词，支持 A/B 测试
• AI Gateway（AI 网关）：统一路由多 LLM 提供商，支持访问控制、限流、降级和成本管理

解决什么问题

AI 应用落地三大难题：链路黑盒（Agent 内部发生了什么不清楚）、质量评估靠人工（没有量化标准）、多模型管理混乱（Key 散落、无法统一管控）。MLflow 一站式解决：

• 60+ 框架一键自动埋点（LangChain、LlamaIndex、AutoGen、CrewAI……），无需改动业务代码
• 自动化 LLM-as-Judge 评估，支持 pytest 集成，质量回归进入 CI/CD
• 统一 OpenAI-compatible 接口，一点接入即可切换不同 LLM 提供商

快速安装

# 最快方式：一条命令完成 AI Agent 埋点接入
uvx mlflow@latest agent setup

# 标准 pip 安装
pip install mlflow

# 开发版
pip install mlflow --pre

MLflow 完全开源，支持 Python、TypeScript/JavaScript、Java，可在本地、私有集群、云平台或 Databricks 托管服务中使用。

核心用法

最快上手：Tracing（追踪）

一行命令启动 MLflow 服务器，再三行代码开启追踪：

# 1. 启动 MLflow 服务器
uvx mlflow server

# 2. Python 代码中启用追踪
import mlflow

mlflow.set_tracking_uri("http://localhost:5000")
mlflow.openai.autolog()  # 自动追踪 OpenAI 调用

# 3. 正常使用你的 LLM 应用
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
    model="gpt-4o-mini",
    input="Hello!",
)

然后在 http://localhost:5000 打开 MLflow UI，即可看到完整调用链。

AI Agent 追踪（AutoGen 为例）

import mlflow
from autogen import ConversableAgent

mlflow.set_tracking_uri("http://localhost:5000")

# autogen 已支持自动追踪
with mlflow.start_span(name="agent_planning") as span:
    agent = ConversableAgent("assistant", llm_config={"model": "gpt-4o"})
    result = agent.generate_reply(messages=[{"role": "user", "content": "写一首诗"}])
    span.set_attribute("result_length", len(result))

AI Gateway（统一路由）

启动 AI 网关：

mlflow gateway start --config-path config.yaml

config.yaml 示例：

routes:
  - name: gpt-4o
    target: https://api.openai.com/v1
    model: gpt-4o

  - name: claude
    target: https://api.anthropic.com
    model: claude-3-5-sonnet-20241022

  - name: deepseek
    target: https://api.deepseek.com
    model: deepseek-chat

providers:
  openai:
    api_key: ${OPENAI_API_KEY}
  anthropic:
    api_key: ${ANTHROPIC_API_KEY}

调用方式（与 OpenAI API 完全兼容）：

from openai import OpenAI

client = OpenAI(base_url="http://localhost:5000/gateway")
response = client.chat.completions.create(
    model="claude",  # 随意切换后端，无需改代码
    messages=[{"role": "user", "content": "你好"}]
)

Evaluation（评估）

import mlflow

# 加载评估数据集
eval_data = mlflow.load_prompt("prompts://quality-check-v1")

# 运行 LLM Judge 评估
results = mlflow.evaluate(
    model="models:/my-agent/production",
    data=eval_data,
    evaluators="default",
    evaluator_config={
        "response_metric": "relevance",
        "threshold": 0.8,
    },
)

pytest 集成（质量回归测试）

import mlflow
import pytest

@pytest.fixture
def mlflow_tracking():
    mlflow.set_tracking_uri("http://localhost:5000")
    yield

@mlflow.test
def test_agent_response_quality(mlflow_tracking):
    """GenAI 质量回归测试"""
    response = my_agent.run("用户咨询退款政策")
    assert response is not None
    assert len(response) > 50

Prompt Registry（提示词版本化管理）

# 注册提示词
mlflow.register_prompt(
    name="customer-service-v3",
    prompt="你是一位专业客服。请用友好语气回复用户问题。",
    tags=["production", "reviewed"],
)

# 获取最新版本
prompt = mlflow.load_prompt("prompts://customer-service-v3")

AI Gateway 流量分配（A/B 测试）

routes:
  - name: gpt-4o-premium
    target: https://api.openai.com/v1
    model: gpt-4o
    weight: 20  # 20% 流量

  - name: gpt-4o-mini
    target: https://api.openai.com/vv1
    model: gpt-4o-mini
    weight: 80  # 80% 流量

典型适用场景

1. LLM 应用调试：当 Agent 行为异常时，通过 Tracing 还原完整执行链，快速定位是哪一步出错
2. 多模型评估与选型：用 LLM Judge 批量评估不同模型在同一任务上的质量，加速模型选型
3. 企业 AI 网关：统一管控多团队、多模型的 API Key，控制成本，防止 Key 泄露
4. CI/CD 质量门禁：将 GenAI 响应质量测试集成进 pytest，质量不达标不能合并
5. 提示词版本管理：A/B 测试不同提示词版本，用数据驱动提示词优化
6. Agent 可观测性：追踪复杂多步骤 Agent 的中间状态，理解规划与执行偏差

坑与注意

存储后端

MLflow 默认使用本地文件系统存储（./mlruns）。生产环境建议配置 S3 / GCS / Azure Blob Storage：

mlflow.set_tracking_uri("s3://my-bucket/mlflow")

Databricks 集成

如果使用 Databricks，MLflow 可以直接对接其托管服务，获取更完善的协作功能，但需额外配置 Databricks CLI 和认证。

Tracing 性能开销

高并发场景下，Tracing（尤其是同步写入）可能带来 5-15% 的延迟开销。生产环境建议使用异步写入或配置 WAL（Write-Ahead Log）缓冲。MLflow 3.x 新增了对 Claude Code 的持久化低延迟 Tracing（写前日志保证网络抖动不丢数据）。

LangChain / LangGraph 版本兼容性

MLflow 的自动追踪依赖各框架的特定版本。强烈建议使用官方集成的版本范围文档（见 MLflow Integrations），避免版本错配导致追踪失效。

私有模型支持

除 OpenAI / Anthropic 外，MLflow 支持接入任何 OpenAI-compatible 接口，包括本地 Ollama、私有部署的 vLLM 等。配置文件使用 provider: custom 并指定 base URL 即可。

监控与成本

AI Gateway 支持设置每个模型的用量上限和每用户限流，防止意外消耗预算。但目前的用量监控精度取决于追踪数据完整性——如果部分调用绕过了 MLflow 追踪（如直接调用 API 而非通过已埋点框架），相关用量不会被计入。

与同类对比

一句话推荐结论

MLflow 是目前最完整的开源 AI 工程平台——不只是追踪工具，而是一个覆盖 Tracing、Evaluation、Prompt 管理、AI Gateway 和完整 ML 生命周期的统一底座。如果你在构建 LLM 应用或 AI Agent，且需要一个能同时解决"黑盒调试"、"质量量化"和"多模型管控"的一站式方案，MLflow 是 2026 年最值得投资的开源选择。

来源：GitHub README (mlflow/mlflow)、mlflow.org、MLflow releases 页面、MLflow 3.x 企业 MLOps 文章、Building Production-Ready AI Agents in 2026 (mlflow.org)、YouTube: Building Trustworthy AI Agents with MLflow (Databricks 2026)

不确定处：pytest @mlflow.test 装饰器具体参数细节，建议查阅 MLflow pytest 集成文档 最新版本；AI Gateway 配置 YAML 中 weight 字段语义（是否支持小数、是否需要总和为 100）以官方文档为准。