הגדרת חיפוש וקטורי באמצעות Private Service Connect

‫Private Service Connect מאפשר שימוש פרטי בשירותים ברשתות VPC ששייכות לקבוצות, לצוותים, לפרויקטים ולארגונים שונים. אתם יכולים לפרסם שירותים ולצרוך אותם באמצעות כתובות IP שאתם מגדירים ושפנימיות לרשת ה-VPC שלכם, וגם להשתמש בנקודות קצה (endpoints) של חיפוש וקטורי כדי לבצע חיפושים של דמיון וקטורי.

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

  1. נדרש זמן אחזור נמוך וחיבור מאובטח לשרתי קצה עורפיים של חיפוש וקטורי.
  2. יש לכם מרחב מוגבל של כתובות IP להזמנת VPC בלעדית.
  3. צריך לגשת לשרתי הקצה העורפיים של ההצגה מכמה רשתות VPC של משתמשים.

מידע נוסף על הגדרת Private Service Connect זמין במאמר סקירה כללית על Private Service Connect במסמכי העזרה בנושא ענן וירטואלי פרטי (VPC).

יצירת נקודת הקצה של האינדקס

צריך להפעיל את Private Service Connect כשיוצרים את נקודת הקצה. התהליך הזה דומה ליצירת נקודות קצה אחרות ב-Gemini Enterprise Agent Platform.

REST

  • ‫PROJECT: המזהה של פרויקט השירות שבו אתם יוצרים משאבים של Gemini Enterprise Agent Platform.

  • ‫REGION: האזור ברשת.

  • ‫DISPLAY_NAME: שם מוצג לנקודת הקצה. השם הזה משמש ליצירת מזהה לנקודת הקצה, ואי אפשר לעדכן אותו בהמשך.

  • ‫VPC_PROJECTS: בהגדרה של VPC משותף, זוהי רשימה מופרדת בפסיקים של פרויקטים מארחים של VPC. הוא מקביל ל-PROJECT בהגדרה של VPC עצמאי.

PROJECT=PROJECT_ID
VPC_PROJECT=VPC_PROJECT_ID
REGION=us-central1
VERTEX_ENDPOINT=REGION-aiplatform.googleapis.com
curl -H "Content-Type: application/json" \
  -H "Authorization: Bearer `gcloud auth print-access-token`" \
  https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/REGION/indexEndpoints \
  -d '{
     "displayName": "DISPLAY_NAME",
     "privateServiceConnectConfig": {
       "enablePrivateServiceConnect": true,
       "projectAllowlist": [ "VPC_PROJECT_1", "VPC_PROJECT_2", "VPC_PROJECT_N"]
     }
   }

המסוף

כדי ליצור את נקודת הקצה:

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

    מעבר אל חיפוש וקטורי

  2. בוחרים בכרטיסייה Index endpoints (נקודות קצה של אינדקס). יופיעו נקודות הקצה של האינדקס.

  3. לוחצים על יצירת נקודת קצה חדשה. נפתחת החלונית Create a new index endpoint (יצירת נקודת קצה חדשה של אינדקס).

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

  5. בוחרים אזור מהתפריט הנפתח אזור.

  6. בקטע גישה, לוחצים על Private Service Connect (גרסת Preview).

  7. מופיע שדה טקסט שבו אפשר לציין באילו פרויקטים של VPC להשתמש. מוסיפים את המזהים או המספרים של פרויקטי ה-VPC שרוצים להשתמש בהם.

  8. לוחצים על יצירה.

מידע על אפשרויות הפריסה של האינדקס

אפשר לפרוס את האינדקס עם קישוריות אוטומטית או ידנית לשירות.

  • פריסה באמצעות אוטומציה של Private Service Connect: מגדירים מדיניות של חיבור לשירות ופורסים את האינדקסים. הגדרת מדיניות של חיבור לשירות מאפשרת לפרוס לרשת ספציפית בלי ליצור כתובת מחשוב וכלל העברה בכל פעם.
  • פריסה עם חיבור ידני: פריסת האינדקס ויצירה ידנית של כתובת מחשוב וכלל העברה. אפשר לבחור באפשרות הזו אם צריך להשתמש בכמה כתובות IP לאותו URI של קובץ מצורף לשירות, אבל זה לא תרחיש שימוש נפוץ.

