Embasamento com o Elasticsearch

Nesta página, explicamos como usar a instância do Elasticsearch para embasar seus dados.

Embasar o Gemini com o Elasticsearch

O embasamento envolve o uso de conjuntos de dados públicos e privados para fornecer contexto e fatos para embasar as respostas do modelo de linguagem grande (LLM) . Ao embasar com o Elasticsearch, você pode aproveitar seus índices do Elasticsearch 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. Isso permite criar aplicativos RAG avançados, como:

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

É possível embasar uma resposta em até 10 fontes de dados ao mesmo tempo. Você pode 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 possíveis ou a informações atualizadas na Internet.

Modelos compatíveis

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

Configurar um modelo de pesquisa no Elasticsearch

Esta seção explica como usar a instância do Elasticsearch para embasar os dados armazenados nela.

Práticas recomendadas

Para as melhores respostas de embasamento, use 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 não ajuda o LLM a responder comandos sobre as propriedades do produto, a menos que o comando peça especificamente um URL. Da mesma forma, evite gerar vetores de incorporação.
O embasamento remove os resultados do Elasticsearch com baixa relevância para seus comandos. Forneça um número maior de resultados do Elasticsearch para capturar todo o contexto relevante.
Os dados de resultados podem estar em um campo ou distribuídos por vários campos.

Modelos de amostra

Você pode usar seus modelos de pesquisa. No entanto, recomendamos usar o modelo de pesquisa kNN genérico com embasamento do Elasticsearch. Para outros modelos de pesquisa, consulte o repositório do GitHub (em inglês).

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

Gerar respostas embasadas com o Elasticsearch

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, conclua as seguintes etapas:

Ativar a API Vertex AI: verifique se a API Vertex AI está ativada para seu Google Cloud projeto.
Instalar e fazer login na Google Cloud CLI: instale e inicialize a ferramenta de linha de comando da CLI gcloud.
Configuração do Elasticsearch: use um cluster e um índice do Elasticsearch que você quer usar para embasamento. Receba as seguintes informações da configuração do Elasticsearch:
- Endpoint: o URL do 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.
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.

Gerar respostas embasadas

Console

Para embasar com o Elasticsearch no Google Cloud console, faça o seguinte:

Acesse o Vertex AI Studio na página Criar comando.

Acessar "Criar comando"
No painel Configurações, para embasar seus dados, clique na opção Embasamento: seus dados.
No painel Personalizar embasamento, selecione Elasticsearch.
Insira o endpoint no campo Endpoint do Elasticsearch.
Insira ApiKey YOUR_API_KEY no campo Chave de API do Elasticsearch.
Insira o índice no campo Índice do Elasticsearch.
Insira o modelo de pesquisa no campo Modelo de pesquisa do Elasticsearch.
Ajuste o número de resultados deslizando o controle deslizante Número de resultados.
Clique em Salvar.
Insira seu comando.
Clique em Enviar.

Entender a resposta

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

Python

Instalar

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 da IA generativa com a 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 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:

PROMPT: 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 embasamento.
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.

Método HTTP e URL:

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

Solicitar corpo JSON:

  {
    "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 chats com vários turnos, consulte o Guia para iniciantes da IA generativa.

Enviar a solicitação da API

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

LOCATION: a região para processar a solicitação. Para usar o endpoint global, exclua o local do nome do endpoint e configure o local do recurso como global.
PROJECT_ID: seu Google Cloud ID do projeto. Para mais informações sobre IDs de projetos, consulte Criar e gerenciar 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"

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 de ambas as APIs inclui o texto gerado pelo LLM, que é chamado de candidato. Se o comando do modelo embasar corretamente a 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 origem ou informações incompletas na resposta do modelo.

A seguir, apresentamos uma análise 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 índice do Elasticsearch que oferecem suporte à resposta.
- Suportes de embasamento: informações sobre uma reivindicação específica na resposta que pode ser usada para mostrar citações:
- Segmento: a parte da resposta do modelo que é comprovada por um bloco de embasamento.
- Índice de blocos de embasamento: o índice dos blocos de embasamento na lista de blocos de embasamento que corresponde a essa reivindicação.
- Pontuações de confiança: um número de 0 a 1 que indica o quão embasada a reivindicação está no conjunto de blocos de embasamento fornecido. Não disponível para o Gemini 2.5 Pro e o Gemini 2.5 Flash e versões mais recentes.

A seguir

Para saber como enviar solicitações de comando de chat, consulte Chat com vários turnos.
Para saber mais sobre as práticas recomendadas de IA responsável e os filtros de segurança da Vertex AI, consulte Práticas recomendadas de segurança.

Embasamento com o Elasticsearch Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Embasar o Gemini com o Elasticsearch

Modelos compatíveis

Configurar um modelo de pesquisa no Elasticsearch

Práticas recomendadas

Modelos de amostra

Gerar respostas embasadas com o Elasticsearch

Pré-requisitos

Gerar respostas embasadas

Console

Entender a resposta

Python

Instalar

REST

Enviar a solicitação da API

Entender a resposta

A seguir

Embasamento com o Elasticsearch