以编程方式使用文档

您可以使用 LangSmith 通过 OpenTelemetry (OTEL) 追踪 Vercel AI SDK 的运行。本指南将通过示例进行讲解。

0. 安装

安装 Vercel AI SDK 和所需的 OTEL 包。我们在下面的代码示例中使用了他们的 OpenAI 集成，但您也可以使用他们的其他选项。

npm install ai @ai-sdk/openai zod
yarn add ai @ai-sdk/openai zod
pnpm add ai @ai-sdk/openai zod
npm install @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-proto @opentelemetry/context-async-hooks
yarn add @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-proto @opentelemetry/context-async-hooks
pnpm add @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-proto @opentelemetry/context-async-hooks

1. 配置您的环境

# This example uses OpenAI, but you can use any LLM provider of choice

2. 记录追踪

Node.js

要开始追踪，您需要在代码开头导入并调用 initializeOTEL 方法：

const { DEFAULT_LANGSMITH_SPAN_PROCESSOR } = initializeOTEL();

之后，将 experimental_telemetry 参数添加到您想要追踪的 AI SDK 调用中。

let result;
try {
  result = await generateText({
    model: openai("gpt-5.4-nano"),
    prompt: "Write a vegetarian lasagna recipe for 4 people.",
    experimental_telemetry: {
      isEnabled: true,
    },
  });
} finally {
  await DEFAULT_LANGSMITH_SPAN_PROCESSOR.shutdown();
}

您应该可以在 LangSmith 仪表板中看到追踪记录 如下所示.

您也可以追踪带有工具调用的运行：

await generateText({
  model: openai("gpt-5.4-nano"),
  messages: [
    {
      role: "user",
      content: "What are my orders and where are they? My user ID is 123",
    },
  ],
  tools: {
    listOrders: tool({
      description: "list all orders",
      parameters: z.object({ userId: z.string() }),
      execute: async ({ userId }) =>
        `User ${userId} has the following orders: 1`,
    }),
    viewTrackingInformation: tool({
      description: "view tracking information for a specific order",
      parameters: z.object({ orderId: z.string() }),
      execute: async ({ orderId }) =>
        `Here is the tracking information for ${orderId}`,
    }),
  },
  experimental_telemetry: {
    isEnabled: true,
  },
  maxSteps: 10,
});

这将产生如下所示的追踪记录 这个.

使用 traceable

您可以包装 traceable 调用在 AI SDK 工具调用的周围或内部。如果您这样做，我们建议您初始化一个 LangSmith client 实例并将其传递到每个 traceable中，然后调用 client.awaitPendingTraceBatches(); 以确保所有追踪记录被刷新。如果您这样做，则无需手动在 shutdown() or forceFlush() 上调用 DEFAULT_LANGSMITH_SPAN_PROCESSOR。以下是示例：

initializeOTEL();






const client = new Client();

const wrappedText = traceable(
  async (content: string) => {
    const { text } = await generateText({
      model: openai("gpt-5.4-nano"),
      messages: [{ role: "user", content }],
      tools: {
        listOrders: tool({
          description: "list all orders",
          parameters: z.object({ userId: z.string() }),
          execute: async ({ userId }) => {
            const getOrderNumber = traceable(
              async () => {
                return "1234";
              },
              { name: "getOrderNumber" }
            );
            const orderNumber = await getOrderNumber();
            return `User ${userId} has the following order: ${orderNumber}`;
          },
        }),
      },
      experimental_telemetry: {
        isEnabled: true,
      },
      maxSteps: 10,
    });
    return { text };
  },
  { name: "parentTraceable", client }
);

let result;
try {
  result = await wrappedText("What are my orders?");
} finally {
  await client.awaitPendingTraceBatches();
}

生成的追踪记录将显示 如下.

Next.js

首先，安装 @vercel/otel package:

npm install @vercel/otel
yarn add @vercel/otel
pnpm add @vercel/otel

然后，在您的根目录中设置一个 instrumentation.ts 文件。 调用 initializeOTEL 并将生成的 DEFAULT_LANGSMITH_SPAN_PROCESSOR 传递到 spanProcessors 字段到您的 registerOTEL(...) call. 它应该类似于这样：

const { DEFAULT_LANGSMITH_SPAN_PROCESSOR } = initializeOTEL({});

  registerOTel({
    serviceName: "your-project-name",
    spanProcessors: [DEFAULT_LANGSMITH_SPAN_PROCESSOR],
  });
}

最后，在您的 API 路由中调用 initializeOTEL 并添加一个 experimental_telemetry 字段到您的 AI SDK 调用中：

initializeOTEL();

  const { text } = await generateText({
    model: openai("gpt-5.4-nano"),
    messages: [{ role: "user", content: "Why is the sky blue?" }],
    experimental_telemetry: {
      isEnabled: true,
    },
  });

  return new Response(text);
}

您也可以将部分代码包装在 traceables 中以获得更细粒度的追踪。

Sentry

如果您使用的是 Sentry，可以按照以下示例将 LangSmith 跟踪导出器附加到 Sentry 的默认 OpenTelemetry 检测中。

const exporter = new LangSmithOTLPTraceExporter();
const spanProcessor = new BatchSpanProcessor(exporter);

const sentry = Sentry.init({
  dsn: "...",
  tracesSampleRate: 1.0,
  openTelemetrySpanProcessors: [spanProcessor],
});

initializeOTEL({
  globalTracerProvider: sentry?.traceProvider,
});

const wrappedText = traceable(
  async (content: string) => {
    const { text } = await generateText({
      model: openai("gpt-5.4-nano"),
      messages: [{ role: "user", content }],
      experimental_telemetry: {
        isEnabled: true,
      },
      maxSteps: 10,
    });
    return { text };
  },
  { name: "parentTraceable" }
);

let result;
try {
  result = await wrappedText("What color is the sky?");
} finally {
  await sentry?.traceProvider?.shutdown();
}

添加其他元数据

您可以向跟踪添加其他元数据，以帮助在 LangSmith UI 中组织和筛选它们：

await generateText({
  model: openai("gpt-5.4-nano"),
  prompt: "Write a vegetarian lasagna recipe for 4 people.",
  experimental_telemetry: {
    isEnabled: true,
    metadata: { userId: "123", language: "english" },
  },
});

元数据将在您的 LangSmith 仪表板中可见，可用于筛选和搜索特定跟踪。 请注意，AI SDK 也会在内部子跨度上传播元数据。

自定义运行名称

您可以通过传递名为 ls_run_name 的元数据键来自定义运行名称 experimental_telemetry.

await generateText({
  model: openai("gpt-5.4-mini"),
  prompt: "Write a vegetarian lasagna recipe for 4 people.",
  experimental_telemetry: {
    isEnabled: true,
    // highlight-start
    metadata: {
      ls_run_name: "my-custom-run-name",
    },
    // highlight-end
  },
});