TanStack AI + Gonka — aplikacje AI w TypeScript za grosze

Instalacja pakietów (rdzeń + adapter OpenAI, w którym znajduje się openaiCompatible):

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

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

Dla interfejsu czatu w React dodaj klienta i hooki:

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

Klucz API JoinGonka: jeśli jeszcze nie masz — zarejestruj się na gate.joingonka.ai/register, uzyskaj 10M darmowych tokenów i utwórz klucz jg-xxx w Dashboard → API Keys. Jeden klucz i jedno saldo działają zarówno dla formatu OpenAI, jak i Anthropic.

W TanStack AI niestandardowy dostawca kompatybilny z OpenAI jest konfigurowany za pomocą funkcji openaiCompatible(): raz określasz baseURL, apiKey i listę modeli, a następnie wybierasz model dla każdego wywołania. Nasz Gateway komunikuje się w formacie Chat Completions, więc pozostawiamy api: 'chat-completions' (jest to wartość domyślna).

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

// Dostawca Gonka — konfiguruje się raz
export const gonka = openaiCompatible({
  name: 'gonka',
  baseURL: 'https://gate.joingonka.ai/v1',
  apiKey: process.env.GONKA_API_KEY!, // jg-twój-klucz
  api: 'chat-completions',
  models: [
    'Qwen/Qwen3-235B-A22B-Instruct-2507-FP8', // domyślne
    'moonshotai/Kimi-K2.6',
    'MiniMaxAI/MiniMax-M2.7',
  ],
})

Streaming-czat na serwerze (na przykład route-handler w dowolnym frameworku fullstack lub TanStack Start). Długość odpowiedzi ustawiamy przez modelOptions — to jedyne miejsce na natywne wire-parametry (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 }, // limit Qwen przez Gateway
  })

  return toServerSentEventsResponse(stream)
}

Klient React poprzez hook useChat — przesyła strumieniowo odpowiedzi z serwera do interfejsu użytkownika:

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('Co to jest Gonka?')}>
        Zapytaj
      </button>
    </div>
  )
}

Bez serwera: ten sam dostawca działa w skrypcie lub backendzie bezpośrednio — wywołaj chat() i czytaj strumień. Połączenie z Gonka jest takie samo dla wszystkich wariantów.

Parametry modeli przez Gateway: kontekst dla wszystkich trzech modeli — 128K tokenów. Limit max_tokens: Qwen3-235B — 8192, Kimi K2.6 — 3072, MiniMax-M2.7 — 4096. Jeśli max_tokens nie jest podany, domyślna wartość dla niestrumieniowych zapytań to 1500, więc dla długich odpowiedzi należy ją jawnie określić.

TanStack AI działa równie wygodnie zarówno poprzez bezpośrednie taryfy OpenAI/Anthropic, jak i przez Gonka – zmienia się tylko baseURL. Ale cena różni się o rzędy wielkości. Porównajmy typowe obciążenia produkcyjnej aplikacji na TanStack AI:

Podejście provider-agnostic w TanStack AI oznacza, że przełączenie na Gonka to zmiana jednej linii (baseURL), a nie przepisywanie kodu. Przy tym Twoje bezpieczne typowo narzędzia, ustrukturyzowane wyjście i React-hooki pozostają bez zmian. Dla aplikacji z tysiącami użytkowników różnica to dziesiątki tysięcy dolarów miesięcznie.

Cena Gonka: wejście ~$0.0005 za 1M tokenów, wyjście ×3. To setki–tysiące razy taniej niż bezpośrednie taryfy OpenAI i Anthropic.

Główną cechą TanStack AI jest jednolita umowa toolDefinition(): narzędzie jest opisywane raz (wejście/wyjście przez Zod, ArkType, Valibot lub JSON Schema), a implementacja jest wiązana na serwerze lub kliencie. Qwen3-235B, Kimi K2.6 i MiniMax-M2.7 obsługują natywne wywołanie narzędzi przez Gonka, dzięki czemu agenci działają niezawodnie – bez parsowania odpowiedzi tekstowych.

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 },
})

Jaką model wybrać:

• Qwen/Qwen3-235B-A22B-Instruct-2507-FP8 – domyślny. Największy limit odpowiedzi (8192) i silne wywołanie narzędzi. Nadaje się do agentów i strukturalnych wyjść.
• moonshotai/Kimi-K2.6 – doskonały do długich dialogów i rozumowań. Limit odpowiedzi 3072.
• MiniMaxAI/MiniMax-M2.7 – równowaga między szybkością a jakością, limit 4096.

Dzięki runtime adapter switching w TanStack AI można przechowywać wszystkie trzy modele u jednego dostawcy i przełączać się między nimi na bieżąco – na przykład, ciężkie zadania agentów na Qwen, szybkie odpowiedzi na MiniMax.