LlamaIndex + Gonka AI — Applicazioni RAG a basso costo

API-chiave JoinGonka: registrati su gate.joingonka.ai/register — all'inizio offriamo 10M di 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 a Gonka:

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,            # 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 via Gateway
)

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

Importante su OpenAILike: specifica obbligatoriamente is_chat_model=True, altrimenti LlamaIndex cercherà di usare il completion-endpoint, che non abbiamo. is_function_calling_model=True abilita i tool calls nativi. Imposta context_window in base al modello affinché LlamaIndex possa suddividere 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 sporadica, ma un flusso costante di richieste: ogni domanda dell'utente comporta 2–5K di token LLM (la domanda stessa più i frammenti di contesto trovati). Calcoliamo i volumi tipici e il loro costo con diversi provider. Prezzi Gonka via JoinGonka Gateway: entrata ~$0.003/1M, uscita ×3.

Con i 10M di token gratuiti puoi testare l'intera pipeline RAG, indicizzare il corpus di test ed eseguire migliaia di richieste senza spendere un centesimo. In volumi di produzione, JoinGonka Gateway trasforma il RAG da un servizio costoso in una voce di spesa impercettibile.

LlamaIndex non solo sa rispondere basandosi sui documenti, ma può anche costruire agenti con strumenti. Entrambi i modelli Gonka supportano tool calling nativo: gli agenti richiamano funzioni in modo strutturato, senza parsing di testo. Esempio di agente con 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 è fino a 8192 per tutti i modelli della rete. Se max_tokens non è specificato per una richiesta non in streaming, di default verranno restituiti fino a 1500 token — per risposte RAG e passi agentici imposta 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 è collegabile nello stack Node.js. Se stai costruendo applicazioni AI su framework Python, dai un'occhiata anche alla guida su LangChain.