跳到主要内容

跟踪 VoltAgent

VoltAgent Tracing

MLflow 跟踪为 VoltAgent 提供自动跟踪功能，VoltAgent 是一个用于构建 AI 代理的开源 TypeScript 框架。VoltAgent MLflow 通过 OpenTelemetry 集成支持对 VoltAgent 的跟踪。

什么是 VoltAgent？

VoltAgent 是一个开源的 TypeScript 框架，通过提供模块化的构建块、标准化的模式和抽象，简化了 AI 代理应用程序的开发。无论您是创建聊天机器人、虚拟助手、自动化工作流还是复杂的多代理系统，VoltAgent 都可以处理底层复杂性，让您专注于定义代理的功能和逻辑。

步骤 1：创建一个 VoltAgent 项目​

使用 VoltAgent CLI 创建一个新的 VoltAgent 项目

bash
npm create voltagent-app@latest
cd my-voltagent-app

有关完整的安装说明，请参阅 VoltAgent 文档。

步骤 2：启动 MLflow Tracking Server​

使用基于 SQL 的后端存储启动 MLflow Tracking Server

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

本示例使用 SQLite 作为后端存储。要使用其他类型的 SQL 数据库（如 PostgreSQL、MySQL 和 MSSQL），请按照 后端存储文档 中的说明更改存储 URI。文件型后端存储不支持 OpenTelemetry 摄取。

步骤 3：安装 OpenTelemetry 包​

安装 OpenTelemetry SDK 和 OTLP protobuf 导出器

bash
npm install @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-proto dotenv
MLflow 跟踪转换

MLflow 自动转换 VoltAgent 的语义约定，以实现最佳的 UI 可视化

  • 聊天 UI：将 VoltAgent 的消息格式转换为具有 role 和 content 字段的标准聊天格式，以实现丰富的消息显示
  • Token 使用量：提取 token 指标 (usage.prompt_tokens, usage.completion_tokens) 并在跟踪摘要中显示它们
  • Span 类型：将 VoltAgent Span（agent、llm、tool、memory）映射到 MLflow Span 类型，以实现正确的图标和过滤

步骤 4：配置 OpenTelemetry​

打开您的主应用程序文件（例如 src/index.ts），并添加 OpenTelemetry 配置，将跟踪导出到 MLflow

typescript
import "dotenv/config";
import { VoltAgent, Agent, VoltAgentObservability } from "@voltagent/core";
import { openai } from "@ai-sdk/openai";
import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";

// Configure the OTLP exporter to send traces to MLflow
const mlflowExporter = new OTLPTraceExporter({
  url: `${process.env.MLFLOW_TRACKING_URI}/v1/traces`,
  headers: { "x-mlflow-experiment-id": process.env.MLFLOW_EXPERIMENT_ID ?? "0" },
});

// Create span processor and observability instance
const mlflowSpanProcessor = new BatchSpanProcessor(mlflowExporter);
const observability = new VoltAgentObservability({
  spanProcessors: [mlflowSpanProcessor],
});

const agent = new Agent({
  name: "my-voltagent-app",
  instructions: "A helpful assistant that answers questions",
  model: openai("gpt-4o-mini"),
});

new VoltAgent({
  agents: { agent },
  observability,
});

别忘了将所需的环境变量添加到您的 .env 文件中

bash
OPENAI_API_KEY=your-api-key
MLFLOW_TRACKING_URI=https://:5000
MLFLOW_EXPERIMENT_ID=0

将实验 ID 替换为您的 MLflow 实验 ID。您可以从 MLflow UI 创建一个实验。

步骤 5：运行您的 VoltAgent 应用程序​

启动 VoltAgent 开发服务器

bash
npm run dev

您的代理现已运行！要与其交互，请打开位于 https://console.voltagent.dev 的 VoltAgent 控制台，并向您的代理发送消息。

步骤 6：在 MLflow 中查看跟踪​

与您的代理聊天后，在 MLflow UI（https://:5000）中打开，然后导航到您的实验以查看跟踪。

VoltAgent trace in MLflow UI

后续步骤​

  • 评估代理：了解如何评估代理的性能。
  • 管理提示：了解如何管理代理的提示。
  • 自动代理优化：了解如何使用最先进的优化算法对代理进行端到端的自动优化。