Linee guida per lo storage degli oggetti dello strumento RAG per gli agenti AI generativi

Esaminare le sezioni riportate di seguito per preparare i dati dello storage degli oggetti per gli strumenti RAG negli agenti AI generativa.

Linee guida generali

Seguire le linee guida riportate di seguito per preparare i dati per le origini dati degli agenti AI generativa prima di eseguire il caricamento nello storage degli oggetti.

  • Origini dati: i dati per gli agenti AI generativi devono essere caricati come file in un bucket di storage degli oggetti.
  • Numero di bucket: è consentito un solo bucket per ogni origine dati.
  • Tipi di file supportati: sono supportati solo i file PDF e txt.
  • Limite delle dimensioni dei file: ogni file non deve superare i 100 MB.
  • Sommario PDF: i file PDF possono includere immagini, grafici e tabelle di riferimento, ma non devono superare gli 8 MB.
  • Preparazione grafico: non è necessaria alcuna preparazione speciale per i grafici, purché siano bidimensionali con assi con etichetta. Il modello può rispondere a domande sui grafici senza spiegazioni esplicite.
  • Preparazione tabella: utilizzare tabelle di riferimento con diverse righe e colonne. Ad esempio, l'agente può leggere la tabella nella pagina limiti.
  • URL: tutti i collegamenti ipertestuali presenti nei documenti PDF vengono estratti e visualizzati come collegamenti ipertestuali nella risposta della chat.
  • Dati non pronti: se i dati non sono ancora disponibili, creare una cartella vuota per l'origine dati e inserirla in un secondo momento. In questo modo, è possibile includere dati nell'origine dopo che la cartella è stata popolata.
Nota

Impostare le autorizzazioni di storage degli oggetti riportate di seguito prima di continuare.

  • Accesso utente ai file di storage degli oggetti
  • Accesso al job di inclusione dati ai file di storage degli oggetti per job con tempi di esecuzione lunghi

Per informazioni sulle autorizzazioni, vedere Come ottenere l'accesso.

Garantire una migliore comprensione delle tabelle

La migliore comprensione delle tabelle, una funzionalità degli strumenti RAG, mira a migliorare l'accuratezza delle risposte alle query con risposte incorporate nei dati delle tabelle PDF. Elabora queste tabelle per generare risposte più precise e pertinenti in linea con le informazioni in esse contenute. In generale, gli strumenti RAG possono leggere le tabelle. Affinché lo strumento RAG legga le tabelle con una migliore comprensione delle tabelle, assicurarsi che le tabelle abbiano le seguenti funzioni:

  • Tutte le celle della tabella sono separate da linee visibili o limiti di oggetti di altre celle, inclusi i nomi di intestazione nella prima riga.
  • Tutte le colonne, inclusa la prima colonna, hanno un nome intestazione.
  • Ogni tabella ha più di una colonna e più di una riga, esclusa la riga con nomi di intestazione.
Le tabelle incluse con una migliore comprensione delle tabelle vengono elencate quando si includono i dati. Messaggio di esempio:
Count of tables that support enhanced table understanding in following PDFs:
      - enhanced_table_test_data/2025_Report1.pdf has 4 tables processed successfully
      - enhanced_table_test_data/2025_Report2.pdf has 3 tables processed successfully
      - enhanced_table_test_data/2025_Report3.pdf has 3 tables processed successfully

Miglioramento delle risposte con il filtro dei metadati

Utilizzare metadati predefiniti per applicare filtri durante una chat. Quando vengono applicati filtri, le ricerche di un agente in una sessione di chat sono limitate ai file di dati associati ai metadati, aiutando il modello a generare risposte pertinenti all'ambito del contenuto, migliorando così l'accuratezza e la pertinenza delle risposte dell'agente.

