Directrices de almacenamiento de objetos de la herramienta RAG para agentes de IA generativa

Revise las siguientes secciones para preparar los datos de Object Storage para las herramientas RAG en los agentes de IA generativa.

Guías generales

Siga estas directrices para preparar datos para orígenes de datos de agentes de IA generativa antes de cargarlos en Object Storage:

  • Orígenes de datos: los datos de los agentes de IA generativa se deben cargar como archivos en un cubo de Object Storage.
  • Número de cubos: solo se permite un cubo por origen de datos.
  • Tipos de archivos soportados: solo están soportados los archivos PDF y txt.
  • Límite de tamaño de archivo: cada archivo no debe tener más de 100 MB.
  • Contenido PDF: los archivos PDF pueden incluir imágenes, gráficos y tablas de referencia, pero no deben superar los 8 MB.
  • Preparación del gráfico: no se necesita ninguna preparación especial para los gráficos, siempre que sean bidimensionales con ejes con etiquetas. El modelo puede responder preguntas sobre los gráficos sin explicaciones explícitas.
  • Preparación de la Tabla: Utilice tablas de referencia con varias filas y columnas. Por ejemplo, el agente puede leer la tabla en la página límites.
  • URL: todos los hipervínculos presentes en los documentos PDF se extraen y se muestran como hipervínculos en la respuesta de chat.
  • Datos no listos: si los datos aún no están disponibles, cree una carpeta vacía para el origen de datos y rellénela más tarde. De esta forma, puede ingerir datos en el origen después de rellenar la carpeta.
Nota

Configure los siguientes permisos de Object Storage antes de continuar.

  • Acceso de usuario a archivos de Object Storage
  • Acceso de trabajo de ingesta de datos a archivos de Object Storage para trabajos de larga ejecución

Consulte Obtención de acceso para obtener los permisos.

Garantía de una mejor comprensión de las tablas

La comprensión mejorada de las tablas, una función de las herramientas de RAG, tiene como objetivo mejorar la precisión de las respuestas a las consultas con respuestas incrustadas en los datos de las tablas PDF. Procesa estas tablas para generar respuestas más precisas y relevantes alineadas con la información que contienen. En general, las herramientas de RAG pueden leer las tablas. Para que la herramienta RAG lea las tablas con una comprensión mejorada de las tablas, asegúrese de que las tablas tengan las siguientes funciones:

  • Todas las celdas de la tabla se separan con líneas visibles o límites de objetos de otras celdas, incluidos los nombres de cabecera de la primera fila.
  • Todas las columnas, incluida la primera columna, tienen un nombre de cabecera.
  • Cada tabla tiene más de una columna y más de una fila, excluyendo la fila con nombres de cabecera.
Las tablas que se ingieren con una mejor comprensión de las tablas se muestran al ingerir los datos. Mensaje de ejemplo:
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

Mejora de respuestas con filtrado de metadatos

Utilizar metadatos predefinidos para aplicar filtros durante un chat. Cuando se aplican filtros, las búsquedas de un agente en una sesión de chat se limitan a los archivos de datos asociados a los metadatos, lo que ayuda al modelo a generar respuestas relevantes para el ámbito de contenido, mejorando así la precisión y relevancia de la respuesta del agente.

