Vercel AI SDK - CoreWeave Docs

OpenTelemetry (OTel)를 사용하면 Weave에서 Vercel AI SDK Call을 트레이스할 수 있습니다. Vercel AI SDK는 AI 기반 애플리케이션을 구축하기 위한 TypeScript 툴킷으로, Next.js, Nuxt, SvelteKit 등의 프레임워크를 지원합니다. 또한 experimental_telemetry 옵션을 통해 OpenTelemetry를 기본 지원합니다. 이 가이드에서는 Vercel AI SDK의 트레이스를 Weave로 전송하도록 OTel을 설정하고, Weights & Biases UI에서 AI SDK Call을 관찰하고 디버깅하는 방법을 설명합니다. AI SDK는 Next.js와 함께 사용하거나 독립 실행형 Node.js 애플리케이션에서 사용할 수 있습니다. 이 가이드는 Vercel AI SDK로 AI 기반 애플리케이션을 구축하고 있으며, 기존 앱에 트레이싱을 추가하려는 개발자를 대상으로 합니다. Weave의 OTel 트레이싱에 대한 자세한 내용은 Weave로 OTel 트레이스 전송하기를 참조하세요.

사전 요구 사항

시작하기 전에 다음 설정을 완료하세요. 이 가이드의 Next.js 예시와 Node.js 예시에는 모두 동일한 의존성이 필요합니다.

다음 Vercel 및 OTel 라이브러리를 설치하세요.

npm install ai @ai-sdk/openai @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-proto @opentelemetry/resources zod

다음 환경 변수를 설정하세요.
export WANDB_API_KEY="your-wandb-api-key" export OPENAI_API_KEY="your-openai-api-key"
W&B API 키는 User Settings에서 확인할 수 있습니다.

Next.js용 OTel 트레이싱 설정하기

이 섹션에서는 Next.js 앱에서 Weave를 설정하는 방법을 설명합니다. 이 예시는 전체 앱이 아니라 계측 설정과 Vercel AI SDK 함수(여기서는 OpenAI 호출)에 계측을 적용하는 방법만 다룹니다.

계측 설정

Next.js 애플리케이션은 instrumentation.ts 파일로 OTel을 설정합니다. 이 파일은 서버가 시작될 때 한 번 실행되며, AI SDK가 사용하는 트레이서 프로바이더를 설정합니다. Weave를 Vercel의 OTel 기능과 통합하려면 프로젝트 루트에 instrumentation.ts 파일을 만들고 다음 코드를 추가하세요. 이때 resourceFromAttributes() 함수의 팀 이름과 프로젝트 이름을 사용자의 값으로 바꾸세요.

instrumentation.ts

// @noErrors
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
import { resourceFromAttributes } from "@opentelemetry/resources";

export function register() {
  const WANDB_API_KEY = process.env.WANDB_API_KEY!;

// W&B Weave 엔드포인트를 사용하도록 OTel 익스포터를 설정합니다.
  const exporter = new OTLPTraceExporter({
    url: "https://trace.wandb.ai/otel/v1/traces",
    headers: { "wandb-api-key": WANDB_API_KEY },
  });

// W&B 자격 증명을 설정합니다.
  const provider = new NodeTracerProvider({
    resource: resourceFromAttributes({
      "wandb.entity": "[YOUR-TEAM-NAME]",
      "wandb.project": "[YOUR-PROJECT-NAME]",
    }),
    spanProcessors: [new BatchSpanProcessor(exporter)],
  });

  provider.register();
}

이렇게 하면 W&B API 키로 인증하여 Weave의 OTel 엔드포인트로 트레이스 데이터를 전송하도록 설정된 OTLP 익스포터가 생성됩니다.

함수에 telemetry 설정하기

계측을 추가한 후 AI SDK 함수를 호출할 때 Vercel의 experimental_telemetry 옵션을 사용하면 OTel span을 내보낼 수 있습니다.

route.ts

// @noErrors
import { openai } from "@ai-sdk/openai";
import { generateText } from "ai";

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

// 함수 호출에 experimental_telemetry 필드를 추가합니다.
  const result = await generateText({
    model: openai("gpt-4o-mini"),
    prompt,
    experimental_telemetry: { isEnabled: true },
  });

  return Response.json({ text: result.text });
}

telemetry가 활성화된 모든 generateText Call은 OTel span을 생성하며, 이 span은 Weave로 내보내집니다. 이제 Next.js 앱에서 Vercel AI SDK 트레이스를 Weave로 보내도록 설정되었습니다.

Node.js용 OTel 트레이싱 설정

Next.js를 사용하지 않는다면 독립 실행형 Node.js 애플리케이션에서 OTel을 직접 설정할 수 있습니다. 독립 실행형 Node.js 애플리케이션에서는 이후의 AI SDK Call이 캡처되도록 엔트리 파일 상단, 즉 AI SDK Call보다 먼저 트레이서 프로바이더를 설정하세요. 사전 요구 사항을 충족하면 추가 설정 없이 다음 예시를 실행해 span을 생성할 수 있습니다.

test-app.ts

// @noErrors
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
import { resourceFromAttributes } from "@opentelemetry/resources";
import { openai } from "@ai-sdk/openai";
import { generateText } from "ai";

const WANDB_API_KEY = process.env.WANDB_API_KEY!;

// W&B Weave 엔드포인트를 사용하도록 OTel 익스포터를 설정합니다.
const exporter = new OTLPTraceExporter({
  url: "https://trace.wandb.ai/otel/v1/traces",
  headers: { "wandb-api-key": WANDB_API_KEY },
});

// W&B 자격 증명을 설정합니다.
const provider = new NodeTracerProvider({
  resource: resourceFromAttributes({
    "wandb.entity": "[YOUR-TEAM-NAME]",
    "wandb.project": "[YOUR-PROJECT-NAME]",
  }),
  spanProcessors: [new BatchSpanProcessor(exporter)],
});

provider.register();

// 함수에 experimental_telemetry 필드를 추가합니다.
async function main() {
  const result = await generateText({
    model: openai("gpt-4o-mini"),
    prompt: "Explain OpenTelemetry in one sentence.",
    experimental_telemetry: { isEnabled: true },
  });

  console.log(result.text);

  await provider.shutdown();
}

main();

BatchSpanProcessor는 span을 비동기적으로 플러시합니다. 독립 실행형 스크립트, 서버리스 함수, CLI 도구처럼 수명이 짧은 프로세스에서는 모든 span이 Weave로 전송되도록 프로세스가 종료되기 전에 provider.shutdown()을 호출하세요. 장시간 실행되는 서버(예: instrumentation.ts를 통해 시작한 Next.js 개발 서버)에서는 이 작업이 필요하지 않습니다.

​사전 요구 사항

​Next.js용 OTel 트레이싱 설정하기

​계측 설정

​함수에 telemetry 설정하기

​Node.js용 OTel 트레이싱 설정

사전 요구 사항

Next.js용 OTel 트레이싱 설정하기

계측 설정

함수에 telemetry 설정하기

Node.js용 OTel 트레이싱 설정