Información acerca de los documentos multimedia y los almacenes de datos

En esta página, se proporciona información sobre los documentos y los almacenes de datos para el contenido multimedia. Si usas recomendaciones de contenido multimedia o la búsqueda de contenido multimedia, revisa los requisitos de esquema para tus documentos y almacenes de datos en esta página antes de subir tus datos.

Descripción general

Un documento es cualquier elemento que subas a un almacén de datos de Vertex AI Agent Builder. En el caso del contenido multimedia, un documento suele contener información de metadatos sobre el contenido multimedia, como videos, artículos de noticias, archivos de música o podcasts. El objeto Document de la API captura esta información de metadatos.

Tu almacén de datos contiene una colección de documentos que subiste. Cuando creas un almacén de datos, especificas que contendrá documentos multimedia. Los almacenes de datos para contenido multimedia solo se pueden adjuntar a apps de este tipo, no a otros tipos de apps, como la búsqueda genérica y las recomendaciones. Los almacenes de datos se representan en la API con el recurso DataStore.

La calidad de los datos que subes tiene un efecto directo en la calidad de los resultados que proporcionan las apps de música. En general, cuanto más precisa y específica sea la información que puedas proporcionar, mejor será la calidad de tus resultados.

Los datos que subas al almacén de datos deben tener el formato de un esquema JSON específico. Los datos organizados en ese esquema deben estar en una tabla de BigQuery, un archivo o un conjunto de archivos en Cloud Storage, o en un objeto JSON que se pueda subir directamente con la consola de Google Cloud.

Esquema predefinido de Google en comparación con el esquema personalizado

Tienes dos opciones para el esquema de datos de medios.

• El esquema predefinido de Google. Si aún no diseñaste un esquema para tus datos multimedia, el esquema predefinido de Google es una buena opción.

• Tu propio esquema. Si ya tienes tus datos con formato en un esquema, puedes usar tu propio esquema, con el siguiente requisito.

  Debes tener campos en tu esquema que se puedan asignar a las cinco propiedades clave para el contenido multimedia:

  • title
  • uri
  • category
  • media_available_time
  • media_duration Este campo es importante para las aplicaciones de recomendaciones de contenido multimedia en las que el objetivo comercial es maximizar el porcentaje de conversiones (CVR) o la duración de reproducción por visitante.

  Hay propiedades clave adicionales que no son obligatorias, pero para obtener resultados de calidad, asigna tantas como puedas a tu esquema. Estas propiedades de medios son las siguientes:

  • description (muy recomendable)
  • image
  • image_name
  • image_uri
  • language-code
  • media_aggregated_rating
  • media_aggregated_rating_count
  • media_aggregated_rating_score
  • media_aggregated_rating_source
  • media_content_index
  • media_content_rating
  • media_country_of_origin
  • media_expire_time
  • media_filter_tag
  • media_hash_tag
  • media_in_language
  • media_organization
  • media_organization_custom_role
  • media_organization_name
  • media_organization_rank
  • media_organization_role
  • media_organization_uri
  • media_person
  • media_person_custom_role
  • media_person_name
  • media_person_rank
  • media_person_role
  • media_person_uri
  • media_production_year
  • media_type

  Para obtener más información sobre estas propiedades, consulta Propiedades clave. Los nombres son similares, pero algunos varían ligeramente. (por ejemplo, algunos nombres tienen el prefijo media_ y algunos están en plural).

Esquema JSON para Document

Cuando se usa contenido multimedia, los documentos pueden usar el esquema JSON predefinido de Google para el contenido multimedia.

Nota: Si usas tu propio esquema en lugar del esquema predefinido de Google, consulta Proporciona o detecta automáticamente un esquema para obtener información sobre cómo usar tu propio esquema.

