Vercel AI SDK + Gonka AI — 저렴한 TypeScript AI 애플리케이션

JoinGonka API 키: gate.joingonka.ai/register에서 등록하세요. 시작 시 10M 무료 토큰을 제공합니다. Dashboard에서 jg- 접두사가 있는 키를 생성하세요.

패키지 설치. 사용자 정의 OpenAI 호환 엔드포인트를 위해 Vercel AI SDK는 @ai-sdk/openai-compatible 프로바이더를 권장합니다:

npm install ai @ai-sdk/openai-compatible

최소 구성으로 연결 — createOpenAICompatible을 통해 프로바이더 인스턴스를 생성하고 generateText를 호출합니다:

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

const gonka = createOpenAICompatible({
  name: 'gonka',
  baseURL: 'https://gate.joingonka.ai/v1',
  apiKey: process.env.GONKA_API_KEY, // jg-ваш-ключ
});

const { text } = await generateText({
  model: gonka('MiniMaxAI/MiniMax-M2.7'),
  prompt: 'Объясни, что такое децентрализованная сеть инференса',
});

console.log(text);

apiKey 매개변수는 Authorization: Bearer jg-ваш-ключ 헤더를 자동으로 추가하므로 별도의 설정이 필요하지 않습니다. 키는 코드 내부에 포함하지 말고 GONKA_API_KEY 환경 변수(예: .env.local)에 저장하세요.

대안 — createOpenAI({ baseURL, apiKey }) 팩토리를 사용하는 @ai-sdk/openai 패키지도 있습니다. 두 방법 모두 가능하지만, OpenAI가 아닌 엔드포인트의 경우 AI SDK 문서에서는 @ai-sdk/openai-compatible을 사용할 것을 권장합니다. 이는 불필요한 OpenAI 전용 가정들을 배제하기 때문입니다.

Vercel AI SDK의 핵심 강점은 스트리밍 응답입니다. streamText 함수는 즉시 토큰을 스트리밍하기 시작하며, toUIMessageStreamResponse() 헬퍼는 Next.js App Router의 route handler에서 직접 스트림을 반환합니다.

서버측 핸들러 app/api/chat/route.ts:

import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { streamText, convertToModelMessages, type UIMessage } from 'ai';

const gonka = createOpenAICompatible({
  name: 'gonka',
  baseURL: 'https://gate.joingonka.ai/v1',
  apiKey: process.env.GONKA_API_KEY,
});

// 스트리밍 허용 시간 30초 설정
export const maxDuration = 30;

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

  const result = streamText({
    model: gonka('MiniMaxAI/MiniMax-M2.7'),
    system: '당신은 유용한 어시스턴트입니다. 짧고 명확하게 답변하세요.',
    messages: convertToModelMessages(messages),
    maxOutputTokens: 8192, // Gateway를 통한 출력 제한
  });

  return result.toUIMessageStreamResponse();
}

클라이언트에서는 @ai-sdk/react의 useChat 훅을 사용하면 /api/chat으로 요청을 보내고 메시지 스트림을 렌더링합니다. 이때 백엔드는 OpenAI가 아닌 Gonka와 통신하게 됩니다.

UI 없는 스크립트 (Node, 스트림에 대한 async 이터레이터):

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

const gonka = createOpenAICompatible({
  name: 'gonka',
  baseURL: 'https://gate.joingonka.ai/v1',
  apiKey: process.env.GONKA_API_KEY,
});

const result = streamText({
  model: gonka('MiniMaxAI/MiniMax-M2.7'),
  prompt: '분산 컴퓨팅에 대한 하이쿠를 작성해줘',
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

모델 매개변수. Gateway를 통해 2개의 모델을 이용할 수 있으며, 두 모델 모두 컨텍스트 길이는 200K 토큰이고 출력 제한(maxOutputTokens)은 각각 8192입니다:

• moonshotai/Kimi-K2.6 — 기본값 (Kimi K2.6);
• MiniMaxAI/MiniMax-M2.7 (MiniMax M2.7).

maxOutputTokens가 지정되지 않은 경우, 비스트리밍 요청 시 Gateway는 기본적으로 최대 1500 토큰을 반환하므로 스트리밍 채팅의 경우 값을 명시하는 것이 좋습니다.

Vercel AI SDK는 보통 채팅, 에이전트, 앱 내 어시스턴트 등 인터랙티브한 인터페이스 배후에서 사용됩니다. 각 메시지는 대화 기록을 포함하며, 에이전트의 각 단계는 도구 컨텍스트를 사용합니다. 따라서 실제 비용은 단일 요청이 아닌 프로덕션 부하에 따라 계산됩니다. 일반적인 시나리오를 비교해 보겠습니다:

JoinGonka의 비용은 입력 1M 토큰당 약 $0.003이며 출력 비용은 그보다 약 3배 정도 높습니다. 하루 수천 번의 요청이 있는 애플리케이션의 경우, 이는 매달 수백 달러와 몇 센트의 청구서 차이가 납니다. 제공되는 10M 토큰 무료 크레딧은 프로덕션으로 전환하기 전 프로젝트를 완전히 실행하고 디버깅하기에 충분합니다.

Vercel AI SDK는 tools 객체와 zod 스키마를 통해 도구를 선언적으로 정의합니다. Kimi K2.6은 네이티브 function calling을 지원하므로, AI SDK는 텍스트 응답을 파싱할 필요 없이 구조화된 tool_calls를 전달받습니다. stopWhen: stepCountIs(n) 매개변수는 여러 단계를 연속으로 허용하며, 모델은 도구를 호출하고 결과를 받은 뒤 계속 진행합니다.

import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { generateText, tool, stepCountIs } from 'ai';
import { z } from 'zod';

const gonka = createOpenAICompatible({
  name: 'gonka',
  baseURL: 'https://gate.joingonka.ai/v1',
  apiKey: process.env.GONKA_API_KEY,
});

const { text } = await generateText({
  model: gonka('MiniMaxAI/MiniMax-M2.7'),
  stopWhen: stepCountIs(5),
  tools: {
    weather: tool({
      description: '도시의 날씨 알아보기',
      inputSchema: z.object({ city: z.string() }),
      execute: async ({ city }) => ({ city, tempC: 17 }),
    }),
  },
  prompt: '모스크바 날씨 어때? 한 문장으로 답해줘.',
});

console.log(text);

모델은 weather 도구를 호출하여 결과를 얻고 최종 답변을 생성합니다. 이 전체 주기는 Gonka를 통해 약 $0.000048가 소요되며, Anthropic이나 OpenAI의 $0.03-$0.10와 비교됩니다. 사용자의 요청마다 5~10단계가 수행되는 에이전트 애플리케이션의 경우, 프로덕션 환경에서의 비용 절감 효과는 월 수천 달러에 달합니다.

Python으로 AI 애플리케이션을 구축 중이라면 LangChain 가이드를 확인하세요. OpenAI 호환 클래스를 통해 동일한 접근 방식을 사용할 수 있습니다.