אחזור דוגמאות

בדף הזה מוסבר איך לאחזר דוגמאות מהחנות לדוגמה. אלה האפשרויות לאחזור הדוגמאות:

  • ‫FetchExamples: מאחזר את כל הדוגמאות שתואמות בדיוק לקריטריוני הסינון. כדאי להשתמש באפשרות הזו אם יש לכם רק כמה דוגמאות או אם אתם צריכים זמן אחזור נמוך יותר.

  • ‫SearchExamples: שליפת דוגמאות באמצעות חיפוש דמיון בין שאילתת המשתמש לבין הדוגמאות המאוחסנות. כדאי להשתמש באפשרות הזו אם יש לכם מספר גדול של דוגמאות.

דרישות מוקדמות

לפני שמשתמשים בדוגמאות של Python שבדף הזה, צריך להתקין ולהפעיל את Agent Platform SDK בסביבת Python המקומית.

  1. מריצים את הפקודה הבאה כדי להתקין את Agent Platform SDK עבור Example Store.

    pip install --upgrade google-cloud-aiplatform>=1.87.0

  2. בדוגמת הקוד הבאה אפשר לראות איך מייבאים ומפעילים את ה-SDK של Example Store.

    import vertexai
from vertexai.preview import example_stores

vertexai.init(
  project="PROJECT_ID",
  location="LOCATION"
)

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫PROJECT_ID: מזהה הפרויקט.

    • ‫LOCATION: האזור שלכם. יש תמיכה רק ב-us-central1.

דוגמאות לאחזור

אפשר להשתמש בדוגמאות הבאות כדי לאחזר דוגמאות. ‫FetchExamples מאחזר את כל הדוגמאות שתואמות בדיוק לקריטריוני הסינון.

Agent Platform SDK

הקוד הבא מחזיר את כל הדוגמאות בחנות לדוגמה, עד 100 דוגמאות בכל דף:

from vertexai.preview import example_stores

example_store = example_stores.ExampleStore(EXAMPLE_STORE_NAME)
# Returns the dictionary representation of FetchExamplesResponse.
examples = example_store.fetch_examples()

אפשר להשתמש בfunction_names כדי לציין מסנן אחד או יותר שמגביל את הדוגמאות שיוחזרו. בדוגמה הבאה מוצגות רק דוגמאות שכוללות את הפונקציות flight_booking_tool ו-hotel_booking_tool:

# Returns examples that include either tool.
example_store.fetch_examples(
    filter={
        "function_names": {
            "values": ["flight_booking_tool", "hotel_booking_tool"],
            "array_operator": "CONTAINS_ANY"
        }
    }
)

# Returns examples that include *both* tools.
example_store.fetch_examples(
    filter={
        "function_names": {
            "values": ["flight_booking_tool", "hotel_booking_tool"],
            "array_operator": "CONTAINS_ALL"
        }
    }
)

אפשר להשתמש במסנן search_keys כדי להגביל את הדוגמאות שמוחזרות לפי מפתח החיפוש שלהן.

# Returns examples that include any of the following search keys.
example_store.fetch_examples(
    filter={"search_keys": ["How do I get to the airport?"]}
)

אתם יכולים להשתמש במסנן example_ids כדי להגביל את הדוגמאות שמוחזרות לפי מזהה הדוגמה. מזהים לדוגמה הם בפורמט exampleTypes/stored_contents_example/examples/<var>EXAMPLE_ID</var>, כאשר EXAMPLE_ID מייצג את המזהה המספרי שנוצר לדוגמה.

# Returns examples that have any of the following Example IDs.
example_store.fetch_examples(
  example_ids=["exampleTypes/stored_contents_example/examples/09b1d383f92c47e7a2583a44ebbc7854"]
)

‫API בארכיטקטורת REST

כדי לאחזר דוגמאות, שולחים בקשת POST באמצעות השיטה exampleStores.fetchExamples.

המסנן function_names שצוין בגוף בקשת ה-JSON לדוגמה מחזיר רק דוגמאות שכוללות את הפונקציות flight_booking_tool ו-hotel_booking_tool:

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫LOCATION: האזור שבו רוצים ליצור את חנות הדוגמה. האזור היחיד שנתמך הוא us-central1.
  • ‫EXAMPLE_STORE_ID: המזהה של מופע Example Store שרוצים להעלות אליו את הדוגמה.

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

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/exampleStores/EXAMPLE_STORE_ID:fetchExamples

גוף בקשת JSON: 

{
  "stored_contents_example_filter": {
    "function_names": {
      "values": ["flight_booking_tool", "hotel_booking_tool"],
      "array_operator": "CONTAINS_ANY"
     }
  }
}

כדי לשלוח את הבקשה עליכם לבחור אחת מהאפשרויות הבאות:

curl

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

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/exampleStores/EXAMPLE_STORE_ID:fetchExamples"

PowerShell

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/exampleStores/EXAMPLE_STORE_ID:fetchExamples" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו, שבה EXAMPLE_ID מייצג את המזהה שנוצר לדוגמה.

דוגמאות לחיפושים

לדוגמה, חנות הדוגמאות מוצאת את הדוגמאות הכי רלוונטיות על סמך ציון הדמיון בין stored_contents_example_key לבין מפתחות החיפוש של הדוגמאות המאוחסנות. שימוש בדוגמאות שרלוונטיות לשיחה עוזר למודל ללמוד את ההתנהגות הצפויה.

Agent Platform SDK

בדוגמת הקוד הבאה אפשר לראות איך מחפשים דוגמאות רלוונטיות באמצעות Agent Platform SDK ל-Python:

example_store.search_examples(
    parameters={
        "stored_contents_example_key": "what's the weather in nyc"
    },
    # Only fetch the most similar examaple. The default value is 3.
    top_k=1
)

"""
Response -- dictionary representation of SearchExamplesResponse.
{'results': [{'example': {'exampleId': 'exampleTypes/stored_contents_example/examples/16834837b178453783e471b459d99195',
    'storedContentsExample': {'searchKey': 'What is the weather like in Boston?',
    'contentsExample': {'contents': [{'role': 'user',
        'parts': [{'text': 'What is the weather like in Boston?'}]}],
      'expectedContents': [{'content': {'parts': [{'functionCall': {'name': 'get_current_weather',
            'args': {'location': 'New York, NY'}}}]}},
      {'content': {'parts': [{'functionResponse': {'name': 'get_current_weather',
            'response': {'humidity': 65.0,
            'description': 'Partly Cloudy',
            'icon': 'partly-cloudy',
            'temperature': 38.0,
            'location': 'Boston, MA',
            'wind': {'speed': 10.0, 'direction': 'NW'}}}}]}},
      {'content': {'role': 'model',
        'parts': [{'text': 'The weather in Boston is 38 degrees and partly cloudy.'}]}}]}}},
  'similarityScore': 0.73527116}]}
"""

אפשר להשתמש במסנן function_names כדי להגביל את הדוגמאות שייכללו בחיפוש הדמיון.

example_store.search_examples(
  parameters={
    "stored_contents_example_key": "What's the weather in nyc",
    "function_names": {
      "values": ["weather_tool", "hotel_booking_tool"],
      "array_operator": "CONTAINS_ANY"
    }
  }
)