יצירה ושימוש בסכימות בהתאמה אישית

בנוסף לסכימות המערכת שהוגדרו מראש, Vertex ML Metadata מספקת מודל נתונים ניתן להרחבה באמצעות סכימות בהתאמה אישית. סכימות מותאמות אישית הן MetadataSchemas שמוגדרות על ידי המשתמש. אפשר להשתמש בסכימות מותאמות אישית כדי לבדוק את סוג המאפיינים של המטא-נתונים וכדי לשלוח שאילתות למשאבים לפי סכימה. לדוגמה: 'רשימה של כל הארטיפקטים מסוג MyCustomModel'.

כדי להגדיר סכימה בהתאמה אישית, צריך ליצור משאב MetadataSchema בתוך MetadataStore ספציפי שמתאר את הסכימה הצפויה. פורמט הסכימה הוא קבוצת משנה של מפרט OpenAPI 3.0{class: external}, עם ההגבלה שסכימת הרמה העליונה חייבת להיות מסוג object. כל סוגי הנתונים שנתמכים ב-OpenAPI 3.0 (לדוגמה, integer, ‏ number, ‏ string, ‏ boolean, ‏ array, ‏ object) נתמכים כמאפיינים של אובייקט הסכימה ברמה העליונה. מגבלה אחת היא שכל שדה בקטע 'מאפיינים' יכול להיות משויך רק לסוג נתונים אחד. אין תמיכה בסוגים מעורבים. אין תמיכה גם בדרישות מתקדמות לנתונים, כמו מינימום, מקסימום, כפולות ופורמטים של מחרוזות.

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

איך רושמים סכימות מותאמות אישית משלכם

תהליך היצירה של MetadataSchema מותאם אישית דומה ליצירה של משאבי מטא-נתונים חדשים. בהוראות הבאות מוסבר איך ליצור MetadataSchema לדוגמה. היקף ההגדרה של MetadataSchemas הוא רק MetadataStore שאליו הם משויכים.

REST

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

• ‫LOCATION_ID: האזור של MetadataStore.
• ‫PROJECT_ID: מזהה הפרויקט או מספר הפרויקט.
• ‫METADATA_STORE: המזהה של מאגר המטא-נתונים שבו נוצר MetadataSchema. מאגר המטא-נתונים שמוגדר כברירת מחדל נקרא default. אפשר להשתמש בחנות ברירת המחדל, אלא אם נדרש MetadataStore חדש.
• ‫METADATA_SCHEMA_ID: (אופציונלי) המזהה של רשומת MetadataSchema. אם לא מציינים את המזהה, Vertex ML Metadata יוצר מזהה ייחודי ל-MetadataSchema הזה.
• ‫METADATA_SCHEMA_TITLE: השם של הסכימה שמתארת את שדה המטא-נתונים. השם של הסכימה צריך להיות בפורמט .. מרחב השמות צריך להתחיל באות קטנה באנגלית, יכול להכיל אותיות קטנות ומספרים, ויכול להיות באורך של שניים עד עשרים תווים. שם הסכימה חייב להתחיל באות גדולה, יכול לכלול אותיות ומספרים, ויכול להיות באורך של שניים עד ארבעים ותשעה תווים.
• ‫METADATA_SCHEMA_VERSION: (אופציונלי) גרסת הסכימה שמתארת את שדה המטא-נתונים. ‫schema_version חייב להיות מחרוזת של שלושה מספרים שמופרדים בנקודות, לדוגמה, 1.0.0, ‏ 1.0.1. הפורמט הזה עוזר לסדר ולהשוות בין גרסאות.
• ‫METADATA_SCHEMA_TYPE: סוג משאב המטא-נתונים שאליו חלה הסכימה שנוצרה. הסוגים הם: ARTIFACT_TYPE,‏ EXECUTION_TYPE או CONTEXT_TYPE.
• ‫METADATA_SCHEMA: הסכימה המפורטת שרוצים ליצור.
• ‫DESCRIPTION: (אופציונלי) תיאור של ההפעלה.
• ‫ARTIFACT_ID: (אופציונלי) המזהה של רשומת הארטיפקט. אם לא מציינים את מזהה הארטיפקט, Vertex ML Metadata יוצר מזהה ייחודי לארטיפקט הזה.
• ‫DISPLAY_NAME: השם המוצג של הארטיפקט. השדה הזה יכול להכיל עד 128 תווים ביוניקוד.

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

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/metadataSchemas?metadata_schema_id=METADATA_SCHEMA_ID

