Usar incorporações personalizadas

Se você já criou os embeddings de vetor personalizados para seus dados, é possível fazer upload deles na Pesquisa de agentes e usá-los ao fazer consultas com a Pesquisa de agentes.

Esse recurso está disponível para repositórios de dados com dados estruturados personalizados ou dados não estruturados com metadados. Esse recurso não está disponível para pesquisas de mídia e saúde.

Por padrão, a Pesquisa de agentes gera embeddings de vetor automaticamente, sem necessidade de configuração. Se você não sabe como criar os embeddings, o Google recomenda que a Pesquisa de agentes faça a criação. No entanto, se você criou os próprios embeddings para os dados, talvez prefira usar esses embeddings em vez dos gerados pela Pesquisa de agentes, principalmente se os embeddings personalizados tiverem o contexto adicional para enriquecer a recuperação e o classificação da pesquisa. Exemplo:

  • Seus embeddings foram treinados em palavras personalizadas, como termos internos cuja similaridade semântica não seria capturada pelo treinamento em dados públicos. Por exemplo, termos específicos da organização que aparecem apenas em documentos particulares.
  • Você criou embeddings para perfis de usuários e quer usá-los para criar uma classificação de documentos personalizada e semanticamente relevante. É possível usar esses embeddings para receber uma classificação personalizada, que pode aumentar os embeddings de documentos do Google, resultando em uma classificação mais relevante.

Para usar seus próprios embeddings:

  1. Antes de começar: verifique se os embeddings atendem a todos os requisitos
  2. Ingerir dados com embeddings: ingira os documentos com os respectivos embeddings.
  3. Atualize seu esquema: atualize o esquema com os campos de propriedades de chave e as especificações de dimensão.
  4. Especifique o embedding: especifique o embedding globalmente ou por solicitação de pesquisa.

Antes de começar

Antes de começar, verifique se os embeddings atendem aos seguintes requisitos:

  • Os embeddings são compatíveis com dados estruturados e não estruturados com metadados.
  • Os embeddings precisam ser fornecidos como matrizes unidimensionais.
  • A dimensionalidade do embedding precisa ser igual ou estar entre 1 e 768.
  • Os embeddings são compatíveis com texto e imagens. Vídeos não são compatíveis.
  • É possível marcar até dois campos como propriedades de chave de embedding. Você pode usar dois campos para casos como testes A/B para seus embeddings.

  • Após definidas, não é possível remover as designações de propriedades de chave do campo do embedding.

Ingerir dados com embeddings

É possível ingerir os embeddings de um documento em um ou dois campos incluídos como parte dos dados ou metadados desse documento durante a ingestão.

Para ingerir dados com embeddings:

  1. Prepare os dados para ingestão, dependendo do tipo de dados:

    • Dados estruturados: ao preparar os dados, inclua os embeddings de cada documento como matrizes unidimensionais em um ou dois campos do documento. É possível fornecer até dois embeddings (por exemplo, se você estiver fazendo um teste A/B entre eles). Cada embedding precisa ser fornecido no próprio campo do documento, por exemplo: "example_embedding_vector": [0.1, 0.2, 0.3 ...]

      Siga as orientações para preparar dados estruturados na documentação Preparar dados para ingestão.

    • Dados não estruturados com metadados: ao preparar seus dados, inclua o embedding de cada documento como uma matriz unidimensional em um campo nos metadados do documento. É possível fornecer até dois embeddings (por exemplo, ao fazer testes A/B entre eles). Cada embedding precisa ser fornecido no próprio campo nos metadados do documento, por exemplo: "example_embedding_vector": [0.1, 0.2, 0.3 ...]

      Siga as orientações para preparar dados não estruturados com metadados para o método de ingestão (Cloud Storage ou BigQuery) na documentação Preparar dados para ingestão.

  2. Siga as instruções para o tipo de dados em Criar um repositório de dados de pesquisa para ingerir os documentos com embeddings.

Em seguida, atualize seu esquema para usar os campos de embedding corretos.

Atualizar seu esquema

Atualize o esquema com os mapeamentos e dimensões de propriedades de chave para os campos de embeddings usando o console do Google Cloud ou a API.

Console

