Embasamento com o Elasticsearch

Neste guia, mostramos como embasar modelos do Gemini nos seus dados no Elasticsearch. Neste guia, abordamos os seguintes tópicos:

O diagrama a seguir resume o fluxo de trabalho geral:

Visão geral do embasamento com o Elasticsearch

O fundamentação usa conjuntos de dados públicos e particulares para fornecer contexto e fatos às respostas do modelo de linguagem grande (LLM). Ao criar embasamento com o Elasticsearch, você pode usar seus índices atuais para melhorar a qualidade e a confiabilidade da saída do Gemini, reduzir alucinações e garantir que as respostas sejam relevantes para seus dados.

Com esse recurso, você pode criar aplicativos RAG avançados, como:

  • Resumos de pesquisa generativos
  • Chatbots de perguntas e respostas com dados corporativos
  • Agentes baseados nos seus dados

É possível embasar uma resposta em até 10 fontes de dados por vez. É possível combinar o embasamento com o Elasticsearch e o embasamento com a Pesquisa Google para conectar o modelo ao conhecimento mundial, a uma ampla variedade de tópicos ou a informações atualizadas na Internet.

Modelos compatíveis

Os seguintes modelos são compatíveis com o embasamento com o Elasticsearch usando apenas entrada de texto:

Configurar um modelo de pesquisa no Elasticsearch

Práticas recomendadas

Para receber as melhores respostas de embasamento, siga estes princípios ao criar um modelo de pesquisa:

  • Inclua apenas dados relevantes e úteis. Por exemplo, em um catálogo de produtos, especificar um URL de imagem pode não ajudar o LLM a responder comandos sobre propriedades do produto, a menos que o comando peça especificamente um URL. Da mesma forma, evite gerar vetores de embedding.
  • Forneça um número maior de resultados. O embasamento remove resultados do Elasticsearch com baixa relevância para seus comandos. Para capturar todo o contexto relevante, forneça um número maior de resultados do Elasticsearch.
  • Estruture seus dados de maneira eficaz. Os dados de resultados podem estar em um campo ou distribuídos em vários.

Modelos de amostra

Você pode usar seus próprios modelos de pesquisa. O modelo de pesquisa kNN genérico a seguir é recomendado para embasamento do Elasticsearch. Para outros modelos de pesquisa, consulte o repositório do GitHub.

O exemplo a seguir mostra um modelo genérico de pesquisa kNN para pesquisa semântica com a Vertex AI.

    PUT _scripts/google-template-knn-multioutput
    {
      "script": {
        "lang": "mustache",
        "source": {
          "_source": {
            "excludes": [ "title_embedding", "description_embedding", "images"]
          },
            "size": "num_hits",
              "knn" : [
              {
                "field": "description_embedding",
                "k": 5,
                "num_candidates": 10,
                "query_vector_builder": {
                  "text_embedding": {
                    "model_id": "googlevertexai_embeddings_004",
                    "model_text": "query"
                  }
                },
                "boost": 0.4
              },
              {
                "field": "title_embedding",
                "k": 5,
                "num_candidates": 10,
                "query_vector_builder": {
                  "text_embedding": {
                    "model_id": "googlevertexai_embeddings_004",
                    "model_text": "query"
                }
              },
              "boost": 0.6
              }
              ]
        }
      }
    }

Gerar respostas embasadas com o Elasticsearch

É possível gerar respostas fundamentadas usando o console do Google Cloud para testes rápidos ou a API REST para integração aos seus aplicativos.

Método Descrição Caso de uso
Console doGoogle Cloud Uma interface gráfica do usuário no console do Google Cloud para criar e testar comandos de forma interativa. Ideal para experimentos rápidos, prototipagem e usuários que preferem uma interface visual sem escrever código.
API REST Uma interface programática para integrar recursos de embasamento diretamente aos seus aplicativos. Ideal para automatizar fluxos de trabalho, criar aplicativos de produção e integrar com sistemas atuais.

Console