Los siguientes pasos describen una descripción general de cómo utilizar la función de filtrado de metadatos. Después de comprender la descripción general del flujo de trabajo, revise los detalles del caso de uso en las secciones proporcionadas después de los pasos de descripción general.

  1. En un editor de texto, cree el esquema de metadatos, que es necesario para los filtros que desea que estén disponibles. Escriba el esquema en formato JSON. Asigne al archivo el nombre _metadata_schema.json.

    Ejemplo:

    {
        "metadataSchema": [
            {
                "name": "publication_year",
                "type": "integer"
            },
            {
                "name": "title",
                "type": "string"
            }
    	]
    }
  2. Cargue el archivo _metadata_schema.json creado en el paso 1 en el nivel raíz del cubo de Object Storage que contiene los archivos de datos para una base de conocimientos.
  3. Cree archivos JSON para asociar archivos de datos a los metadatos predefinidos y proporcione los valores de metadatos.

    Ejemplo:

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

    Puede asociar uno o más archivos de datos o todos los archivos de un cubo a los metadatos. Para obtener más información sobre las convenciones de nombre de archivo JSON que se deben utilizar para las opciones que elija, consulte Opciones de filtro de metadatos (nombre de archivo y ubicación).

  4. Cargue los archivos JSON creados en el paso 3 en el cubo de Object Storage que contiene los archivos de datos para una base de conocimientos. Para cada opción, asegúrese de guardar el archivo en la ubicación correcta en la jerarquía.
  5. Cree una base del conocimiento. Seleccione Object Storage como tipo de almacén de datos y la opción para iniciar automáticamente el trabajo de ingesta.

    Cuando se ingieren los archivos de datos, los agentes de IA generativa crean una lista de los nombres de metadatos y los valores que se pueden seleccionar en un chat. Para ver los nombres y valores de metadatos ingeridos, consulte Obtención de detalles de una base de conocimientos en agentes de IA generativa.

  6. Cree un agente con una herramienta RAG, seleccionando la base de conocimientos creada en el paso 5. En el agente, seleccione la opción para crear automáticamente un punto final. Si necesita ayuda, consulte Creación de un Agente y Creación de una Herramienta RAG.
  7. En una ventana de chat, agregue uno o más filtros de metadatos predefinidos y seleccione los valores que desea aplicar. Consulte Uso de filtros de metadatos en un chat.
Nota

Revise las siguientes secciones para obtener más información sobre la preparación de archivos JSON de metadatos para su caso de uso y cómo agregar y aplicar filtros de metadatos en una sesión de chat.
Opciones de filtro de metadatos (nombre de archivo y ubicación)

Seleccione uno o más de los siguientes métodos que mejor se adapten a sus necesidades.

Método Nombre de Archivo y Ubicación Sintaxis
Incluya metadatos para todos los archivos de un cubo sin mencionar los nombres de archivo. Cree un archivo _common.metadata.json en el nivel raíz de Object Storage. Utilice este archivo para los metadatos que son comunes a todos los archivos del cubo. Este método ayuda a evitar la introducción de duplicados de metadatos entre objetos.
En un archivo, cree una entrada de metadatos para cada archivo de un cubo e incluya los nombres de archivo. Cree un archivo _all.metadata.json en el nivel raíz de Object Storage. Utilice este método si tiene muchos archivos y crear un archivo que incluya todos los nombres de archivo es más conveniente para usted que crear un archivo de metadatos por archivo.
Cree un archivo de metadatos para cada archivo de un cubo. Cree un archivo <file-name>.metadata.json para cada archivo, en el nivel de archivo.

<file-name> debe coincidir con el nombre del archivo de datos del cubo.

Utilice este método cuando los metadatos difieran para cada archivo y no haya muchos archivos para los que crear un archivo de metadatos o si está automatizando la creación de los archivos de metadatos.
Agregue cabeceras de metadatos de Object Storage a cada archivo. Agregue una cabecera de metadatos a través de la propiedad de metadatos de Object Storage de cada archivo. Utilice este método si tiene pocas propiedades de metadatos que incluir. Recomendamos utilizar los otros métodos con archivos JSON, ya que los archivos son más fáciles de actualizar y gestionar y las cabeceras de metadatos son difíciles de actualizar.

Para todos los métodos, debe definir un archivo de esquema de metadatos denominado _metadata_schema.json en el nivel raíz del cubo de Object Storage.

A continuación, se muestra un ejemplo de jerarquía en la que se guardan los archivos de metadatos que se necesitan.

