LlamaIndex + Gonka AI — Applicazioni RAG a basso costo

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

Installazione:

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

Per un'API arbitraria compatibile con OpenAI, LlamaIndex fornisce la classe OpenAILike dal pacchetto llama_index.llms.openai_like. Un esempio minimo di query a 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="Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    is_chat_model=True,            # Gonka è un endpoint di chat
    is_function_calling_model=True, # il tool calling nativo è supportato
    context_window=131072,         # 128K per Qwen3-235B
    max_tokens=8192,               # limite di output tramite Gateway (Qwen)
)

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

Importante su OpenAILike: assicurati di specificare is_chat_model=True — altrimenti LlamaIndex andrà all'endpoint di completamento, che non abbiamo. is_function_calling_model=True abilita le chiamate native agli strumenti. Imposta context_window in base al modello in modo che LlamaIndex tronchi correttamente il contesto.

Uno scenario classico di LlamaIndex è un indice dei tuoi documenti e le query a esso tramite query_engine. L'LLM globale viene impostato una volta tramite Settings.llm, quindi l'intera pipeline utilizza 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-la-tua-chiave",
    model="Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    is_chat_model=True,
    context_window=131072,
    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. Query alla base di conoscenza
query_engine = index.as_query_engine()
response = query_engine.query("Di cosa tratta questo documento?")
print(response)

Nuanza critica sugli incorporamenti: per impostazione predefinita, VectorStoreIndex utilizza gli incorporamenti OpenAI (text-embedding-ada-002) — si tratta di chiamate a pagamento separate a OpenAI, non a Gonka. Per abbandonare completamente OpenAI, imposta un modello di incorporamento locale tramite Settings.embed_model (come nell'esempio sopra — HuggingFaceEmbedding, pacchetto pip install llama-index-embeddings-huggingface). In questo modo, la generazione avviene tramite Gonka, mentre la vettorizzazione è locale e gratuita.

Costo: una query nella pipeline RAG (ricerca + generazione) consuma circa 2-5K token LLM. Tramite Gonka, si tratta di frazioni di centesimo; tramite OpenAI/Anthropic — 3-4 ordini di grandezza più costoso. Su un flusso di migliaia di query 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 comporta 2-5K token LLM (la domanda stessa più i frammenti di contesto trovati). Calcoliamo i volumi tipici e quanto costano ai diversi fornitori. Prezzi Gonka tramite JoinGonka Gateway: ingresso ~$0.0005/1M, uscita ×3.

Con 10 milioni di token gratuiti, puoi mettere a punto l'intera pipeline RAG, indicizzare un corpus di test ed eseguire migliaia di query — senza spendere un centesimo. Su volumi di produzione, JoinGonka Gateway trasforma il RAG da un servizio costoso a una voce di spesa che può essere completamente ignorata.

LlamaIndex non solo può rispondere ai documenti, ma anche costruire 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-la-tua-chiave",
    model="Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    is_chat_model=True,
    is_function_calling_model=True,
    context_window=131072,
    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. Usa gli strumenti quando necessario.",
)

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

asyncio.run(main())

Selezione del modello (campo model e limiti corrispondenti context_window / max_tokens):

Il limite max_tokens tramite Gateway è fino a 8192 sul modello Qwen3; per Kimi e MiniMax, specifica rispettivamente 3072 e 4096. Se max_tokens non è specificato per una richiesta non in streaming, per impostazione predefinita verranno restituiti fino a 1500 token — per le risposte RAG e i passaggi dell'agente, 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 si connette anche nello stack Node.js. Se stai costruendo applicazioni AI anche su framework Python, vedi anche la guida per LangChain.