I passi riportati di seguito descrivono una panoramica di come utilizzare la funzione di filtro dei metadati. Dopo aver compreso la panoramica del flusso di lavoro, esaminare i dettagli del caso d'uso nelle sezioni fornite dopo i passi della panoramica.

  1. In un editor di testo, creare lo schema dei metadati, necessario per i filtri che si desidera rendere disponibili. Scrivere lo schema in formato JSON. Assegnare al file il nome _metadata_schema.json.

    Esempio:

    {
        "metadataSchema": [
            {
                "name": "publication_year",
                "type": "integer"
            },
            {
                "name": "title",
                "type": "string"
            }
    	]
    }
  2. Caricare il file _metadata_schema.json creato nel passo 1 al livello radice del bucket di storage degli oggetti che contiene i file di dati per una knowledge base.
  3. Creare file JSON per associare i file di dati ai metadati predefiniti e fornire i valori dei metadati.

    Esempio:

    {
        "metadataAttributes": {
            "publication_year": 2020
        }
    } 

    È possibile associare uno o più file di dati o tutti i file in un bucket ai metadati. Per informazioni dettagliate sulle convenzioni dei nomi file JSON da utilizzare per le opzioni scelte, vedere Opzioni filtro metadati (nome file e posizione).

  4. Caricare i file JSON creati nel passo 3 nel bucket di storage degli oggetti che contiene i file di dati per una knowledge base. Per ciascuna opzione, assicurarsi di salvare il file nella posizione corretta nella gerarchia.
  5. Creare una knowledge base. Selezionare lo storage degli oggetti come tipo di data store e l'opzione per avviare automaticamente il job di inclusione.

    Quando i file di dati vengono inclusi, gli agenti AI generativa creano una lista dei nomi dei metadati e dei valori che possono essere selezionati in una chat. Per visualizzare i nomi e i valori dei metadati inclusi, vedere Ottenere i dettagli di una Knowledge Base negli agenti AI generativa.

  6. Creare un agente con uno strumento RAG, selezionando la knowledge base creata nel passo 5. Nell'agente, selezionare l'opzione per creare automaticamente un endpoint. Per assistenza, vedere Creazione di un agente e Creazione di uno strumento RAG.
  7. In una finestra di chat, aggiungere uno o più filtri di metadati predefiniti e selezionare i valori da applicare. Vedere Uso di filtri metadati in una chat.
Nota

Per ulteriori informazioni sulla preparazione dei file JSON dei metadati per il caso d'uso e su come aggiungere e applicare i filtri di metadati in una sessione di chat, consultare le sezioni riportate di seguito.
Opzioni filtro metadati (nome file e ubicazione)

Selezionare uno o più dei seguenti metodi che funzionano meglio per l'utente.

Metodo Nome e posizione file Uso
Includi i metadati per tutti i file in un bucket senza menzionare i nomi dei file. Creare un file _common.metadata.json al livello radice dello storage degli oggetti. Utilizzare questo file per i metadati comuni a tutti i file nel bucket. Questo metodo consente di evitare l'immissione di duplicati di metadati tra gli oggetti.
In un file creare una voce di metadati per ogni file in un bucket e includere i nomi dei file. Creare un file _all.metadata.json al livello radice dello storage degli oggetti. Utilizzare questo metodo se si dispone di molti file e la creazione di un file che include tutti i nomi di file è più conveniente che creare un file di metadati per file.
Creare un file di metadati per ogni file in un bucket. Creare un file <file-name>.metadata.json per ogni file, a livello di file.

<file-name> deve corrispondere al nome del file di dati nel bucket.

Utilizzare questo metodo quando i metadati sono diversi per ogni file e non ci sono molti file per i quali creare un file di metadati o se si sta automatizzando la creazione dei file di metadati.
Aggiungere le intestazioni dei metadati dello storage degli oggetti a ogni file. Aggiungere l'intestazione di metadati tramite la proprietà di metadati dello storage degli oggetti di ogni file. Utilizzare questo metodo, se si dispone di poche proprietà dei metadati da includere. Si consiglia di utilizzare gli altri metodi con i file JSON, poiché i file sono più facili da aggiornare e gestire e le intestazioni dei metadati sono difficili da aggiornare.

Per tutti i metodi, è necessario definire un file di schema dei metadati denominato _metadata_schema.json a livello radice del bucket di storage degli oggetti.

Di seguito è riportata una gerarchia di esempio in cui salvare i file di metadati necessari.

Immagine che mostra la gerarchia per i file di metadati nello storage degli oggetti. bucket_root contiene i seguenti file: _all.metadata.json, _common.metadata.json, _metadata_schema.json, file_0.pdf, file_0.pdf.metadata.json, folder_1 e folder_2. Quindi, folder_1 include file_1.pdf e file_1.pdf.metadata.json e folder_2 include file_2.pdf e file_2.pdf.metadata.json.