Los documentos se suben con una representación de datos JSON o Struct. Asegúrate de que el JSON o la estructura del documento cumplan con el siguiente esquema JSON. El esquema JSON usa JSON Schema 2020-12 para la validación. Para obtener más información sobre el esquema JSON, consulta también la documentación de la especificación del esquema JSON en json-schema.org.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
    },
    "description": {
      "type": "string",
    },
    "media_type": {
      "type": "string",
    },
    "language_code": {
      "type": "string",
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
      }
    },
    "uri": {
      "type": "string",
    },
    "images": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "uri": {
            "type": "string",
          },
          "name": {
            "type": "string",
          }
        },
      }
    },
    "in_languages": {
      "type": "array",
      "items": {
        "type": "string",
      }
    },
    "country_of_origin": {
      "type": "string",
    },
    "content_index": {
      "type": "integer",
    },
    "persons": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
          },
          "role": {
            "type": "string",
          },
          "custom_role": {
            "type": "string",
          },
          "rank": {
            "type": "integer",
          },
          "uri": {
            "type": "string",
          }
        },
        "required": ["name", "role"],
      }
    },
    "organizations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
          },
          "role": {
            "type": "string",
          },
          "custom_role": {
            "type": "string",
          },
          "rank": {
            "type": "integer",
          },
          "uri": {
            "type": "string",
          }
        },
        "required": ["name", "role"],
      }
    },
    "hash_tags": {
      "type": "array",
      "items": {
        "type": "string",
      }
    },
    "filter_tags": {
      "type": "array",
      "items": {
        "type": "string",
      }
    },
    "duration": {
      "type": "string",
    },
    "content_rating": {
      "type": "array",
      "items": {
        "type": "string",
      }
    },
    "aggregate_ratings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "rating_source": {
            "type": "string",
          },
          "rating_score": {
            "type": "number",
          },
          "rating_count": {
            "type": "integer",
          }
        },
        "required": ["rating_source"],
      }
    },
    "available_time": {
      "type": "datetime",
    },
    "expire_time": {
      "type": "string",
    },
    "production_year": {
      "type": "integer",
    }
  },
  "required": ["title", "categories", "uri", "available_time"],
}

Ejemplo de objeto JSON Document

En el siguiente ejemplo, se muestra un ejemplo de un objeto Document JSON.

{
  "title": "Test document title",
  "description": "Test document description",
  "media_type": "sports-game",
  "in_languages": [
    "en-US"
  ],
  "language_code": "en-US",
  "categories": [
    "sports > clip",
    "sports > highlight"
  ],
  "uri": "http://www.example.com",
  "images": [
    {
      "uri": "http://example.com/img1",
      "name": "image_1"
    }
  ],
  "country_of_origin": "US",
  "content_index": 0,
  "persons": [
    {
      "name": "sports person",
      "role": "player",
      "rank": 0,
      "uri": "http://example.com/person"
    },
  ],
  "organizations": [
    {
      "name": "sports team",
      "role": "team",
      "rank": 0,
      "uri": "http://example.com/team"
    },
  ],
  "hash_tags": [
    "tag1"
  ],
  "filter_tags": [
    "filter_tag"
  ],
  "duration": "100s",
  "production_year": 1900,
  "content_rating": [
    "PG-13"
  ],
  "aggregate_ratings": [
    {
      "rating_source": "imdb",
      "rating_score": 4.5,
      "rating_count": 1250
    }
  ],
  "available_time": "2022-08-26T23:00:17Z"
}

Campos del documento

En esta sección, se enumeran los valores de campo que proporcionas cuando creas documentos para tu almacén de datos. Los valores deben corresponder a los valores usados en tu base de datos de documentos interna y deben reflejar con precisión el elemento representado.

Campos de objetos Document

Los siguientes campos son campos de nivel superior para el objeto Document. Consulta también estos campos en la página de referencia de Document.

Campo	Notas
name	Es el nombre completo y único del recurso del documento. Obligatorio para todos los métodos Document, excepto create y import. Durante la importación, el nombre se genera automáticamente y no es necesario proporcionarlo de forma manual.
id	El ID de documento que usa tu base de datos interna. El campo de ID debe ser único en todo el almacén de datos. Los mismos valores se usan cuando registras un evento de usuario, y los métodos recommend y search los muestran.
schemaId	Obligatorio. Es el identificador del esquema ubicado en el mismo almacén de datos. Se debe establecer como "default_schema", que se crea automáticamente cuando se crea el almacén de datos predeterminado.
parentDocumentId	Es el ID del documento superior. En el caso de los documentos de nivel superior (raíz), parent_document_id puede estar vacío o puede apuntar a sí mismo. En el caso de los documentos secundarios, parent_document_id debe apuntar a un documento raíz válido.

