Esta página se ha traducido con Cloud Translation API.

Proporcionar o detectar automáticamente un esquema

Cuando importas datos estructurados mediante la consola de Google Cloud , AI Applications detecta automáticamente el esquema. Puede usar este esquema detectado automáticamente en su motor o usar la API para proporcionar un esquema que indique la estructura de los datos.

Si proporciona un esquema y, más adelante, lo actualiza con un nuevo esquema, este debe ser retrocompatible con el original. De lo contrario, la actualización del esquema fallará.

Para obtener información de referencia sobre el esquema, consulta dataStores.schemas.

Métodos para proporcionar el esquema de tu almacén de datos

Hay varias formas de determinar el esquema de los datos estructurados.

Detecta y edita automáticamente. Permite que Aplicaciones de IA detecte automáticamente y sugiera un esquema inicial. A continuación, puedes refinar el esquema a través de la interfaz de la consola. Google recomienda que, después de que se detecten automáticamente los campos, asigne propiedades clave a todos los campos importantes.

Este es el método que usarás cuando sigas las instrucciones de la Google Cloud consola para los datos estructurados en Crear un almacén de datos de búsqueda y Crear un almacén de datos de recomendaciones personalizadas.
Proporciona el esquema como un objeto JSON. Proporciona el esquema a las aplicaciones de IA como un objeto JSON. Debes haber preparado un objeto JSON correcto. Para ver un ejemplo de objeto JSON, consulta Ejemplo de esquema como objeto JSON. Después de crear el esquema, suba sus datos según ese esquema.

Este es el método que puedes usar al crear un almacén de datos a través de la API mediante un comando curl (o un programa). Por ejemplo, consulte Importar una vez desde BigQuery. Consulta también las siguientes instrucciones: Proporcionar tu propio esquema.
Medios: proporcione sus datos en el esquema definido por Google. Si crea un almacén de datos para contenido multimedia, puede usar el esquema predefinido de Google. Si eliges esta opción, se presupone que has estructurado el objeto JSON con el formato que se indica en el artículo Acerca de los documentos multimedia y el almacén de datos. De forma predeterminada, la detección automática añade al esquema los campos nuevos que encuentra durante la ingestión de datos.

Este es el enfoque que se utiliza cuando se siguen las instrucciones de Crear una aplicación multimedia y un almacén de datos. También es el enfoque de los tutoriales Empezar a usar las recomendaciones de contenido multimedia y Empezar a usar la búsqueda de contenido multimedia, donde los datos de muestra se proporcionan en el esquema predefinido de Google.
Multimedia: detecta y edita automáticamente, e incluye las propiedades multimedia necesarias. En el caso de los datos multimedia, puede usar la detección automática para sugerir el esquema y editarlo para perfeccionarlo. En tu objeto JSON, debes incluir campos que se puedan asignar a las propiedades de la clave multimedia: title, uri, category, media_duration y media_available_time.

Este es el método que usarás al importar datos multimedia a través de la consolaGoogle Cloud si los datos multimedia no están en el esquema definido por Google.
Multimedia: proporciona tu propio esquema como objeto JSON. Proporciona el esquema a las aplicaciones de IA como un objeto JSON. Debes haber preparado un objeto JSON correcto. El esquema debe incluir campos que se puedan asignar a las propiedades de la clave multimedia: title, uri, category, media_duration y media_available_time.

Para ver un ejemplo de objeto JSON, consulta Ejemplo de esquema como objeto JSON. Después de crear el esquema, suba sus datos multimedia según ese esquema.

Para este método, se usa la API a través de un comando curl (o un programa). Consulta las instrucciones de la sección Proporcionar tu propio esquema.

Acerca de la detección y la edición automáticas

Cuando empieces a importar datos, Vertex AI Search tomará una muestra de los primeros documentos que se importen. A partir de estos documentos, propone un esquema para los datos, que puedes revisar o editar.

Si los campos que quiere asignar a las propiedades clave no están presentes en los documentos de muestra, puede añadirlos manualmente cuando revise el esquema.

Si Vertex AI Search encuentra campos adicionales más adelante en la importación de datos, los importará y los añadirá al esquema. Si quiere editar el esquema después de importar todos los datos, consulte Actualizar el esquema.

Ejemplo de esquema como objeto JSON

Puedes definir tu propio esquema con el formato JSON Schema, que es un lenguaje declarativo de código abierto para definir, anotar y validar documentos JSON. Por ejemplo, esta es una anotación 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"
    }
  }
}

Si define un esquema de contenido multimedia, debe incluir campos que se puedan asignar a las propiedades de clave de contenido multimedia. Estas propiedades clave se muestran en este ejemplo.

Estos son algunos de los campos de este ejemplo de esquema:

dynamic: si dynamic tiene el valor de cadena "true", las propiedades nuevas que se encuentren en los datos importados se añadirán al esquema. Si dynamic tiene el valor "false", las propiedades nuevas que se encuentren en los datos importados se ignorarán. Las propiedades no se añadirán al esquema ni se importarán los valores.

Por ejemplo, un esquema tiene dos propiedades: title y description, y usted sube datos que contienen propiedades de title, description y rating. Si dynamic es "true", se importarán la propiedad y los datos de valoraciones. Si dynamic es "false", no se importarán las propiedades rating, aunque sí title y description.

El valor predeterminado es "true".
datetime_detection. Si datetime_detection se define como booleano true, cuando se importen datos en formato de fecha y hora, el tipo de esquema se definirá como datetime. Los formatos admitidos son RFC 3339 y ISO 8601.

Por ejemplo:
- 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
Si datatime_detection se define como booleano false, cuando se importan datos en formato de fecha y hora, el tipo de esquema se define como string.

