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

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

Installazione dei pacchetti. Per un endpoint compatibile con OpenAI personalizzato, Vercel AI SDK consiglia 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('MiniMaxAI/MiniMax-M2.7'),
  prompt: 'Spiega cos'è una rete di inferenza decentralizzata',
});

console.log(text);

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

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

La funzione principale di Vercel AI SDK è lo streaming della risposta. La funzione streamText inizia lo streaming dei token immediatamente, e l'helper toUIMessageStreamResponse() trasmette lo stream pronto direttamente dal route handler in Next.js App Router.

Server handler 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,
});

// impostiamo il limite di streaming 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('MiniMaxAI/MiniMax-M2.7'),
    system: 'Sei un assistente utile. Rispondi brevemente e al punto.',
    messages: convertToModelMessages(messages),
    maxOutputTokens: 8192, // limite di output tramite Gateway
  });

  return result.toUIMessageStreamResponse();
}

Sul client, integra l'hook useChat da @ai-sdk/react: gestisce automaticamente la chiamata a /api/chat e il rendering dello stream di messaggi. Il backend, invece, comunica con Gonka anziché con OpenAI.

Script senza UI (Node, async-iteratore sullo stream):

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('MiniMaxAI/MiniMax-M2.7'),
  prompt: 'Scrivi un haiku sul calcolo distribuito',
});

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

Parametri dei modelli. Tramite Gateway sono disponibili due modelli, entrambi con un contesto di 200K token; il limite di risposta (maxOutputTokens) arriva fino a 8192 per ciascuno:

• moonshotai/Kimi-K2.6 — default (Kimi K2.6);
• MiniMaxAI/MiniMax-M2.7 (MiniMax M2.7).

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

Vercel AI SDK solitamente si trova dietro un'interfaccia interattiva: chat, agente, assistente nell'applicazione. Ogni messaggio trascina con sé la cronologia del dialogo, ogni passaggio dell'agente richiede il contesto degli strumenti. Pertanto, il costo reale non viene calcolato per singola richiesta, ma in base al carico di produzione. Confrontiamo gli scenari tipici:

Il prezzo di JoinGonka è di circa $0.003 per 1M di token in input, l'output costa circa tre volte tanto. Per un'applicazione con migliaia di richieste al giorno, questa è la differenza tra un conto di centinaia di dollari e un conto di pochi centesimi. I 10M di token gratuiti sono sufficienti per eseguire e debuggare 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. Kimi K2.6 supporta il function calling nativo, quindi l'AI SDK riceve tool_calls strutturati senza dover analizzare le risposte testuali. Il parametro stopWhen: stepCountIs(n) consente più passaggi consecutivi: il modello chiama lo strumento, riceve il risultato e continua.

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('MiniMaxAI/MiniMax-M2.7'),
  stopWhen: stepCountIs(5),
  tools: {
    weather: tool({
      description: 'Scopri il meteo in una città',
      inputSchema: z.object({ city: z.string() }),
      execute: async ({ city }) => ({ city, tempC: 17 }),
    }),
  },
  prompt: 'Che tempo fa a Mosca? Rispondi in una sola frase.',
});

console.log(text);

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

Se stai costruendo un'applicazione AI in Python, dai un'occhiata alla guida su LangChain: utilizza lo stesso approccio tramite una classe compatibile OpenAI.