Esempi di file JSON dei metadati

I passi riportati di seguito utilizzano esempi per mostrare come formattare i file JSON dei metadati. Vedere anche Limiti per il filtro dei metadati.

  1. Creare un file di schema dei metadati denominato _metadata_schema.json e salvarlo al livello radice dello storage degli oggetti. Esempio:
    {
        "metadataSchema": [
            {
                "name": "field_1",
                "type": "integer"
            },
            {
                "name": "field_2",
                "type": "string"
            },
            {
                "name": "field_3",
                "type": "list_of_string"
            },
            {
                "name": "field_4",
                "type": "double"
            }  
        ]
    }

    Ogni filtro di metadati ha un name e un type.

    I valori consentiti per type sono integer, string, list_of_string e double.

    Esempio:

    {
        "metadataSchema": [
            {
                "name": "rating",
                "type": "double"
            },
            {
                "name": "publication_year",
                "type": "integer"
            },
            {
                "name": "title",
                "type": "string"
            },
            {
                "name": "topic",
                "type": "list_of_string"
            }
        ]
    }
    Mapping dell'indice di esempio per OpenSearch, integer:
    "publication_year": {
      "type": "integer"         
    }
    Mapping dell'indice di esempio per OpenSearch, string:
    "title": {
      "type": "text",
      "fields": {
          "keyword": {
              "type": "keyword"
          },
          "search_as_you_type": {
              "type": "search_as_you_type"
          }
       }
    }
    Mapping dell'indice di esempio per OpenSearch, list_of_string:
    "publishers": {
        "type": "text",
        "fields": {
        "keyword": {
            "type": "keyword"
        },
        "search_as_you_type": {
            "type": "search_as_you_type"
        }
      }
    }
    Mapping dell'indice di esempio per OpenSearch, double:
    "rating": {
      "type": "double"
    }
  2. (Facoltativo) Creare un file JSON denominato _commmon.metadata.json per i metadati comuni a tutti i file in un bucket. Ad esempio:
    {
        "metadataAttributes": {
            "field_1": value_1,
            "field_2": value_2,
            "field_3": value_3,
            ......,
            "field_n": value_n
        }
    }

    Esempio:

    {
        "metadataAttributes": {
            "rating": 3.3,
            "publication_year": "2020",
            "topic": [
                "cooking",
                "health",
                "gardening"
            ]
        }
    }
  3. (Facoltativo) Creare un file JSON denominato _all.metadata.json. In questo file, aggiungere i metadati per ogni file per nome. Ad esempio:
    {
        "folder_1/file_1.pdf" : {
            "metadataAttributes": {
                "field_1": value_1,
                "field_2": value_2,
                "field_3": value_3,
                ......,
                "field_n": value_n
            }
        },
        "folder_2/file_2.pdf": {
            "metadataAttributes": {
                "field_1": value_1,
                "field_2": value_2,
                "field_3": value_3,
                ......,
                "field_n": value_n
            }
        }
    }
  4. (Facoltativo) Aggiungere i metadati separatamente per i file nel bucket creando un file JSON denominato <file-name>.metadata.json per un file.

    <file-name> deve corrispondere al nome del file di dati nel bucket. Ad esempio, il file di dati file1.pdf è associato ai metadati definiti nel file JSON file1.pdf.metadata.json.

    {
        "metadataAttributes": {
            "field_1": value_1,
            "field_2": value_2,
            "field_3": value_3
        }
    }
Nota

Impossibile modificare o rimuovere i campi di metadati dopo l'inclusione dei dati della knowledge base. È possibile aggiungere nuovi campi per il limite consentito. Per rimuovere o aggiornare un campo, ricreare la knowledge base.

Usa filtri metadati in una chat

