Esta página foi traduzida pela API Cloud Translation.

Sobre os documentos de mídia e os repositórios de dados

Esta página contém informações sobre documentos e repositórios de dados para mídia. Se você estiver usando recomendações de mídia ou pesquisa de mídia, revise os requisitos de esquema para seus documentos e repositórios de dados nesta página antes de fazer upload dos dados.

Visão geral

Um documento é qualquer item que você envia para um repositório de dados do Vertex AI Agent Builder. Para mídia, um documento geralmente contém informações de metadados sobre conteúdo de mídia, como vídeos, artigos de notícias, arquivos de música ou podcasts. O objeto Document na API captura essas informações de metadados.

O repositório de dados contém uma coleção de documentos que você enviou. Ao criar um repositório de dados, você especifica que ele vai conter documentos de mídia. Os repositórios de dados para mídia só podem ser anexados a apps de mídia, não a outros tipos de apps, como pesquisa genérica e recomendações. Os repositórios de dados são representados na API pelo recurso DataStore.

A qualidade dos dados enviados afeta diretamente a qualidade dos resultados fornecidos pelos apps de mídia. Em geral, quanto mais precisas e específicas forem as informações que você fornecer, maior será a qualidade dos resultados.

Os dados enviados para o repositório de dados precisam ser formatados em um esquema JSON específico. Os dados organizados nesse esquema precisam estar em uma tabela do BigQuery, em um ou mais arquivos no Cloud Storage ou em um objeto JSON que pode ser enviado diretamente usando o console do Google Cloud.

Esquema predefinido pelo Google x esquema personalizado

Você tem duas opções para o esquema de dados de mídia.

O esquema predefinido do Google. Se você ainda não criou um esquema para seus dados de mídia, o esquema predefinido do Google é uma boa opção.
Seu próprio esquema. Se os dados já estiverem formatados em um esquema, você poderá usar seu próprio esquema, com o seguinte requisito.

É necessário ter campos no esquema que possam ser mapeados para as cinco propriedades principais de mídia:
- title
- uri
- category
- media_available_time
- media_duration Esse campo é importante para apps de recomendações de mídia em que o objetivo de negócios é maximizar a taxa de conversão (CVR) ou a duração de exibição por visitante.
Há outras propriedades principais que não são obrigatórias, mas, para resultados de qualidade, mapeie o máximo possível delas no esquema. Essas propriedades de mídia são as seguintes:
- description (altamente recomendado)
- 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 mais informações sobre essas propriedades, consulte Propriedades chave. Os nomes são semelhantes, mas alguns variam um pouco. Por exemplo, alguns nomes são precedidos por media_ e outros são pluralizados.

Esquema JSON para `Document`

Ao usar mídia, os documentos podem usar o esquema JSON predefinido do Google para mídia.

Os documentos são enviados com uma representação de dados JSON ou Struct. Verifique se o JSON ou a estrutura do documento está em conformidade com o esquema JSON a seguir. O esquema JSON usa o JSON Schema 2020-12 para validação. Para saber mais sobre o esquema JSON, consulte a documentação de especificação do esquema JSON em 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"],
}

Exemplo de objeto JSON `Document`

O exemplo a seguir mostra um objeto JSON Document.

