Ancrage avec Elasticsearch

Console

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

1. Accédez à la page Agent Studio.

   Accéder à Agent Studio

2. Dans le panneau latéral, sous Paramètres du modèle, accédez à la section Ancrage, puis activez le bouton Vos données.

3. Dans le volet de configuration, 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 faisant glisser le curseur Nombre de résultats.

9. Cliquez sur Enregistrer.

10. Saisissez votre prompt.

11. Cliquez sur Envoyer.

Comprendre votre réponse

Si le prompt de votre modèle est correctement ancré sur les datastores Elasticsearch à l'aide d'Agent 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 pertinence de la source est faible ou si des informations sont incomplètes dans la réponse du modèle, il est possible que les métadonnées ne soient pas fournies et que la réponse du prompt ne soit pas ancrée.

Python

Installer

pip install --upgrade google-genai

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

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

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

• PROMPT : prompt textuel à ancrer.
• ELASTIC_SEARCH_ENDPOINT : chemin d'accès absolu au point de terminaison de la ressource Elasticsearch à utiliser pour.
• ELASTIC_SEARCH_API_KEY : clé API pour le point de terminaison des 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 chats multitours, consultez le guide du débutant sur l'IA générative.

Envoyer la requête API

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

• LOCATION : région dans laquelle traiter la requête. Pour utiliser le point de terminaison global, excluez l'emplacement du nom du point de terminaison et configurez l'emplacement de la ressource sur global.
• PROJECT_ID: ID du projet Cloud de Confiance by S3NS . 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 le prompt de votre modèle est correctement ancré 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 du prompt 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, Gemini 2.5 Flash et versions ultérieures.