La procedura riportata di seguito presuppone che siano stati creati lo schema dei metadati richiesto e i file JSON facoltativi del filtro dei metadati, una knowledge base e un agente con uno strumento RAG e un endpoint.

  1. Avviare una chat
  2. Nel pannello a destra, espandere Filtri metadati e selezionare Aggiungi filtro per aggiungere uno o più filtri.
    1. Nel pannello Aggiungi filtro selezionare Aggiungi filtro e utilizzare i menu per selezionare un filtro di metadati predefinito per nome, operatore di condizione e valore di metadati.

      Ad esempio, è possibile aggiungere il filtro topic contains cooking, dove topic è il nome del filtro dei metadati, contains è l'operatore della condizione e cooking è il valore dei metadati.

    2. Selezionare Aggiungi filtro per aggiungere altri filtri in base alle esigenze.

      Per rimuovere un filtro, selezionare l'icona X alla fine della riga.

    3. Al termine, selezionare Aggiungi.

      I filtri aggiunti vengono visualizzati in Filtri metadati nella finestra di chat. Un segno di spunta accanto a un filtro indica che il filtro viene applicato. Se non si desidera applicare un filtro, deselezionare la casella di controllo accanto al filtro.

  3. Avviare una conversazione digitando un messaggio e selezionando Sottometti.

    Durante una sessione di chat, è possibile aggiungere o rimuovere i filtri dei metadati e cancellare o applicare i filtri per continuare la conversazione.

Limiti per filtro metadati
descrizione; Limitato
Numero massimo di voci in _all.metadata.json 10.000
Numero massimo di campi di metadati che è possibile specificare per ogni file 20
Numero massimo di elementi in un list_of_string type 10
Lunghezza massima di un singolo elemento in un tipo list_of_string 50
Lunghezza massima di una chiave metadati in caratteri 25
Lunghezza massima del valore dei metadati in caratteri 50

Aggiunta di metadati a un'intestazione di metadati dello storage degli oggetti

Crea un bucket di storage degli oggetti e carica i file di origine per le risposte RAG negli agenti AI generativi OCI. Facoltativamente, aggiungere un URL personalizzato a ogni file per la citazione.
  1. Nella barra di navigazione della console, selezionare un'area che ospita gli agenti AI generativi, ad esempio Midwest degli Stati Uniti (Chicago). Se non si conosce l'area da selezionare, vedere Aree con agenti AI generativi.
  2. Aprire il menu di navigazione e selezionare Memorizzazione. In Storage degli oggetti e storage di archivio selezionare Bucket.
  3. Selezionare il compartimento in cui si desidera creare un bucket o il compartimento contenente il bucket che si desidera utilizzare. Per aggiungere risorse di storage degli oggetti a questo compartimento, è necessario disporre già dell'autorizzazione seguente.
    allow group <your-group-name> to manage object-family in compartment <compartment-with-bucket>
  4. Per creare un bucket, effettuare le operazioni riportate di seguito.
    1. Selezionare Crea bucket.
    2. Immettere un nome univoco per l'area per il bucket.
    3. Per gli altri campi, selezionare i collegamenti Ulteriori informazioni, quindi selezionare le opzioni applicabili ai dati. Vedere anche Creazione di un bucket di storage degli oggetti.
    4. Selezionare Crea.
      Per impostazione predefinita, un nuovo bucket è privato. È possibile modificare la visibilità di un bucket dopo averlo creato.
  5. Selezionare il nome del bucket che si desidera utilizzare.
  6. Nella pagina dei dettagli del bucket, in Oggetti, selezionare Carica.
  7. (Facoltativo) Selezionare Mostra intestazioni e metadati facoltativi, quindi selezionare e immettere i valori riportati di seguito.
    • Tipo: metadati
    • Nome: gaas-metadata-filtering-field-<metadata-name>
    • Valore: <metadata-value>
    Importante

    Perché il filtro dei metadati funzioni, è necessario utilizzare il prefisso gaas-metadata-filtering-field- per il nome dei metadati.

    Object Storage quindi antepone opc-meta- al nome dei metadati, in modo che l'intestazione venga visualizzata come opc-meta-gaas-metadata-filtering-field-<metadata-name>.

    Ad esempio, per aggiungere un metadati con il nome publication_year, aggiungere un'intestazione di metadati con il nome gaas-metadata-filtering-field-publication_year. Quando si ottengono i dettagli per questo file, il nome dei metadati viene visualizzato come opc-meta-gaas-metadata-filtering-field-publication_year.

    Per i valori di elenco, utilizzare il formato seguente:

    _LIST_OF_STRING_|list_value_1|list_value_2, dove _LIST_OF_STRING_ è fisso e ogni elemento della lista è separato da una barra verticale '|'. Questo formato viene decodificato come elenco di valori: {list_value_1, list_value_2}

  8. Aggiungere uno o più file per l'origine dati e selezionare Carica.
    Nota