Para atualizar seu esquema usando o Google Cloud console, siga estas etapas:

  1. No Google Cloud console, acesse a página Aplicativos de IA.

    Aplicativos de IA

  2. No menu de navegação, selecione Repositório de dados.

  3. Na coluna Nome, clique no repositório de dados com o esquema que você quer atualizar.

  4. Clique na guia Esquema para conferir o esquema dos seus dados.

  5. Clique no botão Editar.

  6. Encontre o campo de embedding no esquema e, na coluna Propriedades de chave, selecione embedding_vector como a propriedade desse campo.

    Se houver um segundo campo de embedding, repita essa etapa.

  7. Na coluna Dimensão, insira o número de dimensões desse campo de embedding.

    Se houver um segundo campo de embedding, repita essa etapa.

  8. Clique em Salvar para aplicar as mudanças de esquema.

    Depois de atualizá-lo, a reindexação pode levar até 24 horas, dependendo do tamanho do seu repositório de dados.

REST

Para atualizar seu esquema usando a API, siga estas etapas:

  1. Seguindo as instruções REST em Atualizar um esquema, especifique o mapeamento da propriedade da chave e o número de dimensões para cada campo de embedding:

    • "keyPropertyMapping": "embedding_vector"
    • "dimension": NUMBER_OF_DIMENSIONS

    Por exemplo, confira um esquema JSON formatado com 768 dimensões para o campo example_embedding_vector:

      {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "example_embedding_vector": {
        "type": "array",
        "keyPropertyMapping": 'embedding_vector',
        "dimension": 768,
        "items": {
          "type": "number"
        }
      }
    }
  }

    Em uma solicitação de atualização do esquema, esse JSON formatado seria incluído como uma string JSON:

      "jsonSchema": "{\"$schema\":\"https://json-schema.org/draft/2020-12/schema\",\"type\":\"object\",\"properties\":{\"example_embedding_vector\":{\"type\":\"array\",\"keyPropertyMapping\":\"embedding_vector\",\"dimension\":768,\"items\":{\"type\":\"number\"}}}}"

    Depois de atualizá-lo, a reindexação pode levar até 24 horas, dependendo do tamanho do seu repositório de dados.

Em seguida, especifique o embedding.

Especificar o embedding

Depois que a indexação da atualização do esquema for concluída, você poderá enviar solicitações de pesquisa que incluam uma especificação de embedding.

Há duas maneiras de especificar um embedding:

Especificar um embedding globalmente

É possível especificar o mesmo embedding em todas as solicitações de pesquisa usando o consoleGoogle Cloud ou a API.

Console

Para fornecer a mesma especificação de embedding a todas as solicitações de pesquisa, atualize as configurações de veiculação com uma especificação de embedding.

  1. No Google Cloud console, acesse a página Aplicativos de IA.

    Aplicativos de IA

  2. Clique em Visualizar no repositório de dados com o esquema que você quer atualizar.

  3. Acesse a página Configurações e clique na guia Controle.

  4. Em Caminho do campo de embedding, insira o nome do campo que você mapeou para a propriedade de chave do embedding.

  5. Em Expressão de classificação, insira uma ou mais funções para controlar a classificação dos resultados. As variáveis são ponderadas de acordo com a expressão inserida. A expressão de classificação é uma única função ou várias funções unidas por + no formato function, { " + ", function }.

    As funções compatíveis são estas:

    • DOUBLE * relevance_score
    • DOUBLE * dotProduct(EMBEDDING_FIELD_PATH)

    As seguintes variáveis são aceitas:

    • relevance_score: uma variável predefinida fornecida pela Pesquisa de agentes para medir a relevância de um documento. A pontuação varia de 0 a 1,0, incluindo os limites.
    • dotProduct(): uma função predefinida fornecida pela Pesquisa de agentes. Você precisa fornecer o mesmo nome de campo para essa função que fez para embeddingVector.fieldPath.

    Exemplo:

    • 0.3 * relevance_score
    • 0.5 * relevance_score + 0.3 * dotProduct(example_embedding_field)

REST

