跟踪版本和环境

跟踪 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 笔记本自动填充笔记本名称。
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；如果运行本地 Python 脚本，则设置为 LOCAL；否则为 UNKNOWN（自动检测）。 在部署的应用中，我们建议根据环境更新此变量，例如 PRODUCTION、STAGING 等。
mlflow.sourceRun	生成跟踪的源运行的 run ID。	自动填充生成跟踪的源运行的 run 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（跟踪选项卡）和 mlflow.search_traces() API 中，您可以使用以下搜索查询按上下文元数据搜索跟踪

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

在 搜索跟踪指南中查看支持的过滤语法的完整列表。