Aggiunta di dati con URL personalizzato a un bucket di storage degli oggetti

Crea un bucket di storage degli oggetti e carica i file di origine per le risposte RAG negli agenti AI generativi OCI. Facoltativamente, aggiungere un URL personalizzato a ogni file per la citazione.
  1. Nella barra di navigazione della console, selezionare un'area che ospita gli agenti AI generativi, ad esempio Midwest degli Stati Uniti (Chicago). Se non si conosce l'area da selezionare, vedere Aree con agenti AI generativi.
  2. Aprire il menu di navigazione e selezionare Memorizzazione. In Storage degli oggetti e storage di archivio selezionare Bucket.
  3. Selezionare il compartimento in cui si desidera creare un bucket o il compartimento contenente il bucket che si desidera utilizzare. Per aggiungere risorse di storage degli oggetti a questo compartimento, è necessario disporre già dell'autorizzazione seguente.
    allow group <your-group-name> to manage object-family in compartment <compartment-with-bucket>
  4. Per creare un bucket, effettuare le operazioni riportate di seguito.
    1. Selezionare Crea bucket.
    2. Immettere un nome univoco per l'area per il bucket.
    3. Per gli altri campi, selezionare i collegamenti Ulteriori informazioni, quindi selezionare le opzioni applicabili ai dati. Vedere anche Creazione di un bucket di storage degli oggetti.
    4. Selezionare Crea.
      Per impostazione predefinita, un nuovo bucket è privato. È possibile modificare la visibilità di un bucket dopo averlo creato.
  5. Selezionare il nome del bucket che si desidera utilizzare.
  6. Nella pagina dei dettagli del bucket, in Oggetti, selezionare Carica.
  7. (Facoltativo) Selezionare Mostra intestazioni e metadati facoltativi, quindi selezionare e immettere i valori riportati di seguito.
    • Tipo: metadati
    • Nome: customized_url_source
    • Valore: <Custom-URL-for-the-file>
    Importante

    Perché l'override del collegamento alla citazione funzioni, è necessario utilizzare Nome: customized_url_source.
  8. Aggiungere uno o più file per l'origine dati e selezionare Carica.
    Nota

    Se nel passo 7 sono stati aggiunti i metadati customized_url_source a un oggetto, questo URL personalizzato si applica a tutti i file caricati per questo oggetto. Impossibile aggiornare la proprietà metadata degli oggetti esistenti. In alternativa, è possibile copiare un file, aggiungere nuovi metadati al file e quindi eliminare il file precedente. Per aggiungere o aggiornare un file con i metadati customized_url_source, utilizzando l'interfaccia CLI OCI, vedere Assegnazione di un URL personalizzato a un citazione.
Nota

Clienti beta:

Se è stata creata una knowledge base nella fase beta, potrebbe essere necessario eliminare e ricreare l'origine dati per il funzionamento della funzione di gestione degli URL.

Assegnazione di un URL personalizzato a una citazione

Quando un agente utilizza l'AG per le risposte, è possibile ottenere le citazioni. Per impostazione predefinita, le citazioni puntano allo storage degli oggetti in cui vengono memorizzati i file. Per fare riferimento a un URL anziché al file a cui viene fatto riferimento, è possibile aggiungere un URL personalizzato all'oggetto metadata per tale file.

