Esta página foi traduzida pela API Cloud Translation.

Fornecer ou detectar automaticamente um esquema

Quando você importa dados estruturados usando o console do Google Cloud, o Vertex AI Agent Builder detecta o esquema automaticamente. É possível usar esse esquema detectado automaticamente no ou usar a API para fornecer um esquema para indicar a estrutura dos dados.

Se você fornecer um esquema e depois atualizá-lo com um novo esquema, precisa ser compatível com versões anteriores do original. Caso contrário, o esquema será atualizado falhar.

Para informações de referência sobre o esquema, consulte dataStores.schemas

Abordagens para fornecer o esquema para seu repositório de dados

Há várias abordagens para determinar o esquema de dados estruturados.

Detectar e editar automaticamente. Deixe a Vertex AI Agent Builder detectar e sugerir automaticamente um esquema inicial. Depois, refina o esquema usando as do console do Cloud. O Google recomenda que, depois que seus campos forem detectados automaticamente, você mapeie as propriedades principais para todos os campos importantes.

Essa é a abordagem que você vai usar ao seguir o console do Google Cloud instruções para dados estruturados em Criar um conjunto de dados store e Create um repositório de dados de recomendações genéricas.
Forneça o esquema como um objeto JSON. Forneça o no Vertex AI Agent Builder como um objeto JSON. Você precisa ter preparado um objeto JSON correto. Para conferir um exemplo de objeto JSON, consulte Exemplo de esquema como um objeto JSON. Depois de criar o esquema, faça upload dos seus dados de acordo com ele.

Essa é a abordagem que você pode usar ao criar um repositório de dados por meio do usando um comando (ou programa) curl. Por exemplo, consulte Importar uma vez do BigQuery. Consulte também os seguintes instruções em Fornecer seu próprio esquema.
Mídia: forneça seus dados no esquema definido pelo Google. Se você criar um data para mídia, use o esquema predefinido do Google. Ao escolher essa opção, presumimos que você tenha estruturado seu objeto JSON no formato fornecido em Sobre documentos de mídia e armazenamento de dados. Por padrão, a detecção automática anexa ao esquema todos os novos campos encontrados durante a transferência de dados.

Essa é a abordagem que você usa ao seguir as instruções em Criar um app de mídia e um repositório de dados. Essa também é a abordagem nos tutoriais Começar a usar as recomendações de mídia e Começar a usar a pesquisa de mídia, em que os dados de amostra são fornecidos no esquema predefinido do Google.
Mídia: detectar e editar automaticamente, certificando-se de incluir a mídia necessária . Para dados de mídia, use a detecção automática para sugerir o esquema e edite para refinar. No objeto JSON, é necessário incluir campos que possam ser mapeados para as propriedades da chave de mídia: title, uri, category, media_duration e media_available_time.

Essa é a abordagem que você usará ao importar dados de mídia por meio do Console do Google Cloud se os dados de mídia não estiverem no esquema definido pelo Google.
Mídia: forneça seu próprio esquema como um objeto JSON. Forneça o no Vertex AI Agent Builder como um objeto JSON. Você precisa ter preparado um objeto JSON correto. O esquema precisa incluir campos que possam ser mapeados para as propriedades da chave de mídia: title, uri, category, media_duration e media_available_time.

Para um exemplo de um objeto JSON, consulte Exemplo de esquema como um objeto JSON. Depois de criar o esquema, faça upload dos dados de mídia de acordo com ele.

Para essa abordagem, você usa a API com um comando curl (ou programa). Consulte as instruções a seguir em Fornecer seu próprio esquema.

Sobre a detecção e edição automáticas

Quando você começa a importar dados, a Vertex AI para Pesquisa cria amostras dos primeiros documentos importados. Com base nesses documentos, ele propõe um esquema para que você pode revisar ou editar.

Se os campos que você quer mapear para propriedades principais não estiverem presentes nos documentos amostrais, adicione esses campos manualmente ao revisar o esquema.