{
  "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 do documento

Esta seção lista os valores de campo que você fornece ao criar documentos para o repositório de dados. Os valores precisam corresponder aos valores usados no banco de dados de documentos interno e refletir com precisão o item representado.

Campos de objeto `Document`

Os campos a seguir são de nível superior para o objeto Document. Consulte estes campos na página de referência Document.

Campo	Observações
`name`	O nome exclusivo completo do recurso do documento. Obrigatório para todos os métodos `Document`, exceto `create` e `import`. Durante a importação, o nome é gerado automaticamente e não precisa ser fornecido manualmente.
`id`	O ID do documento usado pelo seu banco de dados interno. O campo de ID precisa ser exclusivo em todo o repositório de dados. O mesmo valor é usado quando você registra um evento de usuário e também é retornado pelos métodos `recommend` e `search`.
`schemaId`	Obrigatório. O identificador do esquema localizado no mesmo repositório de dados. Precisa ser definido como "default_schema", que é criado automaticamente quando o repositório de dados padrão é criado.
`parentDocumentId`	O ID do documento pai. Para documentos de nível superior (raiz), `parent_document_id` pode estar vazio ou apontar para si mesmo. Para documentos filhos, `parent_document_id` precisa apontar para um documento raiz válido.

Propriedades principais

As propriedades a seguir são definidas usando o formato predefinido do esquema JSON para mídia.

Para mais informações sobre propriedades JSON, consulte a documentação "Como entender o esquema JSON" para propriedades em json-schema.org.

A tabela a seguir define as propriedades de chaves planas.

Nome do campo	Observações
`title`	String: obrigatório Título do documento do seu banco de dados. Uma string codificada em UTF-8. Limitado a 1.000 caracteres.
`categories`	String: obrigatório Categorias de documentos. Essa propriedade é repetida para oferecer suporte a um documento pertencente a várias categorias paralelas. Use o caminho completo da categoria para resultados de maior qualidade. Para representar o caminho completo de uma categoria, use o símbolo `>` para separar as hierarquias. Se `>` fizer parte do nome da categoria, substitua-o por outro caractere. Exemplo: `"categories": [ "sports > highlight" ]` Um documento pode conter no máximo 250 categorias. Cada categoria é uma string codificada em UTF-8 com um limite de comprimento de 5.000 caracteres.
`uri`	String: obrigatório URI do documento. Limite de 5.000 caracteres.
`description`	String: altamente recomendado Descrição do documento. Limite de 5.000 caracteres.
`media_type`	String: este campo é obrigatório para filmes e programas Categoria de nível superior. Tipos aceitos: `movie`, `show`, `concert`, `event`, `live-event`, `broadcast`, `tv-series`, `episode`, `video-game`, `clip`, `vlog`, `audio`, `audio-book`, `music`, `album`, `articles`, `news`, `radio`, `podcast`, `book` e `sports-game`. Os valores `movie` e `show` têm um significado especial. Eles enriquecem os documentos de uma forma que melhora a classificação e ajuda os usuários a fazer pesquisas de título para encontrar conteúdo alternativo em que possam estar interessados.
`language_code`	String: opcional Idioma do título/descrição e outros atributos de string. Use tags de idioma definidas pelo BCP 47. Para recomendações de documentos, esse campo é ignorado, e o idioma do texto é detectado automaticamente. O documento pode incluir texto em diferentes idiomas, mas a duplicação de documentos para fornecer texto em vários idiomas pode resultar em uma performance degradada. Para a pesquisa de documentos, esse campo está em uso. O padrão é "en-US" se não for definido. Por exemplo, `"language_code": "en-US"`
`duration`	String: obrigatório para apps de recomendações de mídia em que o objetivo de negócios é a taxa de cliques (CTR) ou a duração de exibição por sessão. Duração do conteúdo de mídia. A duração precisa ser codificada como uma string. A codificação precisa ser a mesma que a codificação de string JSON `google::protobuf::Duration`. Por exemplo: "5s", "1m"
`available_time`	Data e hora: obrigatório O tempo em que o conteúdo está disponível para os usuários finais. Esse campo identifica a atualidade de um conteúdo para os usuários finais. O carimbo de data/hora precisa estar em conformidade com o padrão RFC 3339. Exemplo: `"2022-08-26T23:00:17Z"`
`expire_time`	String: opcional O tempo de expiração do conteúdo para os usuários finais. Esse campo identifica a atualidade de um conteúdo para os usuários finais. O carimbo de data/hora precisa estar em conformidade com o padrão RFC 3339. Exemplo: `"2032-12-31T23:00:17Z"`
`in_languages`	String: opcional, repetida Idioma do conteúdo de mídia. Use tags de idioma definidas pelo BCP 47. Por exemplo: `"in_languages": [ "en-US"]`
`country_of_origin`	String: opcional País de origem do documento de mídia. Limite de 128 caracteres. Por exemplo: `"country_of_origin": "US"`
`content_index`	Int: opcional Índice de conteúdo do documento de mídia. O campo de índice de conteúdo pode ser usado para ordenar os documentos em relação a outros. Por exemplo, o número do episódio pode ser usado como o índice de conteúdo. O índice de conteúdo precisa ser um número inteiro não negativo. Por exemplo: `"content_index": 0`
`filter_tags`	String: opcional, repetida Filtrar tags do documento. São permitidos no máximo 250 valores por documento, com um limite de comprimento de 1.000 caracteres. Caso contrário, um erro INVALID_ARGUMENT será retornado. Essa tag pode ser usada para filtrar os resultados de recomendação transmitindo a tag como parte do `RecommendRequest.filter`. Por exemplo: `"filter_tags": [ "filter_tag"]`
`hash_tags`	String: opcional, repetida Hashtags do documento. É permitido no máximo 100 valores por documento, com um limite de comprimento de 5.000 caracteres. Por exemplo: `"hash_tags": [ "soccer", "world cup"]`
`content_rating`	String: opcional, repetida A classificação do conteúdo, usada para sistemas de avisos e filtragem de conteúdo com base no público-alvo. São permitidos no máximo 100 valores por documento com um limite de comprimento de 128 caracteres. Essa tag pode ser usada para filtrar os resultados de recomendação transmitindo a tag como parte do `RecommendRequest.filter`. Por exemplo: `content_rating: ["PG-13"]`

A tabela a seguir define as propriedades de chave hierárquicas.

Nome do campo	Observações
`images`	Objeto: opcional, repetido Propriedade da chave raiz para encapsular propriedades relacionadas à imagem.
`images.uri`	String: opcional URI da imagem. Limite de 5.000 caracteres.
`images.name`	String: opcional Nome da imagem. Limite de 128 caracteres.
`persons`	Objeto: opcional, repetido Propriedade da chave raiz para encapsular as propriedades relacionadas à pessoa. Por exemplo: `"persons":[{"name":"sports person","role":"player","rank":0,"uri":"http://example.com/person"}]`
`persons.name`	String: obrigatório Nome da pessoa.
`persons.role`	String: obrigatório O papel da pessoa no item de mídia. Valores aceitos: diretor, ator, jogador, equipe, liga, editor, autor, personagem, colaborador, criador, editor, financiador, produtor, provedor, editor, patrocinador, tradutor, music-by, canal, função personalizada Se nenhum dos valores com suporte for aplicado a `role`, defina `role` como `custom-role` e forneça o valor no campo `custom_role`.
`persons.custom_role`	String: opcional `custom_role` será definido se e somente se `role` estiver definido como `custom-role`. Precisa ser uma string codificada em UTF-8 com um limite de comprimento de 128 caracteres. Precisa corresponder ao padrão: `[a-zA-Z0-9][a-zA-Z0-9_]*`.
`persons.rank`	Int: opcional Usado para classificação de função. Por exemplo, para o primeiro ator, `role = "actor", rank = 1`
`persons.uri`	String: opcional URI da pessoa.
`organizations`	Objeto: opcional, repetido Propriedade da chave raiz para encapsular as propriedades relacionadas a `organization`. Por exemplo: `"organizations ":[{"name":"sports team","role":"team","rank":0,"uri":"http://example.com/team"}]`
`organizations.name`	String: obrigatório Nome da organização.
`organizations.role`	String: obrigatório Função da organização no item de mídia. Valores aceitos: diretor, ator, jogador, equipe, liga, editor, autor, personagem, colaborador, criador, editor, financiador, produtor, provedor, editor, patrocinador, tradutor, music-by, canal, função personalizada Se nenhum dos valores aceitos for aplicado a `role`, defina `role` como `custom-role` e forneça o valor no campo `custom_role`.
`organizations.custom_role`	String: opcional `custom_role` será definido se e somente se `role` estiver definido como `custom-role`. Precisa ser uma string codificada em UTF-8 com um limite de comprimento de 128 caracteres. Precisa corresponder ao padrão: `[a-zA-Z0-9][a-zA-Z0-9_]*`.
`organizations.rank`	String: opcional Usado para classificação de função. Por exemplo, para o primeiro editor: `role = "publisher", rank = 1`.
`organizations.uri`	String: opcional URI da organização.
`aggregate_ratings`	Objeto: opcional, repetido Propriedade da chave raiz para encapsular as propriedades relacionadas a `aggregate_rating`.
`aggregate_ratings.rating_source`	String: obrigatório A origem da classificação. Por exemplo, `imdb` ou `rotten_tomatoes`. Precisa ser uma string codificada em UTF-8 com um limite de 128 caracteres. Precisa corresponder ao padrão: `[a-zA-Z0-9][a-zA-Z0-9_]*`.
`aggregate_ratings.rating_score`	Duplo: opcional A classificação agregada. A classificação precisa ser normalizada para o intervalo [1, 5].
`aggregate_ratings.rating_count`	Int: opcional O número de avaliações individuais. Precisa ser um valor não negativo.

Níveis de documentos

Os níveis de documentos determinam a hierarquia no repositório de dados. Normalmente, você tem um repositório de dados de um ou dois níveis. Há suporte apenas para duas camadas.

Por exemplo, é possível ter um repositório de dados de nível único em que cada documento é um item individual. Como alternativa, você pode escolher um repositório de dados de dois níveis que contenha grupos de itens e itens individuais.

Tipos no nível do documento

Há dois tipos de nível de documento:

Pai. Os documentos principais são o que a Vertex AI para Pesquisa retorna em recomendações e pesquisas. Os documentos principais podem ser documentos individuais ou grupos de documentos semelhantes. Esse tipo de nível é recomendado.
Criança. Os documentos filhos são versões do documento principal de um grupo. As crianças só podem ser documentos individuais. Por exemplo, se o documento pai for "Example TV Show", os filhos podem ser "Episode 1" e "Episode 2". Esse tipo de nível pode ser difícil de configurar e manter e não é recomendado.

Sobre a hierarquia do repositório de dados

Ao planejar a hierarquia do repositório de dados, decida se ele vai conter apenas os pais ou os pais e filhos. O ponto principal a ser lembrado é que as recomendações e pesquisas só retornam documentos principais.

Por exemplo, um repositório de dados somente pai pode funcionar bem para audiolivros, em que um painel de recomendações retorna uma seleção de audiolivros individuais. Por outro lado, se você tiver feito upload de episódios de programas de TV como documentos principais para uma armazenagem de dados somente de pais, vários episódios fora de ordem poderão ser recomendados no mesmo painel.

Um repositório de dados de programa de TV pode funcionar com pais e filhos, em que cada documento pai representa um programa de TV com documentos filhos que representam os episódios desse programa. Esse repositório de dados de dois níveis permite que o painel de recomendações mostre uma variedade de programas de TV semelhantes. O usuário final pode clicar em um programa específico para selecionar um episódio para assistir.

Como as hierarquias pai-filho podem ser difíceis de configurar e manter, armazenamentos de dados somente pai são recomendados.

Por exemplo, um repositório de dados de programa de TV pode funcionar bem como um repositório de dados exclusivo para pais, em que cada documento pai representa um programa de TV que pode ser recomendado e os episódios individuais não são incluídos (e, portanto, não são recomendados).

Se você determinar que o repositório de dados precisa ter pais e filhos, ou seja, grupos e itens únicos, mas tiver apenas itens únicos, será necessário criar os pais para os grupos. As informações mínimas que você precisa fornecer para um pai são id, title e categories. Para mais informações, consulte a seção Campos de documento.

Esquema do BigQuery para mídia

Se você planeja importar seus documentos do BigQuery, use o esquema predefinido do BigQuery para criar uma tabela do BigQuery com o formato correto e carregue-a com os dados dos documentos antes de importar os documentos.

[
  {
    "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": []
  }
]