跳到主要内容

使用外部管理的代码跟踪应用程序版本

本指南演示了 MLflow 在核心应用程序代码位于 Git 等外部版本控制系统 (VCS) 中时，对 GenAI 应用程序进行版本控制的主要方法。在此工作流程中，MLflow 的 LoggedModel 充当**元数据中心**，将概念性应用程序版本链接到其特定的外部代码（例如，Git 提交）、配置和相关的 MLflow 实体，如跟踪和评估结果。

mlflow.set_active_model() 函数是此过程的关键，它建立了一个上下文，以便后续的跟踪和评估能够自动与正确的应用程序版本相关联。

先决条件​

本指南需要以下软件包

  • **mlflow>=3.1**：具有 GenAI 功能的核心 MLflow 功能。不支持 MLflow 2.x，因为它缺少使用 LoggedModel 的版本跟踪功能。
  • **openai>=1.0.0**：本指南中基于 OpenAI 的示例需要此版本（如果使用其他 LLM 提供商，请安装他们各自的 SDK）

安装所需软件包

pip install --upgrade "mlflow>=3.1" openai>=1.0.0

环境设置​

在运行以下示例之前，请配置您的环境

import os
import mlflow

# Optional: Set MLflow tracking URI if using a local or remote tracking server
mlflow.set_tracking_uri("https://:5000")

# Set experiment (creates it if it doesn’t exist)
mlflow.set_experiment("my_genai_app_versions")

# Set your LLM provider API key (e.g., OpenAI)
os.environ["OPENAI_API_KEY"] = "your-api-key-here"

步骤 1：创建一个 LoggedModel（元数据中心）​

LoggedModel 版本充当应用程序特定迭代的中央记录（元数据中心）。它不需要存储应用程序代码本身；相反，它指向代码的管理位置（例如，Git 提交哈希）。

我们使用 mlflow.set_active_model() 来声明我们当前正在使用的 LoggedModel，或者在它尚不存在时创建一个新的。此函数返回一个包含 model_id 的 ActiveModel 对象，该对象对于后续操作很有用。

import subprocess

# Define your application and its version identifier
app_name = "customer_support_agent"

# Get current git commit hash for versioning
try:
    git_commit = (
        subprocess.check_output(["git", "rev-parse", "HEAD"])
        .decode("ascii")
        .strip()[:8]
    )
    version_identifier = f"git-{git_commit}"
except subprocess.CalledProcessError:
    version_identifier = "local-dev"  # Fallback if not in a git repo

logged_model_name = f"{app_name}-{version_identifier}"

# Set the active model context
active_model_info = mlflow.set_active_model(name=logged_model_name)
print(
    f"Active LoggedModel: '{active_model_info.name}', Model ID: '{active_model_info.model_id}'"
)

这个 LoggedModel（customer_support_agent-git-xxxxxxx 或 customer_support_agent-local-dev）现在充当这个特定版本的外部管理代码的参考。

步骤 2：记录模型版本的参数​

您可以使用 mlflow.log_model_params() 将定义此应用程序版本的关键配置参数直接记录到 LoggedModel 中。这对于记录诸如 LLM 名称、温度设置或与此代码版本关联的检索策略之类的信息非常有用。

# Log key parameters defining this application version
app_params = {
    "llm": "gpt-4o-mini",
    "temperature": 0.7,
    "retrieval_strategy": "vector_search_v3",
}

mlflow.log_model_params(model_id=active_model_info.model_id, params=app_params)
print(f"Logged parameters to LoggedModel ID: {active_model_info.model_id}")

设置活动 LoggedModel 后，MLflow 的自动日志记录（或手动跟踪）生成的任何跟踪将自动与此特定 LoggedModel 版本相关联。

import mlflow
import openai

# Enable autologging for OpenAI
mlflow.openai.autolog()


# Define your agent function
def simple_agent_call(user_query):
    client = openai.OpenAI()
    response = client.chat.completions.create(
        model="gpt-4o-mini",  # Matches "llm" param
        messages=[{"role": "user", "content": user_query}],
        temperature=0.7,  # Matches "temperature" param
        max_tokens=150,
    )
    return response.choices[0].message.content


# Example agent invocation
print("\nSimulating agent call...")
agent_response = simple_agent_call("How can I track my package?")
print(f"Agent response: {agent_response}")
print(
    f"Trace for this call is automatically linked to LoggedModel '{active_model_info.name}'."
)

此 openai 调用生成的跟踪现在已链接到 customer_support_agent-git-xxxxxxx。

步骤 4：检索并检查 LoggedModel​

您可以使用 mlflow.get_logged_model() 重新获取 LoggedModel 以检查其属性、参数和关联的元数据。这对于验证记录的内容或检索配置信息非常有用。

# Fetch the LoggedModel using its ID
logged_model = mlflow.get_logged_model(model_id=active_model_info.model_id)

# Inspect basic properties
print(f"\n=== LoggedModel Information ===")
print(f"Model ID: {logged_model.model_id}")
print(f"Name: {logged_model.name}")
print(f"Experiment ID: {logged_model.experiment_id}")
print(f"Status: {logged_model.status}")
print(f"Model Type: {logged_model.model_type}")

# Access the parameters
print(f"\n=== Model Parameters ===")
for param_name, param_value in logged_model.params.items():
    print(f"{param_name}: {param_value}")

# Check creation timestamp
from datetime import datetime

creation_time = datetime.fromtimestamp(logged_model.creation_timestamp / 1000)
print(f"\n=== Timestamps ===")
print(f"Created at: {creation_time}")

# Access tags if any were set
if logged_model.tags:
    print(f"\n=== Model Tags ===")
    for tag_key, tag_value in logged_model.tags.items():
        print(f"{tag_key}: {tag_value}")

# You can also search for all LoggedModels in the experiment
from mlflow import search_logged_models

all_models = search_logged_models(
    experiment_ids=[logged_model.experiment_id],
    filter_string=f"name = '{app_name}'",
    output_format="list",
)
print(f"\n=== All '{app_name}' versions in experiment ===")
for model in all_models:
    print(
        f"- {model.name} (ID: {model.model_id}, Created: {datetime.fromtimestamp(model.creation_timestamp / 1000)})"
    )

LoggedModel 对象提供对有关您的应用程序版本的所有元数据的访问，从而可以轻松地以编程方式检索配置详细信息或围绕您的版本化应用程序构建自动化工作流程。

您可以使用 mlflow.genai.evaluate() 评估您的应用程序并将结果链接到此 LoggedModel 版本，以评估您应用程序的性能，并自动将指标、评估表和跟踪与您的特定 LoggedModel 版本相关联。

后续步骤​