Vercel AI SDK를 활용한 LLM 통합

대규모 언어 모델 (LLMs)은 프롬프트 (prompts)로부터 텍스트를 이해하고 생성합니다. Vercel AI SDK는 LLM API 위에 구축된 프로바이더 불가지론적 (provider-agnostic) 레이어이며, 핵심 기능은 generateText, streamText, 그리고 embed입니다. 이 포스트는 OpenAI 프로바이더를 사용하며 OpenAI Responses API 포스트의 패턴을 반영합니다.

더 낮은 수준의 openai npm 패키지에 대해서는 Chat Completions API 및 Responses API 포스트를 참조하세요.

사전 요구 사항 (Prerequisites)

• OpenAI 계정
• 생성된 API 키
• 결제 활성화
• Node.js 버전 26
• ai, @ai-sdk/openai, 그리고 zod 설치 (npm i ai @ai-sdk/openai zod)
• Markdown 출력을 위한 경우: marked, dompurify, 그리고 jsdom (npm i marked dompurify jsdom)

클라이언트 설정 (Client setup)

API 키를 사용하여 OpenAI 프로바이더를 생성합니다 (프로덕션 환경에서는 환경 변수에서 읽어옵니다).

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

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });

동일한 프로바이더를 사용하여 baseURL과 apiKey를 설정함으로써 호환 가능한 API를 구현하는 다른 호스트를 대상으로 지정할 수 있습니다:

const openai = createOpenAI({
  apiKey: process.env.LLM_API_KEY,
  baseURL: 'https://your-gateway.example/v1',
...

많은 서드파티 게이트웨이(third-party gateways)는 Chat Completions만을 지원합니다. 아래 예제들은 openai(model) (Responses API 경로)를 사용합니다. 만약 사용 중인 프로바이더가 이를 지원하지 않는다면, openai.chat(model)로 전환하고 웹 검색 예제를 건너뛰십시오.

기본 통합 (Basic integration)

prompt로 문자열을 전달하고 결과에서 text를 읽어옵니다.

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

...

시스템 프롬프트 (System prompt)

안정적인 동작 (어조, 형식, 역할)을 위해 system 파라미터를 사용하십시오. 이는 사용자 메시지의 일상적인 문구보다 우선순위를 가집니다.

const { text } = await generateText({
  model: openai('gpt-5.5'),
  system: '한 문장의 짧은 문장으로 답변하세요. 쉬운 언어를 사용하세요.',
...

퓨샷 프롬프팅 (Few-shot prompting)

user 및 assistant 역할을 가진 이전 대화 내용들을 messages 배열로 전달한 뒤, 새로운 사용자 메시지를 전달하십시오. 작업 규칙은 system에 유지하십시오.

const { text } = await generateText({
  model: openai('gpt-5.5'),
  system:
...

스트리밍 (Streaming)

점진적인 텍스트 출력을 위해 streamText를 사용하고 textStream을 반복(iterate)하십시오.

import { streamText } from 'ai';

const result = streamText({
...

JSON 스키마를 활용한 구조화된 출력 (Structured output with JSON schema)

Output.object()와 Zod 스키마를 통해 모델이 귀하의 스키마와 일치하는 JSON을 생성하도록 제한하십시오. SDK가 결과를 검증합니다.

import { generateText, Output } from 'ai';
import { z } from 'zod';

...

마크다운 출력을 HTML로 변환 (Markdown output to HTML)

system에서 마크다운 형식을 요청한 다음, 렌더링하기 전에 text를 HTML로 변환하고 살균(sanitize)하십시오 (예를 들어 브라우저의 innerHTML을 사용하거나 HTML을 저장할 때).

import { marked } from 'marked';
import { JSDOM } from 'jsdom';
import DOMPurify from 'dompurify';
...

모델이 생성한 HTML에는 항상 DOMPurify.sanitize를 실행하십시오. 모델은 안전하지 않은 마크업을 내보낼 수 있습니다. 살균(Sanitization) 과정은 스크립트 및 기타 위험한 콘텐츠를 제거합니다.

웹 검색 도구 (Web search tool)

답변에 웹의 최신 정보가 사용되어야 하는 경우 내장된 웹 검색 도구를 활성화하십시오.

const result = await generateText({
  model: openai('gpt-5.5'),
  tools: { web_search: openai.tools.webSearch() },
...

웹 검색은 지연 시간(latency)과 도구 사용 비용을 추가합니다. 도구를 지원하는 모델을 사용하십시오.

임베딩 (Embeddings)

임베딩 (Embeddings)은 텍스트의 의미론적 의미를 나타내는 숫자 벡터입니다. 의미론적 검색 (semantic search), 클러스터링 (clustering), 그리고 RAG에 사용하십시오.

embed에 단일 문자열을 전달하고 embedding에서 벡터를 읽으십시오.

import { embed } from 'ai';

const { embedding } = await embed({
...

embedMany를 사용하여 values 배열에 여러 문자열을 전달하십시오. 결과는 입력과 동일한 순서로 제공됩니다.

import { embedMany } from 'ai';

const chunks = [
...

pgvector를 사용한 전체 RAG (Retrieval-Augmented Generation) 흐름에 대해서는 RAG with OpenAI embeddings post를 참조하십시오.

데모 (Demo)

각 섹션에 대한 실행 가능한 스크립트는 vercel-ai-sdk-demo 폴더에 있습니다. 코드 데모를 통해 확인하실 수 있습니다.