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

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

החלפת אינדקס שלם

כדי להחליף את התוכן של עדכון קיים בסטרימינג או בחבילת עדכונים של Index, משתמשים ב-method‏ IndexService.UpdateIndex.

  • מגדירים את Index.metadata.contentsDeltaUri ל-URI של Cloud Storage שכולל את הווקטורים שרוצים לעדכן.
  • מגדירים את Index.metadata.isCompleteOverwrite לערך true. אם הערך הוא true, כל האינדקס מוחלף לחלוטין בקובץ המטא-נתונים החדש שאתם מספקים.

gcloud

  1. מעדכנים את קובץ המטא-נתונים של האינדקס כדי להגדיר את contentsDeltaUri ו-isCompleteOverwrite=true.
  2. משתמשים בפקודה gcloud ai indexes update.

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

  • ‫LOCAL_PATH_TO_METADATA_FILE: הנתיב המקומי לקובץ המטא-נתונים.
  • ‫INDEX_ID: מזהה האינדקס.
  • ‫LOCATION: האזור שבו אתם משתמשים ב-Agent Platform.
  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .

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

‫Linux,‏ macOS או Cloud Shell

gcloud ai indexes update INDEX_ID \
    --metadata-file=LOCAL_PATH_TO_METADATA_FILE \
    --region=LOCATION \
    --project=PROJECT_ID

‏Windows (PowerShell)

gcloud ai indexes update INDEX_ID `
    --metadata-file=LOCAL_PATH_TO_METADATA_FILE `
    --region=LOCATION `
    --project=PROJECT_ID

Windows‏ (cmd.exe)

gcloud ai indexes update INDEX_ID ^
    --metadata-file=LOCAL_PATH_TO_METADATA_FILE ^
    --region=LOCATION ^
    --project=PROJECT_ID

REST

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

  • ‫INPUT_DIR: הנתיב לספרייה ב-Cloud Storage של תוכן האינדקס.
  • ‫INDEX_ID: מזהה האינדקס.
  • ‫LOCATION: האזור שבו אתם משתמשים ב-Agent Platform.
  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫PROJECT_NUMBER: מספר הפרויקט שנוצר באופן אוטומטי.

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

PATCH https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexes/INDEX_ID

תוכן בקשת JSON: 

{
 "metadata": {
   "contentsDeltaUri": "INPUT_DIR",
   "isCompleteOverwrite": true
 }
}

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

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

{
 "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID/operations/OPERATION_ID",
 "metadata": {
   "@type": "type.googleapis.com/google.cloud.aiplatform.v1.UpdateIndexOperationMetadata",
   "genericMetadata": {
     "createTime": "2022-01-12T23:56:14.480948Z",
     "updateTime": "2022-01-12T23:56:14.480948Z"
   }
 }
}

Python

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

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

def vector_search_update_index_embeddings(
    project: str,
    location: str,
    index_name: str,
    gcs_uri: str,
    is_complete_overwrite: Optional[bool] = None,
) -> None:
    """Update a vector search index.

    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".
        gcs_uri (str): Required. The Google Cloud Storage uri for index content
        is_complete_overwrite (bool): Optional. If true, the index content will
          be overwritten wth the contents at gcs_uri.
    """
    # 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)

    index.update_embeddings(
        contents_delta_uri=gcs_uri, is_complete_overwrite=is_complete_overwrite
    )

המסוף

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

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

    כניסה לדף Vector Search

  2. בוחרים את האינדקס שרוצים לעדכן. הדף Index info נפתח.
  3. לוחצים על עריכת האינדקס. נפתחת חלונית לעריכת האינדקס.
  4. בשדה Cloud Storage, מחפשים ובוחרים את התיקייה ב-Cloud Storage שבה מאוחסנים נתוני הווקטורים.
  5. כדי להחליף את כל הנתונים הקיימים, מסמנים את התיבה "החלפה מלאה".
  6. לוחצים על עדכון.
  7. לוחצים על סיום כדי לסגור את החלונית.

עדכון חלקי של אינדקס אצווה

כדי לעדכן את ההטמעות של אצווה קיימת של Index, משתמשים ב-method‏ IndexService.UpdateIndex.

  • מגדירים את Index.metadata.contentsDeltaUri ל-URI של Cloud Storage שכולל את הווקטורים שרוצים לעדכן.
  • מגדירים את Index.metadata.isCompleteOverwrite לערך false.

רק הווקטורים שצוינו ב-Index.metadata.contentsDeltaUri מתעדכנים, מתווספים או נמחקים. שאר ההטמעות הקיימות באינדקס נשארות.

gcloud

  1. מעדכנים את קובץ המטא-נתונים של האינדקס כדי להגדיר את contentsDeltaUri.
  2. משתמשים בפקודה gcloud ai indexes update.

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

  • ‫LOCAL_PATH_TO_METADATA_FILE: הנתיב המקומי לקובץ המטא-נתונים.
  • ‫INDEX_ID: מזהה האינדקס.
  • ‫LOCATION: האזור שבו אתם משתמשים ב-Agent Platform.
  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .

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

‫Linux,‏ macOS או Cloud Shell

gcloud ai indexes update INDEX_ID \
    --metadata-file=LOCAL_PATH_TO_METADATA_FILE \
    --region=LOCATION \
    --project=PROJECT_ID

‏Windows (PowerShell)

gcloud ai indexes update INDEX_ID `
    --metadata-file=LOCAL_PATH_TO_METADATA_FILE `
    --region=LOCATION `
    --project=PROJECT_ID

