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: 'Explain what a decentralized inference network is',
});

console.log(text);

apiKey 파라미터는 Authorization: Bearer jg-your-key 헤더를 자동으로 추가하므로 별도 설정이 필요 없습니다. 키는 코드가 아닌 환경 변수 GONKA_API_KEY(예: .env.local)에 보관하세요.

대안 — @ai-sdk/openai 패키지와 createOpenAI({ baseURL, apiKey }) 팩토리. 두 방법 모두 작동하지만, 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,
});

// allow streaming for up to 30 seconds
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: 'You are a helpful assistant. Answer briefly and to the point.',
    messages: convertToModelMessages(messages),
    maxOutputTokens: 8192, // Gateway output cap
  });

  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: 'Write a haiku about distributed computing',
});

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

모델 파라미터. Gateway를 통해 세 가지 모델을 사용할 수 있습니다: MiniMax M2.7은 컨텍스트 180K 토큰, 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, reasoning 모델 — 답변 전에 추론합니다).

maxOutputTokens를 지정하지 않으면 non-stream 요청에 대해 Gateway는 기본적으로 최대 1500 토큰을 반환합니다. 스트리밍 채팅에서는 값을 명시적으로 지정하는 것이 좋습니다.

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

JoinGonka의 가격은 입력 1M 토큰당 약 $0.0062이며, 출력은 약 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: 'Get the weather in a city',
      inputSchema: z.object({ city: z.string() }),
      execute: async ({ city }) => ({ city, tempC: 17 }),
    }),
  },
  prompt: 'What is the weather in Moscow? Answer in one sentence.',
});

console.log(text);

모델이 weather 도구를 호출하고, 결과를 받아 최종 답변을 생성합니다. 이 전체 사이클은 Gonka를 통하면 약 $0.000048이고, Anthropic이나 OpenAI에서는 $0.03~$0.10입니다. 사용자의 요청 하나가 5~10단계로 펼쳐지는 에이전트 애플리케이션이라면, 프로덕션에서의 절감액은 월 수천 달러에 달합니다.

Python으로 AI 앱을 만든다면 LangChain 가이드를 확인해 보세요. 동일한 접근 방식을 OpenAI 호환 클래스로 구현한 내용이 있습니다.