使用 MLflow 跟踪 AI 智能体

MLflow Tracing 会记录 AI 智能体执行的步骤,包括模型请求和响应、链和工具调用、检索步骤、延迟、令牌使用量以及错误。在 Alauda AI Platform 上,跟踪记录存储在选定的 MLflow 实验中,并受到与运行和模型相同的工作区身份验证和 Kubernetes RBAC 保护。

本指南介绍以下场景的推荐跟踪路径:

  • 使用 LangChain 构建的 Python 智能体。
  • 通过兼容 OpenAI 的 API 调用 Llama Stack(现称 OGX) 的应用程序。
  • 已经发出 OpenTelemetry 跟踪记录的 OGX 服务器或其他应用程序。

先决条件

  • 可访问的 MLflow tracking server 和工作区。请参阅 MLflow 工作区和访问控制。
  • MLFLOW_TRACKING_TOKEN 中的 Dex id token。请按照使用带有身份验证和 RBAC 的 MLflow Python SDK 获取并续订令牌。
  • 用于存储跟踪记录的实验。创建或写入跟踪记录需要对工作区的 experiments 资源具有 create 和 update 权限。
  • 智能体到 MLflow tracking server 及其模型端点的网络访问权限。

启动智能体前,设置通用的 MLflow 连接变量:

export MLFLOW_TRACKING_URI=http://mlflow-tracking-server.kubeflow:5000
export MLFLOW_TRACKING_TOKEN='<dex-id-token>'
export MLFLOW_WORKSPACE=team-a

上述 URI 是由 OAuth 代理前置的集群内 Service。对于集群外部的客户端,请改用 https://<platform>/clusters/<cluster>/mlflow。

WARNING

跟踪记录可能包含提示、响应、检索内容以及工具参数或结果。除非组织允许在 MLflow 中存储此类数据,否则请勿发送机密信息或敏感个人数据。

跟踪 LangChain 智能体

MLflow 的 LangChain 集成会自动为智能体、嵌套链、模型请求、检索和工具调用创建 span。它支持同步、异步、批处理和流式 LangChain 调用。

安装智能体依赖项:

pip install "mlflow[genai]" langchain langchain-openai

以下示例使用工具调用智能体和兼容 OpenAI 的模型端点。请根据环境中可用的模型服务设置 MODEL_BASE_URL、MODEL_API_KEY 和 MODEL_ID。

import os

import mlflow
from langchain.agents import create_agent
from langchain.tools import tool
from langchain_openai import ChatOpenAI


mlflow.set_experiment("agent-tracing")
mlflow.langchain.autolog()


@tool
def get_weather(city: str) -> str:
    """Return the current weather for a city."""
    # Replace this example result with a call to your weather service.
    return f"The weather in {city} is sunny and 24 C."


model = ChatOpenAI(
    model=os.environ["MODEL_ID"],
    base_url=os.environ["MODEL_BASE_URL"],
    api_key=os.environ["MODEL_API_KEY"],
)

agent = create_agent(
    model=model,
    tools=[get_weather],
    system_prompt="You are a concise travel assistant.",
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "Should I take a coat to Taipei today?"}]}
)
print(result["messages"][-1].content)

在应用程序启动期间调用一次 mlflow.langchain.autolog(),并确保在调用智能体之前完成。现有的 LangChain 应用程序代码无需进行其他更改。

跟踪 OGX 应用程序

OGX 提供兼容 OpenAI 的 Chat Completions 和 Responses API。对于调用 OGX 的 Python 应用程序,MLflow 的 OpenAI 集成是最简单的选项,并且可以完整跟踪 Responses API 调用。

安装客户端依赖项:

pip install "mlflow[genai]" openai

将 OpenAI 客户端指向 OGX API。@mlflow.trace 包装器会将 run_agent 执行的所有模型和工具活动归入一个父 span;mlflow.openai.autolog() 会为每个 OGX 请求创建嵌套 span。

import os

import mlflow
from openai import OpenAI


mlflow.set_experiment("ogx-agent-tracing")
mlflow.openai.autolog()