Windows‏ (cmd.exe)

gcloud ai indexes update INDEX_ID ^
    --metadata-file=LOCAL_PATH_TO_METADATA_FILE ^
    --region=LOCATION ^
    --project=PROJECT_ID

REST

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

  • ‫INPUT_DIR: הנתיב לספרייה ב-Cloud Storage של תוכן האינדקס.
  • ‫INDEX_ID: מזהה האינדקס.
  • ‫LOCATION: האזור שבו אתם משתמשים ב-Agent Platform.
  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫PROJECT_NUMBER: מספר הפרויקט שנוצר באופן אוטומטי.

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

PATCH https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexes/INDEX_ID

תוכן בקשת JSON: 

{
 "metadata": {
   "contentsDeltaUri": "INPUT_DIR",
   "isCompleteOverwrite": false
 }
}

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

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

{
 "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID/operations/OPERATION_ID",
 "metadata": {
   "@type": "type.googleapis.com/google.cloud.aiplatform.v1.UpdateIndexOperationMetadata",
   "genericMetadata": {
     "createTime": "2022-01-12T23:56:14.480948Z",
     "updateTime": "2022-01-12T23:56:14.480948Z"
   }
 }
}

Python

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

כשמפעילים את השיטה שבהמשך, צריך להגדיר את is_complete_overwrite=False.

def vector_search_update_index_embeddings(
    project: str,
    location: str,
    index_name: str,
    gcs_uri: str,
    is_complete_overwrite: Optional[bool] = None,
) -> None:
    """Update a vector search index.

    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".
        gcs_uri (str): Required. The Google Cloud Storage uri for index content
        is_complete_overwrite (bool): Optional. If true, the index content will
          be overwritten wth the contents at gcs_uri.
    """
    # 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)

    index.update_embeddings(
        contents_delta_uri=gcs_uri, is_complete_overwrite=is_complete_overwrite
    )

המסוף

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

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

    כניסה לדף Vector Search

  2. בוחרים את האינדקס שרוצים לעדכן. הדף Index info נפתח.
  3. לוחצים על עריכת האינדקס. נפתחת חלונית לעריכת האינדקס.
  4. בשדה Cloud Storage, מחפשים ובוחרים את התיקייה ב-Cloud Storage שבה מאוחסנים נתוני הווקטורים.
  5. מוודאים שהתיבה "החלפה מלאה" לא מסומנת.
  6. לוחצים על עדכון.
  7. לוחצים על סיום כדי לסגור את החלונית.

אם ל-Index יש פריסות משויכות (ראו את השדה Index.deployed_indexes), כשמבצעים שינויים מסוימים ב-Index המקורי, ה-DeployedIndex מתעדכן באופן אוטומטי ואסינכרוני ברקע כדי לשקף את השינויים האלה.

