Documentación de Oracle Cloud Infrastructure

Adición de metadatos a archivos de Object Storage para el filtrado de búsqueda

Puede agregar metadatos a los archivos de Object Storage antes de sincronizarlos en un almacén de vectores. Los metadatos ayudan a mejorar la recuperación al permitir que las búsquedas semánticas e híbridas filtren los resultados por atributos relevantes.

Por ejemplo, puede agregar metadatos, como el año de publicación, el título, el tema, el departamento, el área de producto o el tipo de documento. Después de sincronizar los archivos, estos campos de metadatos se pueden utilizar para limitar los resultados de búsqueda a un ámbito de contenido específico.

Los metadatos son opcionales. Sin embargo, si desea que los metadatos estén disponibles para el filtrado de búsqueda, agregue o actualice los metadatos antes de realizar la sincronización de datos. Los metadatos agregados después de una sincronización no se incluyen en esa sincronización a menos que vuelva a ejecutar la sincronización de datos.

Este tema se aplica a los almacenes de vectores que sincronizan datos no estructurados de Object Storage.

Nota

Agregue o actualice metadatos antes de realizar la sincronización de datos. Los metadatos agregados después de una sincronización no se incluyen en esa sincronización.

Funcionamiento de los metadatos

Los metadatos se definen como pares clave-valor. Para utilizar metadatos con archivos de Object Storage, primero debe definir los campos de metadatos en un archivo de esquema. A continuación, asocie los archivos del cubo con valores de metadatos.

Para todos los métodos de metadatos de Object Storage, debe crear un archivo de esquema de metadatos denominado _metadata_schema.json en el nivel raíz del cubo de Object Storage. El esquema define las claves de metadatos que el servicio puede esperar y el tipo de valor para cada clave.

Si el archivo _metadata_schema.json no existe, los metadatos no se calculan para los archivos del cubo.

Cada campo de metadatos tiene un nombre y un tipo. Los tipos de metadatos soportados son:

  • integer
  • string
  • list_of_string
  • double

Descripción general de flujo de trabajo

Utilice el siguiente flujo de trabajo para preparar metadatos antes de sincronizar archivos en un almacén de vectores:

  1. En un editor de texto, cree un archivo de esquema de metadatos denominado _metadata_schema.json.
  2. Defina los campos de metadatos y los tipos de valor en formato JSON.
  3. Cargue _metadata_schema.json en el nivel raíz del cubo de Object Storage que contiene los archivos que desea sincronizar.
  4. Seleccione cómo asociar valores de metadatos a archivos:
    • Aplicar metadatos comunes a todos los archivos del cubo.
    • Defina metadatos para varios archivos en un archivo JSON.
    • Defina metadatos en un archivo JSON independiente para cada archivo de datos.
    • Agregue metadatos mediante las propiedades de metadatos de Object Storage.
  5. Cargue los archivos de metadatos en la ubicación correcta del cubo de Object Storage.
  6. Realice la sincronización de datos para el almacén de vectores.

Ejemplo de esquema de metadatos

Cree un archivo de esquema de metadatos denominado _metadata_schema.json y guárdelo en el nivel raíz del cubo de Object Storage.

{
  "metadataSchema": [
    {
      "name": "publication_year",
      "type": "integer"
    },
    {
      "name": "title",
      "type": "string"
    },
    {
      "name": "topic",
      "type": "list_of_string"
    },
    {
      "name": "rating",
      "type": "double"
    }
  ]
}

Los nombres de metadatos que utilice en los archivos de metadatos deben coincidir con los nombres definidos en el esquema.

Métodos de metadatos para archivos de Object Storage

En la siguiente tabla se describen los métodos soportados para agregar metadatos a los archivos de Object Storage, incluido dónde crear cada cabecera o archivo de metadatos y cuándo utilizar cada método.