פריסה באמצעות אוטומציה של Private Service Connect

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

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

מגבלות

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

יצירת מדיניות לחיבור שירות

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

כדי להפוך את פריסת האינדקס לאוטומטית:

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

    • ‫PROJECT: פרויקט השירות שבו אתם יוצרים משאבים של Gemini Enterprise Agent Platform.

    • ‫VPC_PROJECT: הפרויקט שבו נמצא ה-VPC של הלקוח. בהגדרה של VPC יחיד, זהה לערך של ‎ $PROJECT. בהגדרת VPC משותף, זהו פרויקט מארח של VPC.

    • ‫NETWORK_NAME: השם של הרשת שרוצים לפרוס בה, בפורמט projects//global/networks/.

    • ‫REGION: האזור ברשת.

    • ‫PSC_SUBNETS: רשתות המשנה של Private Service Connect שבהן רוצים להשתמש.

    gcloud network-connectivity service-connection-policies create <policy_name> \
    --project=<vpc_project> --network=<network_name> # in the format projects/<project_id>/global/networks/<network_name> \
    --service-class=gcp-vertexai --region=<region> --subnets=<psc subnets>
    
  2. צפייה במדיניות חיבור השירות.

    gcloud network-connectivity service-connection-policies list --project=<vpc_project> -–region=<region>
    

מידע נוסף על מדיניות חיבור שירותים זמין במאמר הגדרת מדיניות חיבור שירותים.

פריסת האינדקס

REST

  • ‫PROJECT: פרויקט השירות שבו אתם יוצרים משאבים של Gemini Enterprise Agent Platform.

  • ‫VPC_PROJECT: הפרויקט שבו נמצא ה-VPC של הלקוח. בהגדרה של VPC משותף, זהו הפרויקט המארח של ה-VPC.

  • ‫DISPLAY_NAME: שם מוצג לנקודת הקצה. השם הזה משמש ליצירת מזהה לנקודת הקצה, ואי אפשר לעדכן אותו בהמשך.

  • ‫NETWORK_NAME: השם של הרשת שרוצים לפרוס בה, בפורמט projects//global/networks/.

  • ‫REGION: האזור ברשת.

  • ‫PSC_SUBNETS: רשת המשנה של Private Service Connect שבה רוצים להשתמש.

PROJECT=PROJECT
VPC_PROJECTS=VPC_PROJECTS
REGION=REGION
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json; charset=utf-8" "https://LOCATIONAL_ENDPOINT.googleapis.com/v1/projects/PROJECT_NUMBER/locations/REGION/indexEndpoints/INDEX_ENDPOINT_ID:deployIndex"
-d '{
  "deployedIndex": {
    "id": "DEPLOYED_INDEX_ID",
    "index": "projects/PROJECT/locations/us-central1/indexes/INDEX_ID ",
    "displayName": "DISPLAY_NAME",
    "psc_automation_configs": [
      { "project_id": "PROJECT_1", "network": "NETWORK_NAME_1" },
      { "project_id": "PROJECT_2", "network": "NETWORK_NAME_2" },
      { "project_id": "PROJECT_N", "network": "NETWORK_NAME_N" }]
    }
}'

המסוף

כדי לפרוס את נקודת הקצה:

  1. לוחצים על הלחצן הבא כדי לעבור לחיפוש וקטורי ב Google Cloud מסוף. תוצג רשימה של האינדקסים הפעילים.

    מעבר אל חיפוש וקטורי

  2. לוחצים על הלחצן Deploy (פריסה) של נקודת הקצה של חיפוש וקטורי שרוצים לפרוס עם Private Service Connect. מופיעה החלונית הנפתחת Deploy index.

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

  4. לוחצים על Endpoint (נקודת קצה) ובוחרים את נקודת הקצה של האינדקס שאליה רוצים לפרוס.

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

עכשיו צריך להוסיף הגדרות אוטומציה של Private Service Connect. כדי לעשות את זה:

  1. בקטע PSC automation configs (הגדרות אוטומציה של PSC), לוחצים על Add new config (הוספת הגדרה חדשה).

  2. מזינים את השם של פרויקט ה-VPC שאליו רוצים להתחבר.

  3. מזינים את שם הרשת של פרויקט ה-VPC שאליו רוצים להתחבר. הפורמט הנדרש הוא projects/<project_number>/global/networks/<network_name>.

  4. אופציונלי: לוחצים על הוספת הגדרה חדשה וממשיכים להוסיף הגדרות אוטומציה של Private Service Connect.

  5. לסיום, לוחצים על פריסה.