כדי לבדוק אם השינוי הופץ, משווים בין זמן הסיום של פעולת האינדקס של העדכון לבין DeployedIndex.index_sync_time.

עדכון חלקי של אינדקס סטרימינג

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

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

עדכון או הוספה (upsert) של נקודות נתונים

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

Python

Python

def vector_search_upsert_datapoints(
    project: str,
    location: str,
    index_name: str,
    datapoints: Sequence[aiplatform.compat.types.index_v1beta1.IndexDatapoint],
) -> None:
    """Upsert datapoints to the index.

    Args:
      project (str): Required. The Project ID
      location (str): Required. The region name, e.g. "us-central1"
      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".
      datapoints: Sequence[IndexDatapoint]: Required. The datapoints to be
        updated. For example:
        [IndexDatapoint(datapoint_id="1", feature_vector=[1.0, 2.0, 3.0]),
        IndexDatapoint(datapoint_id="2", feature_vector=[4.0, 5.0, 6.0])]
    """
    # Initialize the Vertex AI client
    aiplatform.init(project=project, location=location)

    # Create the index instance from an existing index with stream_update
    # enabled
    my_index = aiplatform.MatchingEngineIndex(index_name=index_name)

    # Upsert the datapoints to the index
    my_index.upsert_datapoints(datapoints=datapoints)

Curl

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

  
  DATAPOINT_ID_1=
  DATAPOINT_ID_2=
  curl -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`" https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/indexes/${INDEX_ID}:upsertDatapoints \
  -d '{datapoints: [{datapoint_id: "'${DATAPOINT_ID_1}'", feature_vector: [...]},
  {datapoint_id: "'${DATAPOINT_ID_2}'", feature_vector: [...]}]}'

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

בדוגמה הזו מתעדכנות גם הטמעות צפופות וגם הטמעות דלילות.

  
    curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`"  https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/indexes/${INDEX_ID}:upsertDatapoints -d '{datapoints: [{datapoint_id: "111", feature_vector: [0.111, 0.111], "sparse_embedding": {"values": [111.0,111.1,111.2], "dimensions": [10,20,30]}}]}'

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

    
      curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`"  https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/indexes/${INDEX_ID}:upsertDatapoints -d '{datapoints: [{datapoint_id: "111", feature_vector: [0.111, 0.111]}]}'

בדוגמה הזו מעדכנים הטמעות דלילות ומסירים הטמעות צפופות.

    
      curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`"  https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/indexes/${INDEX_ID}:upsertDatapoints -d '{datapoints: [{datapoint_id: "111",  "sparse_embedding": {"values": [111.0,111.1,111.2], "dimensions": [10,20,30]}}]}'

המסוף

המסוף

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

  1. במסוף Google Cloud , נכנסים לדף חיפוש וקטורי.

    כניסה לדף Vector Search

  2. בוחרים את האינדקס שרוצים לעדכן. הדף Index info נפתח.
  3. לוחצים על עריכת האינדקס. נפתחת חלונית לעריכת האינדקס.
  4. כדי להוסיף תוכן, בוחרים בחלונית בכרטיסייה עדכון או הוספה (upsert) של נקודת נתונים.
  5. מזינים את המזהה של הנקודה על הגרף.
  6. מזינים לפחות סוג אחד של הטמעה:
    • הטמעה צפופה: מזינים מערך של ערכי נקודה צפה (floating point) שמופרדים בפסיקים. מספר הערכים חייב להתאים למאפייני האינדקס.
    • הטמעה דלילה:
      1. מזינים את המאפיינים של ההטמעה הדלילה כמערך של מספרים שלמים שמופרדים בפסיקים. מספר הערכים לא חייב להתאים למאפיינים של האינדקס.
      2. צריך להזין ערכים כמערך של ערכי נקודה צפה (floating point) שמופרדים בפסיקים. מספר הערכים צריך להיות זהה למספר המאפיינים של ההטמעה הדלילה.
  7. אופציונלי: כדי להפעיל סינון לפי הגבלות טוקן בנקודה הזו על הגרף, לוחצים על הוספת הגבלת טוקן, ואז מזינים מרחב שמות ומחרוזות מופרדות בפסיקים בתור טוקנים.
  8. אופציונלי: כדי להפעיל סינון לפי הגבלות מספריות בנקודה הזו על הגרף, לוחצים על הוספת הגבלה מספרית, מזינים מרחב שמות, בוחרים סוג מספר ומזינים ערך.
  9. אופציונלי: כדי למנוע הצגה של הרבה תוצאות דומות, מזינים מחרוזת של תג ריווח.
  10. לוחצים על עדכון או הוספה (upsert).
  11. לוחצים על סיום כדי לסגור את החלונית.

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