Propiedades principales

Las siguientes propiedades se definen con el formato de esquema JSON predefinido para el contenido multimedia.

Para obtener más información sobre las propiedades JSON, consulta la documentación de Understanding JSON Schema sobre las propiedades en json-schema.org.

En la siguiente tabla, se definen las propiedades clave planas.

Nombre del campo	Notas
title	Cadena: Obligatorio Es el título del documento de tu base de datos. Una string codificada en UTF-8. Límite de 1,000 caracteres.
categories	Cadena: Obligatorio Categorías de documentos Esta propiedad se repite para admitir un documento que pertenece a varias categorías paralelas. Usa la ruta de acceso completa de la categoría para obtener resultados de mayor calidad. Para representar la ruta de acceso completa de una categoría, usa el símbolo > para separar las jerarquías. Si > forma parte del nombre de la categoría, reemplázalo por otros caracteres. Por ejemplo: "categories": [ "sports > highlight" ] Un documento puede contener un máximo de 250 categorías. Cada categoría es una cadena codificada en UTF-8 con un límite de longitud de 5,000 caracteres.
uri	Cadena: Obligatorio Es el URI del documento. El límite de longitud es de 5,000 caracteres.
description	Cadena: Muy recomendable Descripción del documento. El límite de longitud es de 5,000 caracteres.
media_type	Cadena: Este campo es obligatorio para películas y programas. Categoría de nivel superior. Tipos admitidos: movie, show, concert, event, live-event, broadcast, tv-series, episode, video-game, clip, vlog, audio, audio-book, music, album, articles, news, radio, podcast, book y sports-game. Los valores movie y show tienen una importancia especial. Hacen que los documentos se enriquezcan de una manera que mejora la clasificación y ayuda a los usuarios que realizan búsquedas de títulos a encontrar contenido alternativo que podría interesarles.
language_code	Cadena: Opcional Es el idioma del título o la descripción, y de otros atributos de cadena. Usa las etiquetas de idioma definidas en el BCP 47. En el caso de la recomendación de documentos, este campo se ignora y el idioma del texto se detecta automáticamente. El documento puede incluir texto en diferentes idiomas, pero duplicar documentos para proporcionar texto en varios idiomas puede degradar el rendimiento. Para la búsqueda de documentos, este campo está en uso. Si no se establece, el valor predeterminado es “en-US”. Por ejemplo, "language_code": "en-US".
duration	Cadena: Es obligatoria para las apps de recomendaciones de contenido multimedia en las que el objetivo comercial es la tasa de clics (CVR) o la duración de reproducción por sesión. Es la duración del contenido multimedia. La duración se debe codificar como una cadena. La codificación debe ser la misma que la codificación de cadenas JSON de google::protobuf::Duration. Por ejemplo: “5s” o “1m”.
available_time	Fecha y hora: obligatoria Es la hora en la que el contenido está disponible para los usuarios finales. Este campo identifica la actualización de un contenido para los usuarios finales. La marca de tiempo debe cumplir con el estándar RFC 3339. Por ejemplo: "2022-08-26T23:00:17Z"
expire_time	Cadena: Opcional Es la fecha en la que vencerá el contenido para los usuarios finales. Este campo identifica la actualización de un contenido para los usuarios finales. La marca de tiempo debe cumplir con el estándar RFC 3339. Por ejemplo: "2032-12-31T23:00:17Z"
in_languages	Cadena (opcional) repetida Es el idioma del contenido multimedia. Usa etiquetas de idioma definidas en el BCP 47. Por ejemplo: "in_languages": [ "en-US"]
country_of_origin	Cadena: Opcional Es el país de origen del documento multimedia. Tiene un límite de 128 caracteres. Por ejemplo: "country_of_origin": "US"
content_index	Int: Opcional Índice de contenido del documento multimedia. El campo de índice de contenido se puede usar para ordenar los documentos en relación con otros. Por ejemplo, el número de episodio se puede usar como el índice de contenido. El índice de contenido debe ser un número entero no negativo. Por ejemplo: "content_index": 0
filter_tags	Cadena (opcional) repetida Filtrar las etiquetas del documento Se permiten 250 valores como máximo por documento, con un límite de longitud de 1,000 caracteres. De lo contrario, se muestra un error INVALID_ARGUMENT. Esta etiqueta se puede usar para filtrar los resultados de las recomendaciones pasando la etiqueta como parte de RecommendRequest.filter. Por ejemplo: "filter_tags": [ "filter_tag"]
hash_tags	Cadena (opcional) repetida Hashtags del documento Se permiten 100 valores como máximo por documento, con un límite de longitud de 5,000 caracteres. Por ejemplo: "hash_tags": [ "soccer", "world cup"]
content_rating	Cadena (opcional) repetida La clasificación del contenido, que se usa para los sistemas de advertencias y el filtrado de contenido según el público Se permiten 100 valores como máximo por documento con un límite de longitud de 128 caracteres. Esta etiqueta se puede usar para filtrar los resultados de las recomendaciones pasando la etiqueta como parte de RecommendRequest.filter. Por ejemplo: content_rating: ["PG-13"]