Para fornecer a mesma especificação de embedding a todas as solicitações de pesquisa, atualize servingConfig com embeddingConfig.

  1. Corrija a entidade servingConfig com os campos que você quer atualizar. Especifique os campos que você está atualizando com updateMask.

    No exemplo a seguir, embeddingConfig usa embeddings no campo example_embedding_field e atribui um peso de 0,5 a relevance_score.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{
      "name": "projects/PROJECT_ID/locations/LOCATION/collections/default_collection/dataStores/DATA_STORE_ID/servingConfigs/default_search",
      "embeddingConfig": {
        "fieldPath": "example_embedding_field"
      },
      "ranking_expression": "0.5 * relevance_score"
    }' \
'https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/dataStores/DATA_STORE_ID/servingConfigs/default_search?updateMask=embeddingConfig,rankingExpression'
    • fieldPath: o nome do campo que você mapeou para a propriedade de chave do embedding.
    • ranking_expression: controla a classificação dos resultados. As variáveis são ponderadas de acordo com a expressão inserida. A expressão de classificação é uma única função ou várias funções unidas por + no formato function, { " + ", function }.

    As funções compatíveis são estas:

    • DOUBLE * relevance_score
    • DOUBLE * dotProduct(EMBEDDING_FIELD_PATH)

    As seguintes variáveis são aceitas:

    • relevance_score: uma variável predefinida fornecida pela Pesquisa de agentes.
    • dotProduct(): uma função predefinida fornecida pela Pesquisa de agentes. O produto escalar é normalizado. Você precisa fornecer o mesmo nome de campo para essa função que fez para embeddingVector.fieldPath.

    Exemplo:

    • 0.3 * relevance_score
    • 0.5 * relevance_score + 0.3 * dotProduct(example_embedding_field)

  2. Ao enviar solicitações de pesquisa, servingConfig.embeddingConfig é incluído automaticamente.

    Se você enviar uma solicitação de pesquisa que inclua explicitamente um embeddingSpec diferente, ele vai substituir servingConfig.embeddingConfig. Consulte as instruções Por solicitação para saber como fornecer especificações de embedding para solicitações de pesquisa únicas.

Especificar um embedding por solicitação de pesquisa

É possível fornecer uma especificação de embedding para uma única solicitação de pesquisa usando a API. Uma especificação de embedding por solicitação substitui qualquer especificação global.

  1. Envie uma solicitação de pesquisa que inclua embeddingSpec.

    O exemplo a seguir de embeddingSpec usa embeddings no campo example_embedding_field, especifica "Consulta de exemplo" como o vetor de entrada, e atribui um peso de 0,5 a relevance_score e 0,3 a example_embedding_field ao calcular a classificação.

      "embeddingSpec": {
    "embeddingVectors": [{
      "fieldPath": "example_embedding_field",
      "vector": [
        0.96241474,
        -0.45999944,
        0.108588696
      ]
    }]
  },
  "ranking_expression": "0.5 * relevance_score + 0.3 * dotProduct(example_embedding_field)"
    • fieldPath: o nome do campo que você mapeou para a propriedade de chave do embedding.
    • vector: o vetor de entrada fornecido como uma matriz.

    • ranking_expression: controla a classificação dos resultados. As variáveis são ponderadas de acordo com a expressão inserida. A expressão de classificação é uma única função ou várias funções que são unidas por + no formato function, { " + ", function }.

      As funções compatíveis são estas:

      • DOUBLE * relevance_score
      • DOUBLE * dotProduct(EMBEDDING_FIELD_PATH)

      As seguintes variáveis são aceitas:

      • relevance_score: uma variável predefinida fornecida pela Pesquisa de agentes para medir a relevância de um documento. A pontuação varia de 0 a 1,0, incluindo os limites.
      • dotProduct(): uma função predefinida fornecida pela Pesquisa de agentes. Você precisa fornecer o mesmo nome de campo para essa função que fez para embeddingVector.fieldPath.

      Exemplo:

      • 0.3 * relevance_score
      • 0.5 * relevance_score + 0.3 * dotProduct(example_embedding_field)

  2. Receba os resultados na resposta da pesquisa. Cada resultado da pesquisa inclui a pontuação de relevância e os valores do produto escalar. Exemplo:

    "modelScores": {
  "dotProduct(example_embedding_field)": [0.02150772698223591],
  "relevance_score": [ 0.8828125 ]
}
    • dotProduct(): o produto escalar calculado para o documento de resultado da pesquisa.
    • relevance_score: a pontuação de relevância calculada para o documento de resultado da pesquisa.

A seguir