עדכון המטא-נתונים של ההטמעה

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

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

כדי לבצע את העדכונים האלה של המטא-נתונים בלבד, צריך להוסיף לבקשה את השדה update_mask. הערך של update_mask חייב להיות all_restricts. הערכים של restrict ו-numeric restrict שמוגדרים בנקודות על הגרף צריכים להיות הערכים החדשים שרוצים להחיל בעדכון.

בדוגמה הבאה אפשר לראות איך מוסיפים הגבלות לשתי נקודות קיימות על הגרף.

DATAPOINT_ID_1=
DATAPOINT_ID_2=

curl -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`" https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/indexes/${INDEX_ID}:upsertDatapoints \
-d '{datapoints:
[{datapoint_id: "'${DATAPOINT_ID_1}'", feature_vector: [...],  restricts:[{namespace: "color", allow_list: ["red"]}]},
{datapoint_id: "'${DATAPOINT_ID_2}'", feature_vector: [...],  restricts:[{namespace: "color", allow_list: ["red"]}]}
], update_mask: "all_restricts"}'

הסרת נקודות על הגרף

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

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

Curl


curl -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`" https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{REGION}/indexes/{INDEX_ID}:removeDatapoints -d '{datapoint_ids: ["'{DATAPOINT_ID_1}'", "'{DATAPOINT_ID_2}'"]}'

המסוף

המסוף

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

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

    כניסה לדף Vector Search

  2. בוחרים את אינדקס הסטרימינג שרוצים לעדכן. הדף Index info נפתח.
  3. לוחצים על עריכת האינדקס. נפתחת חלונית לעריכת האינדקס.
  4. בחלונית, לוחצים על הכרטיסייה הסרת נקודות על הגרף.
  5. אפשר להוסיף עד 20 נקודות על הגרף. כדי לעשות את זה, צריך להזין רשימה של מזהי נקודות על הגרף שמופרדים בפסיקים.
  6. לוחצים על הסרה.
  7. לוחצים על סיום כדי לסגור את החלונית.

Python

Python

def vector_search_remove_datapoints(
    project: str,
    location: str,
    index_name: str,
    datapoint_ids: Sequence[str],
) -> None:
    """Remove datapoints from a vector search index.

    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".
        datapoint_ids (Sequence[str]): Required. The datapoint IDs to remove.
    """
    # 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)

    index.remove_datapoints(datapoint_ids=datapoint_ids)

עדכון המטא-נתונים של האינדקס

אפשר להשתמש ב-IndexService.UpdateIndex גם כדי לעדכן את שדות המטא-נתונים display_name,‏ description ו-labels באינדקסים של אצווה וסטרימינג. שימו לב שקריאה אחת ל-UpdateIndex יכולה לעדכן את הטמעות האינדקס או את שדות המטא-נתונים האלה, אבל לא את שניהם בו-זמנית.

gcloud

  1. עדכון קובץ המטא-נתונים של האינדקס.
  2. משתמשים בפקודה gcloud ai indexes update.

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

  • ‫LOCAL_PATH_TO_METADATA_FILE: הנתיב המקומי לקובץ המטא-נתונים.
  • ‫INDEX_ID: מזהה האינדקס.
  • ‫LOCATION: האזור שבו אתם משתמשים ב-Agent Platform.
  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .

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

‫Linux,‏ macOS או Cloud Shell

gcloud ai indexes update INDEX_ID \
    --metadata-file=LOCAL_PATH_TO_METADATA_FILE \
    --region=LOCATION \
    --project=PROJECT_ID

‏Windows (PowerShell)

