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 as recomendações ou a pesquisa de mídia, revise o requisitos de esquema para seus documentos e repositórios de dados nesta página antes para fazer o upload dos seus dados.

Visão geral

Um documento é qualquer item que você envia para um repositório de dados da 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. Quando ao criar um repositório de dados, você especifica que ele conterá documentos de mídia. Os repositórios de dados para mídia só podem ser anexados a apps de mídia, e 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 precisos e específicos informações que você puder fornecer, maior será a qualidade dos seus resultados.

Os dados enviados ao repositório de dados precisam estar formatados em um formato JSON específico esquema. 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 seu esquema de dados de mídia.

O esquema predefinido pelo 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.

É preciso ter campos em seu esquema que possam ser mapeados para as cinco chaves para mídia:
- title
- uri
- category
- media_available_time
- media_duration Este campo é importante para apps de recomendações de mídia em que o objetivo de negócio é maximizar a taxa de conversão (CVR). a duração da 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 mídias 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 Chaves do Terraform. Os nomes são parecidos, 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 carregados com uma representação de dados JSON ou Struct. Marca verifique se o documento JSON ou Struct 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": "string",
    },
    "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 campos fornecidos ao criar documentos para seu repositório de dados. Os valores devem corresponder aos valores usados no seu banco de dados interno de documentos e deve refletir com precisão o item representado.

Campos do objeto `Document`

Os campos a seguir são de nível superior do 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 métodos `Document`, exceto `create` e `import`. Durante a importação, o nome é gerado automaticamente e não precisa ser fornecida manualmente.
`id`	O ID do documento usado pelo seu banco de dados interno. O campo de ID precisa ser exclusivo em todo o armazenamento 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 de esquema JSON predefinido para mídia.

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

A tabela a seguir define as propriedades das chaves simples.

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. Usar a categoria completa caminho para resultados de maior qualidade. Para representar o caminho completo de uma categoria, use o símbolo `>` para com hierarquias separadas. Se `>` fizer parte do nome da categoria, substitua-o por outro(s) caractere(s). 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ção 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 desempenho reduzido. 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`	String: obrigatório O tempo em que o conteúdo está disponível para os usuários finais. Este campo identifica a atualização 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) A hora em que o conteúdo vai expirar 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 estão 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 por 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 "Í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 da recomendação ao transmitir o valor como parte de `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 recomendação de conteúdo e conteúdo filtrando com base no público-alvo. No máximo, 100 valores são permitidos por documento com limite 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 principais 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, fornecedor, editor, patrocinador, tradutor, música de, 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`.
`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 com 128 caracteres. Precisa corresponder ao padrão: `[a-zA-Z0-9][a-zA-Z0-9_]*`.
`persons.rank`	Int: opcional Usado para a classificação de funções. 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 os objetos `organization` propriedades. 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 A 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, fornecedor, editor, patrocinador, tradutor, música de, canal, função personalizada Se nenhum dos valores compatíveis for aplicado a `role`, defina `role` a `custom-role` e forneça o valor no `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 com 128 caracteres. Precisa corresponder ao padrão: `[a-zA-Z0-9][a-zA-Z0-9_]*`:
`organizations.rank`	String: opcional Usado para a classificação de funções. 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 o `aggregate_rating` propriedades relacionadas.
`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 comprimento 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 do documento

Os níveis de documento determinam a hierarquia no repositório de dados. Normalmente, você devem ter um repositório de dados de nível único ou de dois níveis. Há suporte apenas para duas camadas.

Por exemplo, você pode ter um repositório de dados de nível único em que cada documento é uma para 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 pai 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 filho são versões do documento pai 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". Isso nível de host podem ser difíceis de configurar e manter, e não é recomendado.

Sobre a hierarquia do repositório de dados

Ao planejar a hierarquia do armazenamento de dados, decida se ele vai conter apenas os pais ou os pais e filhos. O ponto principal a ser lembrado é para que as recomendações e pesquisas retornem apenas documentos pai.

Por exemplo, um repositório de dados exclusivo para pais pode funcionar bem para audiolivros, em que uma O painel de recomendações retorna uma seleção de audiolivros individuais. No outro caso tenha enviado episódios de programas de TV como documentos principais a um conjunto de dados loja, vários episódios fora de ordem podem ser recomendados no mesmo painel.

Um repositório de dados de programas de TV pode trabalhar com pais e filhos, em que cada documento pai representa um programa de TV com documentos filhos que representam o episódios desse programa de TV. 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 determinado para selecionar um episódio para assistir.

Como é difícil configurar e manter hierarquias pai-filho, são recomendados repositórios de dados somente para a família.

Por exemplo, um repositório de dados de programa de TV pode funcionar bem como um repositório de dados somente para os pais em que cada documento principal representa um programa de TV que pode ser recomendado. episódios individuais não estã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 a esquema predefinido do BigQuery para criar com o formato correto e carregue-a com os dados dos seus documentos antes de importar seus 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": []
  }
]