Esta página foi traduzida pela API Cloud Translation.

Forneça ou detete automaticamente um esquema

Quando importa dados estruturados através da Google Cloud consola, as aplicações de IA detetam automaticamente o esquema. Pode usar este esquema detetado automaticamente no seu motor ou usar a API para fornecer um esquema que indique a estrutura dos dados.

Se fornecer um esquema e, posteriormente, o atualizar com um novo esquema, este tem de ser retrocompatível com o original. Caso contrário, a atualização do esquema falha.

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

Abordagens para fornecer o esquema da sua base de dados

Existem várias abordagens para determinar o esquema dos dados estruturados.

Detetar e editar automaticamente. Permitir que as aplicações de IA detetem e sugiram automaticamente um esquema inicial. Em seguida, refina o esquema através da interface da consola. A Google recomenda vivamente que, depois de os campos serem detetados automaticamente, mapeie as propriedades principais para todos os campos importantes.

Esta é a abordagem que vai usar quando seguir as instruções da Google Cloud consola para dados estruturados em Crie um arquivo de dados de pesquisa e Crie um arquivo de dados de recomendações personalizadas.
Forneça o esquema como um objeto JSON. Forneça o esquema às aplicações de IA como um objeto JSON. Tem de ter preparado um objeto JSON correto. Para ver um exemplo de um objeto JSON, consulte o esquema de exemplo como um objeto JSON. Depois de criar o esquema, carrega os dados de acordo com esse esquema.

Esta é a abordagem que pode usar quando cria um arquivo de dados através da API com um comando curl (ou um programa). Por exemplo, consulte o artigo Importe uma vez a partir do BigQuery. Consulte também as seguintes instruções: Forneça o seu próprio esquema.
Conteúdo multimédia: forneça os seus dados no esquema definido pela Google. Se criar um repositório de dados para multimédia, pode optar por usar o esquema predefinido da Google. Se escolher esta opção, assume que estruturou o seu objeto JSON no formato indicado em Acerca dos documentos multimédia e do armazenamento de dados. Por predefinição, a deteção automática anexa ao esquema todos os novos campos que encontra durante o carregamento de dados.

Esta é a abordagem que usa quando segue as instruções em Crie uma app de multimédia e um repositório de dados. Também é a abordagem nos tutoriais Introdução às recomendações de multimédia e Introdução à pesquisa de multimédia, onde os dados de exemplo são fornecidos no esquema predefinido da Google.
Multimédia: detete e edite automaticamente, certificando-se de que inclui as propriedades de multimédia necessárias. Para dados de multimédia, pode usar a deteção automática para sugerir o esquema e editá-lo para o refinar. No objeto JSON, tem de incluir campos que possam ser mapeados para as propriedades da chave de multimédia: title, uri, category, media_duration e media_available_time.

Esta é a abordagem que vai usar quando importar dados multimédia através da Google Cloud consola se os dados multimédia não estiverem no esquema definido pela Google.
Conteúdo multimédia: forneça o seu próprio esquema como um objeto JSON. Forneça o esquema às aplicações de IA como um objeto JSON. Tem de ter preparado um objeto JSON correto. O esquema tem de incluir campos que possam ser mapeados para as propriedades da chave de multimédia: title, uri, category, media_duration e media_available_time.

Para ver um exemplo de um objeto JSON, consulte o esquema de exemplo como um objeto JSON. Depois de criar o esquema, carrega os dados de multimédia de acordo com esse esquema.

Nesta abordagem, usa a API através de um comando curl (ou um programa). Consulte as seguintes instruções: Forneça o seu próprio esquema.

Acerca da deteção e edição automáticas

Quando começa a importar dados, o Vertex AI Search extrai amostras dos primeiros documentos importados. Com base nestes documentos, propõe um esquema para os dados, que pode rever ou editar.

Se os campos que quer mapear para propriedades principais não estiverem presentes nos documentos de exemplo, pode adicioná-los manualmente quando rever o esquema.

Se a Pesquisa do Vertex AI encontrar campos adicionais mais tarde na importação de dados, continua a importar estes campos e adiciona-os ao esquema. Se quiser editar o esquema depois de todos os dados terem sido importados, consulte o artigo Atualize o seu esquema.

Exemplo de esquema como objeto JSON

Pode definir o seu próprio esquema através do formato JSON Schema, 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 estiver a definir um esquema de multimédia, tem de incluir campos que possam ser mapeados para as propriedades das chaves de multimédia. Estas propriedades principais são apresentadas neste exemplo.

Seguem-se alguns dos campos neste exemplo de esquema:

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

Por exemplo, um esquema tem duas propriedades: title e description, e carrega dados que contêm propriedades para title, description e rating. Se dynamic for "true", a propriedade e os dados de classificações são importados. Se dynamic for "false", as propriedades rating não são importadas, embora title e description sejam.

A predefinição é "true".
datetime_detection. Se datetime_detection estiver definido como o valor booleano true, quando os dados no formato de data/hora são importados, o tipo de esquema é definido como datetime. Os formatos suportados são RFC 3339 e ISO 8601.

Por 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 valor booleano false, quando os dados no formato de data/hora são importados, o tipo de esquema é definido como string.

A predefinição é true.
geolocation_detection. Se geolocation_detection estiver definido como o valor booleano true, quando os dados no formato de geolocalização são importados, o tipo de esquema é definido como geolocation. Os dados são detetados como geolocalização se forem um objeto que contenha um número de latitude e um número de longitude ou um objeto que contenha uma string de morada.