client = OpenAI(
    base_url=os.environ.get(
        "OGX_BASE_URL",
        "http://<ogx-service>.<namespace>.svc.cluster.local:8321/v1",
    ),
    api_key=os.environ.get("OGX_API_KEY", "not-used"),
)


@mlflow.trace(name="ogx-agent")
def run_agent(question: str) -> str:
    response = client.responses.create(
        model=os.environ["OGX_MODEL_ID"],
        input=question,
    )
    return response.output_text


print(run_agent("Give me a two-step plan for testing a Kubernetes operator."))

多步骤智能体循环中发起的每次调用都会嵌套在 ogx-agent 跟踪记录下。当请求使用函数工具时,MLflow 还会记录工具定义和模型的工具调用响应。

导出 OGX OpenTelemetry 跟踪记录

如果希望跟踪 OGX 服务器本身、为非 Python 应用程序添加检测,或通过 collector 路由遥测数据,请使用 OpenTelemetry。MLflow 在 /v1/traces 接受通过 OTLP/HTTP 发送的跟踪记录;不接受 OTLP/gRPC 提取。

首先,获取数字实验 ID:

import mlflow

experiment = mlflow.set_experiment("ogx-server-tracing")
print(experiment.experiment_id)

配置 OpenTelemetry Collector 以接收来自 OGX 的跟踪记录,并将其转发到 Alauda MLflow:

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch: {}

exporters:
  otlphttp/mlflow:
    traces_endpoint: http://mlflow-tracking-server.kubeflow:5000/v1/traces
    headers:
      Authorization: "Bearer ${env:MLFLOW_TRACKING_TOKEN}"
      X-MLflow-Experiment-Id: "${env:MLFLOW_EXPERIMENT_ID}"
      X-MLFLOW-WORKSPACE: "${env:MLFLOW_WORKSPACE}"

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/mlflow]

在其环境中设置 MLFLOW_TRACKING_TOKEN、MLFLOW_EXPERIMENT_ID 和 MLFLOW_WORKSPACE,然后启动 collector。接着配置 OGX,将 OTLP/HTTP 跟踪记录发送到 collector:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

opentelemetry-instrument \
  --traces_exporter otlp \
  --metrics_exporter none \
  --service_name ogx-server \
  -- \
  ogx run starter

OGX 使用 OpenTelemetry 自动检测来处理服务器活动和受支持的 SDK 活动。MLflow 的 OTLP 端点仅提取跟踪记录;请将指标单独路由到指标后端。

NOTE

除非有意将 MLflow 自动日志记录和单独的 OpenTelemetry 导出器配置为共享一个 tracer provider,否则不要同时为相同的调用启用二者。独立的导出器可能会创建重复的跟踪记录。对于 OGX Responses API 客户端调用,建议使用 mlflow.openai.autolog(),因为 OpenTelemetry 自动检测可能无法捕获所有 Responses API 操作。

查看跟踪记录

  1. 打开 Alauda AI Platform → Tools → MLFlow。
  2. 选择应用程序或 collector 配置的相同工作区和实验。
  3. 打开实验的 Traces 选项卡。
  4. 选择一个跟踪记录,以检查其 span 层次结构、输入和输出、延迟、令牌使用情况、工具调用和错误。

故障排除

症状检查
请求重定向到登录页面或返回 401确认 MLFLOW_TRACKING_TOKEN 包含当前的 Dex id token,并且 MLflow OAuth proxy 接受 bearer token。请参阅验证令牌方法。
403 PERMISSION_DENIED已认证用户需要具有访问工作区的权限,以及对其 experiments 资源的 create/update 权限。
未显示跟踪记录确认应用程序和 UI 使用相同的 tracking URI、工作区、实验和时间范围。此外,确保在调用智能体之前已启用自动日志记录。
OTLP 导出返回 400 或 403确认导出器使用 OTLP/HTTP,并发送 Authorization、X-MLflow-Experiment-Id 和 X-MLFLOW-WORKSPACE 标头。
同一请求出现两次对该请求路径禁用 MLflow 自动日志记录或独立的 OpenTelemetry 导出器。
OGX Responses API 调用未出现在 OpenTelemetry 跟踪记录中使用支持 Responses API 的 mlflow.openai.autolog() 跟踪客户端。