API per chatbot RAG — assistente di knowledge base basato su Claude in produzione

L'architettura moderna predefinita per chatbot su base di conoscenza

La ricerca tradizionale nella knowledge base restituisce link; l'utente li legge. Il RAG trasforma questo processo in una risposta conversazionale immediata con citazioni. Se fatto bene, gli utenti ricevono risposte in 2 secondi invece di cercare in 5 documenti. Se fatto male, il chatbot allucina e il CTO vieta il progetto per un anno. Questa pagina spiega la differenza.

Lo stack minimo praticabile per la produzione

1. Vector store: pgvector se usi già Postgres, Pinecone o Qdrant per una soluzione gestita
2. Embeddings: text-embedding-3-large, chiamato direttamente su OpenAI — Kunavo non fornisce embeddings e, in ogni caso, la chiamata agli embeddings è separata da quella di generazione
3. Retrieval: ibrido (vettoriale + BM25 con reciprocal rank fusion)
4. Generazione: Claude Sonnet 5 con cache_control nel prompt di sistema
5. UI: risposte in streaming, visualizzazione delle citazioni, fallback «Non lo so»

from openai import OpenAI
client = OpenAI(api_key="sk-kn-...", base_url="https://api.kunavo.com/v1")

def chat(question: str, history: list[dict]) -> dict:
    chunks = hybrid_retrieve(question, k=5)  # vector + BM25
    context = "\n\n---\n\n".join(
        f"[doc:{c['id']}] {c['text']}" for c in chunks
    )
    resp = client.chat.completions.create(
        model="claude-sonnet-5",
        messages=[
            {"role": "system", "content": [{
                "type": "text",
                "text": (
                    "Answer only from Context. Cite [doc:N] for each claim. "
                    "If Context doesn't answer, say 'I don't have that.' "
                    "Be concise, no throat-clearing."
                ),
                "cache_control": {"type": "ephemeral"},
            }]},
            *history,
            {"role": "user", "content": f"# Context\n{context}\n\n# Q\n{question}"},
        ],
        max_tokens=600,
    )
    answer = resp.choices[0].message.content
    cited_ids = parse_citations(answer)  # extract [doc:N] references
    return {"answer": answer, "sources": [c for c in chunks if c["id"] in cited_ids]}

Costo su scala di produzione

• Indicizzazione iniziale: circa $0,25 per 5.000 documenti da 500 token ciascuno
• 1.000 query/giorno: circa $210/mese con caching
• 10.000 query/giorno: circa $2.100/mese
• Se usi Haiku 4.5 invece di Sonnet: circa 4 volte più economico, circa 85% della qualità delle risposte

Analisi architetturale completa nella guida all'implementazione RAG. Note sull'ottimizzazione specifica per lingua nel deep dive sul RAG giapponese e nella guida al RAG spagnolo.

I tre schemi che prevengono davvero le allucinazioni

• Cita ogni affermazione: tag [doc:42] nell'output del modello. Se l'id citato non è nel set recuperato, il modello ha allucinato — blocca e registra
• Rifiuto esplicito nel prompt di sistema: «Se il Contesto non risponde, dì “Non ne ho informazioni.”» Senza questa istruzione, il modello completa usando la conoscenza generale
• Limite di output di 600 token: le risposte brevi sono di solito più accurate. È negli output più lunghi che si insinuano invenzioni aggiuntive

Cosa distribuire nella settimana 1 e nella settimana 4

Inizia da /app/signup

Una ricarica da $10 copre l'indicizzazione iniziale di circa 100.000 documenti e 1.500 query di test — più che sufficiente per un prototipo funzionale, e il saldo non scade mai. Poi leggi la guida RAG completa per gli schemi di produzione.

FAQ