API base di conoscenza: la guida per aggiungere ricerca e risposte con fonti alla Sua app

Integrare una API base di conoscenza significa collegare la Sua app a un motore che cerca nei documenti e restituisce passaggi o risposte con fonti citate, senza dover costruire da zero pipeline di estrazione, chunking e indicizzazione. In pratica si tratta di scegliere tra due tipi di endpoint (ricerca pura o risposta generata), gestire chiavi API in modo sicuro, capire quanto tempo impiega ogni chiamata e quanto costa, e infine mostrare le citazioni nell'interfaccia in modo che l'utente possa verificarle. Questa guida copre tutti questi aspetti con esempi concreti.

Perché usare una API invece di costruire il RAG da zero

Costruire una pipeline RAG interna richiede diverse componenti: un parser per PDF e Word, una strategia di chunking, un database vettoriale, un motore di ricerca ibrida e un livello di orchestrazione che compone il prompt per il modello linguistico. Ognuna di queste scelte ha implicazioni su costi e qualità, come spiegato in Costo di un database vettoriale: cosa si paga davvero e in Chunking per RAG: come dividere i documenti per risposte migliori. Per un team di sviluppo che deve consegnare una funzionalità in poche settimane, affidarsi a una API gestita evita mesi di messa a punto e permette di concentrarsi sull'esperienza utente.

Una piattaforma come Kopik espone questa logica come servizio: Lei carica i documenti una volta, il sistema li indicizza con ricerca ibrida (full-text più espansione semantica), e la Sua app interroga una API REST o un server MCP per ottenere risposte o passaggi grezzi. Il confronto tra questo approccio e altre opzioni (database vettoriali gestiti, pipeline open source) è trattato in Piattaforme RAG as a service a confronto.

I due endpoint principali: ricerca e risposta

Una API base di conoscenza tipica espone due modalità di interrogazione, che corrispondono a due esigenze diverse del Suo prodotto.

Endpoint di ricerca (modalità passages)

Questo endpoint restituisce i passaggi più pertinenti trovati nei documenti, senza generare una sintesi. È utile quando vuole costruire la propria interfaccia di citazione, alimentare un motore di ricerca interno, o passare i risultati a un altro modello linguistico che genererà la risposta finale secondo la Sua logica. Il vantaggio principale è la latenza più bassa, perché non c'è una chiamata aggiuntiva a un modello generativo: il sistema esegue la ricerca ibrida (descritta in dettaglio in Ricerca ibrida: perché BM25 e vettori insieme battono entrambi da soli) e restituisce direttamente i chunk con punteggio di rilevanza.

Endpoint di risposta (modalità answers)

Questo endpoint prende la domanda dell'utente, recupera i passaggi pertinenti e genera una risposta in linguaggio naturale, con i riferimenti ai passaggi usati come fonte. È la modalità più comoda per un chatbot o un assistente integrato nella Sua app, perché l'utente riceve direttamente una frase comprensibile invece di dover leggere estratti grezzi. Il meccanismo tecnico che collega recupero e generazione è descritto passo dopo passo in Come funziona il RAG, passo dopo passo.

Autenticazione e gestione delle chiavi API

Ogni base di conoscenza interrogabile via REST richiede una chiave API associata a un account o a un progetto. Alcune pratiche riducono i rischi di esposizione accidentale delle chiavi, specialmente se la Sua app ha un frontend pubblico:

1. Non inserisca mai la chiave API direttamente nel codice frontend: le chiamate verso la base di conoscenza devono passare da un backend proprio, che aggiunge la chiave lato server.
2. Crei chiavi separate per ambiente di sviluppo e produzione, così un errore in staging non intacca i crediti o l'accesso in produzione.
3. Se la base è privata, verifichi che solo le chiavi autorizzate possano interrogarla: questo evita che documenti riservati finiscano esposti per errore di configurazione.
4. Ruoti periodicamente le chiavi più sensibili, soprattutto se un collaboratore lascia il progetto o se sospetta una fuga di credenziali.
5. Registri un log delle chiamate (domanda, timestamp, base interrogata) per poter diagnosticare costi anomali o usi impropri.

Oltre alla API REST, molte piattaforme offrono anche un server MCP, utilizzabile da client come Claude, Cursor o ChatGPT senza scrivere codice di integrazione: la configurazione è spiegata in Collegare Claude, Cursor o ChatGPT a una base di conoscenza: la guida passo passo e il protocollo stesso in Cos'è MCP (Model Context Protocol). Per un'integrazione dentro la Sua app però, la via più flessibile resta la API REST.

Latenza: cosa aspettarsi e come ottimizzarla

La latenza percepita dall'utente dipende da diverse fasi della chiamata. Conoscerle aiuta a decidere dove investire se l'app deve rispondere in tempo quasi reale.

