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 프로바이더 — 한 번 설정
export const gonka = openaiCompatible({
  name: 'gonka',
  baseURL: 'https://gate.joingonka.ai/v1',
  apiKey: process.env.GONKA_API_KEY!, // jg-내-키
  api: 'chat-completions',
  models: [
    'MiniMaxAI/MiniMax-M2.7', // 기본값
    'deepseek-ai/DeepSeek-V4-Flash-0731',
    'zai-org/GLM-5.3-Flash', // 추론 모델
  ],
})

서버측 스트리밍 채팅 (예: 모든 풀스택 프레임워크 또는 TanStack Start의 라우트 핸들러). 응답 길이는 modelOptions를 통해 설정하며, 이는 네이티브 와이어 파라미터(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를 통한 출력 제한
  })

  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('Gonka가 무엇인가요?')}>
        질문하기
      </button>
    </div>
  )
}

서버 없이 사용: 동일한 프로바이더를 스크립트나 백엔드에서 직접 사용할 수 있습니다. chat()을 호출하여 스트림을 읽으세요. Gonka 연결 방식은 모든 경우에 동일합니다.

Gateway 모델 파라미터: 컨텍스트는 MiniMax M2.7이 200K 토큰, 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.0069/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: '도시의 날씨를 조회합니다',
  inputSchema: z.object({ city: z.string() }),
  outputSchema: z.object({ tempC: z.number() }),
}).server(async ({ city }) => {
  return { tempC: 21 } // 실제 API 호출
})

const stream = chat({
  adapter: gonka('MiniMaxAI/MiniMax-M2.7'),
  messages: [{ role: 'user', content: '모스크바 날씨 어때?' }],
  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 — 추론 모델: 응답 전에 논리적 추론을 수행하며 복잡한 로직에 강합니다. 네트워크에서 가장 긴 컨텍스트(390K)를 가집니다. 응답 상한은 8192이며, 추론 과정이 max_tokens의 일부를 소모합니다.

TanStack AI의 runtime adapter switching 덕분에 동일한 공급자 내에서 세 가지 모델을 모두 유지하면서 즉시 전환할 수 있습니다. 예를 들어, 추론이 필요한 작업에는 GLM-5.3 Flash를, 빠른 응답이 필요한 작업에는 MiniMax를 사용하는 식으로 활용 가능합니다.