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에 등록하고 10M 무료 토큰을 받은 다음 대시보드 → API 키에서 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-your-key
  api: 'chat-completions',
  models: [
    'Qwen/Qwen3-235B-A22B-Instruct-2507-FP8', // 기본값
    'moonshotai/Kimi-K2.6',
    'MiniMaxAI/MiniMax-M2.7',
  ],
})

서버의 스트리밍 채팅 (예: 모든 풀스택 프레임워크의 라우트 핸들러 또는 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('Qwen/Qwen3-235B-A22B-Instruct-2507-FP8'),
    messages,
    modelOptions: { max_tokens: 8192 }, // Gateway를 통한 Qwen 상한
  })

  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를 통한 모델 매개변수: 세 가지 모델 모두의 컨텍스트는 128K 토큰입니다. max_tokens 상한: Qwen3-235B — 8192, Kimi K2.6 — 3072, MiniMax-M2.7 — 4096. max_tokens가 지정되지 않은 경우 스트림이 아닌 요청의 기본값은 1500이므로 긴 응답의 경우 명시적으로 지정하십시오.

TanStack AI는 OpenAI/Anthropic 직접 요금과 Gonka를 통해 모두 잘 작동합니다. baseURL만 변경됩니다. 하지만 가격은 몇 배나 차이가 납니다. TanStack AI의 일반적인 프로덕션 애플리케이션 부하를 비교해 봅시다:

TanStack AI의 공급자 불가지론적 접근 방식은 Gonka로 전환하는 것이 코드 재작성이 아니라 단 한 줄 변경(baseURL)이라는 것을 의미합니다. 유형 안전 도구, 구조화된 출력 및 React 훅은 변경되지 않습니다. 수천 명의 사용자가 있는 애플리케이션의 경우 월 수만 달러의 차이가 발생합니다.

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

TanStack AI의 주요 기능은 통합 toolDefinition() 계약입니다. 도구는 한 번 (Zod, ArkType, Valibot 또는 JSON Schema를 통한 입력/출력) 설명되고, 구현은 서버 또는 클라이언트에 바인딩됩니다. Qwen3-235B, Kimi K2.6 및 MiniMax-M2.7은 Gonka를 통해 네이티브 도구 호출을 지원하므로 에이전트는 텍스트 응답을 구문 분석하지 않고 안정적으로 작동합니다.

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('Qwen/Qwen3-235B-A22B-Instruct-2507-FP8'),
  messages: [{ role: 'user', content: '모스크바 날씨는 어때요?' }],
  tools: [getWeather],
  modelOptions: { max_tokens: 8192 },
})

어떤 모델을 선택할까요:

• Qwen/Qwen3-235B-A22B-Instruct-2507-FP8 — 기본값입니다. 가장 큰 응답 상한선(8192)과 강력한 도구 호출. 에이전트 및 구조화된 출력에 적합합니다.
• moonshotai/Kimi-K2.6 — 긴 대화 및 추론에 탁월합니다. 응답 상한선 3072.
• MiniMaxAI/MiniMax-M2.7 — 속도와 품질의 균형, 상한선 4096.

TanStack AI의 런타임 어댑터 전환 덕분에 하나의 공급자에서 세 가지 모델을 모두 유지하고 즉시 전환할 수 있습니다. 예를 들어, Qwen에서 무거운 에이전트 작업을 처리하고 MiniMax에서 빠른 응답을 처리합니다.