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

패키지 설치 (코어 + openaiCompatible 이 포함된 OpenAI 어댑터):

# pnpm
pnpm add @tanstack/ai @tanstack/ai-openai

# npm
npm install @tanstack/ai @tanstack/ai-openai

React 채팅 인터페이스를 위해 클라이언트와 훅을 추가하세요:

pnpm add @tanstack/ai-client @tanstack/ai-react

JoinGonka API 키: 아직 없으시다면 gate.joingonka.ai/register 에서 등록하시고 3M 무료 토큰을 받으세요. Dashboard의 API Keys 메뉴에서 jg-xxx 키를 생성하면 됩니다. 하나의 키와 하나의 잔액으로 OpenAI 및 Anthropic 포맷을 모두 사용할 수 있습니다.

TanStack AI에서 커스텀 OpenAI 호환 프로바이더는 openaiCompatible() 함수로 설정합니다. baseURL, apiKey, 모델 목록을 한 번만 지정해두고, 호출할 때마다 모델을 선택하면 됩니다. 저희 Gateway는 Chat Completions 형식으로 통신하므로 api: 'chat-completions'를 그대로 둡니다(이 값이 기본값입니다).

import { openaiCompatible } from '@tanstack/ai-openai'

// Gonka provider: configured once
export const gonka = openaiCompatible({
  name: 'gonka',
  baseURL: 'https://gate.joingonka.ai/v1',
  apiKey: process.env.GONKA_API_KEY!, // jg-your-key
  api: 'chat-completions',
  models: [
    'MiniMaxAI/MiniMax-M2.7', // default
    'deepseek-ai/DeepSeek-V4-Flash-0731',
    'zai-org/GLM-5.3-Flash', // reasoning model
  ],
})

서버에서 스트리밍 채팅(예: 모든 풀스택 프레임워크 또는 TanStack Start의 라우트 핸들러). 응답 길이는 modelOptions로 지정합니다. 네이티브 wire 파라미터(max_tokens, temperature)를 전달하는 유일한 지점입니다.

import { chat, toServerSentEventsResponse } from '@tanstack/ai'
import { gonka } from './gonka'

export async function POST(request: Request) {
  const { messages } = await request.json()

  const stream = chat({
    adapter: gonka('MiniMaxAI/MiniMax-M2.7'),
    messages,
    modelOptions: { max_tokens: 8192 }, // Gateway output cap
  })

  return toServerSentEventsResponse(stream)
}

React 클라이언트는 useChat 훅으로 서버의 응답을 UI로 스트리밍합니다.

import { useChat } from '@tanstack/ai-react'

function Chat() {
  const { messages, sendMessage, status } = useChat({ api: '/api/chat' })

  return (
    <div>
      {messages.map((m) => (
        <p key={m.id}><b>{m.role}:</b> {m.content}</p>
      ))}
      <button onClick={() => sendMessage('What is Gonka?')}>
        Ask
      </button>
    </div>
  )
}

서버 없이도 동일한 프로바이더가 스크립트나 백엔드에서 바로 동작합니다. chat()을 호출하고 스트림을 읽으면 됩니다. Gonka 연결 방법은 모든 방식에서 동일합니다.

Gateway를 통한 모델 파라미터: 컨텍스트는 MiniMax M2.7이 180K 토큰, DeepSeek V4 Flash가 380K, GLM-5.3 Flash가 390K입니다. max_tokens 상한은 MiniMax M2.7과 GLM-5.3 Flash가 8192, DeepSeek V4 Flash가 32768입니다. max_tokens를 지정하지 않으면 non-stream 기본값은 1500이므로, 긴 응답이 필요하면 명시적으로 지정하세요.

TanStack AI는 OpenAI/Anthropic의 직접 요금으로도, Gonka를 통해서도 동일하게 편리하며 baseURL만 변경하면 됩니다. 하지만 가격 차이는 수백 배에 달합니다. TanStack AI 프로덕션 애플리케이션의 일반적인 부하를 비교해 보겠습니다:

TanStack AI의 제공자 독립적 접근 방식은 Gonka로의 전환이 코드 재작성이 아닌 단 한 줄(baseURL)의 변경임을 의미합니다. 동시에 타입 안전 툴, 구조화된 출력, React 훅은 그대로 유지됩니다. 사용자 수가 많은 애플리케이션의 경우 월 수만 달러를 절약할 수 있습니다.

Gonka 가격: 입력 토큰당 약 $0.0062/1M, 출력은 3배입니다. 이는 OpenAI 및 Anthropic의 직접 요금보다 수백에서 수천 배 저렴합니다.

TanStack AI의 핵심은 단일 계약 toolDefinition()입니다. 도구를 한 번만 정의하고(입출력은 Zod, ArkType, Valibot 또는 JSON Schema로 지정), 구현은 서버나 클라이언트에 연결합니다. MiniMax M2.7, DeepSeek V4 Flash, GLM-5.3 Flash는 Gonka를 통해 네이티브 tool calling을 지원하므로, 텍스트 응답 파싱 없이 에이전트가 안정적으로 동작합니다.

import { chat, toolDefinition } from '@tanstack/ai'
import { gonka } from './gonka'
import { z } from 'zod'

const getWeather = toolDefinition({
  name: 'getWeather',
  description: 'Get the weather in a city',
  inputSchema: z.object({ city: z.string() }),
  outputSchema: z.object({ tempC: z.number() }),
}).server(async ({ city }) => {
  return { tempC: 21 } // your real API call
})

const stream = chat({
  adapter: gonka('MiniMaxAI/MiniMax-M2.7'),
  messages: [{ role: 'user', content: 'What is the weather in Moscow?' }],
  tools: [getWeather],
  modelOptions: { max_tokens: 8192 },
})

어떤 모델을 선택할까:

• MiniMaxAI/MiniMax-M2.7 — 기본값. 속도와 품질의 균형이 좋고 긴 컨텍스트를 지원합니다. 응답 상한은 8192.
• deepseek-ai/DeepSeek-V4-Flash-0731 — 네트워크에서 가장 긴 컨텍스트 중 하나(380K)를 제공하며, 큰 프롬프트를 저렴하게 처리합니다. 응답 상한은 32768.
• zai-org/GLM-5.3-Flash — reasoning 모델. 답변 전에 추론하며 복잡한 논리에 강합니다. 네트워크에서 가장 긴 컨텍스트(390K)를 갖습니다. 응답 상한은 8192이며, 추론이 max_tokens의 일부를 소모합니다.

TanStack AI의 runtime adapter switching 덕분에 세 모델을 하나의 프로바이더에 두고 실시간으로 전환할 수 있습니다. 예를 들어 추론이 필요한 작업은 GLM-5.3 Flash로, 빠른 응답은 MiniMax로 처리하는 식입니다.