Costruire un assistente RAG su OCI con agenti di IA generativa

Introduzione al concetto di assistente RAG su OCI

Le squadre di supporto spesso possiedono le risposte nei manuali di prodotto, nelle runbook, nelle policy e negli articoli di knowledge base. Il problema principale è trovare rapidamente il passaggio corretto e utilizzarlo per formulare una risposta chiara e contestualizzata.

Questo articolo mostra come costruire un assistente basato su Retrieval‑Augmented Generation (RAG) sfruttando OCI Generative AI Agents. L’assistente recupera informazioni da documenti archiviati in OCI Object Storage prima di generare la risposta, garantendo che le risposte siano ancorate al contenuto interno dell’organizzazione anziché al solo know‑how generale del modello.

Al termine della guida avrai a disposizione:

• Una compartizione dedicata con tutte le risorse OCI necessarie.
• Documenti sorgente caricati in Object Storage.
• Una knowledge base popolata con i contenuti indicizzati.
• Un agente configurato con uno strumento RAG.
• Un endpoint che restituisce risposte corredate da citazioni.

Architettura della soluzione

L’architettura separa l’ingestione dei documenti dal processo di query in tempo reale.

Flusso di ingestione

1. I proprietari dei contenuti caricano i file su Object Storage.

2. Un data source identifica gli oggetti del bucket o i prefissi selezionati.

3. Un job di ingestione elabora i documenti e memorizza le informazioni pronte per il recupero nella knowledge base.

Flusso di query

1. Un client invia un prompt all’endpoint dell’agente.

2. Il modello di routing (LLM) seleziona lo strumento RAG.

3. Lo strumento recupera i passaggi rilevanti dalla knowledge base.

4. Il modello di generazione produce la risposta finale.

Figura 1: Architettura RAG gestita con OCI Object Storage e OCI Generative AI Agents.

Object Storage rimane la fonte di verità. Il job di ingestione trasforma i contenuti selezionati in informazioni indicizzabili e le inserisce nella knowledge base gestita. In fase di runtime, l’agente interroga la knowledge base per estrarre i passaggi pertinenti prima di generare la risposta.

Tutte le risorse sono create all’interno di una tenancy OCI e assegnate a compartimenti per controllare gli accessi, la proprietà e il tracciamento dei costi.

Configurazione dell’infrastruttura OCI

Per semplicità, utilizziamo un compartimento dedicato chiamato genai-rag. Bucket, knowledge base, data source, job di ingestione, agente, strumento RAG ed endpoint verranno creati all’interno di questo compartimento. Un unico compartimento semplifica IAM e il troubleshooting nella fase iniziale.

1. Verifica tenancy, regione e compartimento

Accedi alla Console OCI e assicurati di operare nella tenancy corretta. Usa il selettore di regione nella barra superiore per scegliere una regione elencata in Regions with Generative AI Agents. Object Storage e Generative AI Agents sono servizi regionali, quindi tutte le risorse devono essere create nella stessa regione.

Per creare il compartimento:

• Apri Identity & Security e seleziona Compartments.
• Scegli il compartimento padre (di solito la root tenancy, salvo diversa architettura).
• Fai clic su Create Compartment.
• Inserisci genai-rag come nome, aggiungi una descrizione chiara e applica eventuali tag di costo o proprietà.
• Copia l’OCID del compartimento, necessario per limitare il dynamic group di ingestione.

In ambienti di produzione è consigliabile separare le risorse in compartimenti figli, ad esempio genai-rag-data per i dati e genai-rag-service per i servizi. In tal caso, le politiche IAM devono concedere accesso a Object Storage nel compartimento dati e a Generative AI Agents in quello dei servizi.

Checkpoint: La console è impostata su una regione supportata e il compartimento di destinazione esiste nella tenancy corretta.

2. Configurazione degli accessi IAM

Chiedi a un amministratore di tenancy di creare (o riutilizzare) un gruppo IAM per chi costruirà e gestirà la soluzione. L’amministratore deve definire le policy nella root tenancy o in un compartimento padre che possa concedere i permessi a genai-rag.

Esempio di dichiarazioni di policy a livello di compartimento, da adattare con i nomi reali di gruppo e compartimento:

allow group <group-name> to manage genai-agent-family in compartment genai-rag
allow group <group-name> to manage object-family in compartment genai-rag

La prima riga consente al gruppo di gestire agenti, knowledge base, data source, job di ingestione, strumenti, sessioni, work request ed endpoint. La seconda permette al gruppo di creare il bucket e selezionare gli oggetti durante la configurazione del data source.

Per i job di ingestione a lunga durata, crea un dynamic group per il principal della risorsa di ingestione:

ALL {resource.type = 'genaiagentdataingestionjob', resource.compartment.id = '<genai-rag-compartment-ocid>'}

Concedi al dynamic group il permesso di lettura sugli oggetti:

allow dynamic-group <ingestion-dynamic-group-name> to read objects in compartment genai-rag

Se il bucket risiede in un compartimento diverso, modifica l’ultima istruzione di conseguenza. Gli utenti che configurano il data source devono anch’essi avere accesso a Object Storage nel compartimento del bucket.

I modelli di routing e generazione predefiniti non richiedono policy aggiuntive. Se scegli un modello OCI Generative AI on‑demand o un endpoint dedicato, aggiungi la policy descritta in Getting Access to Generative AI Agents. Rivedi gli esempi con il team di sicurezza e riduci i permessi per i ruoli di produzione.

Checkpoint: Gli sviluppatori possono creare risorse Generative AI Agents e navigare nel bucket, mentre i job di ingestione possono leggere i documenti sorgente.

3. Creazione del bucket Object Storage e caricamento dei documenti

Apri Storage, seleziona Object Storage & Archive Storage e poi Buckets. Imposta lo scope della lista su genai-rag e clicca su Create bucket**.

POST https://generativeai..oraclecloud.com/20231101/agents/<agent-ocid>/endpoints/<endpoint-ocid>/invoke
Authorization: Bearer <api-key>
Content-Type: application/json

{
"prompt": "Qual è la procedura per aggiornare il firmware del router modello X200?",
"temperature": 0.2,
"maxTokens": 500
}

Per aggiornare il firmware del router X200:
1. Accedere all’interfaccia web (vedi documento "RouterX200Guide.pdf", sezione 3.2).
2. Caricare il file firmware.bin (vedi documento "FirmwareRelease2026.pdf", pagina 5).
...
[CITATION: RouterX200Guide.pdf - chunk 12]