LlamaIndex + Gonka AI — Applicazioni RAG a basso costo

Chiave API di JoinGonka: registrati su gate.joingonka.ai/register — per iniziare ti diamo 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 mette a disposizione la classe OpenAILike del pacchetto llama_index.llms.openai_like. Ecco un esempio minimo di chiamata a Gonka:

from llama_index.llms.openai_like import OpenAILike

llm = OpenAILike(
    api_base="https://gate.joingonka.ai/v1",
    api_key="jg-your-key",
    model="MiniMaxAI/MiniMax-M2.7",
    is_chat_model=True,            # Gonka is a chat endpoint
    is_function_calling_model=True, # native tool calling is supported
    context_window=180000,         # MiniMax M2.7 context window
    max_tokens=8192,               # Gateway output cap
)

response = llm.complete("Explain what RAG is in three sentences.")
print(response)

Attenzione con OpenAILike: specifica sempre is_chat_model=True — altrimenti LlamaIndex userà il vecchio endpoint Completions con un prompt grezzo invece di una conversazione. is_function_calling_model=True abilita le tool call native. Imposta context_window in base al modello, così LlamaIndex suddivide correttamente il contesto.

Lo scenario classico di LlamaIndex: un indice sui tuoi documenti e query su di esso tramite query_engine. L'LLM globale si imposta una volta sola con Settings.llm, dopodiché l'intera pipeline usa 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 via Gonka (set once, globally)
Settings.llm = OpenAILike(
    api_base="https://gate.joingonka.ai/v1",
    api_key="jg-your-key",
    model="MiniMaxAI/MiniMax-M2.7",
    is_chat_model=True,
    context_window=180000,
    max_tokens=8192,
)

# 2. Local embeddings (free, no OpenAI)
Settings.embed_model = HuggingFaceEmbedding(
    model_name="BAAI/bge-small-en-v1.5"
)

# 3. Load and index documents from the ./data folder
documents = SimpleDirectoryReader("data").load_data()
index = VectorStoreIndex.from_documents(documents)

# 4. Query the knowledge base
query_engine = index.as_query_engine()
response = query_engine.query("What is this document about?")
print(response)

Dettaglio critico sugli embedding: per impostazione predefinita VectorStoreIndex usa gli embedding di OpenAI (text-embedding-ada-002) — chiamate separate a pagamento verso OpenAI, non verso Gonka. Per eliminare del tutto OpenAI, imposta un modello di embedding locale tramite Settings.embed_model (come nell'esempio qui sopra — HuggingFaceEmbedding, pacchetto pip install llama-index-embeddings-huggingface). Così la generazione passa da Gonka, mentre la vettorizzazione avviene in locale e gratis.

Costi: una singola query di una pipeline RAG (ricerca + generazione) consuma ~2–5K token LLM. Con Gonka parliamo di frazioni di centesimo; con OpenAI/Anthropic costa 3–4 ordini di grandezza in più. Su un flusso di migliaia di query al giorno, la differenza si traduce in decine di migliaia di dollari risparmiati al mese.

Un'applicazione RAG non è una chat una tantum, ma un flusso costante di richieste: ogni domanda dell'utente trascina con sé 2–5K token LLM (la domanda stessa più i frammenti di contesto recuperati). Calcoliamo i volumi tipici e quanto costano presso i diversi provider. Prezzi Gonka tramite JoinGonka Gateway: input ~$0.0062/1M, output ×3.

Con i 3M token gratuiti puoi eseguire le prime richieste della pipeline RAG, indicizzare un corpus di test ed eseguire migliaia di richieste — senza spendere un centesimo. Sui volumi di produzione, JoinGonka Gateway trasforma il RAG da servizio costoso a voce di spesa che puoi non notare affatto.

LlamaIndex non solo risponde sui documenti, ma costruisce anche agenti con strumenti. Tutti e tre i modelli Gonka supportano il native tool calling — gli agenti chiamano le funzioni in modo strutturato, senza parsing del testo. Ecco un esempio di 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-your-key",
    model="MiniMaxAI/MiniMax-M2.7",
    is_chat_model=True,
    is_function_calling_model=True,
    context_window=180000,
    max_tokens=8192,
)

def multiply(a: float, b: float) -> float:
    """Multiplies two numbers."""
    return a * b

agent = FunctionAgent(
    tools=[multiply],
    llm=llm,
    system_prompt="You are a helpful assistant. Use the tools for calculations.",
)

async def main():
    result = await agent.run("What is 1234 multiplied by 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, fino a 32768 per DeepSeek V4 Flash. Se max_tokens non è impostato per una richiesta non in streaming, di default vengono restituiti fino a 1500 token — per risposte RAG e passaggi agentici imposta il valore esplicitamente.

TypeScript: per LlamaIndex.TS esiste un percorso speculare — la classe OpenAI del pacchetto @llamaindex/openai accetta baseURL e apiKey (oppure legge le variabili OPENAI_BASE_URL / OPENAI_API_KEY), così lo stesso Gateway si collega anche nello stack Node.js. Se costruisci applicazioni AI anche con framework Python, dai un'occhiata anche alla guida su LangChain.