El valor predeterminado es true.
geolocation_detection. Si geolocation_detection se define como el valor booleano true, cuando se importen datos en formato de geolocalización, el tipo de esquema se definirá como geolocation. Los datos se detectan como geolocalización si son un objeto que contiene un número de latitud y un número de longitud, o un objeto que contiene una cadena de dirección.

Por ejemplo:
- "myLocation": {"latitude":37.42, "longitude":-122.08}
- "myLocation": {"address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043"}
Si geolocation_detection se define como el valor booleano false, cuando se importen datos en formato de geolocalización, el tipo de esquema se definirá como object.

El valor predeterminado es true.
keyPropertyMapping. Campo que asigna palabras clave predefinidas a campos críticos de tus documentos, lo que ayuda a aclarar su significado semántico. Los valores son title, description, uri y category. Ten en cuenta que el nombre del campo no tiene por qué coincidir con el valor de keyPropertyValues. Por ejemplo, en el caso de un campo al que hayas llamado my_title, puedes incluir un campo keyPropertyValues con el valor title.

En el caso de los almacenes de datos de búsqueda, los campos marcados con keyPropertyMapping se pueden indexar y buscar de forma predeterminada, pero no se pueden recuperar, completar ni usar en facetas dinámicas. Esto significa que no es necesario incluir los campos indexable o searchable con un campo keyPropertyValues para obtener el comportamiento predeterminado esperado.

Nota: Las propiedades clave pueden mejorar la calidad de los resultados de búsqueda y de las recomendaciones, así como la precisión del autocompletado de búsqueda. Si usas la detección automática de esquemas, las propiedades clave no se añaden automáticamente. Te recomendamos que utilices el método schemas.patch para marcar los campos de datos como propiedades clave, especialmente title, uri y description.
type. Tipo del campo. Es un valor de cadena que es datetime, geolocation o uno de los tipos primitivos (integer, boolean, object, array, number o string).

Los siguientes campos de propiedad solo se aplican a las aplicaciones de búsqueda:

retrievable. Indica si este campo se puede devolver en una respuesta de búsqueda. Se puede definir para los campos de tipo number, string, boolean, integer, datetime y geolocation. Se pueden definir un máximo de 50 campos como recuperables. Los campos definidos por el usuario y los campos keyPropertyValues no se pueden recuperar de forma predeterminada. Para que se pueda recuperar un campo, incluye "retrievable": true con el campo.
indexable. Indica si este campo se puede filtrar, facetar, potenciar u ordenar en el método servingConfigs.search. Se puede definir para los campos de tipo number, string, boolean, integer, datetime y geolocation. Se pueden definir un máximo de 50 campos como indexables. Los campos definidos por el usuario no se pueden indexar de forma predeterminada, excepto los campos que contengan el campo keyPropertyMapping. Para que un campo se pueda indexar, incluye "indexable": true con el campo.
dynamicFacetable. Indica que el campo se puede usar como una faceta dinámica. Se puede definir para los campos de tipo number, string, boolean y integer. Para que un campo se pueda usar como facetado dinámico, también debe poder indexarse: incluye "dynamicFacetable": true y "indexable": true con el campo.
searchable. Indica si este campo se puede indexar de forma inversa para que coincida con consultas de texto no estructurado. Solo se puede definir en campos de tipo string. Se pueden definir un máximo de 50 campos como aptos para búsquedas. Los campos definidos por el usuario no se pueden buscar de forma predeterminada, excepto los campos que contienen el campo keyPropertyMapping. Para que se pueda buscar un campo, incluye "searchable": true con el campo.
completable. Indica si este campo se puede devolver como una sugerencia de autocompletado. Solo se puede definir en campos de tipo string. Para que un campo se pueda completar, incluye "completable": true con el campo.

Además, el siguiente campo solo se aplica a las aplicaciones de recomendaciones:

recommendationsFilterable. Indica que el campo se puede usar en una expresión de filtro de recomendaciones. Para obtener información general sobre cómo filtrar recomendaciones, consulta el artículo Filtrar recomendaciones.
```
  ...
    "genres": {
    "type": "string",
    "recommendationsFilterable": true,
    ...
  },
```

Proporcionar tu propio esquema como objeto JSON

Para proporcionar tu propio esquema, crea un almacén de datos que contenga un esquema vacío y, a continuación, actualiza el esquema proporcionando tu esquema como un objeto JSON. Sigue estos pasos:

Prepara el esquema como un objeto JSON. Para ello, consulta el esquema de ejemplo como objeto JSON.

Crea un almacén de datos.

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"
}'

Haz los cambios siguientes:

PROJECT_ID: el ID de tu proyecto de Google Cloud .
DATA_STORE_ID: el ID del almacén de datos de Vertex AI Search que quieres crear. Este ID solo puede contener letras en minúscula, números, guiones bajos y guiones.
DATA_STORE_DISPLAY_NAME: el nombre visible del almacén de datos de Vertex AI Search que quieres crear.
INDUSTRY_VERTICAL: GENERIC o MEDIA

Usa el método de la API schemas.patch para proporcionar tu nuevo esquema JSON como 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
}'

Haz los cambios siguientes:

PROJECT_ID: el ID de tu proyecto de Google Cloud .
DATA_STORE_ID: el ID del almacén de datos de Vertex AI Search.

JSON_SCHEMA_OBJECT: tu nuevo esquema JSON como objeto JSON. Por ejemplo:

{
  "$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"
    }
  }
}

Ejemplo de comando y 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: Revisa el esquema siguiendo el procedimiento Ver una definición de esquema.