תוכן בקשת JSON:

{
    "schemaVersion": "0.0.1",
    "schema": "title: test.Experiment\ntype: object",
    "schemaType": "CONTEXT_TYPE",
}

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

‫Curl (Linux,‏ macOS או Cloud Shell)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

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

cat > request.json << 'EOF'
{
    "schemaVersion": "0.0.1",
    "schema": "title: test.Experiment\ntype: object",
    "schemaType": "CONTEXT_TYPE",
}
EOF

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

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/metadataSchemas?metadata_schema_id=METADATA_SCHEMA_ID"

‎PowerShell (Windows)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

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

@'
{
    "schemaVersion": "0.0.1",
    "schema": "title: test.Experiment\ntype: object",
    "schemaType": "CONTEXT_TYPE",
}
'@  | Out-File -FilePath request.json -Encoding utf8

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

$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_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/metadataSchemas?metadata_schema_id=METADATA_SCHEMA_ID" | Select-Object -Expand Content

הפלט שיוצג אמור להיות דומה לזה שמופיע בהמשך. אפשר להשתמש ב-METADATA_SCHEMA_ID בתור המזהה של רשומת MetadataSchema.

{
  "name": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/metadataSchemas/METADATA_SCHEMA_ID",
  "schemaVersion": "0.0.1",
  "schema": "title: test.Experiment\ntype: object",
  "schemaType": "CONTEXT_TYPE",
  "createTime": "2021-04-06T05:24:04.575481815Z"
}

אחרי כן, קריאות עוקבות ליצירה, לאחזור או לרישום של Artifacts יכולות להתייחס לסכימה הזו על ידי ציון השם (demo.Artifact) בשדה schema_title והגרסה (0.0.1) בשדה schema_version של משאב ה-Artifact. מידע נוסף על יצירה, קבלה או הצגה של משאבי מטא-נתונים זמין במאמר מעקב אחר Vertex ML Metadata.

יצירת גרסאות של הסכימות

כל משאבי MetadataSchema הם בעלי גרסאות. משתמש יכול ליצור סכימה שמשתמשת באותו schema_title כמו סכימה אחרת, אבל עם schema_version שונה. כדי ליצור משאב metadataSchema עם גרסה אחרת, המשתמש יכול לספק מספר גרסה אחר ותוכן סכימה שונה.

בדוגמה הבאה נוצרת גרסה 0.0.2 של סכימת demo.Artifact:

sample_schema_versioned = aip.MetadataSchema()
sample_schema_versioned.schema_type = aip.MetadataSchema.MetadataSchemaType.ARTIFACT_TYPE
sample_schema_versioned.schema ="title: demo.Artifact\ntype: object\nproperties:\n  framework:\n    type: string\n    description: \"The framework type\"\n  model_version:\n    type: integer\n    description: \"The version of the model\""
sample_schema_versioned.schema_version = "0.0.2"
sample_schema_versioned.description = "sample schema 2"

store_client.create_metadata_schema(parent=metadata_store.name, metadata_schema=sample_schema_versioned)

השדות בסכימה תמיד נחשבים אופציונליים, ולכן אין תאימות לאחור או קדימה בין גרסאות של אותו schema_title. המשתמשים עדיין יכולים להשתמש ב-schema_title כדי לסנן ולקבץ משאבים לצורך ניתוח. מידע נוסף על השימוש בפונקציות סינון זמין במאמר ניתוח של Vertex ML Metadata.

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

• איך מתחילים לעקוב אחרי Vertex ML Metadata