Método Nombre y ubicación del archivo Cuándo se usa
Definir el esquema de metadatos Cree _metadata_schema.json en el nivel raíz del cubo de Object Storage. Necesario para todos los métodos de archivo de metadatos de Object Storage. El esquema define las claves de metadatos y los tipos de valores soportados.
Aplicar metadatos comunes a todos los archivos de un cubo Cree _common.metadata.json en el nivel raíz del cubo de Object Storage. Se utiliza cuando se aplican los mismos metadatos a todos los archivos del cubo. Este método evita la duplicación de metadatos entre archivos.
Definir metadatos para varios archivos en un archivo JSON Cree _all.metadata.json en el nivel raíz del cubo de Object Storage. Se utiliza cuando tiene muchos archivos y prefiere gestionar metadatos para todos los archivos en un archivo JSON en lugar de crear un archivo de metadatos por archivo.
Definir metadatos para un archivo Cree <file-name>.metadata.json en el mismo nivel que el archivo de datos correspondiente. El valor <file-name>debe coincidir con el nombre del archivo de datos. Se utiliza cuando los metadatos difieren por archivo y tiene un pequeño número de archivos, o cuando automatiza la creación de archivos de metadatos.
Agregar metadatos como cabeceras de Object Storage Agregue metadatos mediante las propiedades de metadatos de Object Storage de cada archivo. Se utiliza sólo cuando tiene un pequeño número de propiedades de metadatos. Los archivos de metadatos JSON se recomiendan porque son más fáciles de actualizar y gestionar.

Ejemplo de Ubicación del Archivo de Metadatos

En el siguiente ejemplo se muestra dónde guardar los archivos de metadatos en un cubo de Object Storage.

bucket_root/
  _metadata_schema.json
  _common.metadata.json
  _all.metadata.json
  file_0.pdf
  file_0.pdf.metadata.json
  folder_1/
    file_1.pdf
    file_1.pdf.metadata.json
  folder_2/
    file_2.pdf
    file_2.pdf.metadata.json

Para los metadatos específicos del archivo, el archivo de metadatos se debe guardar en el mismo nivel que el archivo de datos correspondiente.

Por ejemplo, si el archivo de datos se guarda como:

folder_1/file_1.pdf

el archivo de metadatos se debe guardar como:

folder_1/file_1.pdf.metadata.json

Ejemplos de archivos JSON de metadatos

Metadatos comunes para todos los archivos

Cree _common.metadata.json en el nivel raíz del cubo para aplicar los mismos metadatos a todos los archivos del cubo.

Ejemplo:

{
  "metadataAttributes": {
    "publication_year": 2020,
    "topic": [
      "cooking",
      "health",
      "gardening"
    ],
    "rating": 3.3
  }
}

Metadatos para varios archivos

Cree _all.metadata.json en el nivel raíz del cubo para definir metadatos para varios archivos en un archivo JSON.

Ejemplo:

{
  "folder_1/file_1.pdf": {
    "metadataAttributes": {
      "publication_year": 2020,
      "title": "Healthy Cooking Guide",
      "topic": [
        "cooking",
        "health"
      ],
      "rating": 4.5
    }
  },
  "folder_2/file_2.pdf": {
    "metadataAttributes": {
      "publication_year": 2022,
      "title": "Gardening Basics",
      "topic": [
        "gardening"
      ],
      "rating": 4.0
    }
  }
}

Metadatos para un archivo

Cree <file-name>.metadata.json en el mismo nivel que el archivo de datos correspondiente.

Por ejemplo, para definir metadatos para file_1.pdf, cree un archivo denominado file_1.pdf.metadata.json.

Ejemplo:

{
  "metadataAttributes": {
    "publication_year": 2020,
    "title": "Healthy Cooking Guide",
    "topic": [
      "cooking",
      "health"
    ],
    "rating": 4.5
  }
}

Límites de metadatos

Los siguientes límites se aplican a los metadatos utilizados para el filtrado de búsqueda.

Descripción Límite
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 artículos en un tipo list_of_string 10
Longitud máxima de cada elemento en un tipo list_of_string 50 caracteres
Longitud máxima de una clave de metadatos 25 caracteres
Longitud máxima de un valor de metadatos 50 caracteres

Uso de metadatos con sincronización de datos

Agregue el esquema de metadatos y los archivos de metadatos antes de sincronizar los datos en el almacén de vectores.

Después de sincronizar los archivos, los metadatos están disponibles para el filtrado de búsqueda. Si agrega o cambia metadatos después de la sincronización, vuelva a realizar la sincronización de datos para que los metadatos actualizados se incluyan en el almacén de vectores.

Para sincronizar archivos desde Object Storage, consulte Sincronización de datos en un almacén de vectores.