Vercel AI SDK + Gonka AI — Applicazioni AI in TypeScript a basso costo

Chiave API JoinGonka: registrati su gate.joingonka.ai/register — all'inizio ti diamo 10 milioni di token gratuiti. Nella Dashboard crea una chiave con il prefisso jg-.

Installazione dei pacchetti. Per un endpoint personalizzato compatibile con OpenAI, Vercel AI SDK raccomanda il provider @ai-sdk/openai-compatible:

npm install ai @ai-sdk/openai-compatible

Connessione minima — creiamo un'istanza del provider tramite createOpenAICompatible e chiamiamo generateText:

import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { generateText } from 'ai';

const gonka = createOpenAICompatible({
  name: 'gonka',
  baseURL: 'https://gate.joingonka.ai/v1',
  apiKey: process.env.GONKA_API_KEY, // jg-la-tua-chiave
});

const { text } = await generateText({
  model: gonka('Qwen/Qwen3-235B-A22B-Instruct-2507-FP8'),
  prompt: 'Spiega cos'è una rete di inferenza decentralizzata',
});

console.log(text);

Il parametro apiKey aggiunge automaticamente l'intestazione Authorization: Bearer jg-la-tua-chiave — non è necessaria una configurazione separata. Conserva la chiave nella variabile d'ambiente GONKA_API_KEY (ad esempio, in .env.local), non nel codice.

Alternativa — il pacchetto @ai-sdk/openai con la factory createOpenAI({ baseURL, apiKey }). Entrambi i metodi sono validi; per gli endpoint non appartenenti a OpenAI, la documentazione di AI SDK consiglia proprio @ai-sdk/openai-compatible — non porta con sé inutili assunzioni specifiche di OpenAI.

La funzione principale di Vercel AI SDK è l'output di risposta in streaming. La funzione streamText inizia immediatamente lo streaming dei token, e l'helper toUIMessageStreamResponse() restituisce il flusso pronto direttamente dal gestore di route nell'App Router di Next.js.

Gestore lato server app/api/chat/route.ts:

import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { streamText, convertToModelMessages, type UIMessage } from 'ai';

const gonka = createOpenAICompatible({
  name: 'gonka',
  baseURL: 'https://gate.joingonka.ai/v1',
  apiKey: process.env.GONKA_API_KEY,
});

// consente lo streaming fino a 30 secondi
export const maxDuration = 30;

export async function POST(req: Request) {
  const { messages }: { messages: UIMessage[] } = await req.json();

  const result = streamText({
    model: gonka('Qwen/Qwen3-235B-A22B-Instruct-2507-FP8'),
    system: 'Sei un assistente utile. Rispondi in modo conciso e pertinente.',
    messages: convertToModelMessages(messages),
    maxOutputTokens: 8192, // limite Qwen3-235B tramite Gateway
  });

  return result.toUIMessageStreamResponse();
}

Sul client, collega l'hook useChat da @ai-sdk/react — si rivolge automaticamente a /api/chat e renderizza il flusso di messaggi. Il backend, nel frattempo, si connette a Gonka, non a OpenAI.

Script senza UI (Node, iteratore asincrono per il flusso):

import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { streamText } from 'ai';

const gonka = createOpenAICompatible({
  name: 'gonka',
  baseURL: 'https://gate.joingonka.ai/v1',
  apiKey: process.env.GONKA_API_KEY,
});

const result = streamText({
  model: gonka('Qwen/Qwen3-235B-A22B-Instruct-2507-FP8'),
  prompt: 'Scrivi un haiku sui calcoli distribuiti',
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

Parametri del modello. Tramite Gateway sono disponibili tre modelli, con un contesto di 128K token per tutti; il limite di risposta (maxOutputTokens) varia:

• Qwen/Qwen3-235B-A22B-Instruct-2507-FP8 — predefinito, fino a 8192 token di output;
• moonshotai/Kimi-K2.6 — fino a 3072 (Kimi K2.6);
• MiniMaxAI/MiniMax-M2.7 — fino a 4096 (MiniMax M2.7).

Se maxOutputTokens non è specificato, per le richieste non in streaming Gateway restituirà per impostazione predefinita fino a 1500 token — per le chat in streaming è meglio specificare il valore esplicitamente.

Vercel AI SDK si basa solitamente su un'interfaccia interattiva: chat, agente, assistente nell'applicazione. Ogni messaggio tira con sé la cronologia del dialogo, ogni passo dell'agente — il contesto degli strumenti. Pertanto, il costo reale non viene calcolato per una singola richiesta, ma per il carico di produzione. Confrontiamo scenari tipici:

Il prezzo di JoinGonka è di circa $0.0005 per 1M di token in ingresso, l'output è circa tre volte più costoso. Per un'applicazione con migliaia di richieste al giorno, questa è la differenza tra una fattura di centinaia di dollari e una fattura di pochi centesimi. 10M di token gratuiti sono sufficienti per eseguire e mettere a punto completamente il progetto prima di andare in produzione.

Vercel AI SDK descrive gli strumenti in modo dichiarativo tramite l'oggetto tools e lo schema zod. Qwen3-235B supporta il function calling nativo, quindi AI SDK riceve tool_calls strutturati senza analizzare le risposte testuali. Il parametro stopWhen: stepCountIs(n) consente più passaggi consecutivi — il modello chiama lo strumento, riceve il risultato e prosegue.

import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { generateText, tool, stepCountIs } from 'ai';
import { z } from 'zod';

const gonka = createOpenAICompatible({
  name: 'gonka',
  baseURL: 'https://gate.joingonka.ai/v1',
  apiKey: process.env.GONKA_API_KEY,
});

const { text } = await generateText({
  model: gonka('Qwen/Qwen3-235B-A22B-Instruct-2507-FP8'),
  stopWhen: stepCountIs(5),
  tools: {
    weather: tool({
      description: 'Scopri il tempo in città',
      inputSchema: z.object({ city: z.string() }),
      execute: async ({ city }) => ({ city, tempC: 17 }),
    }),
  },
  prompt: 'Che tempo fa a Mosca? Rispondi con una frase.',
});

console.log(text);

Il modello richiama lo strumento weather, ottiene il risultato e formula la risposta finale. L'intero ciclo costa circa $0.00001 tramite Gonka contro $0.03-0.10 con Anthropic o OpenAI. Per le applicazioni basate su agenti, dove ogni richiesta dell'utente si articola in 5-10 passaggi, il risparmio in produzione si misura in migliaia di dollari al mese.

Se stai costruendo un'applicazione AI in Python, consulta la guida per LangChain — lì c'è lo stesso approccio tramite la classe compatibile con OpenAI.