חיפוש באמצעות הטמעות

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

בהתאם לסוג נקודת הקצה שהוגדרה למופע של החנות אונליין, אפשר לבצע אחת מהפעולות הבאות:

לפני שמתחילים

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

חיפוש התאמות של השכן הקרוב ביותר באמצעות נקודת קצה ציבורית

אם הגדרתם את מופע החנות שלכם באינטרנט להצגת ערכי תכונות באמצעות הצגה אונליין אופטימלית מנקודת קצה ציבורית, אתם צריכים לבצע את הפעולות הבאות כדי לאחזר התאמות משוערות של השכן הקרוב ביותר:

  1. איך מאחזרים את שם הדומיין של נקודת הקצה הציבורית של חנות האונליין

  2. אחזור התאמות של השכן הקרוב ביותר להטמעה או לישות

אחזור של שם הדומיין של נקודת הקצה הציבורית של החנות אונליין

כשיוצרים מופע של חנות וירטואלית להצגת מודלים אונליין בצורה אופטימלית, Vertex AI Feature Store יוצר שם דומיין של נקודת קצה ציבורית לחנות הוירטואלית. כדי להתחיל לחפש שכנים קרובים מתצוגת תכונות בחנות אונליין, צריך לאחזר את שם הדומיין של נקודת הקצה הציבורית מפרטי החנות אונליין.

אפשר להשתמש בדוגמה הבאה כדי לאחזר את הפרטים של מופע של חנות אונליין.

REST

כדי לאחזר את הפרטים של משאב FeatureOnlineStore בפרויקט, שולחים בקשת GET באמצעות השיטה featureOnlineStores.get.

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

  • ‫LOCATION_ID: האזור שבו נמצאת חנות האונליין, למשל us-central1.
  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫FEATUREONLINESTORE_NAME: השם של מופע החנות באינטרנט.

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

GET https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME

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

curl

מריצים את הפקודה הבאה: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME"

PowerShell

מריצים את הפקודה הבאה: 

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME" | Select-Object -Expand Content

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

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME_1",
  "createTime": "2023-09-06T23:25:04.256314Z",
  "updateTime": "2023-09-06T23:25:04.256314Z",
  "etag": "AMEw9yMgoV0bAsYuKwVxz4Y7lOmxV7riNVHg217KaQAKORqvdqGCrQ1DIt8yHgoGXf8=",
  "state": "STABLE",
  "dedicatedServingEndpoint": {
    "publicEndpointDomainName": "PUBLIC_ENDPOINT_DOMAIN_NAME"
  },
  "optimized": {}
}

תצטרכו את PUBLIC_ENDPOINT_DOMAIN_NAME מהתשובה כדי לאחזר את השכנים הקרובים המשוערים בשלב הבא.

אחזור של שכנים קרובים משוערים באמצעות נקודת קצה ציבורית

אחרי שמקבלים את שם הדומיין של נקודת הקצה הציבורית של החנות אונליין, אפשר להשתמש בו כדי לחפש שכנים קרובים משוערים של הטמעה או ישות.

אחזור של שכנים קרובים משוערים של הטמעה

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

REST

כדי לחפש את השכנים הקרובים ביותר להטמעה, שולחים בקשת POST באמצעות השיטה featureViews.searchNearestEntities.

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

  • ‫PUBLIC_ENDPOINT_DOMAIN_NAME: שם הדומיין של נקודת הקצה הציבורית של מופע החנות אונליין שאוחזר באמצעות ה-method featureOnlineStores.get.
  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫LOCATION_ID: האזור שבו נמצא המופע של החנות הווירטואלית, למשל us-central1.
  • ‫FEATUREONLINESTORE_NAME: השם של מופע החנות אונליין שמכיל את תצוגת התכונות שבה רוצים לחפש התאמות של השכן הקרוב המשוער.
  • ‫FEATUREVIEW_NAME: השם של תצוגת התכונות שבה רוצים לחפש התאמות של השכן הקרוב המשוער.
  • ‫EMBEDDING: ההטמעה שרוצים לאחזר עבורה התאמות משוערות של השכן הקרוב ביותר. הטמעה מיוצגת על ידי מערך של double ערכים.
  • ‫RETURN_FULL_ENTITY (אופציונלי): מציינים אם רוצים לכלול או להחריג את התכונות של הישויות בתשובה. כדי לכלול את התכונות יחד עם הישויות בתשובה, מזינים true. ערך ברירת המחדל הוא false.
  • ‫NEIGHBOR_COUNT: מספר השכנים הקרובים המשוערים שרוצים לאחזר.

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

