版本跟踪 API 参考

概述

使用 MLflow 版本跟踪，您可以使用 LoggedModel 实体为 GenAI 应用程序创建版本化表示。 本页提供用于跟踪 MLflow 中的应用程序版本的 API 参考。

为什么应该对 GenAI 应用程序进行版本控制？

可重现性：捕获或链接到确切代码（例如 Git 提交哈希）和用于特定版本的配置，确保始终可以重新构造它。

调试回归：通过检查代码、配置、评估结果和跟踪的差异，跟踪 LoggedModel 版本以轻松比较有问题的版本与已知良好版本。

目标比较：通过 mlflow.genai.evaluate() 系统地评估版本，比较质量评分、成本和延迟等指标。

可审核性：每个 LoggedModel 版本都充当可审核记录，链接到特定代码和配置，以便进行合规性和事件调查。

核心概念

LoggedModel

MLflow 中的一个 LoggedModel 表示 GenAI 应用程序的特定版本。 要评估、部署或引用的应用程序的每个不同状态都可以捕获为新的 LoggedModel状态。

主要特征：

• GenAI 应用程序的中央版本控制实体
• 捕获应用程序状态 ，包括配置和参数
• 指向外部代码的链接 （通常通过 Git 提交哈希）
• 跟踪生命周期 从开发到生产

版本跟踪方法

MLflow 提供了两种版本跟踪方法：

1. set_active_model：简单的版本跟踪，可根据需要自动创建一个 LoggedModel ，并链接后续跟踪
2. create_external_model：使用广泛的元数据、参数和标记完全控制版本创建

API 参考文档

设置活动模型

将跟踪链接到特定 LoggedModel 版本。 如果具有给定名称的模型不存在，则会自动创建一个模型。

def set_active_model(
    name: Optional[str] = None,
    model_id: Optional[str] = None
) -> ActiveModel:

参数

必须提供name或model_id。

返回值

返回 ActiveModel 可用作上下文管理器的对象（子类 LoggedModel）。

示例用法

import mlflow

# Simple usage - creates model if it doesn't exist
mlflow.set_active_model(name="my-agent-v1.0")

# Use as context manager
with mlflow.set_active_model(name="my-agent-v2.0") as model:
    print(f"Model ID: {model.model_id}")
    # Traces within this context are linked to this model

# Use with existing model ID
mlflow.set_active_model(model_id="existing-model-id")

创建外部模型

为代码和工件存储在 MLflow 外部的应用程序（例如，在 Git 中）创建新的LoggedModel。

def create_external_model(
    name: Optional[str] = None,
    source_run_id: Optional[str] = None,
    tags: Optional[dict[str, str]] = None,
    params: Optional[dict[str, str]] = None,
    model_type: Optional[str] = None,
    experiment_id: Optional[str] = None,
) -> LoggedModel:

参数

返回值

返回一个 LoggedModel 对象，其中包含：

• model_id：模型的唯一标识符
• name：分配的模型名称
• experiment_id：关联的试验 ID
• creation_timestamp：创建模型时
• status：模型状态（对于外部模型始终为“READY” ）
• tags：标记字典
• params：参数字典

示例用法

import mlflow

# Basic usage
model = mlflow.create_external_model(
    name="customer-support-agent-v1.0"
)

# With full metadata
model = mlflow.create_external_model(
    name="recommendation-engine-v2.1",
    model_type="rag-agent",
    params={
        "llm_model": "gpt-4",
        "temperature": "0.7",
        "max_tokens": "1000",
        "retrieval_k": "5"
    },
    tags={
        "team": "ml-platform",
        "environment": "staging",
        "git_commit": "abc123def"
    }
)

# Within a run context
with mlflow.start_run() as run:
    model = mlflow.create_external_model(
        name="my-agent-v3.0",
        source_run_id=run.info.run_id
    )

LoggedModel 类

该 LoggedModel 类表示 MLflow 中的版本控制模型。

性能

常见模式

使用 Git 集成进行版本跟踪

import mlflow
import subprocess

# Get current git commit
git_commit = subprocess.check_output(["git", "rev-parse", "HEAD"]).decode().strip()[:8]

# Create versioned model name
model_name = f"my-app-git-{git_commit}"

# Track the version
model = mlflow.create_external_model(
    name=model_name,
    tags={"git_commit": git_commit}
)

将跟踪链接到版本

import mlflow

# Set active model - all subsequent traces will be linked
mlflow.set_active_model(name="my-agent-v1.0")

# Your application code with tracing
@mlflow.trace
def process_request(query: str):
    # This trace will be automatically linked to my-agent-v1.0
    return f"Processing: {query}"

# Run the application
result = process_request("Hello world")

生产部署

在生产环境中，使用环境变量而不是调用 set_active_model()：

# Set the model ID that traces should be linked to
export MLFLOW_ACTIVE_MODEL_ID="my-agent-v1.0"

最佳做法

1. 在模型名称中使用语义版本控制（例如，“app-v1.2.3”）
2. 在标记中包含 git 提交，以便于跟踪
3. 参数必须是字符串 - 转换数字和布尔值
4. 使用model_type 对类似应用程序进行分类
5. 在跟踪之前设置活动模型 以确保正确的链接

常见问题

参数类型无效：

# Error: Parameters must be strings
# Wrong:
params = {"temperature": 0.7, "max_tokens": 1000}

# Correct:
params = {"temperature": "0.7", "max_tokens": "1000"}

后续步骤

• 跟踪应用程序版本 - GenAI 应用程序版本管理分步指南
• 链接生产跟踪 - 将生产数据连接到应用版本
• 部署包 - 将版本化应用程序部署到模型服务