Vercel AI SDK는 AI 애플리케이션 구축을 위한 TypeScript 툴킷입니다. 텍스트 생성, 스트리밍, 구조화된 출력, 도구 호출 및 다단계 에이전트 루프를 단일 통합 API로 처리하며, 주요 LLM 제공업체와 모두 호환됩니다. OpenAI나 Anthropic을 Next.js 앱에 직접 연결하려다가 세 가지 다른 스트리밍 구현을 유지해야 했던 경험이 있다면, 이 SDK가 그 문제를 해결해 줍니다.
이 가이드에서는 SDK의 핵심 기능, Novita AI의 OpenAI 호환 LLM API에 연결하는 방법, 그리고 단순한 챗봇 이상을 구축하는 개발자를 위한 에이전트 워크플로우의 활용 위치를 다룹니다.
Vercel AI SDK란 무엇인가요?
Vercel AI SDK(npm 패키지: ai)는 LLM 제공업체 간의 차이점을 추상화하는 오픈소스 라이브러리입니다. OpenAI, Anthropic, Google 각각의 스트리밍 프로토콜을 따로 배울 필요 없이 동일한 generateText, streamText, generateObject 함수를 호출하고 단일 임포트를 변경하여 제공업체를 전환할 수 있습니다.
SDK는 두 가지 계층으로 제공됩니다:
- AI SDK Core 는 모델 상호작용을 처리합니다: 텍스트 생성, 스트리밍, 구조화된 객체, 도구 호출, 임베딩 및 에이전트 루프.
- AI SDK UI 는 React 훅(
useChat,useCompletion,useObject,useAssistant)과 Next.js, SvelteKit, Nuxt용 어댑터를 제공하여 브라우저에서 스트리밍 상태를 관리합니다.
또한 OpenAI Chat Completions 형식을 구현하는 모든 제공업체에 연결할 수 있는 @ai-sdk/openai-compatible 패키지도 있습니다. 이것이 Novita AI가 통합되는 방식입니다.
SDK는 Node.js, Deno, 엣지 런타임(Cloudflare Workers, Vercel Edge) 및 브라우저 환경에서 작동합니다.
AI SDK Core: generateText, streamText 및 generateObject
SDK와 제공업체 패키지를 설치합니다:
npm install ai @ai-sdk/openai
generateText
비스트리밍 완성(일괄 처리, 분류, 일회성 생성)의 경우:
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';
const { text } = await generateText({
model: openai('gpt-4o-mini'),
prompt: 'LLM 임베딩이 어떻게 작동하는지 두 문장으로 설명해 주세요.',
});
console.log(text);
streamText
지연 시간이 중요한 채팅 인터페이스의 경우:
import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';
const result = streamText({
model: openai('gpt-4o-mini'),
messages: [
{ role: 'user', content: 'Next.js 앱 설정 과정을 안내해 주세요.' },
],
});
for await (const chunk of result.textStream) {
process.stdout.write(chunk);
}
generateObject
원시 텍스트 대신 구조화된 JSON 출력이 필요할 때 — 스키마 검증은 Zod를 사용하여 자동으로 처리됩니다:
import { generateObject } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';
const { object } = await generateObject({
model: openai('gpt-4o-mini'),
schema: z.object({
name: z.string(),
skills: z.array(z.string()),
experienceLevel: z.enum(['junior', 'mid', 'senior']),
}),
prompt: '가상의 소프트웨어 엔지니어 프로필을 생성해 주세요.',
});
console.log(object.name, object.skills);
SDK는 모델이 유효한 JSON을 출력하도록 유도하는 시스템 프롬프트 주입을 처리하고 잘못된 출력 발생 시 재시도합니다.
AI SDK Tools: 함수 호출 및 도구 사용
도구를 사용하면 모델이 생성 중에 외부 함수(검색 API, 데이터베이스 쿼리, 계산기)를 호출할 수 있습니다. SDK의 tools 매개변수는 각 키가 호출 가능한 함수가 되는 객체를 받습니다:
import { generateText, tool } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';
const { text, toolCalls } = await generateText({
model: openai('gpt-4o-mini'),
tools: {
getWeather: tool({
description: '특정 위치의 현재 날씨를 가져옵니다',
parameters: z.object({
city: z.string().describe('도시 이름'),
unit: z.enum(['celsius', 'fahrenheit']).default('celsius'),
}),
execute: async ({ city, unit }) => {
// 실제 날씨 API 호출로 대체하세요
return { city, temperature: 22, unit, condition: 'sunny' };
},
}),
},
prompt: '지금 도쿄의 날씨는 어떤가요?',
});
console.log(text);
tool() 헬퍼는 Zod 스키마에서 execute 함수 매개변수로의 타입 추론을 제공합니다. 수동 JSON 파싱이 필요 없습니다.
다단계 도구 호출
기본적으로 generateText는 한 라운드의 도구 호출 후 중지됩니다. maxSteps를 설정하면 모델이 후속 추론에서 도구 결과를 사용할 수 있습니다:
const { text } = await generateText({
model: openai('gpt-4o'),
maxSteps: 5,
tools: { getWeather, searchWeb, lookupCalendar },
prompt: '이번 주말 베를린에서 야외 활동을 계획해 주세요.',
});
SDK는 도구 호출 → 결과 → 연속 루프를 자동으로 처리합니다. 각 단계는 중간 추론을 확인해야 하는 경우 onStepFinish를 통해 노출됩니다.
Vercel AI SDK로 AI 에이전트 루프 구축하기
AI SDK의 에이전트는 충분한 정보가 있다고 판단할 때까지 도구와 함께 루프로 실행되는 모델입니다. 패턴은 다단계 도구 호출과 동일하지만 더 많은 도구와 더 긴 maxSteps를 사용합니다:
import { generateText, tool } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';
const result = await generateText({
model: openai('gpt-4o'),
maxSteps: 10,
system: '당신은 연구 보조원입니다. 사용 가능한 도구를 사용하여 철저히 답변하세요.',
prompt: 'Llama 3.1과 Qwen3의 주요 차이점은 무엇인가요?',
tools: {
search: tool({
description: '웹에서 최신 정보를 검색합니다',
parameters: z.object({ query: z.string() }),
execute: async ({ query }) => searchWeb(query),
}),
summarize: tool({
description: 'URL을 요약합니다',
parameters: z.object({ url: z.string() }),
execute: async ({ url }) => fetchAndSummarize(url),
}),
},
onStepFinish({ stepType, toolCalls, toolResults }) {
console.log('Step:', stepType, toolCalls?.map(t => t.toolName));
},
});
프로덕션 에이전트 파이프라인의 경우 Novita AI를 모델 백엔드로 연결하여 비용과 처리량을 대규모로 제어할 수 있습니다. 이 내용은 다음 섹션에서 다룹니다.
AI SDK React: useChat Hook 및 Next.js 통합
useChat 훅은 보일러플레이트 없이 스트리밍 채팅 상태를 관리합니다:
// app/chat/page.tsx
'use client';
import { useChat } from 'ai/react';
export default function Chat() {
const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({
api: '/api/chat',
});
return (
<div>
{messages.map(m => (
<div key={m.id} className={m.role === 'user' ? 'user' : 'assistant'}>
{m.content}
</div>
))}
<form onSubmit={handleSubmit}>
<input
value={input}
onChange={handleInputChange}
placeholder="질문을 입력하세요..."
disabled={isLoading}
/>
<button type="submit" disabled={isLoading}>전송</button>
</form>
</div>
);
}
해당 라우트 핸들러:
// app/api/chat/route.ts
import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';
export async function POST(req: Request) {
const { messages } = await req.json();
const result = streamText({
model: openai('gpt-4o-mini'),
messages,
});
return result.toDataStreamResponse();
}
toDataStreamResponse()는 Vercel AI 스트림 프로토콜을 처리하며, 클라이언트의 useChat이 이를 기본적으로 이해합니다. API에서 구조화된 객체를 스트리밍하려면 useChat 대신 useObject를, streamText 대신 streamObject를 사용하세요.
Novita AI를 Vercel AI SDK와 함께 사용하는 방법
Novita AI는 https://api.novita.ai/v3/openai에서 OpenAI 호환 API를 제공하므로, OpenAI Chat Completions 형식을 사용하는 모든 SDK( Vercel AI SDK 포함)에 드롭인 대체제로 사용할 수 있습니다.
AI SDK와 함께 Novita AI를 사용하는 이유
Novita AI는 단일 API 엔드포인트를 통해 70개 이상의 오픈소스 모델(Llama 3.3 70B, Qwen3, DeepSeek V3, Mistral, Gemma 3)을 호스팅합니다. GPU 인프라를 관리할 필요가 없습니다. 에이전트 워크플로우의 경우 서버리스 API는 구성 변경 없이 소형 7B 명령 모델에서 대형 추론 모델까지 확장됩니다.
설정
OpenAI 호환 제공업체 패키지를 설치합니다:
npm install ai @ai-sdk/openai-compatible
제공업체를 구성합니다:
import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
const novita = createOpenAICompatible({
name: 'novita',
baseURL: 'https://api.novita.ai/v3/openai',
apiKey: process.env.NOVITA_API_KEY,
});
이것이 전체 설정입니다. 이제 다른 AI SDK 제공업체와 동일하게 사용하세요:
import { generateText } from 'ai';
const { text } = await generateText({
model: novita('meta-llama/llama-3.3-70b-instruct'),
prompt: '고객 지원 봇을 위한 RAG와 파인튜닝 간의 트레이드오프는 무엇인가요?',
});
스트리밍도 동일한 방식으로 작동합니다:
import { streamText } from 'ai';
const result = streamText({
model: novita('qwen/qwen3-235b-a22b-instruct-2507'),
messages: [
{ role: 'system', content: '당신은 유용한 코딩 도우미입니다.' },
{ role: 'user', content: 'FastAPI로 REST API를 구축하는 방법을 보여주세요.' },
],
});
for await (const chunk of result.textStream) {
process.stdout.write(chunk);
}
Novita AI로 도구 호출하기
함수 호출을 지원하는 모델은 추가 구성 없이 AI SDK의 tool() 인터페이스와 함께 작동합니다. Llama 3.3 70B Instruct와 Qwen3는 Novita의 API를 통해 도구 호출을 지원합니다:
import { generateText, tool } from 'ai';
import { z } from 'zod';
const { text } = await generateText({
model: novita('meta-llama/llama-3.3-70b-instruct'),
maxSteps: 5,
tools: {
calculator: tool({
description: '수학 표현식을 계산합니다',
parameters: z.object({ expression: z.string() }),
execute: async ({ expression }) => {
return { result: eval(expression) }; // 프로덕션에서는 안전한 수학 파서를 사용하세요
},
}),
},
prompt: '847의 12%를 구한 다음 3.14로 나누면 얼마인가요?',
});
환경 설정
.env.local에 Novita API 키를 추가하세요:
NOVITA_API_KEY=your_novita_api_key_here
novita.ai에서 키를 받을 수 있습니다 — 신규 계정에는 API를 테스트할 수 있는 무료 크레딧이 포함됩니다.
장기 실행 워크로드를 위한 에이전트 샌드박스
코드를 실행하거나, 파일 시스템에 접근하거나, 다단계 워크플로우를 실행하는 에이전트 작업의 경우 Novita AI의 Agent Sandbox는 LLM API 위에 격리된 실행 환경을 제공합니다. AI SDK는 모델 추론 레이어를 처리하고, 샌드박스는 엣지 함수 타임아웃 내에서 실행할 수 없는 상태 저장 실행을 처리합니다.
Vercel AI SDK용 LLM 제공업체 선택하기
AI SDK는 제공업체 전환을 쉽게 만들어 주는데, 이는 유용하지만 프로덕션용으로 선택하기 전에 트레이드오프를 이해하는 것이 좋습니다.
지연 시간: 스트리밍 채팅의 경우 첫 번째 토큰까지의 시간이 전체 생성 속도보다 중요합니다. 소형 모델(8B–14B)이 첫 번째 토큰을 더 빨리 생성합니다. Novita AI의 서버리스 엔드포인트는 오픈 모델에서 낮은 콜드 스타트 지연 시간에 최적화되어 있습니다.
대규모 비용: GPT-4o는 훌륭하지만, 높은 쿼리 볼륨에서는 프론티어 모델과 잘 튜닝된 오픈 모델(예: Llama 3.3 70B) 간의 가격 차이가 상당해집니다. AI SDK를 사용하면 애플리케이션 로직을 다시 작성하지 않고도 두 가지를 모두 실험해 볼 수 있습니다.
도구 호출 지원: 모든 모델이 함수 호출을 안정적으로 지원하는 것은 아닙니다. 특정 모델을 도구 스키마와 함께 테스트하세요 — 동일한 모델 제품군이라도 제공업체에 따라 동작이 다릅니다.
컨텍스트 윈도우: 문서 중심 RAG나 긴 대화 기록의 경우 컨텍스트 제한을 확인하세요. 많은 오픈 모델이 128K 토큰을 지원하므로 대부분의 실제 사용 사례를 충당할 수 있습니다.
벤더 종속: Novita AI의 OpenAI 호환 엔드포인트와 함께 AI SDK의 제공업체 추상화를 사용하면 애플리케이션 코드를 수정하지 않고도 모델을 전환하거나 대체 제공업체를 추가할 수 있습니다.
결론
Vercel AI SDK는 AI 애플리케이션 구축의 보일러플레이트를 제거합니다 — 모든 LLM 제공업체에 걸쳐 텍스트 생성, 스트리밍, 도구 호출 및 에이전트 루프를 위한 하나의 API로 제공됩니다. useChat로 스트리밍 채팅 인터페이스를 구축하든, generateObject로 구조화된 데이터를 추출하든, 외부 도구를 호출하는 다단계 에이전트를 실행하든, SDK가 기본 작업을 처리하므로 애플리케이션 로직에 집중할 수 있습니다.
오픈 모델 추론의 경우 Novita AI의 OpenAI 호환 API가 @ai-sdk/openai-compatible을 통해 SDK에 직접 연결됩니다. GPU 인프라를 관리하지 않고도 Llama, Qwen3, DeepSeek, Mistral 등 70개 이상의 모델에 접근할 수 있으며, 애플리케이션 코드를 수정하지 않고도 모델을 전환하거나 대체 제공업체를 추가할 수 있습니다.
novita.ai에서 시작하세요 — 신규 계정에는 무료 크레딧이 포함됩니다.
FAQ
AI SDK React란 무엇인가요?
AI SDK의 React 통합은 ai/react 패키지에 있습니다. useChat, useCompletion, useObject, useAssistant와 같은 훅을 제공하여 React 프론트엔드를 서버 측 스트리밍 라우트에 연결합니다. 이 훅들은 스트리밍 상태, 메시지 기록, 로딩 표시기 및 오류 처리를 관리하므로 컴포넌트 상태에서 ReadableStream을 직접 관리할 필요가 없습니다.
AI SDK 5는 무엇을 추가하나요?
AI SDK 5(2025년 중반 베타 출시)는 더 나은 타입 안전성을 위해 제공업체 사양을 재설계하고, UI 상태 관리를 모델 상호작용 로직과 분리했으며, 에이전틱 UI 상태를 직렬화하기 더 쉽게 만드는 개선된 메시지 형식을 도입했습니다. 2026년에 새 프로젝트를 시작한다면 최신 안정 버전을 확인하려면 ai-sdk.dev를 방문하세요 — SDK는 버전 6과 7을 통해 계속 발전해 왔습니다.
참고할 수 있는 AI SDK 문서가 있나요?
공식 문서는 ai-sdk.dev에 있습니다. 제공업체 설정 가이드, 모든 핵심 함수의 API 참조, 프레임워크 통합 워크스루(Next.js, Nuxt, SvelteKit), 그리고 RAG, 에이전트 루프, 구조화된 추출과 같은 일반적인 패턴에 대한 레시피 예제가 포함되어 있습니다.
AI SDK 도구를 비 OpenAI 모델과 함께 사용할 수 있나요?
네. 함수 호출을 지원하는 모든 제공업체는 AI SDK의 tool() 인터페이스와 함께 작동합니다. Novita AI는 함수 호출을 지원하는 여러 오픈 모델을 호스팅합니다. 동작 품질은 다양합니다 — Novita의 API를 통해 사용 가능한 오픈 모델 중 다단계 도구 사용에 가장 안정적인 것은 Llama 3.3 70B와 Qwen3입니다.
Vercel AI SDK 문서와 ai-sdk.dev 문서의 차이점은 무엇인가요?
동일한 제품입니다. 문서는 이전에 sdk.vercel.ai에 있었으며 ai-sdk.dev로 리디렉션됩니다. SDK는 Vercel 팀이 유지 관리하지만 오픈소스이며 Vercel 인프라에 배포하는 것과는 관련이 없습니다.
인공지능 SDK는 LLM API를 직접 호출하는 것과 어떻게 비교되나요?
직접 API 호출은 단순한 일회성 요청에 적합합니다. SDK는 UI 프레임워크에 통합된 스트리밍, 다단계 도구 호출 루프, 구조화된 출력 검증, 통합된 제공업체 전환, 일관된 재시도/오류 처리를 동시에 필요로 할 때 가치가 있습니다. AI SDK는 이 모든 것을 라이브러리 수준에서 처리하므로 프로젝트마다 다시 구축할 필요가 없습니다.