Para fazer o embasamento com o Elasticsearch no console do Google Cloud , siga estas etapas:

  1. Acesse a página Criar comando no Vertex AI Studio.

    Acessar "Criar comando"

  2. No painel Configurações, para embasar seus dados, clique na chave Fundamentação: seus dados.

  3. No painel Personalizar embasamento, selecione Elasticsearch.

  4. No campo Endpoint do Elasticsearch, insira o endpoint.

  5. No campo Chave de API do Elasticsearch, insira a chave de API.

  6. No campo Índice do Elasticsearch, insira o índice.

  7. No campo Modelo de pesquisa do Elasticsearch, insira o modelo de pesquisa.

  8. Para ajustar o número de hits, use o controle deslizante Número de hits.

  9. Clique em Salvar.

  10. Insira seu comando.

  11. Clique em Enviar.

Entender a resposta

Se o comando do modelo embasar corretamente com os repositórios de dados do Elasticsearch usando o Vertex AI Studio ou a API, as respostas do modelo incluirão metadados com citações e conteúdo de origem. Se houver baixa relevância de fonte ou informações incompletas na resposta do modelo, os metadados não serão fornecidos, e a resposta do comando não será embasada.

REST

Esta seção explica como usar a API Vertex AI para embasar as respostas do LLM.

Pré-requisitos

Antes de embasar as respostas do LLM com o Elasticsearch, faça o seguinte:

  1. Ative a API Vertex AI: verifique se a API Vertex AI está ativada no seu projeto Google Cloud .

  2. Instale e faça login na CLI do Google Cloud: instale e inicialize a ferramenta de linha de comando da CLI gcloud.

  3. Configuração do Elasticsearch: use um cluster e um índice do Elasticsearch que você quer usar para embasamento. Obtenha as seguintes informações da sua configuração do Elasticsearch:

    • Endpoint: o URL do seu cluster do Elasticsearch.
    • Nome do índice: o nome do índice que você quer pesquisar, como my-data-index.
    • Chave de API: uma chave de API que permite o acesso ao cluster do Elasticsearch. A chave de API precisa começar com o prefixo ApiKey.

  4. Criar um modelo de pesquisa do Elasticsearch: use uma fonte de dados do Elasticsearch que usa um modelo de referência que retorna dados de resultado para embasamento.

Acesso à API

Use as instruções a seguir para basear o Gemini na sua fonte de dados do Elasticsearch usando a API Vertex AI.

Preparar uma solicitação de geração embasada

Para enviar um comando de texto e embasá-lo com o Elasticsearch, envie uma solicitação POST para a API Vertex AI. No mínimo, você precisa fornecer o corpo da solicitação. Faça as seguintes substituições:

  • QUERY: o comando de texto a ser embasado.
  • ELASTIC_SEARCH_ENDPOINT: o caminho absoluto do endpoint para o recurso do Elasticsearch a ser usado.
  • ELASTIC_SEARCH_API_KEY: a chave de API do endpoint de dados do Elasticsearch.
  • INDEX_NAME: o nome do índice do Elasticsearch usado para fundamentação.
  • SEARCH_TEMPLATE_NAME: o modelo de pesquisa do Elasticsearch usado para embasamento.
  • NUM_HITS: o número de resultados retornados da fonte de dados do Elasticsearch e usados para embasamento.

Solicitar corpo JSON:

    {
      "contents": [
        {
          "role": "user",
          "parts": [
            {
              "text": "QUERY"
            }
          ]
        }
      ],
      "tools": [{
        "retrieval": {
          "externalApi": {
            "api_spec": "ELASTIC_SEARCH",
            "endpoint": "ELASTIC_SEARCH_ENDPOINT",
            "apiAuth": {
              "apiKeyConfig": {
                "apiKeyString": "ApiKey ELASTIC_SEARCH_API_KEY"
              }
            },
            "elasticSearchParams": {
              "index": "INDEX_NAME",
              "searchTemplate": "SEARCH_TEMPLATE_NAME",
              "numHits": "NUM_HITS",
            }
          }
        }
      }]
    }

Para mais informações sobre outros campos da API, como instruções do sistema e conversas em várias etapas, consulte o Guia para iniciantes da IA generativa.