En la siguiente tabla, se definen las propiedades clave jerárquicas.

Nombre del campo	Notas
images	Objeto: Opcional, repetido Es la propiedad de clave raíz para encapsular propiedades relacionadas con imágenes.
images.uri	Cadena: Opcional Es el URI de la imagen. El límite de longitud es de 5,000 caracteres.
images.name	Cadena: Opcional Es el nombre de la imagen. Tiene un límite de 128 caracteres.
persons	Objeto: Opcional, repetido Es la propiedad de clave raíz para encapsular las propiedades relacionadas con la persona. Por ejemplo: "persons":[{"name":"sports person","role":"player","rank":0,"uri":"http://example.com/person"}]
persons.name	Cadena: Obligatorio Es el nombre de la persona.
persons.role	Cadena: Obligatorio Es el rol de la persona en el elemento multimedia. Valores admitidos: director, actor, jugador, equipo, liga, editor, autor, personaje, colaborador, creador, editor, financiador, productor, proveedor, publicador, patrocinador, traductor, música de, canal, rol personalizado Si no se aplica ninguno de los valores admitidos a role, establece role en custom-role y proporciona el valor en el campo custom_role.
persons.custom_role	Cadena: Opcional custom_role se establece solo si role se configura como custom-role. Debe ser una cadena codificada en UTF-8 con un límite de longitud de 128 caracteres. Debe coincidir con el patrón [a-zA-Z0-9][a-zA-Z0-9_]*.
persons.rank	Int: Opcional Se usa para la clasificación de roles. Por ejemplo, para el primer actor, role = "actor", rank = 1
persons.uri	Cadena: Opcional Es el URI de la persona.
organizations	Objeto: Opcional, repetido Es la propiedad de clave raíz para encapsular las propiedades relacionadas con organization. Por ejemplo: "organizations ":[{"name":"sports team","role":"team","rank":0,"uri":"http://example.com/team"}]
organizations.name	Cadena: Obligatorio Nombre de la organización.
organizations.role	Cadena: Obligatorio Es el rol de la organización en el elemento multimedia. Valores admitidos: director, actor, jugador, equipo, liga, editor, autor, personaje, colaborador, creador, editor, financiador, productor, proveedor, publicador, patrocinador, traductor, música de, canal, rol personalizado Si no se aplica ninguno de los valores admitidos a role, establece role en custom-role y proporciona el valor en el campo custom_role.
organizations.custom_role	Cadena: Opcional custom_role se establece solo si role se configura como custom-role. Debe ser una cadena codificada en UTF-8 con un límite de longitud de 128 caracteres. Debe coincidir con el patrón [a-zA-Z0-9][a-zA-Z0-9_]*.
organizations.rank	Cadena: Opcional Se usa para la clasificación de roles. Por ejemplo, para el primer publicador: role = "publisher", rank = 1.
organizations.uri	Cadena: Opcional Es el URI de la organización.
aggregate_ratings	Objeto: Opcional, repetido Es la propiedad de clave raíz para encapsular las propiedades relacionadas con aggregate_rating.
aggregate_ratings.rating_source	Cadena: Obligatorio Es la fuente de la clasificación. Por ejemplo, imdb o rotten_tomatoes. Debe ser una cadena codificada en UTF-8 con un límite de longitud de 128 caracteres. Debe coincidir con el patrón [a-zA-Z0-9][a-zA-Z0-9_]*.
aggregate_ratings.rating_score	Doble (opcional) Es la calificación agregada. La calificación se debe normalizar al rango [1, 5].
aggregate_ratings.rating_count	Int: Opcional Es la cantidad de opiniones individuales. Debe ser un valor no negativo.

