跟踪版本与环境

跟踪 GenAI 应用程序的执行环境和应用程序版本，可以帮助您相对于代码调试性能和质量问题。这些元数据支持

• 跨 development、staging 和 production 的特定环境分析
• 跨应用程序版本的性能/质量跟踪和回归检测
• 出现问题时更快的根本原因分析

标准与自定义元数据

MLflow 使用不可变的元数据（键值字符串对）来存储跟踪中的上下文信息。

python

import mlflow

trace = mlflow.get_trace(trace_id="your-trace-id")
print(trace.info.trace_metadata)
# Output: {'environment': 'production', 'app_version': '1.0.0'}

自动填充的标签

这些标准标签由 MLflow 根据您的执行环境自动捕获

元数据字段	描述	自动设置逻辑
mlflow.source.name	生成跟踪的入口点或脚本。	对于 Python 脚本，自动填充为文件名；对于 Databricks/Jupyter notebook，自动填充为 notebook 名称。
mlflow.source.git.commit	Git 提交哈希。	如果从 Git 存储库运行，则会自动检测并填充提交哈希。
mlflow.source.git.branch	Git 分支。	如果从 Git 存储库运行，则会自动检测并填充当前分支名称。
mlflow.source.git.repoURL	Git 存储库 URL。	如果从 Git 存储库运行，则会自动检测并填充存储库 URL。
mlflow.source.type	捕获执行环境。	如果在 Jupyter 或 Databricks notebook 中运行，则自动设置为 NOTEBOOK；如果运行本地 Python 脚本，则设置为 LOCAL；否则为 UNKNOWN（自动检测）。 在您的已部署应用程序中，我们建议根据环境更新此变量，例如 PRODUCTION、STAGING 等。
mlflow.sourceRun	生成跟踪的源运行的运行 ID。	会自动用生成跟踪的源运行的运行 ID 进行填充。

注意

MLflow 还设置了其他跟踪元数据字段，例如 mlflow.trace.sizeBytes、mlflow.trace.tokenUsage 等。它们与应用程序版本控制无关，但对性能分析很有用。

保留的标准元数据

一些标准元数据字段具有特殊含义，但必须手动设置

元数据字段	描述	自动设置逻辑
mlflow.trace.session	将来自多轮对话或用户会话的跟踪分组在一起	会自动用生成跟踪的用户会话的会话 ID 进行填充。
mlflow.trace.user	将跟踪与特定用户关联，以便进行以用户为中心的分析	会自动用生成跟踪的用户的用户 ID 进行填充。

有关如何从应用程序设置这些元数据的更多详细信息，请参阅设置元数据部分。

自定义元数据

您可以定义自定义元数据或覆盖自动填充的元数据，以捕获任何业务特定或应用程序特定的上下文。例如，您可能希望附加信息，例如

• app_version：例如，"1.0.0"（来自 APP_VERSION 环境变量）
• deployment_id：例如，"deploy-abc-123"（来自 DEPLOYMENT_ID 环境变量）
• region：例如，"us-east-1"（来自 REGION 环境变量）
• （还可以添加其他自定义标签，例如功能标志）

设置元数据

要从您的应用程序为跟踪设置元数据，请使用 mlflow.update_current_trace() API，并将元数据传递给 metadata 参数。

python

mlflow.update_current_trace(metadata={"key": "value"})

实际的应用程序代码可能如下所示

python

import mlflow
import os
from fastapi import FastAPI, Request
from pydantic import BaseModel

app = FastAPI()


class ChatRequest(BaseModel):
    message: str


@mlflow.trace  # Ensure @mlflow.trace is the outermost decorator
@app.post("/chat")  # FastAPI decorator should be inner
def handle_chat(request: Request, chat_request: ChatRequest):
    # Retrieve all context from request headers
    client_request_id = request.headers.get("X-Request-ID")
    session_id = request.headers.get("X-Session-ID")
    user_id = request.headers.get("X-User-ID")

    # Update the current trace with all context and environment metadata
    # The @mlflow.trace decorator ensures an active trace is available
    mlflow.update_current_trace(
        client_request_id=client_request_id,
        metadata={
            # Reserved session metadata - groups traces from multi-turn conversations
            "mlflow.trace.session": session_id,
            # Reserved user metadata - associates traces with specific users
            "mlflow.trace.user": user_id,
            # Override automatically populated environment metadata
            "mlflow.source.type": os.getenv(
                "APP_ENVIRONMENT", "development"
            ),  # Override default LOCAL/NOTEBOOK
            # Add custom environment metadata
            "environment": "production",
            "app_version": os.getenv("APP_VERSION", "1.0.0"),
            "deployment_id": os.getenv("DEPLOYMENT_ID", "unknown"),
            "region": os.getenv("REGION", "us-east-1"),
        },
    )

    # --- Your application logic for processing the chat message ---
    # For example, calling a language model with context
    # response_text = my_llm_call(
    #     message=chat_request.message,
    #     session_id=session_id,
    #     user_id=user_id
    # )
    response_text = f"Processed message: '{chat_request.message}'"

    return {"response": response_text}


# To run this example (requires uvicorn and fastapi):
# uvicorn your_file_name:app --reload
#
# Example curl request with context headers:
# curl -X POST "http://127.0.0.1:8000/chat" \
#      -H "Content-Type: application/json" \
#      -H "X-Request-ID: req-abc-123-xyz-789" \
#      -H "X-Session-ID: session-def-456-uvw-012" \
#      -H "X-User-ID: user-jane-doe-12345" \
#      -d '{"message": "What is my account balance?"}'

查询和分析上下文数据

使用 MLflow UI

在 MLflow UI（Traces Tab）和 mlflow.search_traces() API 中，您可以使用以下搜索查询按上下文元数据搜索跟踪

• metadata.environment = 'production'
• metadata.app_version = '2.1.0'
• metadata.`mlflow.trace.session` = 'session-abc-456'

在 Search Traces 指南中查看支持的过滤器语法的完整列表。