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, o Gemini Enterprise deteta 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. Permita que o Gemini Enterprise detete automaticamente e sugira 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 originais.
Forneça o esquema como um objeto JSON. Forneça o esquema ao Gemini Enterprise 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.

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

Quando começa a importar dados, o Gemini Enterprise 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 o Gemini Enterprise 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
    }
  }
}

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.

Os campos marcados com keyPropertyMapping são, por predefinição, indexáveis e pesquisáveis, mas nã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 a precisão do 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).
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.

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 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 o seguinte:

PROJECT_ID: o ID do seu projeto.
DATA_STORE_ID: o ID do armazenamento de dados 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 da base de dados que quer criar.
INDUSTRY_VERTICAL: GENERIC

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.
DATA_STORE_ID: o ID do armazenamento de dados.

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.