Skip to content

使用 MLflow 进行智能体可观测性

MLflow Tracing 提供了一流的支持来导入 OpenTelemetry (OTel) 追踪。Google ADK 为智能体运行、工具调用和模型请求发出 OTel spans，你可以直接将这些数据发送到 MLflow 追踪服务器进行分析和调试。

前提条件

  • MLflow 版本 3.6.0 或更高版本。OpenTelemetry 仅支持在 MLflow 3.6.0+ 中导入 OpenTelemetry 数据。
  • 基于 SQL 的后端存储（例如，SQLite、PostgreSQL、MySQL）。基于文件的存储 不支持 OTLP 导入。
  • Google ADK 已安装在你的环境中。

安装依赖项

pip install "mlflow>=3.6.0" google-adk opentelemetry-sdk opentelemetry-exporter-otlp-proto-http

启动 MLflow 追踪服务器

使用 SQL 后端和端口（此示例中为 5000）启动 MLflow：

mlflow server --backend-store-uri sqlite:///mlflow.db --port 5000

你可以将 --backend-store-uri 指向其他 SQL 后端（PostgreSQL、MySQL、MSSQL）。基于文件的后端不支持 OTLP 导入。

配置 OpenTelemetry（必需）

在使用任何 ADK 组件之前，你必须配置一个 OTLP 导出器并设置全局追踪提供程序，以便 spans 被发送到 MLflow。

在导入或构建 ADK 智能体/工具之前，在代码中初始化 OTLP 导出器和全局追踪提供程序：

# my_agent/agent.py
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor

exporter = OTLPSpanExporter(
    endpoint="http://localhost:5000/v1/traces",
    headers={"x-mlflow-experiment-id": "123"}  # 替换为你的实验 ID
)

provider = TracerProvider()
provider.add_span_processor(SimpleSpanProcessor(exporter))
trace.set_tracer_provider(provider)  # 在导入/使用 ADK 之前设置

这将配置 OpenTelemetry 流水线，并在每次运行时将 ADK spans 发送到 MLflow 服务器。

示例：追踪一个 ADK 智能体

现在你可以在设置 OTLP 导出器和追踪提供程序的代码之后， 添加一个简单数学智能体的智能体代码：

# my_agent/agent.py
from google.adk.agents import LlmAgent
from google.adk.tools import FunctionTool


def calculator(a: float, b: float) -> str:
    """将两个数字相加并返回结果。"""
    return str(a + b)


calculator_tool = FunctionTool(func=calculator)

root_agent = LlmAgent(
    name="MathAgent",
    model="gemini-2.0-flash-exp",
    instruction=(
        "你是一个可以做数学的有用助手。 "
        "当被问到数学问题时，使用计算器工具来解决它。"
    ),
    tools=[calculator_tool],
)

使用以下命令运行智能体：

adk run my_agent

然后向它询问一个数学问题：

What is 12 + 34?

你将看到类似于以下的输出：

[MathAgent]: The answer is 46.

在 MLflow 中查看追踪

在 http://localhost:5000 打开 MLflow UI，选择你的实验，然后检查你的 ADK 智能体生成的追踪树和 spans。

MLflow Traces

提示

  • 在导入或初始化 ADK 对象之前设置追踪提供程序，以便捕获所有 spans。
  • 在代理后面或远程主机上，将 localhost:5000 替换为你的服务器地址。

资源