POST https://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities

גוף בקשת JSON: 

{
  "query": {
    "embedding": {
      "value": EMBEDDING
    },
    "neighbor_count": NEIGHBOR_COUNT
  },
  "return_full_entity": RETURN_FULL_ENTITY
}

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

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://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities"

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://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities" | Select-Object -Expand Content

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

{
  "nearestNeighbors": {
    "neighbors": [
    {
      "entityId": "305281",
      "distance": -41.115459442138672
    },
    {
      "entityId": "80280",
      "distance": -38.703567504882812
    },
    {
      "entityId": "80280",
      "distance":-38.703567504882812
    },
    {
      "entityId": "903779",
      "distance": -38.214759826660156
    },
    {
      "entityId": "1008145",
      "distance": -36.271354675292969
    },
    {
      "entityId": "606431",
      "distance": -34.791431427001953
    } ]
  }
}

אחזור של שכנים קרובים משוערים של ישות

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

REST

כדי לחפש ישויות קרובות למזהה ישות, שולחים בקשת POST באמצעות השיטה featureViews.searchNearestEntities.

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

  • ‫PUBLIC_ENDPOINT_DOMAIN_NAME: שם הדומיין של נקודת הקצה הציבורית של מופע החנות אונליין שאוחזר באמצעות ה-method featureOnlineStores.get.
  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫LOCATION_ID: האזור שבו נמצא המופע של החנות הווירטואלית, למשל us-central1.
  • ‫FEATUREONLINESTORE_NAME: השם של מופע החנות אונליין שמכיל את תצוגת התכונות שבה רוצים לחפש התאמות של השכן הקרוב המשוער.
  • ‫FEATUREVIEW_NAME: השם של תצוגת התכונות שבה רוצים לחפש התאמות של השכן הקרוב המשוער.
  • ‫ENTITY_ID: מזהה הישות שרוצים לאחזר עבורה התאמות משוערות לשכנים הקרובים ביותר.
  • ‫RETURN_FULL_ENTITY (אופציונלי): מציינים אם רוצים לכלול או להחריג את התכונות של הישויות בתשובה. כדי לכלול את התכונות יחד עם הישויות בתשובה, מזינים true. ערך ברירת המחדל הוא false.
  • ‫NEIGHBOR_COUNT: מספר השכנים הקרובים המשוערים שרוצים לאחזר.

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

POST https://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities

גוף בקשת JSON: 

{
  "query": {
    "entity_id": ENTITY_ID,
    "neighbor_count": NEIGHBOR_COUNT
  },
  "return_full_entity": RETURN_FULL_ENTITY
}

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

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://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities"

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://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities" | Select-Object -Expand Content

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

{
  "nearestNeighbors": {
    "neighbors": [
    {
      "entityId": "305281",
      "distance": -41.115459442138672
    },
    {
      "entityId": "80280",
      "distance": -38.703567504882812
    },
    {
      "entityId": "80280",
      "distance":-38.703567504882812
    },
    {
      "entityId": "903779",
      "distance": -38.214759826660156
    },
    {
      "entityId": "1008145",
      "distance": -36.271354675292969
    },
    {
      "entityId": "606431",
      "distance": -34.791431427001953
    } ]
  }
}

חיפוש התאמות של השכן הקרוב ביותר באמצעות נקודת קצה של Private Service Connect

אם הגדרתם את מופע החנות שלכם באינטרנט כך שיציג ערכי תכונות באמצעות נקודת קצה של Private Service Connect, אתם צריכים לבצע את הפעולות הבאות כדי לאחזר התאמות משוערות של השכן הקרוב ביותר:

  1. מאחזרים את מחרוזת צירוף השירות של חנות אונליין.

  2. מוסיפים נקודת קצה ל-Private Service Connect להגדרת הרשת.

  3. מתחברים לנקודת הקצה של Private Service Connect דרך gRPC.

  4. אחזור התאמות של השכן הקרוב ביותר להטמעה או לישות

