יצירת קבוצת תכונות

קבוצת תכונות היא משאב של Feature Registry שמשויך לטבלה או לתצוגה ב-BigQuery שמכילות את נתוני התכונות. קבוצת תכונות יכולה להכיל כמה תכונות, כאשר כל תכונה משויכת לעמודה במקור נתוני התכונות. אם רוצים לרשום את מקור נתוני התכונות במאגר התכונות, צריך ליצור קבוצת תכונות ואז להוסיף לה תכונות.

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

למה כדאי להשתמש בקבוצות של תכונות ובתכונות?

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

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

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

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

  • צבירת תכונות ממקורות מרובים: אפשר להשתמש בקבוצות תכונות כדי לצבור עמודות ספציפיות ממקורות נתונים מרובים ב-BigQuery כשיוצרים מופע של תצוגת תכונות.

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

  • שימוש בסנכרון נתונים רציף בתצוגות התכונות: רישום התכונות הוא תנאי מוקדם לשימוש בסנכרון נתונים רציף בתצוגות התכונות.

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

מתי לא כדאי להשתמש בקבוצות תכונות ובתכונות

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

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

בקרת הגישה

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

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

  • שליטה בגישה למקור הנתונים ב-BigQuery: כברירת מחדל, קבוצת תכונות משתמשת בחשבון השירות שמוגדר כברירת מחדל לפרויקט. מאגר התכונות של Vertex AI מקצה לחשבון השירות הזה את תפקיד ניהול הזהויות והרשאות הגישה (IAM) BigQuery Data Viewer. כך כל משתמש שיש לו הרשאה ליצור קבוצת תכונות בפרויקט יכול לגשת למקור נתוני התכונות ב-BigQuery. כדי להגביל את הגישה למקור הנתונים ב-BigQuery או להעניק גישה למשתמשים נוספים, אתם יכולים להגדיר את קבוצת התכונות כך שתשתמש בחשבון שירות ייעודי משלה. ‫Vertex AI Feature Store יוצר כתובת אימייל ייחודית של חשבון שירות לכל קבוצת תכונות שהוגדרה עם חשבון שירות ייעודי.

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

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

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

  • מעצבים את נתוני התכונות בטבלה או בתצוגה ב-BigQuery בהתאם להנחיות להכנת מקור נתונים.

  • מוודאים שמקור הנתונים ב-BigQuery מכיל לפחות עמודה אחת של מזהי ישויות עם הערכים string או int.

  • מאמתים את Gemini Enterprise Agent Platform, אלא אם כבר עשיתם זאת.

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

    המסוף

    כשמשתמשים במסוף Google Cloud כדי לגשת לשירותים Google Cloud ולממשקי ה-API, לא צריך להגדיר אימות.

    Python

    כדי להשתמש בסביבת פיתוח מקומית בדוגמאות של Python שבדף הזה, מתקינים ומפעילים את ה-CLI של gcloud, ואז מגדירים את Application Default Credentials באמצעות פרטי הכניסה של המשתמש.

    1. התקינו את ה-CLI של Google Cloud.

    2. אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

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

      gcloud auth application-default login

      אם אתם משתמשים ב-Cloud Shell, אתם לא צריכים לעשות את זה.

      אם מוחזרת שגיאת אימות ואתם משתמשים בספק זהויות חיצוני (IdP), ודאו ש נכנסתם ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

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

    REST

    כדי להשתמש בסביבת פיתוח מקומית בדוגמאות של API בארכיטקטורת REST שבדף הזה, צריך להשתמש בפרטי הכניסה שאתם נותנים ל-CLI של gcloud.

      התקינו את ה-CLI של Google Cloud.

      אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

    מידע נוסף מופיע במאמר אימות לשימוש ב-REST במסמכי האימות של Google Cloud .

יצירת קבוצת תכונות לרישום מקור נתוני תכונות

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

המסוף

חשוב לדעת: אי אפשר ליצור קבוצת תכונות עם חשבון שירות ייעודי ממסוף Google Cloud . כדי ליצור קבוצת תכונות עם חשבון שירות ייעודי, משתמשים ב-API בארכיטקטורת REST או ב-Agent Platform SDK ל-Python.

כדי ליצור קבוצת תכונות באמצעות מסוף Google Cloud :

  1. בקטע Agent Platform במסוף Google Cloud , עוברים לדף Feature Store.

    כניסה לדף Feature Store

  2. בקטע Feature groups (קבוצות תכונות), לוחצים על Create (יצירה) כדי לפתוח את החלונית Basic info (מידע בסיסי) בדף Create Feature Group (יצירת קבוצת תכונות).

  3. מציינים את שם קבוצת התכונות.

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

  5. בשדה BigQuery path (נתיב BigQuery), לוחצים על Browse (עיון) כדי לבחור טבלת מקור או תצוגה של BigQuery לשיוך לקבוצת התכונות.

  6. ברשימה Entity ID column (עמודת מזהה הישות), בוחרים את העמודות של מזהה הישות מטבלת המקור או מהתצוגה ב-BigQuery.

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

  7. לוחצים על Continue.

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

    • Include all columns from the BigQuery table (הכללת כל העמודות מטבלת BigQuery) – יצירת תכונות בתוך קבוצת התכונות לכל העמודות בטבלה ב-BigQuery או בתצוגה המפורטת של BigQuery.

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

      כדי להוסיף עוד תכונות, לוחצים על הוספת תכונה נוספת.

    • יצירת קבוצת תכונות ריקה – יצירת קבוצת התכונות בלי להוסיף לה תכונות.

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

Python

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

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

from google.cloud import aiplatform
from vertexai.resources.preview import feature_store
from typing import List


