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 automaticamente o esquema. Você pode usar esse esquema detectado automaticamente no seu motor ou usar a API para fornecer um esquema que indique a estrutura dos dados.

Se você fornecer um esquema e o atualizar mais tarde com outro, ele precisa ser compatível com versões anteriores do original. Caso contrário, a atualização do esquema falhará.

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

Abordagens para fornecer o esquema do repositório de dados

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

Detectar e editar automaticamente. Deixe o Vertex AI Agent Builder detectar e sugerir automaticamente um esquema inicial. Em seguida, refine o esquema pela interface do console. 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 as instruções do console do Google Cloud para dados estruturados em Criar um repositório de dados de pesquisa e Criar um repositório de dados de recomendações genéricas.
Forneça o esquema como um objeto JSON. Forneça o esquema ao 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 pela API usando um comando curl (ou programa). Por exemplo, consulte Importar uma vez do BigQuery. Consulte também as instruções a seguir, Fornecer seu próprio esquema.
Mídia: forneça seus dados no esquema definido pelo Google. Se você criar um repositório de dados para mídia, poderá usar 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 ingestão 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: detecte e edite automaticamente, incluindo as propriedades de mídia necessárias. 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 podem ser mapeados para as propriedades da chave de mídia: title, uri, category, media_duration e media_available_time.

Essa é a abordagem que você vai usar ao importar dados de mídia pelo console do Google Cloud se eles não estiverem no esquema definido pelo Google.
Mídia: forneça seu próprio esquema como um objeto JSON. Forneça o esquema ao 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 conferir um exemplo de 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, Forneça 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 os dados, que você pode analisar 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 você quiser editar o esquema depois que todos os dados forem importados, 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ê estiver definindo um esquema de mídia, inclua campos que possam ser mapeados para as propriedades da chave de mídia. Essas propriedades principais são mostradas neste exemplo.

Confira alguns dos campos neste exemplo de esquema:

dynamic. Se dynamic for definido como o valor de string "true", todas as novas propriedades encontradas nos dados importados serã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ê faz upload de dados 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 aceitos são RFC 3339 e ISO 8601.

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 for definido como o booleano false, quando os dados no formato de data/hora forem importados, o tipo de esquema será definido 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 importantes nos documentos, ajudando a esclarecer o significado semântico delas. Os 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 incluir os campos indexable ou searchable com um keyPropertyValues para receber o comportamento padrão esperado.

Observação: as propriedades principais podem melhorar a qualidade dos resultados da pesquisa e das recomendações, além da precisão do preenchimento automático. 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: o 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 a apps de pesquisa:

retrievable: indica se esse campo pode ser retornado em uma resposta de pesquisa. Isso pode ser definido para campos do tipo number, string, boolean, integer, datetime e geolocation. É possível definir como recuperáveis no máximo 50 campos. Os campos definidos pelo usuário e 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. Os campos definidos pelo usuário não são indexáveis por padrão, exceto os que contêm o campo keyPropertyMapping. Para tornar um campo indexável, inclua "indexable": true com ele.
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 esse campo pode ser indexado de forma inversa para corresponder a consultas de texto não estruturado. Isso só pode ser definido para campos do tipo string. É possível definir no máximo 50 campos como pesquisáveis. Por padrão, não é possível pesquisar campos definidos pelo usuário, exceto aqueles que contêm o campo keyPropertyMapping. Para tornar um campo pesquisável, inclua "searchable": true com ele.
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ções:

recommendationsFilterable: indica que o campo pode ser usado em uma expressão de filtro de recomendações. Para informações gerais sobre as recomendações de filtragem, 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 esquema vazio e atualize-o, fornecendo-o 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.

Crie 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 do repositório de dados da Vertex AI para Pesquisa que você quer criar.
INDUSTRY_VERTICAL: GENERIC ou MEDIA.

Use o método da API schemas.patch para fornecer o 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
}'