אחזור מחרוזת צירוף השירות לחנות אונליין

כשיוצרים מכונה של חנות אונליין להצגת מודלים אונליין בצורה אופטימלית עם נקודת קצה (endpoint) של Private Service Connect, ‏ Vertex AI Feature Store יוצר מחרוזת של קובץ מצורף לשירות. אפשר לאחזר את מחרוזת צירוף השירות מפרטי החנות אונליין ולהשתמש במחרוזת הזו כדי להגדיר את נקודת הקצה (endpoint) של Private Service Connect.

אפשר להשתמש בדוגמה הבאה כדי לאחזר את הפרטים של מופע של חנות אונליין.

REST

כדי לאחזר את הפרטים של משאב FeatureOnlineStore בפרויקט, שולחים בקשת GET באמצעות השיטה featureOnlineStores.get.

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

  • ‫LOCATION_ID: האזור שבו נמצאת חנות האונליין, למשל us-central1.
  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫FEATUREONLINESTORE_NAME: השם של מופע החנות באינטרנט.

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

GET https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME

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

curl

מריצים את הפקודה הבאה: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME"

PowerShell

מריצים את הפקודה הבאה: 

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME" | Select-Object -Expand Content

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

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME_1",
  "createTime": "2023-09-06T23:25:04.256314Z",
  "updateTime": "2023-09-06T23:25:04.256314Z",
  "etag": "AMEw9yMgoV0bAsYuKwVxz4Y7lOmxV7riNVHg217KaQAKORqvdqGCrQ1DIt8yHgoGXf8=",
  "state": "STABLE",
  "dedicatedServingEndpoint": {
    "privateServiceConnectConfig": {
      "enablePrivateServiceConnect": "true",
      "projectAllowlist": [
        "PROJECT_NAME"
      ]
    },
    serviceAttachment: "SERVICE_ATTACHMENT_STRING"
  },
  "optimized": {}
}

תצטרכו את הערך SERVICE_ATTACHMENT_STRING מהתגובה כדי לאחזר את ערכי התכונות בשלב הבא.

הוספת נקודת קצה ל-Private Service Connect

כדי להוסיף נקודת קצה של Private Service Connect להצגת מודעות אונליין אופטימלית להגדרת הרשת, מבצעים את השלבים הבאים:

  1. במסוף Cloud de Confiance , בוחרים את הפרויקט שמכיל את המופע של חנות אונליין.

  2. יוצרים נקודת קצה ל-Private Service Connect על ידי ציון SERVICE_ATTACHMENT_STRING כשירות היעד.

אחרי שיוצרים את נקודת הקצה, היא מופיעה בכרטיסייה Connected endpoints בדף Private Service Connect. כתובת ה-IP של נקודת הקצה מופיעה בעמודה IP addresses.

מעבר לכרטיסייה Connected endpoints

בשלב הבא תצטרכו להשתמש בכתובת ה-IP הזו כדי להתחבר לנקודת הקצה של מופע החנות האונליין שלכם לנקודת הקצה של Private Service Connect באמצעות gRPC.

התחברות לנקודת הקצה של Private Service Connect דרך gRPC

אפשר להשתמש בדוגמת הקוד הבאה כדי להתחבר לנקודת הקצה (endpoint) של Private Service Connect שנוצרה לחנות שלכם אונליין באמצעות gRPC.

Python 

from google.cloud.aiplatform_v1 import FeatureOnlineStoreServiceClient
from google.cloud.aiplatform_v1.services.feature_online_store_service.transports.grpc import FeatureOnlineStoreServiceGrpcTransport
import grpc

data_client = FeatureOnlineStoreServiceClient(
  transport = FeatureOnlineStoreServiceGrpcTransport(
    # Add the IP address of the Endpoint you just created.
    channel = grpc.insecure_channel("ENDPOINT_IP:10002")
  )
)

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

  • ‫ENDPOINT_IP: כתובת ה-IP של נקודת הקצה בעמודה כתובות IP בדף Private Service Connect.

