TanStack AI + Gonka — Applicazioni AI in TypeScript a basso costo

Installazione dei pacchetti (core + adattatore OpenAI, in cui risiede openaiCompatible):

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

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

Per l'interfaccia di chat su React, aggiungi il client e gli hook:

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

Chiave API JoinGonka: se non l'hai ancora, registrati su gate.joingonka.ai/register, ottieni 10 milioni di token gratuiti e crea una chiave jg-xxx in Dashboard → API Keys. Una singola chiave e un singolo saldo funzionano sia per il formato OpenAI che per il formato Anthropic.

In TanStack AI, un provider personalizzato compatibile con OpenAI viene configurato tramite la funzione openaiCompatible(): si imposta una volta baseURL, apiKey e un elenco di modelli, quindi si seleziona il modello per ogni chiamata. Il nostro Gateway parla il formato Chat Completions, quindi lasciamo api: 'chat-completions' (questo è il valore predefinito).

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

// Provider Gonka — configurato una sola volta
export const gonka = openaiCompatible({
  name: 'gonka',
  baseURL: 'https://gate.joingonka.ai/v1',
  apiKey: process.env.GONKA_API_KEY!, // jg-la-tua-chiave
  api: 'chat-completions',
  models: [
    'Qwen/Qwen3-235B-A22B-Instruct-2507-FP8', // predefinito
    'moonshotai/Kimi-K2.6',
    'MiniMaxAI/MiniMax-M2.7',
  ],
})

Chat in streaming sul server (ad esempio, un route handler in qualsiasi fullstack-framework o TanStack Start). La lunghezza della risposta viene impostata tramite modelOptions — questo è l'unico punto per i parametri wire nativi (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 }, // limite Qwen tramite Gateway
  })

  return toServerSentEventsResponse(stream)
}

Client React tramite l'hook useChat — trasmette in streaming le risposte dal server all'interfaccia utente:

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('Cos'è Gonka?')}>
        Chiedi
      </button>
    </div>
  )
}

Senza server: lo stesso provider funziona direttamente in uno script o nel backend — chiama chat() e leggi il flusso. La connessione a Gonka è la stessa per tutte le opzioni.

Parametri del modello tramite Gateway: il contesto per tutti e tre i modelli è di 128K token. Il limite max_tokens: Qwen3-235B — 8192, Kimi K2.6 — 3072, MiniMax-M2.7 — 4096. Se max_tokens non è specificato, il valore predefinito per non-stream è 1500, quindi per risposte lunghe specificarlo esplicitamente.

TanStack AI funziona con la stessa facilità sia tramite le tariffe dirette di OpenAI/Anthropic che tramite Gonka – cambia solo la baseURL. Ma il prezzo differisce di ordini di grandezza. Confrontiamo i carichi tipici di un'applicazione di produzione su TanStack AI:

L'approccio provider-agnostic di TanStack AI significa che il passaggio a Gonka è una modifica di una singola riga (baseURL) e non una riscrittura del codice. Allo stesso tempo, i tuoi strumenti type-safe, l'output strutturato e i React-hooks rimangono invariati. Per un'applicazione con migliaia di utenti, la differenza è di decine di migliaia di dollari al mese.

Prezzo Gonka: ingresso ~$0.0005 per 1M token, uscita ×3. Questo è centinaia–migliaia di volte più economico delle tariffe dirette di OpenAI e Anthropic.

La caratteristica principale di TanStack AI è il contratto unificato toolDefinition(): uno strumento viene descritto una sola volta (input/output tramite Zod, ArkType, Valibot o JSON Schema) e l'implementazione è collegata al server o al client. Qwen3-235B, Kimi K2.6 e MiniMax-M2.7 supportano il native tool calling tramite Gonka, quindi gli agenti funzionano in modo affidabile – senza analizzare le risposte testuali.

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

Quale modello scegliere:

• Qwen/Qwen3-235B-A22B-Instruct-2507-FP8 – predefinito. Il tetto di risposta più grande (8192) e un potente tool calling. Adatto per agenti e output strutturati.
• moonshotai/Kimi-K2.6 – eccellente per dialoghi lunghi e ragionamenti. Tetto di risposta 3072.
• MiniMaxAI/MiniMax-M2.7 – equilibrio tra velocità e qualità, tetto 4096.

Grazie al runtime adapter switching in TanStack AI, è possibile mantenere tutti e tre i modelli in un unico provider e passare da uno all'altro al volo – ad esempio, compiti complessi di agente su Qwen, risposte rapide su MiniMax.