עיגון באמצעות Elasticsearch

המסוף

כדי לבצע קרקוע באמצעות Elasticsearch במסוף Cloud de Confiance :

1. עוברים לדף Agent Studio.

   מעבר אל Agent Studio

2. בחלונית הצדדית, בקטע הגדרות המודל, עוברים לקטע ביסוס ומפעילים את המתג הנתונים שלך.

3. בחלונית ההגדרות, בוחרים באפשרות Elasticsearch.

4. מזינים את נקודת הקצה בשדה Elasticsearch endpoint.

5. מזינים את הערך ApiKey YOUR_API_KEY בשדה Elasticsearch API Key.

6. מזינים את האינדקס בשדה Elasticsearch index.

7. מזינים את תבנית החיפוש בשדה Elasticsearch search template.

8. כדי לשנות את מספר ההיטים, מזיזים את פס ההזזה מספר ההיטים.

9. לוחצים על Save.

10. מזינים את הפרומפט.

11. לוחצים על שליחה.

הסבר על התשובה

אם ההנחיה למודל מבססת בהצלחה את הנתונים על מאגרי נתונים של Elasticsearch באמצעות Agent Studio או ה-API, התשובות של המודל כוללות מטא-נתונים עם ציטוטים ותוכן מקור. אם בתשובה של המודל יש רלוונטיות נמוכה למקור או מידע חלקי, יכול להיות שלא יסופקו מטא-נתונים והתשובה להנחיה לא תהיה מבוססת.

Python

התקנה

pip install --upgrade google-genai

מידע נוסף מופיע ב מאמרי העזרה בנושא SDK.

מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם 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

כדי לשלוח פרומפט טקסטואלי ולעגן אותו באמצעות Elasticsearch, שולחים בקשת POST ל-Agent Platform API. חובה לספק לפחות את גוף הבקשה. חשוב לבצע את ההחלפות הבאות:

• ‫PROMPT: הפרומפט הטקסטואלי לעיגון.
• ‫ELASTIC_SEARCH_ENDPOINT: הנתיב המוחלט של נקודת הקצה של משאב Elasticsearch שבו רוצים להשתמש.
• ‫ELASTIC_SEARCH_API_KEY: מפתח ה-API של נקודת הנתונים של Elasticsearch.
• ‫INDEX_NAME: השם של אינדקס Elasticsearch שמשמש לביסוס.
• ‫SEARCH_TEMPLATE_NAME: תבנית החיפוש של Elasticsearch שמשמשת לעיגון.

• ‫NUM_HITS: מספר התוצאות שהוחזרו ממקור הנתונים של Elasticsearch ושימשו להארקה.

  ה-method של ה-HTTP וכתובת ה-URL:

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

  תוכן בקשת 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",
            }
          }
        }
      }]
    }
  

מידע נוסף על שדות אחרים של API, כמו הוראות מערכת ושיחות עם זיכרון, זמין במאמר מדריך למתחילים בנושא AI גנרטיבי.

שליחת בקשת ה-API

אפשר לשמור את גוף הבקשה בקובץ בשם request.json. לאחר מכן מבצעים את בקשת ה-API מסוג POST, ומחליפים את הפרטים הבאים:

• ‫LOCATION: האזור שבו הבקשה תעובד. כדי להשתמש בנקודת הקצה הגלובלית, צריך להחריג את המיקום משם נקודת הקצה ולהגדיר את מיקום המשאב ל-global.
• ‫PROJECT_ID: מזהה הפרויקט ב- Cloud de Confiance by S3NS . מידע נוסף על מזהי פרויקטים זמין במאמר יצירה וניהול של פרויקטים.
• ‫MODEL_ID: מזהה המודל של המודל המולטי-מודאלי.

  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"

אתם אמורים לקבל תגובת JSON שדומה לזו:

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

הסבר על התשובה

התשובה משני ממשקי ה-API כוללת את הטקסט שנוצר על ידי ה-LLM, שנקרא מועמד. אם הפרומפט של המודל מתבסס בהצלחה על מקור הנתונים שלכם ב-Elasticsearch, התשובות כוללות מטא-נתונים של ביסוס, שמזהים את החלקים בתשובה שהתקבלו מהנתונים שלכם ב-Elasticsearch. עם זאת, יש כמה סיבות לכך שהמטא-נתונים האלה לא יסופקו, והתשובה להנחיה לא תהיה מבוססת. למשל, אם המקורות לא רלוונטיים או שהמידע בתשובה של המודל לא מלא.

הנה פירוט של נתוני הפלט:

• תפקיד: מציין את השולח של התשובה שמבוססת על מקורות. התשובה תמיד מכילה טקסט מבוסס-קרקע, ולכן התפקיד הוא תמיד model.
• טקסט: התשובה שמבוססת על מקורות שנוצרה על ידי מודל שפה גדול (LLM).
• מטא-נתונים של ביסוס: מידע על מקור הביסוס, שכולל את הרכיבים הבאים:
  • חלקים מעוגנים: רשימת תוצאות מאינדקס Elasticsearch שתומכות בתשובה.
  • תמיכה בעיגון: מידע על טענה ספציפית בתשובה שאפשר להשתמש בו כדי להציג ציטוטים:
  • קטע: החלק בתשובה של המודל שמבוסס על קטע מידע מסוים.
  • Grounding chunk index: The index of the grounding chunks in the grounding chunks list that corresponds to this claim.
  • ציוני מהימנות: מספר מ-0 עד 1 שמציין עד כמה הטענה מבוססת על קבוצת קטעי הטקסט שסופקו לצורך ביסוס. לא זמין ב-Gemini 2.5 Pro, ב-Gemini 2.5 Flash ובגרסאות מתקדמות יותר.