跳到主要内容

Tracing Vercel AI SDK

MLflow Tracing 为使用 Vercel AI SDK (ai 包) 构建的应用程序通过 OpenTelemetry 提供自动跟踪，为 TypeScript 和 Javascript 应用程序开发者解锁强大的可观测性功能。

启用集成后，MLflow 允许您记录 Vercel AI SDK 调用的以下信息：

  • Prompt 或消息以及生成的响应
  • 延迟
  • 调用层级
  • Provider 返回的 token 使用量
  • 如果抛出任何异常

快速入门 (NextJS)​

如果您使用的是 NextJS，启用 MLflow Tracing for Vercel AI SDK 非常简单。

提示

如果您没有现成的应用程序可供测试，可以使用 Vercel 提供的 演示聊天机器人应用。

1. 启动 MLflow Tracking Server​

如果您还没有 MLflow Tracking Server，请启动一个。

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

或者，您可以使用 Docker Compose 在不设置 Python 环境的情况下启动服务器。有关更多详细信息，请参阅 自托管指南。

2. 配置环境变量​

在您的 .env.local 文件中设置以下环境变量：

.env.local
bash
OTEL_EXPORTER_OTLP_ENDPOINT=<your-mlflow-tracking-server-endpoint>
OTEL_EXPORTER_OTLP_TRACES_HEADERS=x-mlflow-experiment-id=<your-experiment-id>
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf

例如：OTEL_EXPORTER_OTLP_ENDPOINT=https://:5000。

3. 启用 OpenTelemetry​

安装以下软件包以使用 Vercel OpenTelemetry 集成。

bash
pnpm i @opentelemetry/api @vercel/otel

在您的 NextJS 项目根目录中创建一个 instrumentation.ts 文件，并添加以下代码：

instrumentation.ts
typescript
import { registerOTel } from '@vercel/otel';

export async function register() {
  registerOTel({ serviceName: 'next-app' })
}

然后在应用程序中使用 Vercel AI SDK 的地方指定 experimental_telemetry: {isEnabled: true}。

route.ts
typescript
import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

export async function POST(req: Request) {
  const { prompt } = await req.json();

const { text } = await generateText({
  model: openai('gpt-4o-mini'),
  maxOutputTokens: 100,
  prompt,
  experimental_telemetry: {isEnabled: true},
});

  return new Response(JSON.stringify({ text }), {
    headers: { 'Content-Type': 'application/json' },
  });
}

有关上下文传播等高级用法，请参阅 Vercel OpenTelemetry 文档。

5. 运行应用程序并查看跟踪​

运行应用程序并在 MLflow UI 中查看跟踪。UI 可在您在环境变量中指定的跟踪服务器端点访问，例如 https://:5000。

其他 Node.js 应用程序​

如果您使用的是其他 Node.js 框架，请手动设置 OpenTelemetry Node SDK 和 OTLP Exporter 以将跟踪导出到 MLflow。

main.ts
typescript
import { init } from "mlflow-tracing";
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
import { NodeSDK } from '@opentelemetry/sdk-node';
import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';


const sdk = new NodeSDK({
  spanProcessors: [
    new SimpleSpanProcessor(
      new OTLPTraceExporter({
        url: '<your-mlflow-tracking-server-endpoint>/v1/traces',
        headers: { 'x-mlflow-experiment-id': '<your-experiment-id>' },
      }),
    ),
  ],
});

sdk.start();

// Make an AI SDK call with telemetry enabled
const result = await generateText({
  model: openai('gpt-4o-mini'),
  prompt: 'What is MLflow?',
  // IMPORTANT: enable telemetry is required for tracing
  experimental_telemetry: { isEnabled: true }
});

console.log(result.text);
sdk.shutdown();
bash
npx tsx main.ts

流式传输​

流式传输也得到了支持。与 generateText 函数类似，将 experimental_telemetry.isEnabled 选项指定为 true 以启用跟踪。

typescript
import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';

const stream = await streamText({
  model: openai('gpt-4o-mini'),
  prompt: 'Explain vector databases in one paragraph.',
  experimental_telemetry: { isEnabled: true }
});

for await (const part of stream.textStream) {
  process.stdout.write(part);
}

Token 用量​

当底层 provider 提供 token 使用量（例如，输入和输出 token）时，MLflow 会将其聚合到跟踪中。您可以使用 TypeScript SDK 从跟踪信息中检索它。

typescript
// Flush any pending spans then fetch the most recent trace
await mlflow.flushTraces();
const lastTraceId = mlflow.getLastActiveTraceId();

if (lastTraceId) {
  const client = new mlflow.MlflowClient({ trackingUri: 'https://:5000' });
  const trace = await client.getTrace(lastTraceId);
  console.log('Token usage:', trace.info.tokenUsage);  // { input_tokens, output_tokens, total_tokens }
}

禁用自动跟踪​

要禁用 Vercel AI SDK 的跟踪，请在 AI SDK 调用上将 experimental_telemetry: { isEnabled: false } 设置为 false。