gcloud ai indexes update INDEX_ID `
    --metadata-file=LOCAL_PATH_TO_METADATA_FILE `
    --region=LOCATION `
    --project=PROJECT_ID

Windows‏ (cmd.exe)

gcloud ai indexes update INDEX_ID ^
    --metadata-file=LOCAL_PATH_TO_METADATA_FILE ^
    --region=LOCATION ^
    --project=PROJECT_ID

REST

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

  • ‫INPUT_DIR: הנתיב לספרייה ב-Cloud Storage של תוכן האינדקס.
  • ‫INDEX_ID: מזהה האינדקס.
  • ‫LOCATION: האזור שבו אתם משתמשים ב-Agent Platform.
  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫PROJECT_NUMBER: מספר הפרויקט שנוצר באופן אוטומטי.

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

PATCH https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexes/INDEX_ID

תוכן בקשת JSON: 

{
 "metadata": {
   "description": "Updated description",
   "display_name": "Updated display name"
 }
}

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

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

{
 "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID/operations/OPERATION_ID",
 "metadata": {
   "@type": "type.googleapis.com/google.cloud.aiplatform.v1.UpdateIndexOperationMetadata",
   "genericMetadata": {
     "createTime": "2022-01-12T23:56:14.480948Z",
     "updateTime": "2022-01-12T23:56:14.480948Z"
   }
 }
}

Python

def vector_search_update_index_metadata(
    project: str,
    location: str,
    index_name: str,
    display_name: Optional[str] = None,
    description: Optional[str] = None,
    labels: Optional[Dict[str, str]] = None,
) -> None:
    """Update a vector search index.

    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".
        display_name (str): Optional. The display name of the Index. The name
          can be up to 128 characters long and can be consist of any UTF-8
          characters.
        description (str): Optional. The description of the Index.
        labels (Dict[str, str]): Optional. The labels with user-defined
          metadata to organize your Indexs. Label keys and values can be no
          longer than 64 characters (Unicode codepoints), can only contain
          lowercase letters, numeric characters, underscores and dashes.
          International characters are allowed. See https://goo.gl/xmQnxf for
          more information on and examples of labels. No more than 64 user
          labels can be associated with one Index (System labels are excluded).
          System reserved label keys are prefixed with
          "aiplatform.googleapis.com/" and are immutable.
    """
    # 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)

    index.update_metadata(
        display_name=display_name,
        description=description,
        labels=labels,
    )

המסוף

אתם יכולים להשתמש בהוראות האלה כדי לעדכן את המטא-נתונים של האינדקס (במסוף אפשר לעדכן רק את display_name ו-description).

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

    כניסה לדף Vector Search

  2. בוחרים את האינדקס שרוצים לעדכן. הדף Index info נפתח.
  3. לוחצים על עריכת האינדקס. נפתחת חלונית לעריכת האינדקס.
  4. מעדכנים את שדות המטא-נתונים הרצויים.
  5. לוחצים על עדכון.
  6. לוחצים על סיום כדי לסגור את החלונית.

דחיסה

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

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

  • עדכון באצווה: מתרחש כשגודל קבוצת הנתונים המצטברת הוא > 20% מגודל קבוצת הנתונים הבסיסית.

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

אתם יכולים לשלוח בקשות התאמה או בקשות התאמה באצווה כרגיל באמצעות ה-CLI של gRPC, ספריית הלקוח או ה-SDK של Agent Platform ל-Python. כשמריצים מחדש את השאילתה, העדכונים אמורים להופיע תוך כמה שניות. במאמר שליחת שאילתות לאינדקסים כדי לקבל את השכנים הקרובים ביותר מוסבר איך שולחים שאילתות לאינדקס.

שדות אופציונליים

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

עדכון או הוספה (upsert) עם הגבלות

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

בנוסף להגבלות על טוקנים, בדוגמה נעשה שימוש בהגבלות מספריות. במקרה הזה, נקודת הנתונים משויכת למחיר של 20, לאורך של 0.3 ולרוחב של 0.5. בזמן השאילתה, אתם יכולים להשתמש בהגבלות המספריות האלה כדי לסנן את התוצאות ולהגביל את תוצאות השאילתה לפי ערכי המחיר, האורך והרוחב. לדוגמה, נקודת הנתונים הזו תופיע בשאילתה שמסננת לפי מחיר > 25, אורך < 1 ורוחב < 1.

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

Python 

# Upsert datapoints
_TEST_DATAPOINT_1 = aiplatform_v1.types.index.IndexDatapoint(
    datapoint_id="3",
    feature_vector=[0.00526886899, -0.0198396724],
    restricts=[
        aiplatform_v1.types.index.IndexDatapoint.Restriction(namespace="Color", allow_list=["red"])
    ],
    numeric_restricts=[
        aiplatform_v1.types.index.IndexDatapoint.NumericRestriction(
            namespace="cost",
            value_int=1,
        )
    ],
)
_TEST_DATAPOINT_2 =  aiplatform_v1.types.index.IndexDatapoint(
    datapoint_id="4",
    feature_vector=[0.00526886899, -0.0198396724],
    numeric_restricts=[
        aiplatform_v1.types.index.IndexDatapoint.NumericRestriction(
            namespace="cost",
            value_double=0.1,
        )
    ],
    crowding_tag=aiplatform_v1.types.index.IndexDatapoint.CrowdingTag(crowding_attribute="crowding"),
)
_TEST_DATAPOINT_3 = aiplatform_v1.types.index.IndexDatapoint(
    datapoint_id="5",
    feature_vector=[0.00526886899, -0.0198396724],
    numeric_restricts=[
        aiplatform_v1.types.index.IndexDatapoint.NumericRestriction(
            namespace="cost",
            value_float=1.1,
        )
    ],
)

_TEST_DATAPOINTS = [_TEST_DATAPOINT_1, _TEST_DATAPOINT_2, _TEST_DATAPOINT_3]

my_streaming_index = my_streaming_index.upsert_datapoints(datapoints=_TEST_DATAPOINTS)

# Dynamic metadata update
_TEST_DATAPOINT_4 = aiplatform_v1.types.index.IndexDatapoint(
    datapoint_id="-2",
    numeric_restricts=[
        aiplatform_v1.types.index.IndexDatapoint.NumericRestriction(
            namespace="cost",
            value_float=1.1,
        )
    ],
)
my_streaming_index = my_streaming_index.upsert_datapoints(datapoints=[_TEST_DATAPOINT4], update_mask=["all_restricts"])

curl 

curl -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`" https://${ENDPOINT}/v1/projects/${PROJECT_ID}/locations/us-central1/indexes/${INDEX_ID}:upsertDatapoints \
-d '{
datapoints: [
  {
    datapoint_id: "'${DATAPOINT_ID_1}'",
    feature_vector: [...],
    restricts: { namespace: "color", allow_list: ["red"], deny_list: ["blue"]},
    numeric_restricts: [{namespace: "price", value_int: 20}, {namespace: "length", value_float: 0.3}, {namespace: "width", value_double: 0.5}]
  }
]}'

