ניהול העשרת אובייקטים

תצוגה מקדימה

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

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

בדף הזה מוסבר איך לבדוק מטא-נתונים בסיסיים של הקשר, לאחזר מטען ייעודי (payload) של נתונים מורחבים, למחוק העשרות מאובייקטים ולעקוב אחרי התקדמות העיבוד ב-Cloud Monitoring.

קבלת התפקידים הנדרשים

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

• צפייה במטא-נתונים של העשרת אובייקטים בסיסיים: צפייה באובייקטים באחסון (roles/storage.objectViewer)
• אחזור נתונים מורחבים של העשרת אובייקטים: Storage Object User (roles/storage.objectUser)
• ביטול העשרות של אובייקטים במהלך שכתוב אובייקטים: אדמין של אובייקטים באחסון (roles/storage.objectAdmin)

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

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

ההרשאות הנדרשות

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

• הצגת מטא-נתונים בסיסיים של הקשר העשרת אובייקטים: storage.objects.get
• אחזור נתונים מורחבים של העשרת אובייקטים: storage.objects.viewFullContext
• מחיקת העשרת אובייקטים במהלך כתיבה מחדש של אובייקטים:
  • storage.objects.get
  • storage.objects.create
  • storage.objects.delete
  • storage.objects.update

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

צפייה בהעשרת אובייקטים

‫Cloud Storage מצרף מטא-נתונים של העשרה ישירות לאובייקטים שלכם כהקשרים של אובייקטים שמנוהלים על ידי Google, במסגרת המאפיין contexts.custom. כל מודל משתמש במפתח שמור עם הקידומת google:annotation: (לדוגמה, google:annotation:label-detector-v1 או google:annotation:face-detector-v1).

ב-Cloud Storage, נתוני ההעשרה מאורגנים בשתי רמות:

• מטא-נתונים של הקשר: מכילים את מפתח ההקשר, סטטוס הפעלת המודל (value), חותמות זמן וכתובת ה-URL של סוג ה-protobuf. פעולות על אובייקט רגיל describe ו-get מחזירות את המטא-נתונים האלה.
• נתונים מורחבים (תצוגה מקדימה): מכילים את המטען הייעודי (payload) המלא של ההעשרה המובנית ב-JSON (עד 128KiB). המטען הייעודי (payload) הזה כולל פרטים כמו קואורדינטות של מצולע תחום, ציוני מהימנות של סיווג, הבעות פנים ודירוגי בטיחות.

הצגת מטא-נתונים בסיסיים של ההקשר

כדי לבדוק אילו מודלים עיבדו אובייקט ולראות מטא-נתונים בסיסיים של הקשר, משתמשים במסוף Google Cloud או ב-API בפורמט JSON:

המסוף

1. במסוף Google Cloud , נכנסים לדף Buckets של Cloud Storage.
   

   כניסה לדף Buckets

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

   בטבלה Objects, בעמודה Custom contexts מוצג צ'יפ לכל מודל שעיבד אובייקט (Content Safety,‏ Face Detector,‏ Label Detector,‏ Object Detector או PDF Classification).

3. כדי לבדוק אובייקט ספציפי, לוחצים על שם האובייקט.

4. בדף Object details, עוברים לשדה Custom contexts. אם בשדה יש כמה צ'יפים, לוחצים על כדי להרחיב את השורה.

5. כדי לראות את המטא-נתונים של ההקשר הבסיסי של המודל, מעבירים את העכבר מעל הצ'יפ של המודל או לוחצים עליו:

   • מפתח הקשר: מפתח המודל השמור, כמו google:annotation:label-detector-v1.
   • ערך ההקשר: סטטוס ההפעלה של המודל (SUCCESS או FAILURE).
   • זמן היצירה והזמן של השינוי האחרון: חותמות הזמן שבהן Cloud Storage יצר את ההעשרה ועדכן אותה בפעם האחרונה.
   • הצגת מרכז ההגדרות: פותח את הדף Object enrichments (העשרת אובייקטים). כשמציגים צ'יפ מהטבלה Objects של הקטגוריה, אפשר גם ללחוץ על Filter contexts כדי לסנן את האובייקטים בקטגוריה לפי ההקשר הזה.