מחיקת מדיניות של חיבור שירות

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

gcloud network-connectivity service-connection-policies delete --project=<vpc_project> –-region=<region> <policy_name>

מידע נוסף על מדיניות חיבור שירותים זמין במאמר הגדרת מדיניות חיבור שירותים.

פריסה עם חיבור ידני

פורסים את האינדקס ויוצרים כלל העברה בפרויקט ה-VPC.

פריסת האינדקס

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

gcloud

בדוגמה הזו נשתמש בפקודה gcloud ai index-endpoints deploy-index.

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

  • ‫INDEX_ENDPOINT_ID: המזהה של נקודת הקצה של האינדקס.
  • ‫DEPLOYED_INDEX_ID: מחרוזת שצוינה על ידי המשתמש כדי לזהות באופן ייחודי את האינדקס שנפרס. הוא צריך להתחיל באות ולהכיל רק אותיות, מספרים או קווים תחתונים. הנחיות לגבי הפורמט מופיעות במאמר DeployedIndex.id.
  • ‫DEPLOYED_INDEX_ENDPOINT_NAME: השם המוצג של נקודת הקצה של האינדקס שנפרס.
  • ‫INDEX_ID: מזהה האינדקס.
  • ‫LOCATION: האזור שבו משתמשים ב-Agent Platform.
  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .

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

‫Linux,‏ macOS או Cloud Shell

gcloud ai index-endpoints deploy-index INDEX_ENDPOINT_ID \
    --deployed-index-id=DEPLOYED_INDEX_ID \
    --display-name=DEPLOYED_INDEX_ENDPOINT_NAME \
    --index=INDEX_ID \
    --region=LOCATION \
    --project=PROJECT_ID

‏Windows (PowerShell)

