콘텐츠로 이동

LLM 호출과 모델 추상화

LLM호출은 겉보기엔 그냥 "문자열 넣고 결과 받기"지만, 실제로는 모델마다 API가 제각각이라 벤더별 코드가 갈라지기 쉽습니다. Vercel AI SDK의 핵심(ai-sdk-core)은 그 호출을 하나의 공통 함수로 추상화해서, OpenAI든 Claude든 Gemini든 같은 코드로 다루게 해줍니다. 이 페이지는 소스 문서 AI SDK Core 를 바탕으로 텍스트 생성 함수와 모델 추상화를 설명합니다.

개요

애플리케이션 코드에 벤더별 API 호출이 여기저기 박혀 있으면, 모델을 바꿀 때마다 공사가 됩니다. AI SDK Core는 그 호출을 generateText·streamText 같은 표준 함수로 접고, 모델은 문자열로 지정해서 교체 가능하게 만듭니다. 대화형이 아닌 배치 작업과 에이전트는 이 함수 하나로 처리하고, 도구 호출·구조화 출력 같은 고급 기능도 텍스트 생성 위에 얹히는 구조예요.

핵심 개념

generateText — 한 번에 텍스트 생성

많은 텍스트를 한꺼번에 만들어야 하는 비대화형 작업에 맞는 함수입니다. 이메일 초안을 쓰거나 웹페이지를 요약하거나, 도구를 쓰는 에이전트의 한 단계에 씁니다. 결과 객체에는 생성한 text뿐 아니라 toolCalls, toolResults, usage, finishReason, steps 같은 메타데이터가 함께 담겨, 생성 과정을 추적할 수 있어요.

streamText — 토큰 단위로 흘려보내기

generateText가 완성된 텍스트를 돌려준다면, streamText는 토큰이 도착하는 대로 내보냅니다. 프론트엔드 useChat과 짝을 이루어 실시간 렌더링을 만들거나, 서버-투-서버 스트리밍에도 씁니다. UI로 흘려보내는 방법은 스트리밍 챕터 에서 다룹니다.

프롬프트를 역할 지시와 요청으로 나누기

generateText에 단일 prompt만 줄 수도 있지만, instructions(역할·규칙)와 prompt(사용자 요청)를 나눠 넣을 수 있어요. 예를 들어 "너는 전문 작가야, 간결하게 써"라는 지시와 "이 글을 3~5문장으로 요약해"라는 요청을 분리하면, 반복해서 쓸 수 있는 지시는 고정하고 요청만 바꿀 수 있습니다.

모델 추상화 — 문자열로 모델 고르기

model 파라미터는 문자열로 주는데, 예를 들어 "xai/grok-4.6"처럼 공급자/모델 형태예요. 모델을 바꾸려면 그 문자열만 바꾸면 되고, 호출 코드는 그대로입니다. 여러 공급자를 한 번에 지원(SDK Gateway)하거나, 벤더를 직접 고를 수도 있어요. 우리 제품이 특정 벤더에 묶이지 않게 해주는 바로 이 부분이 벤더 중립(VLSD) 구조의 바탕이 됩니다.

결과 객체가 주는 정보

generateText 결과에는 생성된 모든 단계의 content, 마지막 단계의 text, 그리고 사용량(usage)과 종료 사유(finishReason)가 있습니다. 구조화 출력을 요청했다면 output에도 접근할 수 있어요. 이 값들로 비용·지연·품질을 측정하는 바탕이 됩니다.

실제 적용 (데이터스케쳐스)

  • 웹빌더 콘텐츠 생성 — 웹페이지 문구를 만들 때 generateText로 한 번에 생성하고, 회사 톤 지시는 instructions에 고정해 반복 사용합니다.
  • 이벤트 NLG 리포트 — 경기 데이터를 문장으로 바꿀 때 generateText로 만들고, 결과의 usage로 비용을 추적합니다.
  • 캔버스·뉴런의 스트리밍 단계 — 실시간으로 보여줘야 하는 곳은 streamText, 결과만 필요하면 generateText로 구분해 씁니다.
  • 벤더 교체 — model 문자열만 바꾸면 코드 변경 없이 Claude·GPT·Gemini를 오갈 수 있어, 벤더별 단종·가격 변동에 유연하게 대응합니다.

더 알아보기