Se la Sua applicazione richiede risposte quasi istantanee, consideri l'endpoint di ricerca per mostrare subito i passaggi rilevanti, e aggiunga una sintesi generata in un secondo momento (pattern simile allo streaming). Molte API supportano anche lo streaming della risposta token per token, che migliora la percezione di velocità anche se il tempo totale resta simile. Un'altra leva è limitare il numero di passaggi recuperati: meno contesto da elaborare significa generazione più rapida, a scapito però della completezza della risposta.

Costi: crediti, abbonamento e prezzo per domanda

I modelli di prezzo delle API di basi di conoscenza seguono generalmente due logiche, spesso combinabili: crediti prepagati consumati per domanda, oppure un abbonamento con una soglia di utilizzo inclusa. Su Kopik, ad esempio, è possibile acquistare crediti da consumare per ogni domanda posta, oppure sottoscrivere un piano chat a 12 euro al mese con un indicatore di consumo, utile per chi integra l'uso in un prodotto con volumi prevedibili.

Per le basi pubbliche nel catalogo, chi crea la base fissa il prezzo per domanda e trattiene il 70% dei ricavi: questo è rilevante se la Sua app intende rivendere l'accesso a una base di conoscenza specialistica, un modello descritto in Vendere la propria competenza agli agenti IA e in Come monetizzare le proprie competenze da consulente, avvocato o commercialista. Se invece la base è privata e serve solo alla Sua applicazione interna, il costo da monitorare è semplicemente il volume di domande moltiplicato per il prezzo unitario o la quota dell'abbonamento.

• Stimi il volume mensile di domande previste prima di scegliere tra crediti e abbonamento.
• Separi i costi di indicizzazione (una tantum o per aggiornamento documenti) dai costi di interrogazione (ricorrenti).
• Monitori il costo medio per risposta generata rispetto al costo per passaggio recuperato: la modalità passages è quasi sempre più economica.
• Verifichi se esistono limiti di rate o quote giornaliere che potrebbero bloccare picchi di traffico imprevisti.

Mostrare le fonti nell'interfaccia utente

Una risposta generata senza riferimento al documento di origine è difficile da verificare e rischia di essere presa per buona anche quando contiene un'imprecisione. Per questo la maggior parte delle API di basi di conoscenza restituisce, insieme alla risposta, un elenco di passaggi citati con riferimento al documento e, idealmente, al numero di pagina o alla sezione. Integrare questa informazione in UI richiede poco lavoro ma cambia molto la percezione di affidabilità del prodotto.

Alcune pratiche concrete per la Sua interfaccia:

1. Mostri le citazioni come link o riquadri cliccabili subito sotto la risposta, non in una sezione nascosta.
2. Evidenzi nel passaggio citato la frase esatta usata dal modello, se l'API la fornisce.
3. Permetta all'utente di aprire il documento originale o almeno di leggere il contesto completo del passaggio.
4. Segnali chiaramente quando una domanda non trova riscontro nei documenti, invece di lasciare che il modello generi una risposta non supportata.
5. Registri il feedback dell'utente (risposta utile o no) per capire se le citazioni corrispondono davvero a ciò che l'utente cercava.

Questi accorgimenti riducono il rischio di allucinazioni percepite e aiutano l'utente a fidarsi del sistema, un tema approfondito in Come ridurre le allucinazioni dell'IA con risposte basate sulle fonti e in Risposte dell'IA con citazioni: come verificare una risposta sui propri documenti.

Esempio pratico di integrazione passo dopo passo

Ecco un percorso tipico per aggiungere una API base di conoscenza a un'app esistente, ad esempio un portale di assistenza clienti o uno strumento interno per il team supporto.

1. Carichi i documenti di riferimento (manuali, FAQ, policy interne) su una base, pubblica o privata, tramite l'interfaccia di creazione.
2. Testi alcune domande direttamente sul sito per verificare che le risposte siano pertinenti e che i passaggi citati siano corretti.
3. Generi una chiave API dal pannello sviluppatore e la salvi come variabile d'ambiente nel Suo backend, mai nel codice frontend.
4. Implementi una chiamata al Suo backend che inoltra la domanda dell'utente all'endpoint di risposta, passando la chiave API nell'header di autenticazione.
5. Riceva la risposta con i passaggi citati e li mostri in UI come descritto nella sezione precedente.
6. Monitori latenza e consumo di crediti nei primi giorni di produzione, regolando eventualmente il numero di passaggi recuperati per bilanciare qualità e velocità.
7. Aggiorni la base quando i documenti sorgente cambiano, per evitare risposte basate su informazioni superate.

Questo schema vale sia per un caso di customer support, come descritto in RAG per il customer support: come rispondere ai ticket con fonti citate, sia per contesti più verticali come uno studio legale o una funzione compliance interna.