Se o Vertex AI Search encontrar outros campos mais tarde na importação de dados, ele ainda vai importar esses campos e adicioná-los ao esquema. Se se quiser editar o esquema depois da importação de todos os dados, consulte Atualizar seu esquema.

Exemplo de esquema como um objeto JSON

Você pode definir seu próprio esquema usando o formato Esquema JSON, que é uma linguagem declarativa de código aberto para definir, anotar e validar documentos JSON. Por exemplo, esta é uma anotação de esquema JSON válida:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "dynamic": "true",
  "datetime_detection": true,
  "geolocation_detection": true,
  "properties": {
    "title": {
      "type": "string",
      "keyPropertyMapping": "title",
      "retrievable": true,
      "completable": true
    },
    "description": {
      "type": "string",
      "keyPropertyMapping": "description"
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "keyPropertyMapping": "category"
      }
    },
    "uri": {
      "type": "string",
      "keyPropertyMapping": "uri"
    },
    "brand": {
      "type": "string",
      "indexable": true,
      "dynamicFacetable": true
    },
    "location": {
      "type": "geolocation",
      "indexable": true,
      "retrievable": true
    },
    "creationDate": {
      "type": "datetime",
      "indexable": true,
      "retrievable": true
    },
    "isCurrent": {
      "type": "boolean",
      "indexable": true,
      "retrievable": true
    },
    "runtime": {
      "type": "string",
      "keyPropertyMapping": "media_duration"
    },
    "releaseDate": {
      "type": "string",
      "keyPropertyMapping": "media_available_time"
    }
  }
}

Se você está definindo um esquema de mídia, deve incluir campos que podem ser mapeadas para as propriedades da chave de mídia. Essas principais propriedades são mostradas exemplo.

Veja alguns dos campos neste exemplo de esquema:

dynamic Se dynamic for definido como o valor de string "true", então qualquer novas propriedades encontradas nos dados importados são adicionadas ao esquema. Se dynamic for definido como "false", as novas propriedades encontradas nos dados importados serão ignoradas. As propriedades não serão adicionadas ao esquema nem os valores serão importados.

Por exemplo, um esquema tem duas propriedades: title e description, e você fizer o upload de um dado que contém propriedades para title, description e rating Se dynamic for "true", a propriedade e os dados de classificação serão importados. Se dynamic for "false", as propriedades rating não serão importadas, mas title e description serão.

O padrão é "true".
datetime_detection. Se datetime_detection for definido como true booleano, quando os dados no formato de data/hora forem importados, o tipo de esquema será definido como datetime. Os formatos compatíveis são RFC 3339 e ISO 8.601.

Exemplo:
- 2024-08-05 08:30:00 UTC
- 2024-08-05T08:30:00Z
- 2024-08-05T01:30:00-07:00
- 2024-08-05
- 2024-08-05T08:30:00+00:00
Se datatime_detection estiver definido como o booleano false, então, quando os dados em formato de data e hora são importados, o tipo de esquema é Defina como string.

O padrão é true.
geolocation_detection. Se geolocation_detection for definido como true booleano, quando os dados no formato de geolocalização forem importados, o tipo de esquema será definido como geolocation. Os dados são detectados como geolocalização se forem um objeto que contém um número de latitude e um número de longitude ou um objeto que contém uma string de endereço.

Exemplo:
- "myLocation": {"latitude":37.42, "longitude":-122.08}
- "myLocation": {"address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043"}
Se geolocation_detection for definido como o booleano false, quando os dados no formato de geolocalização forem importados, o tipo de esquema será definido como object.

O padrão é true.
keyPropertyMapping Um campo que mapeia palavras-chave predefinidas para campos em seus documentos, ajudando a esclarecer seu significado semântico. Valores incluem title, description, uri e category. O nome do campo não precisa corresponder ao valor keyPropertyValues. Por exemplo, para um campo chamado my_title, você pode incluir um campo keyPropertyValues com um valor de title.

Para repositórios de dados de pesquisa, os campos marcados com keyPropertyMapping são indexáveis e pesquisáveis por padrão, mas não recuperáveis, completáveis ou dinâmicos. Isso significa que você não precisa precisa incluir os campos indexable ou searchable com um keyPropertyValues para obter o comportamento padrão esperado.

