LlamaIndex + Gonka AI — Applicazioni RAG a basso costo

Chiave API JoinGonka: registrati su gate.joingonka.ai/register — all'inizio offriamo 3M token gratuiti — e crea una chiave jg-xxx nella Dashboard.

Installazione:

pip install llama-index llama-index-llms-openai-like

Per qualsiasi API compatibile con OpenAI, LlamaIndex fornisce la classe OpenAILike dal pacchetto llama_index.llms.openai_like. Esempio minimo di richiesta verso Gonka:

from llama_index.llms.openai_like import OpenAILike

llm = OpenAILike(
    api_base="https://gate.joingonka.ai/v1",
    api_key="jg-la-tua-chiave",
    model="MiniMaxAI/MiniMax-M2.7",
    is_chat_model=True,            # Gonka è un chat-endpoint
    is_function_calling_model=True, # tool calling nativo supportato
    context_window=200000,         # 200K per i modelli di rete
    max_tokens=8192,               # limite di output tramite Gateway
)

response = llm.complete("Spiega cos'è la RAG in tre frasi.")
print(response)

Importante su OpenAILike: è necessario specificare is_chat_model=True, altrimenti LlamaIndex cercherà un completion-endpoint che non abbiamo. is_function_calling_model=True abilita i tool calls nativi. Imposta il context_window in base al modello, così LlamaIndex gestirà correttamente il contesto.

Lo scenario classico di LlamaIndex è l'indice sui tuoi documenti e le richieste tramite query_engine. La LLM globale viene impostata una volta sola tramite Settings.llm, dopodiché l'intera pipeline utilizzerà Gonka automaticamente.

from llama_index.core import (
    VectorStoreIndex,
    SimpleDirectoryReader,
    Settings,
)
from llama_index.llms.openai_like import OpenAILike
from llama_index.embeddings.huggingface import HuggingFaceEmbedding

# 1. LLM tramite Gonka (una volta, globalmente)
Settings.llm = OpenAILike(
    api_base="https://gate.joingonka.ai/v1",
    api_key="jg-tua-chiave",
    model="MiniMaxAI/MiniMax-M2.7",
    is_chat_model=True,
    context_window=200000,
    max_tokens=8192,
)

# 2. Embedding locali (gratuiti, senza OpenAI)
Settings.embed_model = HuggingFaceEmbedding(
    model_name="BAAI/bge-small-en-v1.5"
)

# 3. Caricamento e indicizzazione dei documenti dalla cartella ./data
documents = SimpleDirectoryReader("data").load_data()
index = VectorStoreIndex.from_documents(documents)

# 4. Richiesta alla base di conoscenza
query_engine = index.as_query_engine()
response = query_engine.query("Di cosa tratta questo documento?")
print(response)

Un dettaglio critico sugli embedding: di default VectorStoreIndex utilizza gli embedding OpenAI (text-embedding-ada-002) — queste sono chiamate a pagamento separate verso OpenAI, non verso Gonka. Per evitare completamente OpenAI, imposta un modello di embedding locale tramite Settings.embed_model (come nell'esempio sopra — HuggingFaceEmbedding, pacchetto pip install llama-index-embeddings-huggingface). In tal caso la generazione avviene tramite Gonka, mentre la vettorizzazione è locale e gratuita.

Costi: una singola richiesta RAG-pipeline (ricerca + generazione) consuma ~2-5K di token LLM. Tramite Gonka questo equivale a frazioni di centesimo; tramite OpenAI/Anthropic è di 3-4 ordini di grandezza più costoso. Su migliaia di richieste al giorno, la differenza si traduce in decine di migliaia di dollari di risparmio al mese.

Un'applicazione RAG non è una chat una tantum, ma un flusso costante di richieste: ogni domanda dell'utente consuma 2–5K token LLM (la domanda stessa più i frammenti di contesto trovati). Calcoliamo i volumi tipici e il costo sui diversi provider. Prezzi Gonka tramite JoinGonka Gateway: input ~$0.0069/1M, output ×3.

Con i 3M token gratuiti è possibile avviare le prime richieste della RAG-pipeline, indicizzare il corpus di prova ed eseguire migliaia di richieste — senza spendere un centesimo. Con volumi di produzione, JoinGonka Gateway trasforma la RAG da un servizio costoso a una voce di spesa trascurabile.

LlamaIndex non solo sa rispondere basandosi sui documenti, ma può anche creare agenti con strumenti. Tutti e tre i modelli Gonka supportano il tool calling nativo — gli agenti chiamano le funzioni in modo strutturato, senza analizzare il testo. Esempio di un agente con uno strumento:

import asyncio
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai_like import OpenAILike

llm = OpenAILike(
    api_base="https://gate.joingonka.ai/v1",
    api_key="jg-tua-chiave",
    model="MiniMaxAI/MiniMax-M2.7",
    is_chat_model=True,
    is_function_calling_model=True,
    context_window=200000,
    max_tokens=8192,
)

def multiply(a: float, b: float) -> float:
    """Moltiplica due numeri."""
    return a * b

agent = FunctionAgent(
    tools=[multiply],
    llm=llm,
    system_prompt="Sei un assistente utile. Per i calcoli usa gli strumenti.",
)

async def main():
    result = await agent.run("Quanto fa 1234 moltiplicato per 5678?")
    print(result)

asyncio.run(main())

Scelta del modello (campo model e relativi limiti context_window / max_tokens):

Il limite max_tokens tramite Gateway arriva fino a 8192 per MiniMax M2.7 e GLM-5.3 Flash, e fino a 32768 per DeepSeek V4 Flash. Se max_tokens non è impostato per una richiesta non in streaming, per impostazione predefinita verranno restituiti fino a 1500 token: per risposte RAG e passaggi degli agenti, specifica il valore esplicitamente.

TypeScript: per LlamaIndex.TS esiste un percorso speculare: la classe OpenAI del pacchetto @llamaindex/openai accetta baseURL e apiKey (o legge le variabili OPENAI_BASE_URL / OPENAI_API_KEY), quindi lo stesso Gateway può essere collegato anche nello stack Node.js. Se stai costruendo applicazioni AI con framework Python, dai un'occhiata anche alla guida su LangChain.