Niveles de documentos

Los niveles de documentos determinan la jerarquía de tu almacén de datos. Por lo general, debes tener un almacén de datos de un nivel o de dos niveles. Solo se admiten dos capas.

Por ejemplo, puedes tener un almacén de datos de un solo nivel en el que cada documento sea un elemento individual. Como alternativa, puedes elegir un almacén de datos de dos niveles que contenga grupos de elementos y elementos individuales.

Tipos a nivel del documento

Existen dos tipos de documentos:

• Madre o padre. Los documentos superiores son lo que Vertex AI Search muestra en las recomendaciones y búsquedas. Los elementos superiores pueden ser documentos individuales o grupos de documentos similares. Se recomienda este tipo de nivel.

• Menor. Los documentos secundarios son versiones del documento superior de un grupo. Los documentos secundarios solo pueden ser documentos individuales. Por ejemplo, si el documento superior es "Ejemplo de programa de TV", los documentos secundarios podrían ser "Episodio 1" y "Episodio 2". Este tipo de nivel puede ser difícil de configurar y mantener, por lo que no se recomienda.

Información acerca de la jerarquía del almacén de datos

Cuando planifiques la jerarquía de tu almacén de datos, decide si este debe contener solo elementos superiores o superiores y secundarios. El punto clave que debes recordar es que las recomendaciones y las búsquedas solo muestran documentos superiores.

Por ejemplo, un almacén de datos solo para padres podría funcionar bien para los audiolibros, en los que un panel de recomendaciones muestra una selección de audiolibros individuales. Por otro lado, si subiste episodios de programas de TV como documentos superiores a un almacén de datos solo para superiores, se podrían recomendar varios episodios fuera de orden en el mismo panel.

Un almacén de datos de programas de TV podría funcionar con elementos superiores y secundarios, en el que cada documento superior representa un programa de TV con documentos secundarios que representan los episodios de ese programa. Este almacén de datos de dos niveles permite que el panel de recomendaciones muestre una variedad de programas de TV similares. El usuario final puede hacer clic en un programa en particular para seleccionar un episodio y mirarlo.

Debido a que las jerarquías de elementos superiores y secundarios pueden ser difíciles de configurar y mantener, se recomiendan los almacenes de datos solo para elementos superiores.

Por ejemplo, un almacén de datos de programas de TV puede funcionar bien como un almacén de datos solo para elementos superiores, en el que cada documento superior representa un programa de TV que se puede recomendar y no se incluyen episodios individuales (por lo que no se recomienda).

Si determinas que tu almacén de datos debe tener elementos superiores e inferiores, es decir, grupos y elementos individuales, pero solo tienes elementos individuales, debes crear elementos superiores para los grupos. La información mínima que debes proporcionar para un elemento superior es id, title y categories. Para obtener más información, consulta la sección Campos de documentos.

Esquema de BigQuery para el contenido multimedia

Si planeas importar tus documentos desde BigQuery, usa el esquema predefinido de BigQuery para crear una tabla de BigQuery con el formato correcto y cargarla con los datos de tus documentos antes de importarlos.

[
  {
    "name": "id",
    "mode": "REQUIRED",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "schemaId",
    "mode": "REQUIRED",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "parentDocumentId",
    "mode": "NULLABLE",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "jsonData",
    "mode": "NULLABLE",
    "type": "STRING",
    "fields": []
  }
]