Vercel AI SDK 설치 및 챗봇 빌드 방법 입문

Published on Jake

2026년 6월 기준, Vercel AI SDK의 최신 안정 버전은 4.x 계열이다. Next.js(넥스트JS, 리액트 기반의 풀스택 웹 프레임워크)와 함께 쓰면 백엔드 API 라우트와 프론트엔드 채팅 UI를 같은 프로젝트 안에서 처리할 수 있어 구조가 단순해진다. 이 글에서는 SDK(Software Development Kit, 개발에 필요한 도구 묶음) 설치부터 챗봇 배포까지 실제 코드 흐름을 따라간다.

Vercel AI SDK가 하는 일

Vercel AI SDK는 OpenAI, Anthropic, Google Gemini 등 여러 AI 제공사의 API(Application Programming Interface, 프로그램끼리 데이터를 주고받는 약속)를 하나의 인터페이스로 묶어주는 TypeScript(타입스크립트) 라이브러리다. 제공사를 바꿔도 코드 대부분을 그대로 쓸 수 있도록 추상화 계층을 둔다는 게 핵심이다.

내부적으로 스트리밍(streaming, 응답을 한 번에 받지 않고 생성되는 즉시 조각씩 받는 방식)을 기본으로 채택해 사용자가 첫 단어부터 실시간으로 볼 수 있다. 클라이언트 훅인 useChat이 상태 관리와 전송, 중단 처리를 자동으로 담당해서 직접 구현할 코드 분량이 크게 줄어든다.

AI 기능을 앱에 직접 붙이는 방법이 궁금하다면 앱에 AI 기능 추가하는 법도 함께 읽어볼 만하다.

npm 설치와 환경 변수 설정

Node.js 18 이상, npm 10 이상이 사전 요건이다. Node.js 20 LTS나 22 버전을 쓰면 가장 무난하다. Next.js 15 프로젝트를 먼저 만들고 SDK 패키지를 추가하는 순서로 진행한다.

# Next.js 프로젝트 생성 (App Router 선택 권장)
npx create-next-app@latest my-chatbot --typescript --app

# 프로젝트 디렉토리 이동
cd my-chatbot

# Vercel AI SDK 코어와 OpenAI 어댑터 설치
npm install ai @ai-sdk/openai

# 스키마 검증 라이브러리 (구조화 출력 필요 시)
npm install zod

설치 후에는 OpenAI API 키를 환경 변수 파일에 넣어야 한다. 프로젝트 루트에 .env.local 파일을 만들고 OPENAI_API_KEY=sk-... 형태로 저장한다. 이 파일은 .gitignore에 이미 포함돼 있어 실수로 외부에 노출될 위험이 낮다.

Anthropic이나 Google Gemini를 쓸 경우엔 @ai-sdk/anthropic 또는 @ai-sdk/google 패키지를 추가로 설치하면 된다. 코어 ai 패키지는 공통으로 유지된다.

Next.js 챗봇 기본 코드 구성

Next.js App Router 구조에서는 백엔드 로직을 app/api/chat/route.ts에, 프론트엔드 UI를 app/page.tsx에 배치한다. 아래는 동작하는 최소 구성이다.

백엔드 API 라우트 (app/api/chat/route.ts)

import { openai } from '@ai-sdk/openai';
import { streamText } from 'ai';

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

  const result = streamText({
    model: openai('gpt-4o-mini'),
    messages,
  });

  return result.toDataStreamResponse();
}

streamText는 AI 모델에 메시지를 보내고 스트리밍 응답을 돌려주는 함수다. toDataStreamResponse()는 그 스트림을 브라우저가 받을 수 있는 HTTP 응답으로 변환한다.

프론트엔드 채팅 컴포넌트 (app/page.tsx)

'use client';

import { useChat } from 'ai/react';

export default function ChatPage() {
  const { messages, input, handleInputChange, handleSubmit } = useChat();

  return (
    <main>
      <ul>
        {messages.map((m) => (
          <li key={m.id}>
            <b>{m.role === 'user' ? '나' : 'AI'}</b>: {m.content}
          </li>
        ))}
      </ul>
      <form onSubmit={handleSubmit}>
        <input value={input} onChange={handleInputChange} placeholder="메시지 입력" />
        <button type="submit">전송</button>
      </form>
    </main>
  );
}

useChat 훅이 메시지 목록, 입력값, 제출 핸들러를 한 번에 제공한다. 폼을 제출하면 /api/chat 엔드포인트로 자동 요청이 가고, 스트리밍 응답이 실시간으로 messages 배열에 반영된다. 별도로 fetch나 상태 관리 코드를 짤 필요가 없다.

