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

JoinGonka API 키: gate.joingonka.ai/register 에서 등록하세요. 초기 혜택으로 3M 무료 토큰을 드립니다. 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-your-key
});

const { text } = await generateText({
  model: gonka('MiniMaxAI/MiniMax-M2.7'),
  prompt: '탈중앙화 추론 네트워크가 무엇인지 설명해줘',
});

console.log(text);

apiKey 파라미터는 자동으로 Authorization: Bearer jg-your-key 헤더를 추가하므로 별도의 설정이 필요 없습니다. 키는 코드에 직접 넣지 말고 환경 변수 GONKA_API_KEY (예: .env.local)에 저장하세요.

대안 — createOpenAI({ baseURL, apiKey }) 팩토리를 사용하는 @ai-sdk/openai 패키지가 있습니다. 두 방법 모두 작동하지만, OpenAI가 아닌 엔드포인트의 경우 AI SDK 문서에서는 불필요한 OpenAI 특정 가정을 포함하지 않는 @ai-sdk/openai-compatible 을 권장합니다.

Vercel AI SDK의 주요 기능은 응답 스트리밍입니다. streamText 함수는 즉시 토큰 스트리밍을 시작하며, toUIMessageStreamResponse() 헬퍼는 Next.js App Router의 라우트 핸들러에서 바로 준비된 스트림을 출력합니다.

서버측 핸들러 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, 스트림 비동기 이터레이터):

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를 통해 세 가지 모델을 사용할 수 있습니다: MiniMax M2.7은 200K 토큰 컨텍스트, DeepSeek V4 Flash는 380K, GLM-5.3 Flash는 390K입니다. 응답 제한(maxOutputTokens)은 MiniMax M2.7과 GLM-5.3 Flash가 8192, DeepSeek V4 Flash가 32768입니다:

• MiniMaxAI/MiniMax-M2.7 — 기본값 (MiniMax M2.7);
• deepseek-ai/DeepSeek-V4-Flash-0731 (DeepSeek V4 Flash, 컨텍스트 380K);
• zai-org/GLM-5.3-Flash (GLM-5.3 Flash, 추론 모델 — 답변 전 추론 수행).

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

Vercel AI SDK는 보통 애플리케이션 내의 챗봇, 에이전트, 어시스턴트와 같은 대화형 인터페이스 뒤에서 사용됩니다. 각 메시지는 대화 기록을 포함하고, 에이전트의 각 단계는 도구 컨텍스트를 동반합니다. 따라서 실제 비용은 요청 한 번이 아니라 프로덕션 환경의 부하에 따라 계산됩니다. 일반적인 시나리오를 비교해 보겠습니다:

JoinGonka의 가격은 입력 1M 토큰당 약 $0.0069이며, 출력은 약 3배 정도입니다. 하루에 수천 번의 요청이 발생하는 애플리케이션의 경우, 수백 달러의 청구서와 몇 센트의 청구서라는 엄청난 차이가 발생합니다. 무료로 제공되는 3M 토큰은 프로젝트의 초기 요청을 실행하기에 충분합니다.

Vercel AI SDK는 tools 객체와 zod 스키마를 통해 도구를 선언적으로 정의합니다. 네트워크 모델들이 네이티브 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 호환 클래스를 통해 동일한 방식으로 접근할 수 있습니다.