跳到主要内容

跟踪 Vercel AI SDK

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

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

  • 提示或消息以及生成的响应
  • 延迟
  • 调用层次结构
  • 当提供程序返回时，令牌使用情况
  • 如果抛出任何异常

快速开始 (NextJS)​

如果您正在使用 NextJS，启用 Vercel AI SDK 的 MLflow 跟踪非常简单。

提示

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

1. 启动 MLflow 跟踪服务器​

如果还没有，请启动 MLflow 跟踪服务器

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 导出器，将跟踪导出到 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 用量​

当底层提供程序提供令牌使用情况（例如输入和输出令牌）时，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 }