Imagen que muestra la jerarquía de los archivos de metadatos en Object Storage. El archivo bucket_root tiene los siguientes archivos: _all.metadata.json, _common.metadata.json, _metadata_schema.json, file_0.pdf, file_0.pdf.metadata.json, folder_1 y folder_2. A continuación, folder_1 incluye file_1.pdf y file_1.pdf.metadata.json y folder_2 incluye file_2.pdf y file_2.pdf.metadata.json.

Ejemplos de archivos JSON de metadatos

Los siguientes pasos utilizan ejemplos para mostrar cómo formatear los archivos JSON de metadatos. Consulte también Límites para filtrado de metadatos.

  1. Cree un archivo de esquema de metadatos denominado _metadata_schema.json y guárdelo en el nivel raíz de Object Storage. Por ejemplo:.
    {
        "metadataSchema": [
            {
                "name": "field_1",
                "type": "integer"
            },
            {
                "name": "field_2",
                "type": "string"
            },
            {
                "name": "field_3",
                "type": "list_of_string"
            },
            {
                "name": "field_4",
                "type": "double"
            }  
        ]
    }

    Cada filtro de metadatos tiene un name y un type.

    Los valores permitidos para type son integer, string, list_of_string y double.

    Ejemplo:

    {
        "metadataSchema": [
            {
                "name": "rating",
                "type": "double"
            },
            {
                "name": "publication_year",
                "type": "integer"
            },
            {
                "name": "title",
                "type": "string"
            },
            {
                "name": "topic",
                "type": "list_of_string"
            }
        ]
    }
    Asignación de índice de ejemplo para OpenSearch, integer:
    "publication_year": {
      "type": "integer"         
    }
    Asignación de índice de ejemplo para OpenSearch, string:
    "title": {
      "type": "text",
      "fields": {
          "keyword": {
              "type": "keyword"
          },
          "search_as_you_type": {
              "type": "search_as_you_type"
          }
       }
    }
    Asignación de índice de ejemplo para OpenSearch, list_of_string:
    "publishers": {
        "type": "text",
        "fields": {
        "keyword": {
            "type": "keyword"
        },
        "search_as_you_type": {
            "type": "search_as_you_type"
        }
      }
    }
    Asignación de índice de ejemplo para OpenSearch, double:
    "rating": {
      "type": "double"
    }
  2. (Opcional) Cree un archivo JSON denominado _commmon.metadata.json para los metadatos que son comunes a todos los archivos de un cubo. Por ejemplo:
    {
        "metadataAttributes": {
            "field_1": value_1,
            "field_2": value_2,
            "field_3": value_3,
            ......,
            "field_n": value_n
        }
    }

    Ejemplo:

    {
        "metadataAttributes": {
            "rating": 3.3,
            "publication_year": "2020",
            "topic": [
                "cooking",
                "health",
                "gardening"
            ]
        }
    }
  3. (Opcional) Cree un archivo JSON denominado _all.metadata.json. En este archivo, agregue metadatos para cada archivo por nombre. Por ejemplo:
    {
        "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. (Opcional) Agregue metadatos por separado para los archivos del cubo mediante la creación de un archivo JSON denominado <file-name>.metadata.json para un archivo.

    <file-name> debe coincidir con el nombre del archivo de datos del cubo. Por ejemplo, el archivo de datos file1.pdf está asociado a los metadatos definidos en el archivo JSON file1.pdf.metadata.json.

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

No puede cambiar ni eliminar los campos de metadatos una vez que se ingieren los datos de la base de conocimientos. Puede agregar nuevos campos hasta el límite permitido. Para eliminar o actualizar un campo, vuelva a crear la base de conocimientos.

Uso de filtros de metadatos en un chat

En el siguiente procedimiento se asume que ha creado el esquema de metadatos necesario y los archivos JSON de filtro de metadatos opcionales, una base de conocimientos y un agente con una herramienta RAG y un punto final.

  1. Iniciar Chat.
  2. En el panel de la derecha, amplíe Filtros de metadatos y seleccione Agregar filtro para agregar uno o más filtros.
    1. En el panel Agregar filtro, seleccione Agregar filtro y utilice los menús para seleccionar un filtro de metadatos predefinido por nombre, un operador de condición y un valor de metadatos.

      Por ejemplo, puede agregar el filtro topic contains cooking, donde topic es el nombre del filtro de metadatos, contains es el operador de condición y cooking es el valor de metadatos.

    2. Seleccione Agregar filtro para agregar más filtros según sea necesario.

      Para eliminar un filtro, seleccione el icono X que se encuentra al final de la fila.

    3. Cuando haya terminado, seleccione Agregar.

      Los filtros agregados aparecen en Filtros de metadatos en la ventana de chat. Una marca de verificación junto a un filtro significa que se aplica el filtro. Si no desea aplicar un filtro, desactive la casilla de control situada junto al filtro.

  3. Inicie una conversación escribiendo un mensaje y seleccionando Enviar.

    Durante una sesión de chat, puede agregar o eliminar filtros de metadatos y borrar o aplicar filtros para continuar la conversación.

Límites para el filtrado de metadatos
Descripción Limitar
Número máximo de entradas en _all.metadata.json 10.000
Número máximo de campos de metadatos que se pueden especificar para cada archivo 20
Número máximo de elementos en list_of_string type 10
Longitud máxima de elemento individual en un tipo list_of_string 50
Longitud máxima de una clave de metadatos en caracteres 25
Longitud máxima del valor de metadatos en caracteres 50

Adición de metadatos a una cabecera de metadatos de Object Storage

Cree un cubo de Object Storage y cargue los archivos de origen para las respuestas de RAG en los agentes de IA generativa de OCI. Opcionalmente, agregue una URL personalizada a cada archivo para citar.
  1. En la barra de navegación de la consola, seleccione una región que aloje agentes de IA generativa, por ejemplo, US Midwest (Chicago). Si no sabe qué región seleccionar, consulte Regiones con agentes de IA generativa.
  2. Abra el menú de navegación y seleccione Almacenamiento. En Object Storage & Archive Storage, seleccione Cubos.
  3. Seleccione el compartimento en el que desea crear un cubo o el compartimento que contiene el cubo que desea utilizar. Ya debe tener el siguiente permiso para agregar recursos de Object Storage a este compartimento.
    allow group <your-group-name> to manage object-family in compartment <compartment-with-bucket>
  4. Para crear un cubo, siga estos pasos:
    1. Seleccione Crear cubo.
    2. Introduzca un nombre único para la región del cubo.
    3. Para otros campos, seleccione los enlaces Más información y, a continuación, seleccione las opciones que se aplican a los datos. Consulte también Creación de un cubo de Object Storage.
    4. Haga clic en Crear.
      Por defecto, un nuevo bloque es privado. Puede cambiar la visibilidad de un bloque después de crearlo.
  5. Seleccione el nombre del cubo que desea utilizar.
  6. En la página Detalles de cubo, en Objetos, seleccione Cargar.
  7. (Opcional) Seleccione Mostrar cabeceras y metadatos opcionales y, a continuación, seleccione e introduzca los siguientes valores.
    • Tipo: metadatos
    • Name: gaas-metadata-filtering-field-<metadata-name>
    • Valor: <metadata-value>
    Importante

    Para que el filtrado de metadatos funcione, debe utilizar el prefijo gaas-metadata-filtering-field- para el nombre de metadatos.

    A continuación, Object Storage antepone opc-meta- al nombre de metadatos, por lo que la cabecera se muestra como opc-meta-gaas-metadata-filtering-field-<metadata-name>.

    Por ejemplo, para agregar metadatos con el nombre publication_year, agregue una cabecera de metadatos con el nombre gaas-metadata-filtering-field-publication_year. Al obtener los detalles de este archivo, el nombre de metadatos se muestra como opc-meta-gaas-metadata-filtering-field-publication_year.

    Para los valores de lista, utilice el siguiente formato:

    _LIST_OF_STRING_|list_value_1|list_value_2, donde _LIST_OF_STRING_ es fijo, y cada elemento de lista está separado por un carácter '|' de pleca. Este formato se descodifica como una lista de valores: {list_value_1, list_value_2}

  8. Agregue uno o más archivos para el origen de datos y seleccione Cargar.
    Nota

    • No puede actualizar la propiedad metadata de los objetos existentes. En su lugar, puede copiar un archivo, agregar nuevos metadatos a ese archivo y, a continuación, suprimir el archivo antiguo.

    • Puede agregar filtros a la conversación de chat con un agente mediante el filtrado de metadatos después de ingerir los datos de la base de conocimientos de Object Storage y sus metadatos. Para obtener más información sobre cómo agregar filtros, consulte el paso 11 en Chatting with Agents in Generative AI Agents. También puede ver los detalles de los valores de metadatos después de ingerir los datos en una base de conocimientos. Consulte el recurso Metadata en Getting a Knowledge Base's Details in Generative AI Agents.

Adición de datos con una URL personalizada a un cubo de Object Storage

Cree un cubo de Object Storage y cargue los archivos de origen para las respuestas de RAG en los agentes de IA generativa de OCI. Opcionalmente, agregue una URL personalizada a cada archivo para citar.
  1. En la barra de navegación de la consola, seleccione una región que aloje agentes de IA generativa, por ejemplo, US Midwest (Chicago). Si no sabe qué región seleccionar, consulte Regiones con agentes de IA generativa.
  2. Abra el menú de navegación y seleccione Almacenamiento. En Object Storage & Archive Storage, seleccione Cubos.
  3. Seleccione el compartimento en el que desea crear un cubo o el compartimento que contiene el cubo que desea utilizar. Ya debe tener el siguiente permiso para agregar recursos de Object Storage a este compartimento.
    allow group <your-group-name> to manage object-family in compartment <compartment-with-bucket>
  4. Para crear un cubo, siga estos pasos:
    1. Seleccione Crear cubo.
    2. Introduzca un nombre único para la región del cubo.
    3. Para otros campos, seleccione los enlaces Más información y, a continuación, seleccione las opciones que se aplican a los datos. Consulte también Creación de un cubo de Object Storage.
    4. Haga clic en Crear.
      Por defecto, un nuevo bloque es privado. Puede cambiar la visibilidad de un bloque después de crearlo.
  5. Seleccione el nombre del cubo que desea utilizar.
  6. En la página Detalles de cubo, en Objetos, seleccione Cargar.
  7. (Opcional) Seleccione Mostrar cabeceras y metadatos opcionales y, a continuación, seleccione e introduzca los siguientes valores.
    • Tipo: metadatos
    • Name: customized_url_source
    • Valor: <Custom-URL-for-the-file>
    Importante

    Para que la sustitución del enlace de cita funcione, debe utilizar Nombre: customized_url_source.
  8. Agregue uno o más archivos para el origen de datos y seleccione Cargar.
    Nota

    Si ha agregado los metadatos customized_url_source a un objeto en el paso 7, esta URL personalizada se aplica a todos los archivos que cargue para este objeto. No puede actualizar la propiedad metadata de los objetos existentes. En su lugar, puede copiar un archivo, agregar nuevos metadatos a ese archivo y, a continuación, suprimir el archivo antiguo. Para agregar o actualizar un archivo con los metadatos customized_url_source mediante la CLI de OCI, consulte Asignación de una URL personalizada a una citación.
Nota

Clientes beta:

Si creó una base de conocimientos en la fase beta, es posible que deba suprimir y volver a crear el origen de datos para que funcione la función de manejo de URL.

Asignación de una URL personalizada a una cita

Cuando un agente utiliza la RAG para sus respuestas, puede obtener citas. Por defecto, las citas apuntan a Object Storage donde se almacenan los archivos. Para hacer referencia a una URL en lugar del archivo al que se hace referencia, puede agregar una URL personalizada al objeto metadata para ese archivo.

En este tema se muestra cómo agregar o actualizar el objeto metadata mediante la CLI de OCI.

  1. Inicie la CLI de OCI en un entorno o en Cloud Shell. Recomendamos que primero lo pruebe en Cloud Shell para familiarizarse con los comandos.
  2. Obtenga el nombre del objeto para el archivo al que desea agregar una URL personalizada:
    oci os object list --bucket-name <the-bucket-name> 
    --file <the-file-name>
    Salida de ejemplo:
    "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.

    También puede encontrar el nombre del objeto en la consola. En la página de detalles del cubo, seleccione el menú Acciones Menú Acciones para el objeto, seleccione Ver detalles de objeto y copie el nombre.

    Nota

    Si un archivo está en una carpeta, el nombre del archivo y su nombre de objeto son diferentes. Por ejemplo, para un archivo denominado file1.pdf, su nombre de objeto podría ser folder1/file1.pdf. De lo contrario, el nombre de archivo y su nombre de objeto son los mismos.
  3. Descargue el archivo en el directorio de trabajo actual.

    Para agregar o actualizar un objeto metadata de archivo, sustituya el archivo por el mismo archivo que tiene un nuevo objeto metadata. Es por eso que está copiando el archivo en el directorio de trabajo actual primero.

    oci os object get 
    --bucket-name <the-bucket-name> 
    --file <the-file-name>
    --name <the-object-name>
  4. Busque los valores de objeto metadata para el archivo actual.
    oci os object head 
    --bucket-name <the-bucket-name> 
    --name <the-object-name>
    Salida de ejemplo:
    {
     some data
    
      "opc-client-request-id": "xxx",
      "opc-meta-key1": "value1",
      "opc-meta-key2": "value2",
      "opc-request-id": "xxx",
     ...
    }
    

    En este ejemplo se muestra que el valor del objeto metadata es '{"key1":"value1","key2":"value2"}'. El nombre metadata se guarda con el prefijo opc-meta-, pero no tiene que agregar este prefijo al agregar el nombre metadata en los siguientes pasos. Este prefijo se agrega automáticamente a cada nombre metadata.

  5. Sustituya el archivo que está en Object Storage por el mismo archivo que está en el directorio de trabajo actual y agregue un nuevo objeto metadata.

    Para mantener los metadatos actuales y agregar el nombre y los valores de la URL personalizada, '{"customized_url_source":"<the-custom-url>" al objeto 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>"}'

    Por ejemplo, para mantener los nombres y valores metadata mostrados en el ejemplo del paso 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"}'

    Para sustituir el objeto metadata existente para incluir solo la URL personalizada, ejecute el siguiente comando:

    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. Asegúrese de que se sustituye el objeto metadata de la URL personalizada.
    oci os object head 
    --bucket-name <the-bucket-name> 
    --name <the-object-name>
    Salida de ejemplo:
    {
     some data
    
      "opc-meta-customized_url_source": "some-new-link",
     ...
    }
    
Importante

  • El objeto metadata que sustituye la cita por defecto debe tener el nombre customized_url_source.
  • Puede tener un objeto metadata con el nombre customized_url_source
  • Cada customized_url_source solo puede tener una URL.
  • Los comandos del paso 5 funcionan tanto para agregar como para actualizar el objeto metadata, ya que sustituyen el valor del objeto metadata actual.
  • Asegúrese de transferir los valores para el objeto --metadata con el formato mostrado en los comandos del paso 5.
Enlaces