Ancrage avec Elasticsearch

Cette page explique comment utiliser votre instance Elasticsearch pour ancrer vos données.

Ancrer Gemini avec Elasticsearch

L'ancrage consiste à utiliser des ensembles de données publics et privés pour fournir du contexte et des faits afin d'ancrer les réponses des grands modèles de langage (LLM). En ancrant Gemini avec Elasticsearch, vous pouvez tirer parti de vos index Elasticsearch existants pour améliorer la qualité et la fiabilité des résultats de Gemini, réduire les hallucinations et vous assurer que les réponses sont pertinentes par rapport à vos données. Cela vous permet de créer des applications RAG puissantes, par exemple :

• Résumés de recherche génératifs
• Chatbots de questions/réponses avec des données d'entreprise
• Agents ancrés dans vos données

Vous pouvez ancrer une réponse sur un maximum de 10 sources de données à la fois. Vous pouvez combiner l'ancrage avec Elasticsearch et l'ancrage avec la recherche Google pour associer le modèle à des connaissances du monde entier, à un large éventail de sujets possibles ou à des informations à jour disponibles sur Internet.

Modèles compatibles

Les modèles suivants sont compatibles avec l'ancrage avec Elasticsearch avec entrée de texte uniquement :

• Gemini 2.5 Flash (preview)
• Gemini 2.5 Flash-Lite (preview)
• Gemini 2.5 Flash-Lite
• Gemini 2.5 Flash avec l'audio natif de l'API Live (Preview)
• Gemini 2.0 Flash avec l'API Live (Preview)
• Gemini 2.5 Pro
• Gemini 2.5 Flash
• Gemini 2.0 Flash

Configurer un modèle de recherche dans Elasticsearch

Cette section explique comment utiliser votre instance Elasticsearch pour ancrer vos données stockées dans l'instance.

Bonnes pratiques

Pour obtenir les meilleures réponses d'ancrage, suivez ces principes lorsque vous créez un modèle de recherche :

• N'incluez que des données pertinentes et utiles. Par exemple, dans un catalogue de produits, spécifier une URL d'image peut ne pas aider le LLM à répondre aux requêtes sur les propriétés des produits, sauf si la requête demande spécifiquement une URL. De même, évitez de générer des vecteurs d'embedding.

• L'ancrage supprime les résultats Elasticsearch peu pertinents par rapport à vos requêtes. Vous devez fournir un nombre plus élevé de résultats Elasticsearch pour capturer tout le contexte pertinent.

• Les données de résultats peuvent se trouver dans un seul champ ou être réparties sur plusieurs champs.

Exemples de modèles

Vous pouvez utiliser vos modèles de recherche. Toutefois, nous vous recommandons d'utiliser le modèle de recherche kNN générique avec l'ancrage Elasticsearch. Pour obtenir d'autres modèles de recherche, consultez le dépôt GitHub.

Cette recherche sémantique avec Vertex AI est une recherche kNN générique.

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

Générer des réponses ancrées avec Elasticsearch

Cette section explique comment utiliser l'API Vertex AI pour ancrer les réponses de votre LLM.

Prérequis

Avant de pouvoir ancrer les réponses LLM avec Elasticsearch, vous devez effectuer les opérations suivantes :

1. Activez l'API Vertex AI : assurez-vous que l'API Vertex AI est activée pour votre projet Google Cloud .

2. Installez et connectez-vous à la Google Cloud CLI : installez et initialisez l'outil de ligne de commande gcloud CLI.

3. Configuration d'Elasticsearch : utilisez un cluster et un index Elasticsearch existants que vous souhaitez utiliser pour l'ancrage. Obtenez les informations suivantes à partir de votre configuration Elasticsearch :

   • Point de terminaison : URL de votre cluster Elasticsearch.
   • Nom de l'index : nom de l'index dans lequel vous souhaitez effectuer une recherche, par exemple my-data-index.
   • Clé API : clé API permettant d'accéder à votre cluster Elasticsearch. La clé API doit commencer par le préfixe ApiKey.

4. Créer un modèle de recherche Elasticsearch : utilisez une source de données Elasticsearch qui utilise un modèle de référence renvoyant des données de résultat pour l'ancrage.

Générer des réponses ancrées

Console

Pour ancrer avec Elasticsearch dans la console Google Cloud , procédez comme suit :

1. Accédez à la page Créer un prompt de Vertex AI Studio.

   Accéder à la page Créer une requête

2. Dans le panneau Paramètres, cliquez sur le bouton Ancrage : vos données pour ancrer vos données.

3. Dans le volet Personnaliser l'ancrage, sélectionnez Elasticsearch.

4. Saisissez le point de terminaison dans le champ Point de terminaison Elasticsearch.

