Fundamentação com o Elasticsearch

Esta página explica como pode usar a sua instância do Elasticsearch para fundamentar os resultados com base nos seus dados.

Fundamentar o Gemini com o Elasticsearch

A fundamentação envolve a utilização de conjuntos de dados públicos e privados para fornecer contexto e factos para fundamentar as respostas do modelo de linguagem (conteúdo extenso) (MDL/CE). Ao fundamentar com o Elasticsearch, pode tirar partido dos seus índices do Elasticsearch existentes para ajudar a melhorar a qualidade e a fiabilidade do resultado do Gemini, reduzindo as alucinações e ajudando a garantir que as respostas são relevantes para os seus dados. Isto permite-lhe criar aplicações RAG poderosas, como:

  • Resumos da pesquisa generativa
  • Chatbots de perguntas e respostas com dados empresariais
  • Agentes baseados nos seus dados

Pode fundamentar uma resposta em até 10 origens de dados em simultâneo. Pode combinar a fundamentação com o Elasticsearch com a fundamentação com a Pesquisa Google para associar o modelo a conhecimentos mundiais, uma vasta gama possível de tópicos ou informações atualizadas na Internet.

Modelos suportados

Os seguintes modelos suportam o fundamento com o Elasticsearch apenas com entrada de texto:

Configure um modelo de pesquisa no Elasticsearch

Esta secção explica como pode usar a sua instância do Elasticsearch para basear-se nos dados armazenados na instância.

Práticas recomendadas

Para as melhores respostas de fundamentação, use estes princípios ao criar um modelo de pesquisa:

  • Inclua apenas dados relevantes e úteis. Por exemplo, num catálogo de produtos, especificar um URL de imagem pode não ajudar o GML a responder a comandos sobre propriedades do produto, a menos que o comando peça especificamente um URL. Da mesma forma, evite gerar vetores de incorporação.

  • A fundamentação remove os resultados do Elasticsearch com baixa relevância para os seus comandos. Deve fornecer um número mais elevado de resultados do Elasticsearch para captar todo o contexto relevante.

  • Os dados de resultados podem estar num campo ou distribuídos por vários campos.

Modelos de exemplo

Pode usar os seus modelos de pesquisa. No entanto, recomendamos que use o modelo de pesquisa kNN genérico com base no Elasticsearch. Para ver modelos de pesquisa adicionais, consulte o repositório do GitHub.

Esta pesquisa semântica com a Vertex AI é uma pesquisa kNN genérica.

    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
              }
              ]
        }
      }
    }

Gere respostas fundamentadas com o Elasticsearch

Esta secção explica como usar a API Vertex AI para fundamentar as respostas do seu MDG.

Pré-requisitos

Antes de poder fundamentar as respostas do MDG com o Elasticsearch, tem de concluir o seguinte:

  1. Ative a API Vertex AI: certifique-se de que a API Vertex AI está ativada para o seu Google Cloud projeto.

  2. Instale e inicie sessão na CLI do Google Cloud: instale e inicialize a ferramenta de linhas de comando da CLI gcloud.

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

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

  4. Crie um modelo de pesquisa do Elasticsearch: use uma origem de dados do Elasticsearch que use um modelo de referência que devolva dados de resultados para fundamentação.

Gere respostas fundamentadas

Consola

Para fundamentar com o Elasticsearch na Google Cloud consola, faça o seguinte:

  1. Aceda ao Vertex AI Studio e à página Criar comando.

    Aceder a Criar comando

  2. No painel Definições, para fundamentar os seus dados, clique no botão Fundamentação: os seus dados.

  3. No painel Personalizar base, selecione Elasticsearch.

  4. Introduza o ponto final no campo Ponto final do Elasticsearch.

  5. Introduza ApiKey YOUR_API_KEY no campo Chave da API Elasticsearch.

  6. Introduza o índice no campo Índice do Elasticsearch.

  7. Introduza o modelo de pesquisa no campo Modelo de pesquisa do Elasticsearch.

  8. Ajuste o número de resultados deslizando o controlo de deslize Número de resultados.

  9. Clique em Guardar.

  10. Introduza o comando.

  11. Clique em Enviar.

Compreenda a sua resposta

Se o comando do modelo for fundamentado com êxito em repositórios de dados do Elasticsearch através do Vertex AI Studio ou da API, as respostas do modelo incluem metadados com citações e conteúdo de origem. Se ocorrer uma baixa relevância da origem ou informações incompletas na resposta do modelo, os metadados podem não ser fornecidos e a resposta ao comando não é fundamentada.

Python

Instalação

pip install --upgrade google-genai

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA gen com o Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True
 

from google import genai
from google.genai.types import (
    GenerateContentConfig,
    Elasticsearch,
    Retrieval,
    Tool,
    HttpOptions,
)

