Esta página foi traduzida pela API Cloud Translation.

Fornecer ou detectar automaticamente um esquema

Ao importar dados estruturados usando o console Google Cloud , o Gemini Enterprise detecta automaticamente o esquema. Você pode usar esse esquema detectado automaticamente no seu mecanismo ou usar a API para fornecer um esquema que indique a estrutura dos dados.

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

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

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

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

Detecção e edição automáticas. Deixe o Gemini Enterprise detectar e sugerir automaticamente um esquema inicial. Em seguida, refine o esquema na interface do console. O Google recomenda que, depois que os 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 próprios.
Forneça o esquema como um objeto JSON. Forneça o esquema ao Gemini Enterprise como um objeto JSON. Você precisa ter preparado um objeto JSON correto. Para ver um exemplo de objeto JSON, consulte Exemplo de esquema como um objeto JSON. Depois de criar o esquema, faça upload dos dados de acordo com ele.

Essa é a abordagem que você pode usar ao criar um repositório de dados pela API usando um comando (ou programa) curl. Por exemplo, consulte Importar uma vez do BigQuery. Consulte também as instruções a seguir: Fornecer seu próprio esquema.

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

Quando você começa a importar dados, o Gemini Enterprise faz uma amostragem dos primeiros documentos importados. Com base nesses documentos, ele propõe um esquema para os dados, que você pode revisar ou editar.

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

Se o Gemini Enterprise encontrar outros campos mais tarde na importação de dados, ele ainda vai importar e adicionar esses campos 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

É possível definir seu próprio esquema usando o 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
    }
  }
}

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 estiver definido como "false", as novas propriedades encontradas nos dados importados serão ignoradas. Elas 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ções 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 o booleano true, quando os dados no formato de data e hora forem importados, o tipo de esquema será definido como datetime. Os formatos compatíveis 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 estiver definido como o booleano false, quando os dados no formato de data e hora forem importados, o tipo de esquema será definido como string.

O padrão é true.
geolocation_detection. Se geolocation_detection for definido como o booleano true, 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 em 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 críticos nos seus documentos, ajudando a esclarecer o significado semântico deles. 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 o valor title.

Os campos marcados com keyPropertyMapping são indexáveis e pesquisáveis por padrão, mas não podem ser recuperados, completados ou usados em facetas dinâmicas. Isso significa que não é necessário incluir os campos indexable ou searchable com um campo keyPropertyValues para ter o comportamento padrão esperado.

Observação: as propriedades principais podem melhorar a qualidade dos resultados da pesquisa e a 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. Esse é um valor de string que é datetime, geolocation ou um dos tipos primitivos (integer, boolean, object, array, number ou string).
retrievable. Indica se este 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 no máximo 50 campos como recuperáveis. 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 o campo.
indexable. Indica se este campo pode ser filtrado, facetado, impulsionado 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. Por padrão, os campos definidos pelo usuário não são indexáveis, exceto aqueles 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 atributo dinâmico. Isso pode ser definido para campos do tipo number, string, boolean e integer. Para que um campo seja 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, os campos definidos pelo usuário não são pesquisáveis, exceto aqueles 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 retornado como uma sugestão de preenchimento automático. Só pode ser definido para campos do tipo string. Para tornar um campo completável, inclua "completable": true com ele.

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 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.

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: ID do projeto.
DATA_STORE_ID: o ID do repositório de dados que você quer criar. Ele só pode conter letras minúsculas, dígitos, sublinhados e hífens.
DATA_STORE_DISPLAY_NAME: o nome de exibição do repositório de dados que você quer criar.
INDUSTRY_VERTICAL: GENERIC

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

Substitua:

PROJECT_ID: ID do projeto.
DATA_STORE_ID: o ID do repositório de dados.

JSON_SCHEMA_OBJECT: seu novo esquema JSON como um objeto JSON. 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: revise o esquema seguindo o procedimento Ver uma definição de esquema.