使用 MLflow 跟踪 AI 智能体
MLflow Tracing 会记录 AI 智能体执行的步骤,包括模型请求和响应、链和工具调用、检索步骤、延迟、令牌使用量以及错误。在 Alauda AI Platform 上,跟踪记录存储在选定的 MLflow 实验中,并受到与运行和模型相同的工作区身份验证和 Kubernetes RBAC 保护。
本指南介绍以下场景的推荐跟踪路径:
先决条件
- 可访问的 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 操作。
查看跟踪记录
- 打开 Alauda AI Platform → Tools → MLFlow。
- 选择应用程序或 collector 配置的相同工作区和实验。
- 打开实验的 Traces 选项卡。
- 选择一个跟踪记录,以检查其 span 层次结构、输入和输出、延迟、令牌使用情况、工具调用和错误。
故障排除