Questo argomento mostra come aggiungere o aggiornare l'oggetto metadata tramite l'interfaccia CLI OCI.

  1. Avviare l'interfaccia CLI OCI in un ambiente o in Cloud Shell. Si consiglia di provare in Cloud Shell prima di familiarizzare con i comandi.
  2. Ottenere il nome oggetto per il file a cui si desidera aggiungere un URL personalizzato:
    oci os object list --bucket-name <the-bucket-name> 
    --file <the-file-name>
    Output di esempio:
    "data": [
        {
          "archival-state": null,
          "etag": "xxx",
          "md5": "xxx==",
          "name": "<the-object-name>",
          "size": 1117630,
          "storage-tier": "Standard",
          "time-created": "2025-03-12T22:21:26.991000+00:00",
          "time-modified": "2025-03-12T22:38:10.217000+00:00"
        },
    Other objects are listed similarly after this comma.

    È inoltre possibile trovare il nome dell'oggetto nella console. Nella pagina dei dettagli del bucket, selezionare il menu Azioni Menu Azioni per l'oggetto, selezionare Visualizza dettagli oggetto e copiare il nome.

    Nota

    Se un file si trova in una cartella, il nome del file e il relativo nome oggetto differiscono. Ad esempio, per un file denominato file1.pdf, il nome dell'oggetto potrebbe essere folder1/file1.pdf. In caso contrario, il nome file e il nome oggetto sono uguali.
  3. Scaricare il file nella directory di lavoro corrente.

    Per aggiungere o aggiornare un oggetto metadata di un file, sostituire il file con lo stesso file con un nuovo oggetto metadata. Ecco perché stai prima copiando il file nella directory di lavoro corrente.

    oci os object get 
    --bucket-name <the-bucket-name> 
    --file <the-file-name>
    --name <the-object-name>
  4. Trovare i valori dell'oggetto metadata per il file corrente.
    oci os object head 
    --bucket-name <the-bucket-name> 
    --name <the-object-name>
    Output di esempio:
    {
     some data
    
      "opc-client-request-id": "xxx",
      "opc-meta-key1": "value1",
      "opc-meta-key2": "value2",
      "opc-request-id": "xxx",
     ...
    }
    

    Questo esempio mostra che il valore dell'oggetto metadata è '{"key1":"value1","key2":"value2"}'. Il nome metadata viene salvato con il prefisso opc-meta-, ma non è necessario aggiungere questo prefisso quando si aggiunge il nome metadata nei passi successivi. Questo prefisso viene aggiunto automaticamente a ogni nome metadata.

  5. Sostituire il file presente nello storage degli oggetti con lo stesso file presente nella directory di lavoro corrente e aggiungere un nuovo oggetto metadata.

    Per conservare i metadati correnti e aggiungere il nome e i valori dell'URL personalizzato, '{"customized_url_source":"<the-custom-url>" all'oggetto metadata:

    oci os object put 
    --bucket-name <the-bucket-name> 
    --file <the-file-name> 
    --name <the-object-name>
    --force --metadata 
    '{"customized_url_source":"<the-custom-url>",
    "<existing-metadata-name-1>":"<existing-metadata-value-1>"
    "<existing-metadata-name-2>":"<existing-metadata-value-2>"}'

    Ad esempio, per mantenere i nomi e i valori di metadata visualizzati nell'esempio del passo 4:

    oci os object put 
    --bucket-name <the-bucket-name> 
    --file <the-file-name> 
    --name <the-object-name>
    --force --metadata 
    '{"customized_url_source":"<the-custom-url>",
    "key1":"value1",
    "key2":"value2"}'

    Per sostituire l'oggetto metadata esistente per includere solo l'URL personalizzato, eseguire il comando seguente

    oci os object put 
    --bucket-name <the-bucket-name> 
    --file <the-file-name> 
    --name <the-object-name>
    --force --metadata '{"customized_url_source":"<the-custom-url>"}'
  6. Assicurarsi che l'oggetto metadata per l'URL personalizzato venga sostituito.
    oci os object head 
    --bucket-name <the-bucket-name> 
    --name <the-object-name>
    Output di esempio:
    {
     some data
    
      "opc-meta-customized_url_source": "some-new-link",
     ...
    }
    
Importante

  • L'oggetto metadata che sostituisce la citazione predefinita deve avere il nome customized_url_source.
  • È possibile avere un oggetto metadata con il nome customized_url_source
  • Ogni customized_url_source può avere un solo URL.
  • I comandi del passo 5 funzionano sia per l'aggiunta che per l'aggiornamento dell'oggetto metadata, poiché sostituiscono il valore dell'oggetto metadata corrente.
  • Assicurarsi di passare i valori per l'oggetto --metadata con il formato mostrato nei comandi nel passo 5.
Link