אחזור של שכנים קרובים משוערים באמצעות נקודת קצה של Private Service Connect

אחרי שמתחברים לנקודת הקצה של Private Service Connect דרך gRPC, אפשר לחפש שכנים קרובים משוערים של הטמעה או ישות.

אחזור של שכנים קרובים משוערים של הטמעה

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

Python 

data_client.search_nearest_entities(
  request=feature_online_store_service_pb2.SearchNearestEntitiesRequest(
      feature_view=f"projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME",
      query=feature_online_store_service_pb2.NearestNeighborQuery(
          embedding = "EMBEDDING",
          neighbor_count = NEIGHBOR_COUNT,
      ),
      return_full_entity=RETURN_FULL_ENTITY
  ))

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

  • ‫LOCATION_ID: האזור שבו נמצאת חנות האונליין, למשל us-central1.

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

  • ‫FEATUREONLINESTORE_NAME: השם של החנות אונליין שמכילה את תצוגת התכונות.

  • ‫FEATUREVIEW_NAME: השם של תצוגת התכונות שבה רוצים לחפש התאמות של השכנים הקרובים המשוערים.

  • ‫EMBEDDING: הטמעה שרוצים לאחזר בשבילה התאמות משוערות של השכן הקרוב ביותר. הטמעה מיוצגת על ידי מערך של double ערכים.

  • ‫FORMAT: אופציונלי: הפורמט שבו רוצים לאחזר את ערכי התכונות. הפורמטים הנתמכים כוללים צמד מפתח-ערך בפורמט JSON ופורמטים של פרוטו Struct. שימו לב שפורמט הפרוטו Struct לא תומך בסוג הערך של התכונה bytes. אם רוצים לאחזר ערכי תכונות בפורמט של בייטים, צריך להשתמש ב-JSON כפורמט התגובה.

  • ‫RETURN_FULL_ENTITY (אופציונלי): מציינים אם רוצים לכלול או להחריג את התכונות של הישויות בתשובה. כדי לכלול את התכונות יחד עם הישויות בתשובה, מזינים true. ערך ברירת המחדל הוא false.

  • ‫NEIGHBOR_COUNT: מספר השכנים הקרובים המשוערים שרוצים לאחזר.

אחזור של שכנים קרובים משוערים של ישות

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

Python 

data_client.search_nearest_entities(
  request=feature_online_store_service_pb2.SearchNearestEntitiesRequest(
      feature_view=f"projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME",
      query=feature_online_store_service_pb2.NearestNeighborQuery(
          entity_id = "ENTITY_ID",
          neighbor_count = NEIGHBOR_COUNT,
      ),
      return_full_entity=RETURN_FULL_ENTITY
  ))
 ```

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

  • ‫LOCATION_ID: האזור שבו נמצאת חנות האונליין, למשל us-central1.

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

  • ‫FEATUREONLINESTORE_NAME: השם של החנות אונליין שמכילה את תצוגת התכונות.

  • ‫FEATUREVIEW_NAME: השם של תצוגת התכונות שבה רוצים לחפש התאמות של השכנים הקרובים המשוערים.

  • ‫ENTITY_ID: מזהה הישות שרוצים לאחזר עבורה התאמות משוערות של השכנים הקרובים ביותר.

  • ‫FORMAT: אופציונלי: הפורמט שבו רוצים לאחזר את ערכי התכונות. הפורמטים הנתמכים כוללים צמד מפתח-ערך בפורמט JSON ופורמטים של פרוטו Struct. שימו לב שפורמט הפרוטו Struct לא תומך בסוג הערך של התכונה bytes. אם רוצים לאחזר ערכי תכונות בפורמט של בייטים, צריך להשתמש ב-JSON כפורמט התגובה.

  • ‫RETURN_FULL_ENTITY (אופציונלי): מציינים אם רוצים לכלול או להחריג את התכונות של הישויות בתשובה. כדי לכלול את התכונות יחד עם הישויות בתשובה, מזינים true. ערך ברירת המחדל הוא false.

  • ‫NEIGHBOR_COUNT: מספר השכנים הקרובים המשוערים שרוצים לאחזר.