‫API בפורמט JSON

1. התקנה והפעלה של ה-CLI של gcloud, שמאפשרות ליצור אסימון גישה לכותרת Authorization.

2. משתמשים ב-cURL כדי לשלוח בקשת Objects: get עם פרמטר השאילתה projection=full אל ה-API בפורמט JSON:

   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Accept: application/json" \
     "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?projection=full"

   כאשר:

   • ‫BUCKET_NAME הוא שם הקטגוריה המכילה את האובייקט. לדוגמה, my-bucket.
   • ‫OBJECT_NAME הוא שם האובייקט עם קידוד כתובת URL. לדוגמה, image.jpg.

   התשובה מחזירה את המבנה contexts.custom:

   {
     "kind": "storage#object",
     "id": "my-bucket/image.jpg/1700000000000000",
     "name": "image.jpg",
     "bucket": "my-bucket",
     "contexts": {
       "custom": {
         "google:annotation:label-detector-v1": {
           "value": "SUCCESS",
           "createTime": "2026-09-29T17:20:00.000Z",
           "updateTime": "2026-09-29T17:20:00.000Z",
           "extendedDataTypeUrl": "type.googleapis.com/google.protobuf.Struct"
         }
       }
     }
   }
   

   השדה value מציין את סטטוס ההפעלה של המודל לאובייקט, למשל SUCCESS או FAILURE.

אחזור נתונים מורחבים

כדי לאחזר את הנתונים המובְנים המלאים של ההעשרה (כמו תיבות תוחמות, פוליגונים תוחמים, תוויות או פנים שזוהו), מפעילים את השיטה viewFullContext (תצוגה מקדימה) באמצעות ה-API בפורמט JSON.

1. התקנה והפעלה של ה-CLI של gcloud, שמאפשרות ליצור אסימון גישה לכותרת Authorization.

2. משתמשים ב-cURL כדי לשלוח בקשת viewFullContext אל API בפורמט JSON, ומציינים את מפתח ההקשר של המודל שרוצים לבדוק:

   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Accept: application/json" \
     "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME/viewFullContext?contextKey=CONTEXT_KEY"

   כאשר:

   • ‫BUCKET_NAME הוא שם הקטגוריה שמכילה את האובייקט. לדוגמה, my-bucket.
   • ‫OBJECT_NAME הוא שם האובייקט בקידוד כתובת URL. לדוגמה, image.jpg.
   • ‫CONTEXT_KEY הוא מפתח ההקשר של המודל. לדוגמה, google:annotation:label-detector-v1.

   התשובה מכילה את המבנה extendedData עם המטען הייעודי (payload) המלא של ההעשרה:

   {
     "kind": "storage#objectFullContext",
     "type": "CUSTOM",
     "key": "google:annotation:label-detector-v1",
     "value": "SUCCESS",
     "createTime": "2026-09-29T17:20:00.000Z",
     "updateTime": "2026-09-29T17:20:00.000Z",
     "extendedData": {
       "@type": "type.googleapis.com/google.protobuf.Struct",
       "modelName": "label-detector",
       "modelVersion": "v1",
       "labelAnnotationGroup": {
         "labelAnnotations": [
           {
             "description": "Night",
             "knowledgeGraphId": "/m/01d74z",
             "score": 0.92,
             "topicality": 0.19
           }
         ]
       }
     }
   }
   

במאמר סכימות ומודלים נתמכים מפורטים הסכימות והשדות של כל מודל בפורמט JSON.

ביטול העשרת אובייקטים

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

‫Google מנהלת את מפתחות ההקשר שמתחילים בקידומת google:, ולכן אי אפשר לשנות או למחוק אותם באמצעות שיטות רגילות לעדכון מטא-נתונים. במקום זאת, אתם יכולים למחוק אותם במהלך פעולת שכתוב, העתקה או יצירה של אובייקט, על ידי ציון הפרמטר dropContextGroups=custom, שמוחק את כל ההקשרים של האובייקט.