Enviar a solicitação de API

Salve o corpo da solicitação em um arquivo chamado request.json. Em seguida, execute a solicitação POST da API e faça as seguintes substituições:

  curl -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json; charset=utf-8" \
      -d @request.json \
  "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent"

Você receberá uma resposta JSON semelhante a esta:

  {
    "candidates": [
      {
        "content": {
          "role": "model",
          "parts": [
            {
              "text": "Based on the information ..."
            }
          ]
        },
        "finishReason": "STOP",
        "safetyRatings": [ "..." ],
        "groundingMetadata": {
          "groundingChunks": [
            {
              "retrievedContext": {
                "text": "ipsum lorem ..."
              }
            },
            {...},
            {...},
          ],
          "groundingSupports": [
            {
              "segment": {
                "startIndex": 25,
                "endIndex": 147,
                "text": "ipsum lorem ..."
              },
              "groundingChunkIndices": [1,2],
              "confidenceScores": [0.6626542, 0.82018316],
            },
          ],
        },
      }
    ],
  }

Entender a resposta

A resposta das duas APIs inclui o texto gerado pelo LLM, que é chamado de candidato. Se o comando do modelo embasar corretamente com sua fonte de dados do Elasticsearch, as respostas vão incluir metadados de embasamento, que identificam as partes da resposta derivadas dos dados do Elasticsearch. No entanto, há vários motivos para esses metadados não serem fornecidos e a resposta ao comando não ser embasada. Esses motivos incluem baixa relevância de fonte ou informações incompletas na resposta do modelo.

Confira a seguir um detalhamento dos dados de saída:

  • Função: indica o remetente da resposta embasada. Como a resposta sempre contém texto embasado, a função é sempre model.
  • Texto: a resposta embasada gerada pelo LLM.
  • Metadados de embasamento: informações sobre a fonte de embasamento, que contém os seguintes elementos:
    • Blocos de embasamento: uma lista de resultados do seu índice do Elasticsearch que embasam a resposta.
    • O embasamento oferece suporte a: informações sobre uma declaração específica na resposta que podem ser usadas para mostrar citações:
    • Segmento: a parte da resposta do modelo que é fundamentada por um trecho de embasamento.
    • Índice do trecho de embasamento: o índice dos trechos de embasamento na lista de trechos de embasamento que corresponde a esta declaração.
    • Níveis de confiança: um número de 0 a 1 que indica o nível de embasamento da declaração no conjunto de partes de embasamento fornecido. Não disponível para Gemini 2.5 Pro e Gemini 2.5 Flash e versões mais recentes.

Entender a resposta

A resposta do Vertex AI Studio ou da API inclui o texto gerado pelo LLM, que é chamado de candidato. Se o comando do modelo embasar corretamente com sua fonte de dados do Elasticsearch, a resposta vai incluir metadados de embasamento que identificam as partes da resposta derivadas dos seus dados.

No entanto, se houver baixa relevância de fonte ou informações incompletas, os metadados não serão fornecidos, e a resposta não será embasada.

A resposta da API contém os seguintes detalhes:

  • Função: indica o remetente da resposta. Para uma resposta gerada pelo modelo, a função é model.
  • Texto: a resposta gerada pelo LLM.
  • Metadados de embasamento: informações sobre a fonte de embasamento, que contém os seguintes elementos:
    • Blocos de embasamento: uma lista de resultados do seu índice do Elasticsearch que embasam a resposta.
    • Fundamentação: informações sobre uma declaração específica na resposta que podem ser usadas para mostrar citações:
      • Segmento: a parte da resposta do modelo que é fundamentada por um trecho de embasamento.
      • Índice do trecho de embasamento: o índice dos trechos de embasamento na lista de trechos de embasamento que corresponde a esta declaração.
      • Níveis de confiança: um número de 0 a 1 que indica o nível de embasamento da declaração no conjunto de partes de embasamento fornecido. Não disponível para Gemini 2.5 Pro e Gemini 2.5 Flash e versões mais recentes.

A seguir