Nesta página, explicamos como usar sua instância do Elasticsearch para embasar respostas nos seus dados.
Embasamento do Gemini com o Elasticsearch
O embasamento envolve o uso de conjuntos de dados públicos e privados para fornecer contexto e fatos que embasam as respostas do modelo de linguagem grande (LLM). Ao usar o Elasticsearch como embasamento, você pode aproveitar os índices do Elasticsearch para melhorar a qualidade e a confiabilidade da saída do Gemini, reduzindo alucinações e ajudando a 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 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 com 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 seguintes modelos dão suporte ao embasamento com o Elasticsearch apenas com entrada de texto:
Clique para abrir os modelos compatíveis
- Gemini Robotics ER 2
- Gemini Nano Banana 2.1
- Gemini 4 Neon
- Gemini 4 Hydrogen
- Gemini 4 Carbon para segurança cibernética
- Gemini 4 Carbon
- Gemini 4 Argon Cyber Permissive
- Gemini 4 Argon
- Gemini 3.8 Live
- Gemini 3.8 Flash Cyber
- Gemini 3.8 Flash
- Gemini 3.7 Flash
- Gemini 3.6 Flash
- Gemini 3.5 Flash-Lite
- Gemini 3.5 Flash
- Gemini 3.1 Pro
- Gemini 3.1 Flash-Lite
- Gemini 3.1 Flash Image
- Gemini 3 Pro Image
- Gemini 3 Flash
- Gemini 2.5 Pro
- Gemini 2.5 Flash-Lite
- Gemini 2.5 Flash com áudio nativo da API Gemini Live
- Gemini 2.5 Flash
Configurar um modelo de pesquisa no Elasticsearch
Nesta seção, explicamos como usar a instância do Elasticsearch para fundamentar os dados armazenados no repositório de dados.
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 pode não ajudar o LLM a responder a comandos sobre propriedades de produtos, a menos que o comando peça especificamente um URL. Da mesma forma, evite gerar vetores de embedding.
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 em vários campos.
Modelos de amostra
Você pode usar seus modelos de pesquisa. No entanto, recomendamos que você use o modelo de pesquisa kNN genérico com o embasamento do Elasticsearch. Para mais modelos de pesquisa, consulte o repositório do GitHub.
Essa pesquisa semântica com a Gemini Enterprise Agent Platform é 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
Nesta seção, explicamos como usar a API Agent Platform para embasar as respostas do LLM.
Pré-requisitos
Antes de embasar as respostas do LLM com o Elasticsearch, é necessário concluir o seguinte:
Ative a API Agent Platform: verifique se a API Agent Platform está ativada no seu projeto do Google Cloud .
Instale e faça 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 o embasamento. Consiga as seguintes informações da sua 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 use um modelo de referência que retorne dados de resultado para embasamento.
Gerar respostas embasadas
Console
Para fazer o embasamento com o Elasticsearch no console do Google Cloud , faça o seguinte:
Acesse a página do Agent Studio.
No painel lateral, em Configurações do modelo, acesse a seção Embasamento e ative a opção Seus dados.
No painel de configuração, selecione Elasticsearch.
Insira o endpoint no campo Endpoint do Elasticsearch.
Insira
ApiKey YOUR_API_KEYno 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 hits deslizando o controle Número de hits.
Clique em Salvar.
Insira seu comando.
Clique em Enviar.
Entender a resposta
Se o comando do modelo for embasado corretamente nos repositórios de dados do Elasticsearch usando o Agent 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 fonte ou informações incompletas na resposta do modelo, os metadados podem não ser 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 de IA generativa do Google 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_ENTERPRISE=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 Agent Platform. No mínimo, é preciso 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:generateContentCorpo JSON da solicitação:
{ "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 multiturno, consulte o Guia para iniciantes em 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:
- 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: o ID do projeto do Google Cloud . Para mais informações sobre IDs de projeto, consulte Como 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 for embasado corretamente na fonte de dados do Elasticsearch, as respostas vão incluir metadados de embasamento, que identificam as partes da resposta que foram 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:
- Papel: indica o remetente da resposta embasada. Como a resposta
sempre contém texto embasado, o papel é 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:
- Fragmentos de embasamento: uma lista de resultados do índice do Elasticsearch que corroboram a resposta.
- Suportes de embasamento: 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 fragmento de embasamento.
- Índice de fragmentos de embasamento: o índice dos fragmentos de embasamento na lista de fragmentos de embasamento que corresponde a essa declaração.
- Pontuações de confiança: um número de 0 a 1 que indica o nível de embasamento da declaração no conjunto de blocos de embasamento fornecido. Não disponível para o Gemini 2.5 Pro, 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 Agent Platform, consulte Práticas recomendadas de segurança.