RAG multi-tenant dietro un gateway API compatibile con OpenAI
Un'architettura di riferimento pratica per creare una generazione aumentata di recupero dietro un gateway API multimodello: indici con ambito tenant, adattatori di recupero indipendenti dal fornitore, citazioni normalizzate, controlli del ciclo di vita e attribuzione dei costi.
Gli assistenti IA rivolti al cliente necessitano di una generazione aumentata di recupero, ma RAG diventa più difficile quando le richieste passano attraverso un gateway API compatibile con OpenAI invece che attraverso lo stack nativo di un fornitore di modelli. Il gateway deve mantenere isolati i dati del tenant, preservare le citazioni tra i fornitori di modelli, eliminare i contenuti indicizzati nei tempi previsti e attribuire i costi di incorporamento, recupero e generazione al cliente giusto.
La risposta pratica è trattare il recupero come un sottosistema gateway di prima classe. Non nasconderlo all'interno dell'integrazione di un fornitore. Mantieni il recupero separato dalla generazione, fornisci a ogni richiesta un contesto di recupero in base al tenant, normalizza le citazioni prima di restituirle e registra ogni passaggio fatturabile in un registro.
Il problema del lettore
Un team che crea un assistente AI per molti clienti di solito inizia con un flusso semplice: caricare documenti, incorporare blocchi, recuperare le corrispondenze principali, inserire questi snippet nel prompt e chiedere a un modello di rispondere. Funziona finché il prodotto non necessita di più fornitori di modelli, fatturazione a livello di cliente, offboarding e verificabilità.
Il rischio non è solo rappresentato da risposte imprecise. I rischi operativi maggiori sono errori nello spazio dei nomi dei tenant, citazioni non verificabili, indici obsoleti dopo l'eliminazione dei documenti e margini che non possono essere spiegati perché i costi di recupero scompaiono nella spesa per infrastrutture generiche.
Questo articolo separa fatti, raccomandazioni e previsioni. I fatti sono capacità di implementazione documentate dal provider attuale e dalle API del database vettoriale. Le raccomandazioni sono scelte di architettura per un prodotto gateway. Le previsioni indicano i punti in cui è probabile che questa architettura necessiti di flessibilità poiché le funzionalità di recupero del provider continuano a cambiare.
Architettura di riferimento
Una progettazione RAG a livello di gateway dovrebbe avere cinque componenti:
- Risolutore tenant: mappa la chiave API in entrata, l'area di lavoro, l'account cliente o il cliente API Partner su un tenant_id canonico.
- Profilo di recupero: definisce quale corpus cercare, quale modello di incorporamento utilizzare, conteggio dei risultati, filtri, opzioni di riclassificazione, requisiti di citazione e comportamento di fallback.
- Livello adattatore di recupero: chiama il recupero del provider nativo, un database vettoriale esterno o un servizio di ricerca personalizzato tramite un'interfaccia interna.
- Adattatore di assemblaggio e generazione prompt: passa il contesto recuperato al provider del modello scelto senza esporre i dettagli del backend vettoriale ai chiamanti.
- Utilizzo e controllo. registro: registra incorporamento, indicizzazione, recupero, token di richiesta, token di completamento, tenant, modello, provider e identificatori di traccia.
Un contratto con richiesta minima può rimanere neutrale rispetto al fornitore:
{
"tenant_id": "tenant_123",
"model": "modello-compatibile-gpt-o-claude-compatibile",
"retrieval_profile": "support_docs_v2",
"citation_required": vero,
"messaggi": [
{"role": "user", "content": "Qual è la nostra politica di rimborso per i piani annuali?"}
]
}Anche la risposta dovrebbe essere indipendente dal fornitore:
{
"answer": "I piani annuali possono essere rimborsati all'interno della finestra di policy configurata...",
"citazioni": [
{
"source_id": "doc_789",
"title": "Politica di fatturazione",
"url_or_internal_ref": "kb://politica-di-fatturazione",
"chunk_id": "chunk_044",
"offset": {"pagina": 3},
"punteggio": 0,82,
"retrieval_provider": "vettore_db",
"model_provider": "openai_compatibili",
"provider_payload": {}
}
],
"retrieval_trace_id": "rt_456",
"billable_tenant": "tenant_123",
"embedding_usage": null,
"retrieval_usage": {"queries": 1, "risultati": 6},
"model_usage": {"input_tokens": 1920, "output_tokens": 180}}Fatto: le funzionalità di recupero dei provider non sono identiche
L'API Vector Stores di OpenAI supporta archivi vettoriali che possono essere creati, cercati, configurati con strategie di suddivisione in blocchi, associati ai metadati dei file ed eliminati. La ricerca nell'archivio vettoriale supporta query, filtri, conteggi massimi di risultati, opzioni di classificazione, soglie di punteggio e controlli di riscrittura delle query. Questi controlli offrono agli autori del gateway utili manopole per latenza, pertinenza e costi.
I controlli dei dati della piattaforma OpenAI rendono importante anche la progettazione del ciclo di vita: i contenuti dei clienti negli archivi vettoriali vengono conservati fino all'eliminazione. Se un tenant esegue l'offboarding o se un progetto temporaneo scade, il gateway non può presumere che il fornitore rimuoverà automaticamente i contenuti indicizzati dalla pianificazione aziendale del prodotto.
Anthropic espone un modello diverso per le citazioni. Le applicazioni possono fornire blocchi di contenuti dei risultati di ricerca con metadati di origine e titolo e, quando le citazioni sono abilitate, il modello può allegare riferimenti di citazione al testo generato. Esistono vincoli pratici: le impostazioni di citazione dei risultati di ricerca sono tutto o niente all'interno di una richiesta, i blocchi dei risultati di ricerca supportano il contenuto testuale e la granularità delle citazioni dipende da come il contenuto è suddiviso in blocchi.
L'implicazione è diretta: un gateway non dovrebbe esporre la forma di recupero di un fornitore come contratto pubblico a meno che non intenda rendere quel fornitore l'autorità di recupero permanente.
Raccomandazione: utilizzare adattatori di recupero, non recupero. Lock-In
Crea un'interfaccia dell'adattatore di recupero interno. Il gateway può supportare diversi backend:
- Recupero del provider nativo: utile quando un cliente desidera il percorso più veloce per accedere alle funzionalità di ricerca file o archivio vettoriale di un provider.
- Database vettoriale esterno: utile quando il prodotto deve supportare molti fornitori di modelli con isolamento dei tenant e controlli del ciclo di vita coerenti.
- Blocchi di risultati di ricerca precaricati: utile quando il gateway assembla il testo recuperato e lo passa a un provider che supporta un contesto esplicito in grado di riconoscere citazioni.
L'adattatore deve restituire la stessa struttura interna indipendentemente dal backend:
interface RetrievalResult {
recuperoTraceId: stringa;
ID inquilino: stringa;
corpusId: stringa;
pezzi: Array<{
IDorigine: stringa;
titolo: stringa;
testo: stringa;
urlOrInternalRef?: stringa;
ID blocco: stringa;
offset?: { pagina?: numero; byteInizio?: numero; byteFine?: numero; tokenInizio?: numero; tokenEnd?: numero };
punteggio?: numero;
metadati: Record;
providerPayload?: sconosciuto;
}>;
recuperoUtilizzo: {
fornitore: stringa;
queryCount: numero;
risultatoConteggio: numero;
BillableUnits?: numero;
};} Ciò consente al livello di generazione di ricevere il contesto senza sapere se proviene da archivi vettoriali OpenAI, Pinecone, Weaviate, un indice di ricerca full-text del database o un retriever ibrido interno.
L'isolamento del tenant inizia prima della query sul vettore
L'isolamento del tenant non deve dipendere da istruzioni tempestive. Deve essere applicato prima del recupero, al limite dello storage e al limite della query.
Per i sistemi in stile Pinecone, il modello multi-tenancy documentato è uno spazio dei nomi per tenant negli indici serverless. Le operazioni del piano dati hanno come target uno spazio dei nomi, il che semplifica l'isolamento e l'offboarding del tenant perché l'eliminazione dello spazio dei nomi rimuove i record del tenant. Pinecone documenta anche i compromessi tra spazi dei nomi e filtraggio dei metadati: il filtraggio all'interno di un ampio spazio dei nomi condiviso può scansionare più dati, costare di più ed eseguire query più lente rispetto alle query con ambito spazio dei nomi.
Per i sistemi in stile Weaviate, la multi-tenancy archivia ciascun tenant su uno shard separato, quindi i dati di un tenant non sono visibili a un altro tenant. L'eliminazione del tenant elimina lo shard associato. Weaviate supporta anche stati tenant come attivo, inattivo e scaricato, il che crea un'opzione del ciclo di vita per tenant utilizzati raramente.
Elenco di controllo per l'implementazione
- Risolvi tenant_id dall'identità del gateway autenticato, non solo da un campo del corpo fornito dall'utente.
- Mappa tenant_id su uno spazio dei nomi vettoriale, uno shard o un identificatore di archivio vettoriale del provider tramite un lato server registro.
- Rifiuta le richieste in cui il tenant della chiave API e il tenant del corpus richiesto non corrispondono.
- Mantieni i corpora pubblici condivisi separati dai corpora dei tenant privati.
- Utilizza il filtro dei metadati per tipo di documento, lingua, area di prodotto o intervallo di date dopo che il limite del tenant è già stato selezionato.
- Registra spazio dei nomi, shard, corpus_id, retrieval_profile e retrieval_trace_id per verificabilità.
Riserva la ricerca tra tenant per flussi di lavoro amministrativi espliciti con autorizzazioni separate, indici separati o percorsi di aggregazione controllati. Non rendere la ricerca tra tenant un effetto collaterale accidentale dei filtri dei metadati.
Normalizza le citazioni come oggetti gateway
Le citazioni sono un contratto di prodotto, non solo una decorazione. Un assistente dell'assistenza clienti, uno strumento di redazione legale o un assistente conoscitivo interno deve mostrare il motivo per cui è stata prodotta una risposta e da dove proviene il testo di supporto.
Il gateway dovrebbe normalizzare i dati delle citazioni nel proprio schema:
{
"source_id": "doc_123",
"title": "Termini di rimborso",
"url_or_internal_ref": "kb://refund-terms",
"chunk_id": "chunk_006",
"offsets": {"page": 2, "byte_start": 4410, "byte_end": 5020},
"punteggio": 0,79,
"retrieval_provider": "weaviate",
"model_provider": "antropico",
"model_provider_citation_payload": {}
}Mantieni stabili i campi normalizzati e consenti estensioni specifiche del provider. Alcuni fornitori esporranno dettagli sulle citazioni più ricchi di altri. Alcuni citeranno i blocchi dei risultati di ricerca. Alcuni citeranno i file caricati. Alcuni non forniranno l'esatto formato offset richiesto dalla tua applicazione. Il gateway dovrebbe preservare ciò che esiste senza pretendere che ogni fornitore abbia la stessa semantica di citazione.
Modalità citazione rigorosa
Quando citation_required è vero, definisci in anticipo il comportamento di errore. Una modalità rigorosa può richiedere che ogni paragrafo basato sui fatti includa almeno una citazione o che la risposta finale contenga citazioni da blocchi recuperati al di sopra di una soglia minima di punteggio. Se il fornitore del modello selezionato non può soddisfare il contratto di citazione, il gateway dovrebbe fallire rapidamente, utilizzare un fornitore compatibile o restituire un rifiuto strutturato.
Questa è una raccomandazione, non una regola universale. La modalità di citazione rigorosa migliora la fiducia, ma può aumentare i rifiuti, i tentativi e la complessità del fallback. Per i flussi di lavoro creativi a basso rischio, le citazioni potrebbero essere facoltative. Per il supporto rivolto al cliente o flussi di lavoro interni regolamentati, citation_required dovrebbe spesso far parte del profilo di recupero.
Il ciclo di vita dell'indice è una caratteristica del prodotto
I sistemi RAG accumulano dati. I caricamenti temporanei diventano permanenti per sbaglio. Gli ex clienti lasciano gli incorporamenti. I team di prodotto modificano le strategie di suddivisione in blocchi e dimenticano di ricostruire i vecchi indici.Un gateway dovrebbe rendere espliciti i controlli del ciclo di vita.
I controlli del ciclo di vita consigliati includono:
- Scadenza temporanea del corpus: i documenti caricati per una sessione di breve durata devono avere un timestamp di scadenza e un processo di eliminazione.
- Offboarding del tenant: l'eliminazione di un tenant dovrebbe accodare l'eliminazione di spazi dei nomi, shard, archivi di vettori del provider e file correlati oggetti.
- Gestione dei tenant a freddo: dove supportato, i tenant inattivi possono essere contrassegnati come inattivi o scaricati per ridurre l'utilizzo delle risorse.
- Controllo della versione di reindicizzazione: memorizza il modello di incorporamento, la policy di suddivisione in blocchi, la versione del parser e l'indexed_at per ciascun blocco.
- Esposizione dello stato di eliminazione: i flussi di lavoro dell'API partner devono mostrare se l'eliminazione dei documenti, l'eliminazione dei vettori e l'eliminazione lato provider completato.
Il fatto importante è che alcuni contenuti dell'archivio vettoriale vengono conservati fino all'eliminazione. Il consiglio sull'architettura è di rendere l'eliminazione visibile e verificabile invece di seppellirla in un lavoro asincrono senza stato rivolto al cliente.
Traccia tre registri dei costi
Un singolo registro dei token non è sufficiente per RAG. Un gateway necessita di almeno tre registri:
- Costo di incorporamento e indicizzazione: analisi dei documenti, suddivisione in blocchi, chiamate di incorporamento, archiviazione di file, scritture di indici e reindicizzazione.
- Costo di recupero: letture di database vettoriali, ricerca di archivi di vettori nativi, riclassificazione, riscrittura di query ed espansione dei risultati.
- Costo di generazione: token di input dai messaggi degli utenti e recuperati contesto, token di output, chiamate agli strumenti, nuovi tentativi e fallback.
Ciò è particolarmente importante per le agenzie, i fornitori SaaS e i team interni della piattaforma che rivendono o allocano i costi dell'IA. Senza registri separati, i margini RAG diventano difficili da spiegare. Un tenant con utilizzo di piccole generazioni può comunque essere costoso se carica costantemente documenti, reindicizza corpora di grandi dimensioni o esegue query di recupero estese.
Ogni evento del registro deve includere tenant_id, customer_id se diverso, ID chiave API, retrieval_profile, corpus_id, modello, provider, trace_id e unità fatturabili. Ciò consente all'analisi dell'utilizzo di rispondere a domande pratiche: quali tenant hanno profili di recupero costosi, quali corpora sono obsoleti, quali modelli producono errori di citazione e quali clienti generano prompt sovradimensionati perché il recupero restituisce troppo contesto.
Modalità di errore da testare
Un sottosistema RAG gateway dovrebbe disporre di test per le modalità di errore che creano danni visibili al cliente:
- Citazioni mancanti: citation_required è vero, ma la risposta del fornitore non contiene riferimenti a citazioni utilizzabili.
- Indici obsoleti: un documento è stato aggiornato o eliminato, ma i vecchi blocchi appaiono ancora nei risultati del recupero.
- Mancata corrispondenza del tenant: la richiesta viene risolta al tenant A, mentre il corpus o lo spazio dei nomi appartiene al tenant B.
- Recupero eccessivo: il profilo restituisce troppi blocchi, in aumento costi e diluizione della qualità della risposta.
- Mancata corrispondenza delle dimensioni dei blocchi: i blocchi sono così grandi che le citazioni sono imprecise o così piccole che il contesto perde significato.
- Mancata corrispondenza delle funzionalità del fornitore: un modello può emettere citazioni nella forma richiesta mentre un altro no.
- Errore del ciclo di vita: è richiesta l'eliminazione ma l'archiviazione lato provider rimane attiva o non verificato.
Questi test dovrebbero essere eseguiti a livello di contratto del gateway, non solo all'interno dell'adattatore di un fornitore. L'obiettivo è dimostrare che il comportamento pubblico rimane stabile quando cambia il backend di recupero o il provider di generazione.
Compromessi
Il recupero del provider nativo può ridurre il codice dell'applicazione e accelerare una prima versione. Il compromesso è che il ciclo di vita dell'archiviazione, il formato delle citazioni, i controlli delle query e la disponibilità delle funzionalità potrebbero diventare legati a un unico fornitore.
I database vettoriali esterni aggiungono superficie operativa. Il vantaggio è una maggiore portabilità tra modelli compatibili con OpenAI, modelli antropici e fornitori futuri. Inoltre, rendono più semplice ragionare sugli spazi dei nomi o sugli shard con ambito tenant quando il gateway è responsabile della fatturazione e dell'offboarding.
I blocchi a grana fine migliorano la precisione delle citazioni e la verificabilità. Inoltre aumentano la dimensione dell'indice, il volume di recupero e la complessità dell'assemblaggio rapido. Le parti grossolane sono più semplici, ma possono produrre citazioni che rimandano a una pagina o sezione ampia anziché all'esatto passaggio di supporto.
La modalità con richiesta di citazione rigorosa migliora la fiducia dell'utente.Inoltre, forza il gateway a gestire modelli che non possono produrre il formato di citazione richiesto, il che potrebbe significare rifiutare la richiesta, modificare i modelli o restituire una risposta con uno stato di confidenza inferiore.
Previsione: il recupero diventerà più nativo, ma i gateway necessitano ancora del proprio contratto
Le funzionalità di recupero native del provider probabilmente diventeranno più capaci. Più modelli accetteranno il contesto recuperato con metadati di origine strutturati. Più API esporranno controlli di classificazione, riscrittura delle query e impostazioni di citazione. Ciò non elimina la necessità di un contratto gateway.
Il gateway possiede ancora l'identità del tenant, la gestione delle chiavi, i limiti di spesa, l'analisi dell'utilizzo, i flussi di lavoro dell'API Partner e le promesse di eliminazione rivolte al cliente. Le funzionalità del provider possono essere utilizzate dietro il livello dell'adattatore, ma il prodotto non deve forzare ogni tenant, modello e flusso di lavoro di fatturazione nell'astrazione di recupero di un provider.
Conclusione pratica
Crea RAG multi-tenant come sottosistema gateway con confini espliciti. Risolvere l'identità del tenant prima del recupero. Utilizzare spazi dei nomi, partizioni o archivi vettoriali con ambito tenant. Mantenere il recupero dietro gli adattatori. Normalizza le citazioni in uno schema di proprietà del gateway. Aggiungi stati del ciclo di vita e verifica dell'eliminazione. Tieni traccia separatamente dei costi di incorporamento, recupero e generazione.
Questa architettura mantiene RAG con i piedi per terra senza vincolare il prodotto a un fornitore di recupero. Offre inoltre ai team i controlli operativi di cui hanno bisogno quando un assistente AI passa da un prototipo a un sistema rivolto al cliente: isolamento, citazioni, portabilità, gestione del ciclo di vita e attribuzione dei costi.