HOW TO USE
Vercel AI SDK 챗봇 — 사용법
airusk.com
01
npm install ai @ai-sdk/openai
Next.js 프로젝트에 SDK 코어와 AI 제공사 어댑터를 설치한다. Node.js 18 이상 필수.
02
app/api/chat/route.ts 작성
streamText로 AI 모델에 요청을 보내고 스트리밍 응답을 반환하는 백엔드 라우트를 만든다.
03
useChat 훅으로 UI 연결
프론트엔드에서 useChat 훅 하나로 메시지 상태와 실시간 스트리밍 렌더링을 처리한다.

Vercel 배포 절차

로컬에서 npm run dev로 동작을 확인한 뒤 Vercel에 배포한다. Vercel CLI(Command Line Interface, 터미널에서 명령어로 조작하는 도구)를 쓰거나 GitHub 리포지토리를 Vercel 대시보드에 연결하는 두 가지 방법이 있다.

CLI로 배포하는 경우: npm install -g vercel로 CLI를 먼저 설치하고, 프로젝트 루트에서 vercel login으로 계정을 연결한다. 이후 vercel --prod를 실행하면 빌드와 배포가 자동으로 진행된다.

환경 변수 등록: Vercel 대시보드의 프로젝트 설정 → Environment Variables에서 OPENAI_API_KEY를 입력한다. 로컬의 .env.local에 있던 값을 그대로 넣으면 된다. 이 값은 서버 측에서만 쓰이며 브라우저에 노출되지 않는다.

배포 후 Vercel이 자동으로 HTTPS(암호화 연결)와 CDN(전 세계 서버에 분산해 빠르게 제공하는 네트워크)을 적용해 별도 설정 없이 전 세계에서 접근 가능한 챗봇이 완성된다.

실제 사용 시 주의할 점

스트리밍 응답을 DB에 저장하려면 onFinish 콜백을 써야 한다. 스트리밍 중간 조각을 저장하면 데이터가 깨지므로 반드시 응답이 완전히 끝난 뒤 저장한다.

API 키 비용 관리도 초기부터 신경 쓰는 게 좋다. maxTokens 옵션으로 응답 최대 길이를 제한하고, Vercel 대시보드에서 함수 실행 제한 시간을 확인해 두면 예상치 못한 과금을 막을 수 있다. 프리 플랜에서는 서버리스 함수(Serverless Function, 서버를 직접 운영하지 않고 요청이 올 때만 실행되는 함수) 실행 시간 제한이 있어 긴 AI 응답이 도중에 끊길 수 있다. Vercel Pro 이상 플랜에서는 이 제한이 완화된다.

STEP BY STEP
Vercel 배포까지 전체 흐름
airusk.com
1
Next.js 프로젝트 생성
create-next-app으로 App Router 프로젝트를 만들고 TypeScript를 활성화한다.
2
SDK 설치 및 API 키 설정
npm install ai @ai-sdk/openai 후 .env.local에 OPENAI_API_KEY를 입력한다.
3
API 라우트와 UI 작성
streamText로 백엔드를 만들고 useChat 훅으로 프론트엔드 채팅 화면을 연결한다.
vercel –prod 로 배포
Vercel 대시보드에서 환경 변수를 등록한 뒤 명령어 한 줄로 HTTPS 챗봇이 올라간다.

자주 묻는 질문

Q1) OpenAI 말고 다른 AI 모델도 쓸 수 있나?

가능하다. @ai-sdk/anthropic을 설치하면 Claude 모델을, @ai-sdk/google을 설치하면 Gemini 모델을 쓸 수 있다. streamText에 넘기는 model 인자만 바꾸면 되고 나머지 코드는 그대로다.

Q2) 무료로 배포가 가능한가?

Vercel 무료 플랜(Hobby)으로 배포 자체는 가능하다. 다만 서버리스 함수 실행 시간이 10초로 제한돼 AI 응답이 길어지면 중간에 끊길 수 있다. AI 응답 시간이 10초를 넘을 것 같으면 Pro 플랜($20/월)으로 올리거나 최대 토큰 수를 줄이는 방식으로 대응한다.

Q3) 대화 기록은 어떻게 저장하나?

useChat의 onFinish 콜백에서 완료된 메시지를 받아 데이터베이스에 저장한다. Vercel KV(Redis 기반의 키-값 저장소)나 Supabase, PlanetScale 같은 서비스와 함께 쓰면 대화 이력을 영구 보존할 수 있다. 스트리밍 중간 조각을 저장하면 데이터가 깨지므로 반드시 onFinish를 활용해야 한다.

Q4) 한국어 응답 품질이 괜찮은가?

GPT-4o-mini 기준으로 한국어 응답 품질은 실용적인 수준이다. 시스템 프롬프트(AI에게 역할과 말투를 지시하는 첫 메시지)에 “한국어로 답변하라”를 명시하면 일관성이 높아진다. 더 정확한 한국어가 필요하다면 Claude 3.5 Sonnet 모델이 비교적 자연스럽다는 평가가 많다.

댓글 남기기