> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Vercel AI SDK

> OpenTelemetry를 사용하여 Weave에서 Vercel AI SDK Call 트레이스하기

[OpenTelemetry (OTel)](https://opentelemetry.io/)를 사용하면 Weave에서 [Vercel AI SDK](https://ai-sdk.dev/) 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 트레이스 전송하기](/ko/products/wandb/weave/guides/tracking/otel)를 참조하세요.

<h2 id="prerequisites">
  사전 요구 사항
</h2>

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

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

   ```bash theme={"system"}
   npm install ai @ai-sdk/openai @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-proto @opentelemetry/resources zod
   ```

2. 다음 환경 변수를 설정하세요.

   ```bash theme={"system"}
   export WANDB_API_KEY="your-wandb-api-key"
   export OPENAI_API_KEY="your-openai-api-key"
   ```

   W\&B API 키는 [User Settings](https://forge.coreweave.com/settings)에서 확인할 수 있습니다.

<h2 id="configure-otel-tracing-for-nextjs">
  Next.js용 OTel 트레이싱 설정하기
</h2>

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

<h3 id="configure-instrumentation">
  계측 설정
</h3>

Next.js 애플리케이션은 `instrumentation.ts` 파일로 OTel을 설정합니다. 이 파일은 서버가 시작될 때 한 번 실행되며, AI SDK가 사용하는 트레이서 프로바이더를 설정합니다.

Weave를 Vercel의 OTel 기능과 통합하려면 프로젝트 루트에 `instrumentation.ts` 파일을 만들고 다음 코드를 추가하세요. 이때 `resourceFromAttributes()` 함수의 팀 이름과 프로젝트 이름을 사용자의 값으로 바꾸세요.

```typescript lines {17-19} title="instrumentation.ts" theme={"system"}
// @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 익스포터가 생성됩니다.

<h3 id="configure-telemetry-on-a-function">
  함수에 telemetry 설정하기
</h3>

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

```typescript lines {10} title="route.ts" theme={"system"}
// @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로 보내도록 설정되었습니다.

<h2 id="configure-otel-tracing-for-nodejs">
  Node.js용 OTel 트레이싱 설정
</h2>

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

사전 요구 사항을 충족하면 추가 설정 없이 다음 예시를 실행해 span을 생성할 수 있습니다.

```typescript lines {11-14,18-19,31} title="test-app.ts" theme={"system"}
// @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 개발 서버)에서는 이 작업이 필요하지 않습니다.