Por exemplo:
- "myLocation": {"latitude":37.42, "longitude":-122.08}
- "myLocation": {"address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043"}
Se geolocation_detection estiver definido como o valor booleano false, quando os dados no formato de geolocalização são importados, o tipo de esquema é definido como object.

A predefinição é true.
keyPropertyMapping. Um campo que mapeia palavras-chave predefinidas para campos críticos nos seus documentos, ajudando a esclarecer o respetivo significado semântico. Os valores incluem title, description, uri e category. Tenha em atenção que o nome do campo não tem de corresponder ao valor keyPropertyValues. Por exemplo, para um campo que denominou my_title, pode incluir um campo keyPropertyValues com um valor de title.

Para as lojas de dados de pesquisa, os campos marcados com keyPropertyMapping são, por predefinição, indexáveis e pesquisáveis, mas não são recuperáveis, preenchíveis nem dynamicFacetable. Isto significa que não tem de incluir os campos indexable ou searchable com um campo keyPropertyValues para obter o comportamento predefinido esperado.

Nota: as propriedades principais podem melhorar a qualidade dos resultados da pesquisa e das recomendações, bem como a precisão da funcionalidade de preenchimento automático da pesquisa. Se usar a deteção automática de esquemas, as propriedades principais não são adicionadas automaticamente. Recomendamos vivamente que use o método schemas.patch para marcar os campos de dados como propriedades principais, especialmente title, uri e description.
type. O tipo do campo. Este é um valor de string que é datetime, geolocation ou um dos tipos primitivos (integer, boolean, object, array, number ou string).

Os seguintes campos de propriedades aplicam-se apenas a apps de pesquisa:

retrievable. Indica se este campo pode ser devolvido numa resposta de pesquisa. Isto pode ser definido para campos do tipo number, string, boolean, integer, datetime e geolocation. É possível definir um máximo de 50 campos como recuperáveis. Os campos definidos pelo utilizador e os campos keyPropertyValues não são recuperáveis por predefinição. Para tornar um campo recuperável, inclua "retrievable": true com o campo.
indexable. Indica se este campo pode ser filtrado, dividido em facetas, aumentado ou ordenado no método servingConfigs.search. Isto pode ser definido para campos do tipo number, string, boolean, integer, datetime e geolocation. Pode definir um máximo de 50 campos como indexáveis. Os campos definidos pelo utilizador não são indexáveis por predefinição, exceto os campos que contêm o campo keyPropertyMapping. Para tornar um campo indexável, inclua "indexable": true com o campo.
dynamicFacetable. Indica que o campo pode ser usado como um aspeto dinâmico. Isto pode ser definido para campos do tipo number, string, boolean e integer. Para tornar um campo dinamicamente filtrável, também tem de ser indexável: inclua "dynamicFacetable": true e "indexable": true com o campo.
searchable. Indica se este campo pode ser indexado inversamente para corresponder a consultas de texto não estruturado. Só é possível definir esta opção para campos do tipo string. É possível definir um máximo de 50 campos como pesquisáveis. Os campos definidos pelo utilizador não são pesquisáveis por predefinição, exceto os campos que contêm o campo keyPropertyMapping. Para tornar um campo pesquisável, inclua "searchable": true com o campo.
completable. Indica se este campo pode ser devolvido como uma sugestão de preenchimento automático. Só é possível definir esta opção para campos do tipo string. Para tornar um campo preenchível, inclua "completable": true com o campo.

Além disso, o campo seguinte aplica-se apenas a apps de recomendações:

recommendationsFilterable. Indica que o campo pode ser usado numa expressão de filtro de recomendações. Para informações gerais sobre a filtragem de recomendações, consulte o artigo Filtre recomendações.
```
  ...
    "genres": {
    "type": "string",
    "recommendationsFilterable": true,
    ...
  },
```

Forneça o seu próprio esquema como um objeto JSON

Para fornecer o seu próprio esquema, cria um repositório de dados que contém um esquema vazio e, em seguida, atualiza o esquema, fornecendo o seu esquema como um objeto JSON. Siga estes passos:

Prepare o esquema como um objeto JSON, usando o Esquema de exemplo como um objeto JSON como guia.

Crie um arquivo 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 o seguinte:

PROJECT_ID: o ID do seu projeto Google Cloud .
DATA_STORE_ID: o ID do arquivo de dados do Vertex AI Search que quer criar. Este ID só pode conter letras minúsculas, dígitos, sublinhados e hífenes.
DATA_STORE_DISPLAY_NAME: o nome a apresentar do arquivo de dados do Vertex AI que 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
}'

Substitua o seguinte:

PROJECT_ID: o ID do seu projeto Google Cloud .
DATA_STORE_ID: o ID do arquivo de dados do Vertex AI Search.

JSON_SCHEMA_OBJECT: o novo esquema JSON como um objeto JSON. Por exemplo:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "keyPropertyMapping": "title"
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "keyPropertyMapping": "category"
      }
    },
    "uri": {
      "type": "string",
      "keyPropertyMapping": "uri"
    }
  }
}

Exemplo de comando e resultado

curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" "https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/dataStores/my-data-store/schemas/default_schema" -d '{
"structSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"title": {
"type": "string",
"keyPropertyMapping": "title"
},
"categories": {
"type": "array",
"items": {
"type": "string",
"keyPropertyMapping": "category"
}
},
"uri": {
"type": "string",
"keyPropertyMapping": "uri"
}
}
}
}'

{
"name": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/schemas/default_schema/operations/update-schema-10569824819404198922",
"metadata": {
"@type": "type.googleapis.com/google.cloud.discoveryengine.v1.UpdateSchemaMetadata"
}
}

Opcional: reveja o esquema seguindo o procedimento Veja uma definição de esquema.