def create_feature_group_sample(
    project: str,
    location: str,
    feature_group_id: str,
    bq_table_uri: str,
    entity_id_columns: List[str],
):
    aiplatform.init(project=project, location=location)
    fg = feature_store.FeatureGroup.create(
        name=feature_group_id,
        source=feature_store.utils.FeatureGroupBigQuerySource(
            uri=bq_table_uri, entity_id_columns=entity_id_columns
        ),
    )
    return fg
  • ‫project: מזהה הפרויקט.
  • ‫location: האזור שבו רוצים ליצור את קבוצת התכונות, למשל us-central1.
  • ‫feature_group_id: השם של קבוצת התכונות החדשה שרוצים ליצור.
  • ‫bq_table_uri: ה-URI של טבלת המקור או התצוגה ב-BigQuery שרוצים לרשום לקבוצת התכונות.
  • ‫entity_id_columns: השמות של העמודות שמכילות את מזהי הישויות. אפשר לציין עמודה אחת או כמה עמודות.
    • כדי לציין רק עמודה אחת של מזהה ישות, מציינים את שם העמודה בפורמט הבא:
      "entity_id_column_name".
    • כדי לציין כמה עמודות של מזהי ישויות, מציינים את שמות העמודות בפורמט הבא:
      ["entity_id_column_1_name", "entity_id_column_2_name", ...].

REST

כדי ליצור משאב FeatureGroup, שולחים בקשת POST באמצעות ה-method‏ featureGroups.create.

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

  • ‫LOCATION_ID: האזור שבו רוצים ליצור את קבוצת התכונות, למשל us-central1.
  • ‫SERVICE_AGENT_TYPE: אופציונלי. הגדרת חשבון השירות לקבוצת התכונות. כדי להשתמש בחשבון שירות ייעודי לקבוצת התכונות, מזינים SERVICE_AGENT_TYPE_FEATURE_GROUP.
  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫ENTITY_ID_COLUMNS: השמות של העמודות שמכילות את מזהי הישויות. אפשר לציין עמודה אחת או כמה עמודות.
    • כדי לציין רק עמודה אחת של מזהה ישות, מציינים את שם העמודה בפורמט הבא:
      "entity_id_column_name".
    • כדי לציין כמה עמודות של מזהי ישויות, מציינים את שמות העמודות בפורמט הבא:
      ["entity_id_column_1_name", "entity_id_column_2_name", ...].
  • ‫FEATUREGROUP_NAME: השם של קבוצת התכונות החדשה שרוצים ליצור.
  • ‫BIGQUERY_SOURCE_URI: ה-URI של טבלת המקור או התצוגה ב-BigQuery שרוצים לרשום לקבוצת התכונות.
  • ‫TIMESTAMP_COLUMN: אופציונלי. מציינים את שם העמודה שמכילה את חותמות הזמן של התכונות בטבלה או בתצוגה של מקור BigQuery.
    צריך לציין את שם העמודה של חותמות הזמן רק אם הנתונים מפורמטים כסדרת זמן והעמודה שמכילה את חותמות הזמן של התכונות לא נקראת feature_timestamp.
  • ‫STATIC_DATA_SOURCE: אופציונלי. מזינים true אם הנתונים לא בפורמט של סדרת זמן. ערך ברירת המחדל הוא false.
  • ‫DENSE: אופציונלי. מציינים איך Vertex AI Feature Store מטפל בערכי null בזמן הצגת נתונים מתצוגות תכונות שמשויכות לקבוצת התכונות:
    • false – זו הגדרת ברירת המחדל. ‫Vertex AI Feature Store מציג רק את הערכים העדכניים ביותר של תכונות שאינן null. אם הערך האחרון של תכונה הוא null, ‏ Vertex AI Feature Store מציג את הערך ההיסטורי האחרון שאינו null. עם זאת, אם הערכים הנוכחיים וההיסטוריים של התכונה הם null, אז Vertex AI Feature Store מחזיר null כערך התכונה.
    • true‫— בתצוגות של תכונות עם סנכרון נתונים מתוזמן, Vertex AI Feature Store מציג רק את הערכים האחרונים של התכונות, כולל ערכי null. בתצוגות של תכונות עם סנכרון נתונים רציף, Vertex AI Feature Store מציג רק את הערכים העדכניים ביותר של התכונות שאינם null. עם זאת, אם הערכים הנוכחיים וההיסטוריים של התכונה הם null, ‏ Vertex AI Feature Store יציג null כערך התכונה. מידע נוסף על סוגי סנכרון נתונים ועל אופן ההגדרה של סוג סנכרון הנתונים בתצוגת תכונות זמין במאמר סנכרון הנתונים בתצוגת תכונות.

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

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureGroups?feature_group_id=FEATUREGROUP_NAME

גוף בקשת JSON: 

{
  "service_agent_type": "SERVICE_AGENT_TYPE",
  "big_query": {
    "entity_id_columns": "ENTITY_ID_COLUMNS",
    "big_query_source": {
      "input_uri": "BIGQUERY_SOURCE_URI",
    }
    "time_series": {
      "timestamp_column": ""TIMESTAMP_COLUMN"",
    },
    "static_data_source": STATIC_DATA_SOURCE,
    "dense": DENSE
  }
}

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

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://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureGroups?feature_group_id=FEATUREGROUP_NAME"

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://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureGroups?feature_group_id=FEATUREGROUP_NAME" | Select-Object -Expand Content

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

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/featureGroups/FEATUREGROUP_NAME/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.UpdateFeatureGroupOperationMetadata",
    "genericMetadata": {
      "createTime": "2023-09-18T03:00:13.060636Z",
      "updateTime": "2023-09-18T03:00:13.060636Z"
    }
  }
}

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