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: [
    'moonshotai/Kimi-K2.6', // 기본값
    'MiniMaxAI/MiniMax-M2.7',
  ],
})

서버사이드 스트리밍 채팅 (예: 모든 fullstack 프레임워크의 라우트 핸들러나 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를 통한 출력 제한
  })

  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를 통한 모델 파라미터: 두 모델의 컨텍스트는 200K 토큰입니다. 모든 네트워크 모델의 max_tokens 제한은 8192입니다. max_tokens가 명시되지 않은 경우, non-stream의 기본값은 1500이므로 긴 응답이 필요한 경우 명시적으로 설정하십시오.

TanStack AI는 OpenAI/Anthropic 직접 계약이나 Gonka를 통해 동일하게 편리하게 작동하며, baseURL만 수정하면 됩니다. 하지만 비용은 수십 배에서 수백 배 차이가 납니다. TanStack AI 프로덕션 환경의 일반적인 부하를 비교해 보십시오:

TanStack AI의 프로바이더 독립적 접근 방식은 Gonka로의 전환이 baseURL 한 줄 수정으로 가능하다는 것을 의미하며, 전체 코드를 다시 작성할 필요가 없습니다. 동시에 타입 세이프 tools, 구조화된 출력, React 훅은 그대로 유지됩니다. 수천 명의 사용자가 있는 애플리케이션의 경우 매월 수만 달러를 절약할 수 있습니다.

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

TanStack AI의 핵심은 toolDefinition()의 통합 계약입니다. 도구를 한 번 정의하면(Zod, ArkType, Valibot 또는 JSON Schema를 사용한 입/출력), 구현은 서버나 클라이언트에 연결됩니다. Kimi K2.6과 MiniMax-M2.7은 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 },
})

모델 선택 가이드:

• moonshotai/Kimi-K2.6 — 코딩, 추론 및 에이전트 시나리오에 강력합니다. 응답 제한 8192.
• MiniMaxAI/MiniMax-M2.7 — 기본 모델, 속도와 품질의 균형이 좋으며 긴 컨텍스트 지원. 응답 제한 8192.

TanStack AI의 런타임 어댑터 전환 기능을 통해 하나의 프로바이더에서 두 모델을 모두 관리하고 즉석에서 전환할 수 있습니다. 예를 들어, 복잡한 에이전트 작업에는 Kimi를, 빠른 응답에는 MiniMax를 사용하는 식으로 활용할 수 있습니다.