כדי למחוק הקשרי אובייקטים (כולל העשרת אובייקטים) כשמשכתבים אובייקט באמצעות ה-API בפורמט JSON:

1. להתקין ולהפעיל את ה-CLI של gcloud, כדי שתוכלו ליצור אסימון גישה לכותרת Authorization.

2. משתמשים ב-cURL כדי לשלוח קריאה ל-API בפורמט JSON באמצעות בקשת אובייקט POST לשכתוב ופרמטר השאילתה dropContextGroups=custom:

   curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Length: 0" \
     "https://storage.googleapis.com/storage/v1/b/SOURCE_BUCKET/o/SOURCE_OBJECT/rewriteTo/b/DESTINATION_BUCKET/o/DESTINATION_OBJECT?dropContextGroups=custom"

   כאשר:

   • ‫SOURCE_BUCKET הוא שם הקטגוריה שמכילה את אובייקט המקור. לדוגמה, my-source-bucket.
   • ‫SOURCE_OBJECT הוא השם בקידוד כתובת URL של אובייקט המקור. לדוגמה, image.jpg.
   • ‫DESTINATION_BUCKET הוא שם קטגוריית היעד (יכול להיות זהה לשם של קטגוריית המקור). לדוגמה, my-source-bucket.
   • ‫DESTINATION_OBJECT הוא השם של אובייקט היעד, בקידודי תווים שמתאימים לכתובת URL (יכול להיות זהה לאובייקט המקור). לדוגמה, image.jpg.

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

מעקב אחרי מדדי העשרת אובייקטים

אתם יכולים לעקוב אחרי קצב העיבוד של ההעשרה, האובייקטים בהמתנה ומספר ההפעלות של המודל באמצעות Cloud Monitoring. ‫Cloud Storage מייצא את המדדים הבאים במרחב השמות storage.googleapis.com במשאב במעקב gcs_bucket:

סוג המדד (עם הקידומת storage.googleapis.com/)	סוג	תיאור ותוויות
auto_annotate/operations/pending_objects	GAUGE, INT64	המספר הכולל של האובייקטים שממתינים להעשרה בקטגוריה. הדגימה מתבצעת כל 300 שניות.
auto_annotate/operations/processed_object_count	DELTA, INT64	המספר הכולל של האובייקטים שעברו עיבוד על ידי העשרות אובייקטים במהלך חלון הזמן. נדגם כל 300 שניות.
auto_annotate/operations/model_count	DELTA, INT64	המספר הכולל של המודלים שהופעלו בקטגוריה במהלך חלון הזמן, מקובצים לפי model_name, model_version ו-status (כמו SUCCESS או FAILURE).
auto_annotate/operations/request_count	DELTA, INT64	המספר הכולל של הקריאות ל-API שבוצעו במהלך חלון הזמן, מקובצות לפי method ו-response_code.
auto_annotate/storage/annotated_objects	GAUGE, INT64	תמונת מצב יומית של המספר הכולל של אובייקטים בקטגוריה שנוצרו להם העשרות, מקובצים לפי type ו-data_locations.
auto_annotate/storage/model_outputs	GAUGE, INT64	תמונת מצב יומית של המספר הכולל של פלטים מהמודל שמאוחסנים בקטגוריה, מקובצים לפי model_name, model_version, status, type ו-data_locations.

למידע נוסף על שליחת שאילתות לגבי מדדים והגדרת התראות, קראו את המאמרים מדדי Cloud Monitoring ל-Cloud Storage ויצירת תרשימים באמצעות Metrics Explorer.

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

• הגדרת העשרת אובייקטים
• ניתוח העשרת אובייקטים באמצעות SQL ב-BigQuery.
• בדיקת המודלים הנתמכים וסכימות הפלט
• סקירה כללית על העשרת אובייקטים
• בודקים את המשאבים והשיטות של ה-API בפורמט JSON של featureConfigs.
• מידע ולמידה על הקשרים של אובייקטים
• ניהול אובייקטים בכמות גדולה באמצעות פעולות רבות על פריטי אחסון.