5. Saisissez ApiKey YOUR_API_KEY dans le champ Clé API Elasticsearch.

6. Saisissez l'index dans le champ Index Elasticsearch.

7. Saisissez le modèle de recherche dans le champ Modèle de recherche Elasticsearch.

8. Ajustez le nombre de résultats en déplaçant le curseur Nombre de résultats.

9. Cliquez sur Enregistrer.

10. Saisissez votre requête.

11. Cliquez sur Envoyer.

Comprendre votre réponse

Si la requête de votre modèle est correctement ancrée dans les magasins de données Elasticsearch à l'aide de Vertex AI Studio ou de l'API, les réponses du modèle incluent des métadonnées avec des citations et du contenu source. Si la réponse du modèle présente une faible pertinence de la source ou des informations incomplètes, il est possible que les métadonnées ne soient pas fournies et que la réponse à la requête ne soit pas ancrée.

Python

Installer

pip install --upgrade google-genai

Pour en savoir plus, lisez la documentation de référence du SDK.

Définissez des variables d'environnement pour utiliser le SDK Gen AI avec 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

Pour envoyer une requête textuelle et l'ancrer avec Elasticsearch, envoyez une requête POST à l'API Vertex AI. Vous devez au minimum fournir le corps de la requête. Veillez à effectuer les remplacements suivants :

• PROMPT : requête textuelle à ancrer.
• ELASTIC_SEARCH_ENDPOINT : chemin d'accès absolu au point de terminaison de la ressource Elasticsearch à utiliser.
• ELASTIC_SEARCH_API_KEY : clé API pour le point de terminaison de données Elasticsearch.
• INDEX_NAME : nom de l'index Elasticsearch utilisé pour l'ancrage.
• SEARCH_TEMPLATE_NAME : modèle de recherche Elasticsearch utilisé pour l'ancrage.

• NUM_HITS : nombre de résultats renvoyés par la source de données Elasticsearch et utilisés pour l'ancrage.

  Méthode HTTP et URL :

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

  Corps JSON de la requête :

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

Pour en savoir plus sur les autres champs d'API, tels que les instructions système et les conversations multitours, consultez le guide du débutant sur l'IA générative.

Envoyer la requête d'API

Vous pouvez enregistrer le corps de la requête dans un fichier nommé request.json. Exécutez ensuite la requête POST de l'API et effectuez les remplacements suivants :

• LOCATION : région dans laquelle traiter la requête. Pour utiliser le point de terminaison mondial, excluez l'emplacement du nom du point de terminaison et configurez l'emplacement de la ressource sur global.
• PROJECT_ID : ID de votre projet Google Cloud . Pour en savoir plus sur les ID de projet, consultez Créer et gérer des projets.
• MODEL_ID : ID du modèle 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"

Vous devriez recevoir une réponse JSON de ce type :

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

Comprendre votre réponse

La réponse des deux API inclut le texte généré par le LLM, appelé candidat. Si la requête de votre modèle est correctement ancrée sur votre source de données Elasticsearch, les réponses incluent des métadonnées d'ancrage, qui identifient les parties de la réponse provenant de vos données Elasticsearch. Toutefois, il existe plusieurs raisons pour lesquelles ces métadonnées peuvent ne pas être fournies et la réponse de la requête ne sera pas ancrée. Ces raisons peuvent être une faible pertinence de la source ou des informations incomplètes dans la réponse du modèle.

Voici une répartition des données de sortie :

• Rôle : indique l'expéditeur de la réponse ancrée. Étant donné que la réponse contient toujours du texte ancré, le rôle est toujours model.
• Texte : réponse ancrée générée par le LLM.
• Métadonnées d'ancrage : informations sur la source d'ancrage, qui contient les éléments suivants :
  • Segments d'ancrage : liste des résultats de votre index Elasticsearch qui correspondent à la réponse.
  • Supports d'ancrage : informations sur une affirmation spécifique dans la réponse qui peuvent être utilisées pour afficher des citations :
  • Segment : partie de la réponse du modèle qui est étayée par un segment d'ancrage.
  • Index de segment d'ancrage : index des segments d'ancrage dans la liste des segments d'ancrage correspondant à cette affirmation.
  • Scores de confiance : nombre compris entre 0 et 1 qui indique le niveau d'ancrage de l'affirmation dans l'ensemble fourni de segments d'ancrage. Non disponible pour Gemini 2.5 Pro et Gemini 2.5 Flash et versions ultérieures.

Étapes suivantes

• Pour en savoir plus sur l'envoi de requêtes de chat, consultez la section Chat multitour.
• Pour en savoir plus sur les bonnes pratiques d'IA responsable et les filtres de sécurité de Vertex AI, consultez Bonnes pratiques de sécurité.