Documentação do Oracle Cloud Infrastructure

Adicionando Metadados aos Arquivos do Serviço Object Storage para Filtragem de Pesquisa

Você pode adicionar metadados aos arquivos do Object Storage antes de sincronizá-los com um armazenamento de vetores. Os metadados ajudam a melhorar a recuperação, permitindo que as pesquisas semânticas e híbridas filtrem os resultados por atributos relevantes.

Por exemplo, você pode adicionar metadados, como ano de publicação, título, tópico, departamento, área de produto ou tipo de documento. Após a sincronização dos arquivos, esses campos de metadados podem ser usados para restringir os resultados da pesquisa a um escopo de conteúdo específico.

Os Metadados são opcionais. No entanto, se você quiser que os metadados estejam disponíveis para filtragem de pesquisa, adicione ou atualize os metadados antes de executar a sincronização de dados. Os metadados adicionados após uma sincronização não são incluídos nessa sincronização, a menos que você execute a sincronização de dados novamente.

Este tópico se aplica a armazenamentos de vetores que sincronizam dados não estruturados do serviço Object Storage.

Observação

Adicione ou atualize metadados antes de executar a sincronização de dados. Os metadados adicionados após uma sincronização não são incluídos nessa sincronização.

Como Funcionam os Metadados

Os metadados são definidos como pares chave-valor. Para usar metadados com arquivos do serviço Object Storage, primeiro defina os campos de metadados em um arquivo de esquema. Em seguida, você associa arquivos no bucket a valores de metadados.

Para todos os métodos de metadados do serviço Object Storage, crie um arquivo de esquema de metadados chamado _metadata_schema.json no nível raiz do bucket do serviço Object Storage. O esquema define as chaves de metadados que o serviço pode esperar e o tipo de valor de cada chave.

Se o arquivo _metadata_schema.json não existir, os metadados não serão calculados para arquivos no bucket.

Cada campo de metadados tem um nome e um tipo. Os tipos de metadados suportados são:

  • integer
  • string
  • list_of_string
  • double

Visão Geral do Workflow

Use o seguinte workflow para preparar metadados antes de sincronizar arquivos com um armazenamento de vetores:

  1. Em um editor de texto, crie um arquivo de esquema de metadados chamado _metadata_schema.json.
  2. Defina os campos de metadados e os tipos de valor no formato JSON.
  3. Faça upload do _metadata_schema.json para o nível raiz do bucket do Object Storage que contém os arquivos a serem sincronizados.
  4. Selecione como associar valores de metadados a arquivos:
    • Aplicar metadados comuns a todos os arquivos do bucket.
    • Defina metadados para vários arquivos em um arquivo JSON.
    • Defina metadados em um arquivo JSON separado para cada arquivo de dados.
    • Adicione metadados usando propriedades de metadados do Object Storage.
  5. Faça upload dos arquivos de metadados para o local correto no bucket do Object Storage.
  6. Execute a sincronização de dados para o armazenamento de vetores.

Exemplo de Esquema de Metadados

Crie um arquivo de esquema de metadados chamado _metadata_schema.json e salve-o no nível raiz do bucket do Object Storage.

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

Os nomes de metadados que você usa nos arquivos de metadados devem corresponder aos nomes definidos no esquema.

Métodos de Metadados para Arquivos do Serviço Object Storage

A tabela a seguir descreve os métodos suportados para adicionar metadados a arquivos no Object Storage, incluindo onde criar cada arquivo ou cabeçalho de metadados e quando usar cada método.

Método Nome e localização do arquivo Quando usar
Definir o esquema de metadados Crie _metadata_schema.json no nível raiz do bucket do Object Storage. Obrigatório para todos os métodos de arquivo de metadados do Object Storage. O esquema define as chaves de metadados e os tipos de valor suportados.
Aplicar metadados comuns a todos os arquivos em um bucket Crie _common.metadata.json no nível raiz do bucket do Object Storage. Use quando os mesmos metadados se aplicarem a todos os arquivos do bucket. Este método evita a duplicação de metadados entre arquivos.
Definir metadados para vários arquivos em um arquivo JSON Crie _all.metadata.json no nível raiz do bucket do Object Storage. Use quando tiver muitos arquivos e preferir gerenciar metadados para todos os arquivos em um arquivo JSON, em vez de criar um arquivo de metadados por arquivo.
Definir metadados para um arquivo Crie <file-name>.metadata.json no mesmo nível do arquivo de dados correspondente. O valor <file-name>deve corresponder ao nome do arquivo de dados. Use quando os metadados forem diferentes por arquivo e você tiver um pequeno número de arquivos ou quando automatizar a criação de arquivos de metadados.
Adicionar metadados como cabeçalhos do Object Storage Adicione metadados usando as propriedades de metadados do Object Storage de cada arquivo. Use somente quando tiver um pequeno número de propriedades de metadados. Os arquivos de metadados JSON são recomendados porque são mais fáceis de atualizar e gerenciar.

Exemplo de Localização do Arquivo de Metadados

O exemplo a seguir mostra onde salvar arquivos de metadados em um bucket do 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 metadados específicos do arquivo, o arquivo de metadados deve ser salvo no mesmo nível do arquivo de dados correspondente.

Por exemplo, se o arquivo de dados for salvo como:

folder_1/file_1.pdf

o arquivo de metadados deve ser salvo como:

folder_1/file_1.pdf.metadata.json

Exemplos de Arquivo JSON de Metadados

Metadados Comuns para Todos os Arquivos

Crie _common.metadata.json no nível raiz do bucket para aplicar os mesmos metadados a todos os arquivos do bucket.

Exemplo:

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

Metadados para Vários Arquivos

Crie _all.metadata.json no nível raiz do bucket para definir metadados para vários arquivos em um arquivo JSON.

Exemplo:

{
  "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
    }
  }
}

Metadados para um Arquivo

Crie <file-name>.metadata.json no mesmo nível do arquivo de dados correspondente.

Por exemplo, para definir metadados para file_1.pdf, crie um arquivo chamado file_1.pdf.metadata.json.

Exemplo:

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

Limites de Metadados

Os limites a seguir se aplicam aos metadados usados para filtragem de pesquisa.

Descrição Limite
Número máximo de entradas em _all.metadata.json 10.000
Número máximo de campos de metadados que podem ser especificados para cada arquivo 20
Número máximo de itens em um tipo list_of_string 10
Comprimento máximo de cada item em um tipo list_of_string 50 caracteres
Tamanho máximo de uma chave de metadados 25 caracteres
Tamanho máximo de um valor de metadados 50 caracteres

Usando Metadados com o Data Sync

Adicione o esquema de metadados e os arquivos de metadados antes de sincronizar dados com o armazenamento de vetores.

Depois que os arquivos são sincronizados, os metadados ficam disponíveis para filtragem de pesquisa. Se você adicionar ou alterar metadados após a sincronização, execute a sincronização de dados novamente para que os metadados atualizados sejam incluídos no armazenamento de vetores.

Para sincronizar arquivos do serviço Object Storage, consulte Sincronizar Dados com um Vector Store.