Vercel AI SDK v6 기반 로컬 LLM용 채팅 인터페이스 템플릿

실용적 조언

로컬 LLM 연동 시 .env 파일의 AI_BASE_URL을 http://localhost:11434/v1로 설정하여 Ollama를 즉시 활용하라.
새로운 기능을 추가하려면 제공된 Zod 스키마 패턴을 복사하여 로컬 파일 검색이나 API 호출 함수를 작성하라.

섹션별 상세

Vercel AI SDK v6를 기반으로 구축된 이 템플릿은 OpenAI 호환 API를 지원하며 특히 Ollama와의 연동이 매우 간편하다. .env 파일에서 AI_BASE_URL을 로컬 호스트 주소로 설정하는 것만으로 즉시 연결이 가능하여 로컬 환경 구축 비용을 최소화했다.

bash

AI_BASE_URL=http://localhost:11434/v1

Ollama와 같은 로컬 LLM 프로바이더를 연동하기 위한 환경 변수 설정 예시

사용자 인터페이스는 실시간 스트리밍, 모델 스위칭, 그리고 모델의 추론 과정을 보여주는 기능을 포함한다. 추론 토큰을 지원하는 모델의 경우 모델이 답변을 내놓기까지의 사고 과정을 시각적으로 확인할 수 있어 투명한 상호작용이 가능하다.

도구 실행 시스템은 Zod 스키마와 함수가 결합된 단일 파일 구조로 설계되어 확장이 용이하다. 기본적으로 날씨와 시간 도구가 포함되어 있으며 로컬 파일 검색이나 데이터베이스 쿼리 등 사용자가 원하는 기능을 에이전트에 쉽게 추가할 수 있는 패턴을 제시한다.

typescript

export const weatherTool = {
  description: 'Get the weather in a location',
  parameters: z.object({
    location: z.string().describe('The city and state, e.g. San Francisco, CA'),
  }),
  execute: async ({ location }: { location: string }) => {
    // ...(중략)
    return { location, temperature: '72°F' };
  },
};

Zod 스키마를 사용하여 에이전트가 사용할 도구를 정의하는 구조

UI는 도구 호출 과정을 실시간으로 표시하여 모델이 어떤 도구를 어떤 인자와 함께 호출했는지 보여준다. 도구의 실행 결과와 그에 따른 모델의 최종 응답이 순차적으로 노출되어 복잡한 에이전트 작업의 흐름을 직관적으로 파악할 수 있다.

용어 해설

버셀 AI SDK(Vercel AI SDK): — Vercel에서 개발한 오픈소스 라이브러리로 React, Next.js 등 웹 프레임워크에서 AI 기반 사용자 인터페이스를 구축할 때 사용한다. 스트리밍 응답 처리, 도구 호출, 상태 관리 기능을 추상화하여 개발자가 복잡한 로직 없이도 LLM 연동 기능을 구현하도록 돕는다.
조드(Zod): — TypeScript 우선의 스키마 선언 및 데이터 검증 라이브러리이다. 이 프로젝트에서는 LLM이 호출할 도구(Tool)의 입력 파라미터 형식을 정의하고 검증하는 데 사용되며, 모델이 정확한 인자를 전달하도록 보장하는 역할을 수행한다.
추론 토큰(Reasoning Tokens): — 모델이 최종 답변을 생성하기 전에 내부적으로 논리적 사고 과정을 거치며 생성하는 특수 토큰이다. DeepSeek-R1이나 OpenAI o1과 같은 모델에서 지원하며, 사용자에게 모델이 어떤 단계를 거쳐 결론에 도달했는지 시각적으로 보여주는 데 활용된다.
OpenAI 호환 API(OpenAI Compatible API): — OpenAI의 API 규격과 동일한 엔드포인트 및 데이터 형식을 제공하는 인터페이스이다. Ollama, vLLM 등 많은 로컬 추론 엔진이 이 규격을 따르므로, 기존 OpenAI용으로 작성된 코드를 최소한의 수정만으로 로컬 모델에 적용할 수 있게 한다.

언급된 도구

Vercel AI SDK추천

AI 채팅 인터페이스 및 스트리밍 로직 구현

Ollama추천

로컬 LLM 추론 및 API 제공

Next.js추천

웹 애플리케이션 프레임워크