עדכון או הוספה (upsert) עם צפיפות

תג הריווח מגביל את התוצאות הדומות על ידי שיפור הגיוון בתוצאות. צפיפות היא אילוץ על רשימת שכנים שנוצרת על ידי חיפוש השכן הקרוב ביותר, שדורש שלא יותר מערך מסוים, מתוך קבוצת תוצאות, יחזיר את אותו ערך של crowding_attribute. לדוגמה, נניח שחזרתם לקנות נעליים באינטרנט. אתם רוצים לראות מגוון רחב של צבעים בתוצאות, אבל אולי בסגנון אחד, כמו נעלי כדורגל. אתם יכולים לבקש שיוחזרו לא יותר מ-3 זוגות נעליים באותו צבע, על ידי הגדרת per_crowding_attribute_num_neighbors = 3 בשאילתה, בהנחה שהגדרתם את crowding_attribute לצבע הנעליים כשאתם מוסיפים את הנקודה על הגרף.

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

curl -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`" https://${ENDPOINT}/v1/projects/${PROJECT_ID}/locations/us-central1/indexes/${INDEX_ID}:upsertDatapoints \
-d '{
datapoints: [
  {
    datapoint_id: "'${DATAPOINT_ID_1}'",
    feature_vector: [...],
    restricts: { namespace: "type", allow_list: ["cleats"]}
    crowding_tag: { crowding_attribute: "red-shoe"},
  }
]}'

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