Observação :as propriedades principais podem melhorar a qualidade da pesquisa e resultados de recomendações e precisão do preenchimento automático da pesquisa. Se você usar a detecção automática de esquema, as propriedades principais não serão adicionadas automaticamente. Recomendamos usar o método schemas.patch para marcar campos de dados como propriedades principais, especialmente title, uri e description.
type Tipo do campo. É um valor de string que é datetime, geolocation ou um dos tipos primitivos (integer, boolean, object, array, number ou string).

Os campos de propriedade a seguir se aplicam apenas aos apps de pesquisa:

retrievable Indica se este campo pode ser retornado em uma pesquisa resposta. Isso pode ser definido para campos do tipo number, string, boolean, integer, datetime e geolocation. No máximo 50 podem ser definidos como recuperáveis. campos definidos pelo usuário e Os campos keyPropertyValues não podem ser recuperados por padrão. Para tornar um campo recuperável, inclua "retrievable": true com ele.
indexable: indica se esse campo pode ser filtrado, segmentado, otimizado ou classificado no método servingConfigs.search. Isso pode ser definido para campos do tipo number, string, boolean, integer, datetime e geolocation. É possível definir no máximo 50 campos como indexáveis. Definido pelo usuário não são indexáveis por padrão, exceto aqueles que contêm o keyPropertyMapping. Para tornar um campo indexável, inclua "indexable": true com o campo.
dynamicFacetable: indica que o campo pode ser usado como um filtro dinâmico. Isso pode ser definido para campos do tipo number, string, boolean e integer. Para tornar um campo dinamicamente facetável, ele também precisa ser indexável: inclua "dynamicFacetable": true e "indexable": true com o campo.
searchable Indica se este campo pode ser indexado de forma reversa para corresponder a consultas de texto não estruturadas. Isso só pode ser definido para campos do tipo string. É possível definir no máximo 50 campos como pesquisáveis. Definido pelo usuário não são pesquisáveis por padrão, exceto aqueles que contêm o keyPropertyMapping. Para tornar um campo pesquisável, inclua "searchable": true com o campo.
completable: indica se esse campo pode ser retornado como uma sugestão de preenchimento automático. Isso só pode ser definido para campos do tipo string. Para tornar um campo completável, inclua "completable": true com ele.

Além disso, o campo a seguir se aplica apenas a apps de recomendação:

recommendationsFilterable: indica que o campo pode ser usado em uma expressão de filtro de recomendações. Para informações gerais sobre filtragem recomendações, consulte Filtrar recomendações.
```
  ...
    "genres": {
    "type": "string",
    "recommendationsFilterable": true,
    ...
  },
```

Fornecer seu próprio esquema como um objeto JSON

Para fornecer seu próprio esquema, crie um repositório de dados que contenha um e o atualiza, fornecendo seu esquema como um objeto JSON. Siga estas etapas:

Prepare o esquema como um objeto JSON usando o Exemplo de esquema como um objeto JSON como guia.

Criar um repositório de dados.

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores?dataStoreId=DATA_STORE_ID" \
-d '{
  "displayName": "DATA_STORE_DISPLAY_NAME",
  "industryVertical": "INDUSTRY_VERTICAL"
}'

Substitua:

PROJECT_ID: o ID do seu projeto do Google Cloud.
DATA_STORE_ID: o ID do repositório de dados da Vertex AI para Pesquisa que você quer criar. Esse ID só pode conter letras minúsculas, dígitos, sublinhados e hifens.
DATA_STORE_DISPLAY_NAME: o nome de exibição da Vertex AI. Pesquise o repositório de dados que você quer criar.
INDUSTRY_VERTICAL: GENERIC ou MEDIA.

Usar o schemas.patch método de API para fornecer seu novo esquema JSON como um objeto JSON.

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/schemas/default_schema" \
-d '{
  "structSchema": JSON_SCHEMA_OBJECT
}'