client = genai.Client(http_options=HttpOptions(api_version="v1"))

# Replace with your Elasticsearch details
ELASTIC_SEARCH_ENDPOINT = "YOUR_ELASTICSEARCH_ENDPOINT"
ELASTIC_SEARCH_API_KEY = "YOUR_ELASTICSEARCH_API_KEY"
INDEX_NAME = "YOUR_INDEX_NAME"
SEARCH_TEMPLATE_NAME = "YOUR_SEARCH_TEMPLATE_NAME"
NUM_HITS = 5

tool = Tool(
    retrieval=Retrieval(
        external_api=Elasticsearch(
            api_spec="ELASTIC_SEARCH",
            endpoint=ELASTIC_SEARCH_ENDPOINT,
            api_auth={
                "apiKeyConfig": {
                    "apiKeyString": f"ApiKey {ELASTIC_SEARCH_API_KEY}"
                }
            },
            elastic_search_params={
                "index": INDEX_NAME,
                "searchTemplate": SEARCH_TEMPLATE_NAME,
                "numHits": NUM_HITS,
            },
        )
    )
)

response = client.models.generate_content(
    model="gemini-2.5-flash",  # Or another supported model
    contents="What are the main features of product X?", # Your query
    config=GenerateContentConfig(
        tools=[tool],
    ),
)

print(response.text)

REST

Para enviar um comando de texto e fundamentá-lo com o Elasticsearch, envie um pedido POST para a API Vertex AI. No mínimo, tem de fornecer o corpo do pedido. Certifique-se de que faz as seguintes substituições:

  • PROMPT: o comando de texto a fundamentar.
  • ELASTIC_SEARCH_ENDPOINT: O caminho absoluto do ponto final para o recurso do Elasticsearch a usar.
  • ELASTIC_SEARCH_API_KEY: a chave da API para o ponto final de dados do Elasticsearch.
  • INDEX_NAME: o nome do índice do Elasticsearch usado para a fundamentação.
  • SEARCH_TEMPLATE_NAME: O modelo de pesquisa do Elasticsearch usado para fundamentação.

  • NUM_HITS: o número de resultados devolvidos da origem de dados do Elasticsearch e usados para fundamentação.

    Método HTTP e URL:

    POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent

    Corpo JSON do pedido:

      {
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "PROMPT"
          }
        ]
      }
    ],
    "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 com várias interações, consulte o guia para principiantes da IA generativa.

Envie o pedido de API

Pode guardar o corpo do pedido num ficheiro com o nome request.json. Em seguida, execute o pedido da API POST e faça as seguintes substituições:

  • LOCATION: a região para processar o pedido. Para usar o ponto final global, exclua a localização do nome do ponto final e configure a localização do recurso para global.
  • PROJECT_ID: o ID do seu projeto Google Cloud . Para mais informações sobre IDs de projetos, consulte o artigo Criar e gerir projetos.
  • MODEL_ID: o ID do modelo multimodal.
  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"

Deve receber uma resposta JSON semelhante à seguinte:

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

Compreenda a sua resposta

A resposta de ambas as APIs inclui o texto gerado pelo MDI/CE, que se denomina candidato. Se o comando do modelo for fundamentado com êxito na sua origem de dados do Elasticsearch, as respostas incluem metadados de fundamentação, que identificam as partes da resposta que foram derivadas dos seus dados do Elasticsearch. No entanto, existem vários motivos pelos quais estes metadados podem não ser fornecidos e a resposta ao comando não é fundamentada. Estes motivos incluem baixa relevância da fonte ou informações incompletas na resposta do modelo.

Segue-se uma análise detalhada dos dados de saída:

  • Função: indica o remetente da resposta fundamentada. Uma vez que a resposta contém sempre texto fundamentado, a função é sempre model.
  • Texto: a resposta fundamentada gerada pelo MDI/CE.
  • Metadados de fundamentação: informações sobre a origem da fundamentação, que contém os seguintes elementos:
    • Fragmentos de base: uma lista de resultados do seu índice do Elasticsearch que suportam a resposta.
    • Fundamentação suportada: informações sobre uma reivindicação específica na resposta que podem ser usadas para mostrar citações:
    • Segmento: a parte da resposta do modelo que é fundamentada por um bloco de base.
    • Índice do fragmento de fundamentação: o índice dos fragmentos de fundamentação na lista de fragmentos de fundamentação que corresponde a esta reivindicação.
    • Níveis de confiança: um número de 0 a 1 que indica o quão fundamentada está a reivindicação no conjunto de fragmentos de fundamentação fornecido. Não disponível para o Gemini 2.5 Pro, o Gemini 2.5 Flash e versões posteriores.

O que se segue?