gcloud ai index-endpoints deploy-index INDEX_ENDPOINT_ID `
    --deployed-index-id=DEPLOYED_INDEX_ID `
    --display-name=DEPLOYED_INDEX_ENDPOINT_NAME `
    --index=INDEX_ID `
    --region=LOCATION `
    --project=PROJECT_ID

Windows‏ (cmd.exe)

gcloud ai index-endpoints deploy-index INDEX_ENDPOINT_ID ^
    --deployed-index-id=DEPLOYED_INDEX_ID ^
    --display-name=DEPLOYED_INDEX_ENDPOINT_NAME ^
    --index=INDEX_ID ^
    --region=LOCATION ^
    --project=PROJECT_ID

REST

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

  • ‫INDEX_ENDPOINT_ID: המזהה של נקודת הקצה של האינדקס.
  • ‫DEPLOYED_INDEX_ID: מחרוזת שצוינה על ידי המשתמש כדי לזהות באופן ייחודי את האינדקס שנפרס. הוא צריך להתחיל באות ולהכיל רק אותיות, מספרים או קווים תחתונים. הנחיות לגבי הפורמט מופיעות במאמר DeployedIndex.id.
  • ‫DEPLOYED_INDEX_ENDPOINT_NAME: השם המוצג של נקודת הקצה של האינדקס שנפרס.
  • ‫INDEX_ID: מזהה האינדקס.
  • ‫LOCATION: האזור שבו משתמשים ב-Agent Platform.
  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫PROJECT_NUMBER: מספר הפרויקט שנוצר באופן אוטומטי.

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

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID:deployIndex

תוכן בקשת JSON:

{
 "deployedIndex": {
   "id": "DEPLOYED_INDEX_ID",
   "index": "projects/PROJECT_ID/locations/LOCATION/indexes/INDEX_ID",
   "displayName": "DEPLOYED_INDEX_ENDPOINT_NAME"
 }
}

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

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

{
 "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID/operations/OPERATION_ID",
 "metadata": {
   "@type": "type.googleapis.com/google.cloud.aiplatform.v1.DeployIndexOperationMetadata",
   "genericMetadata": {
     "createTime": "2022-10-19T17:53:16.502088Z",
     "updateTime": "2022-10-19T17:53:16.502088Z"
   },
   "deployedIndexId": "DEPLOYED_INDEX_ID"
 }
}

Terraform

בדוגמה הבאה נעשה שימוש במשאב vertex_ai_index_endpoint_deployed_index Terraform כדי ליצור נקודת קצה של אינדקס שנפרס.

כדי ללמוד איך להחיל הגדרות ב-Terraform או להסיר אותן, ראו פקודות בסיסיות ב-Terraform.

provider "google" {
  region = "us-central1"
}

resource "google_vertex_ai_index_endpoint_deployed_index" "default" {
  depends_on        = [google_vertex_ai_index_endpoint.default]
  index_endpoint    = google_vertex_ai_index_endpoint.default.id
  index             = google_vertex_ai_index.default.id
  deployed_index_id = "deployed_index_for_psc"
}

resource "google_vertex_ai_index_endpoint" "default" {
  display_name = "sample-endpoint"
  description  = "A sample index endpoint with Private Service Connect enabled"
  region       = "us-central1"
  private_service_connect_config {
    enable_private_service_connect = true
    project_allowlist = [
      data.google_project.project.project_id,
    ]
  }
}

data "google_project" "project" {}

# Cloud Storage bucket name must be unique
resource "random_id" "default" {
  byte_length = 8
}

# Create a Cloud Storage bucket
resource "google_storage_bucket" "bucket" {
  name                        = "vertex-ai-index-bucket-${random_id.default.hex}"
  location                    = "us-central1"
  uniform_bucket_level_access = true
}

# Create index content
resource "google_storage_bucket_object" "data" {
  name    = "contents/data.json"
  bucket  = google_storage_bucket.bucket.name
  content = <<EOF
{"id": "42", "embedding": [0.5, 1.0], "restricts": [{"namespace": "class", "allow": ["cat", "pet"]},{"namespace": "category", "allow": ["feline"]}]}
{"id": "43", "embedding": [0.6, 1.0], "restricts": [{"namespace": "class", "allow": ["dog", "pet"]},{"namespace": "category", "allow": ["canine"]}]}
EOF
}

resource "google_vertex_ai_index" "default" {
  region       = "us-central1"
  display_name = "sample-index-batch-update"
  description  = "A sample index for batch update"
  labels = {
    foo = "bar"
  }

  metadata {
    contents_delta_uri = "gs://${google_storage_bucket.bucket.name}/contents"
    config {
      dimensions                  = 2
      approximate_neighbors_count = 150
      distance_measure_type       = "DOT_PRODUCT_DISTANCE"
      algorithm_config {
        tree_ah_config {
          leaf_node_embedding_count    = 500
          leaf_nodes_to_search_percent = 7
        }
      }
    }
  }
  index_update_method = "BATCH_UPDATE"

  timeouts {
    create = "2h"
    update = "1h"
  }
}

Python

במאמר התקנת Vertex AI SDK ל-Python מוסבר איך להתקין או לעדכן את Vertex AI SDK ל-Python. מידע נוסף מופיע ב מאמרי העזרה של Python API.

def vector_search_deploy_index(
    project: str,
    location: str,
    index_name: str,
    index_endpoint_name: str,
    deployed_index_id: str,
) -> None:
    """Deploy a vector search index to a vector search index endpoint.

    Args:
        project (str): Required. Project ID
        location (str): Required. The region name
        index_name (str): Required. The index to update. A fully-qualified index
          resource name or a index ID.  Example:
          "projects/123/locations/us-central1/indexes/my_index_id" or
          "my_index_id".
        index_endpoint_name (str): Required. Index endpoint to deploy the index
          to.
        deployed_index_id (str): Required. The user specified ID of the
          DeployedIndex.
    """
    # Initialize the Vertex AI client
    aiplatform.init(project=project, location=location)

    # Create the index instance from an existing index
    index = aiplatform.MatchingEngineIndex(index_name=index_name)

    # Create the index endpoint instance from an existing endpoint.
    index_endpoint = aiplatform.MatchingEngineIndexEndpoint(
        index_endpoint_name=index_endpoint_name
    )

    # Deploy Index to Endpoint
    index_endpoint = index_endpoint.deploy_index(
        index=index, deployed_index_id=deployed_index_id
    )

    print(index_endpoint.deployed_indexes)

המסוף

כדי לפרוס את האינדקס, צריך לפעול לפי ההוראות הבאות.

  1. בקטע Agent Platform במסוף Google Cloud , עוברים לקטע Deploy and Use. בוחרים באפשרות חיפוש וקטורי.

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

  2. בוחרים את שם האינדקס שרוצים לפרוס. ייפתח דף הפרטים של האינדקס.
  3. בדף פרטי האינדקס, לוחצים על Deploy to endpoint (פריסה לנקודת קצה). החלונית של פריסת האינדקס תיפתח.
  4. מזינים שם לתצוגה – השם הזה משמש כמזהה ואי אפשר לעדכן אותו.
  5. בתפריט הנפתח Endpoint (נקודת קצה), בוחרים את נקודת הקצה שאליה רוצים לפרוס את האינדקס הזה. הערה: נקודת הקצה לא זמינה אם האינדקס כבר נפרס בה.
  6. אופציונלי: בשדה סוג המכונה, בוחרים באפשרות 'רגיל' או 'זיכרון גבוה'.
  7. זה שינוי אופציונלי. בוחרים באפשרות הפעלת התאמה אוטומטית לעומס כדי לשנות באופן אוטומטי את גודל מספר הצמתים בהתאם לדרישות של עומסי העבודה. מספר הרפליקות שמוגדר כברירת מחדל הוא 2 אם ההתאמה האוטומטית של קנה המידה מושבתת.
  8. לוחצים על Deploy (פריסה) כדי לפרוס את האינדקס לנקודת הקצה. הערה: תהליך הפריסה נמשך כ-30 דקות.

יצירת כלל העברה בפרויקט VPC

אחרי פריסת האינדקס, נקודת הקצה של האינדקס מחזירה URI של קובץ מצורף לשירות במקום כתובת IP. צריך ליצור כתובת Compute וגם כלל העברה בפרויקט ה-VPC שמטרגט את קובץ השירות באמצעות כתובת ה-Compute שנוצרה. כדי ליצור כתובת מחשוב, משתמשים בדוגמה הבאה:

gcloud compute addresses create ${ADDRESS_NAME:?} \
    --region=${REGION:?} \
    --subnet=${SUBNET_NAME:?} \
    --project=${VPC_PROJECT:?}

כדי ליצור כלל העברה שמכוון ל-URI של קובץ השירות באמצעות כתובת ה-Compute שנוצרה, משתמשים בדוגמה הבאה:

SERVICE_ATTACHMENT_URI=`gcloud ai index-endpoints describe {INDEX_ENDPOINT_ID}
--format="value(deployedIndexes.privateEndpoints.serviceAttachment)"`

gcloud compute forwarding-rules create ${ENDPOINT_NAME:?} \
    --network=${NETWORK_NAME:?} \
    --address=${ADDRESS_NAME:?} \
    --target-service-attachment=${SERVICE_ATTACHMENT_URI:?} \
    --project=${VPC_PROJECT:?} \
    --region=${REGION:?}

(אופציונלי) יצירת רשומת DNS לכתובת ה-IP

אם רוצים להתחבר ולטעון בלי לזכור את כתובת ה-IP בפועל, אפשר ליצור רשומת DNS. השלב הזה הוא אופציונלי.

DNS_NAME_SUFFIX=matchingengine.vertexai.goog. # Don't forget the "." in the end.
DNS_NAME=${INDEX_ENDPOINT_ID:?}.${REGION:?}.${DNS_NAME_SUFFIX:?}

gcloud dns managed-zones create ${DNS_ZONE_NAME:?} \
    --dns-name=${DNS_NAME_SUFFIX:?} \
    --visibility=private \
    --project=${VPC_PROJECT:?} \
    --region=${REGION:?}

gcloud dns record-sets create ${DNS_NAME:?} \
    --rrdatas=${IP_ADDRESS:?} \
    --type=A --ttl=60 \
    --zone=${DNS_ZONE_NAME:?} \
    --project=${VPC_PROJECT:?} \
    --region=${REGION:?}

שליחת שאילתות לנקודת הקצה של האינדקס

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

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

המאמרים הבאים