יצירה, העלאה ושימוש בתבנית של פייפליין

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

לקוח הרישום של Kubeflow Pipelines SDK הוא ממשק לקוח חדש שאפשר להשתמש בו עם שרת רישום תואם, כמו Artifact Registry, לניהול גרסאות של תבניות Kubeflow Pipelines ‏ (KFP). מידע נוסף זמין במאמר שימוש בתבנית בלקוח של מאגר Kubeflow Pipelines SDK.

בדף הזה נסביר איך:

• יצירת תבנית של צינור KFP
• משתמשים בלקוח הרישום של Kubeflow Pipelines SDK כדי להעלות את התבנית למאגר תבניות של צינורות עיבוד נתונים
• שימוש בתבנית בלקוח של Kubeflow Pipelines

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

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

1. מתקינים את גרסה 2 ואילך של Kubeflow Pipelines SDK.

   pip install --upgrade "kfp>=2,<3"
   

הערה: כדי לשדרג לגרסה העדכנית של Kubeflow Pipelines SDK, מריצים את הפקודה הבאה:
pip install kfp --upgrade
אם יש גרסה מעודכנת, הפעלת הפקודה הזו תגרום להסרת KFP ולהתקנת הגרסה העדכנית.

1. מתקינים את הגרסה 1.15.0 ואילך של Vertex AI SDK ל-Python.
   (אופציונלי) לפני ההתקנה, מריצים את הפקודה הבאה כדי לראות איזו גרסה של Vertex AI SDK ל-Python מותקנת:

   ‫

     pip freeze | grep google-cloud-aiplatform
   

   הערה: כדי לשדרג לגרסה העדכנית של Vertex AI SDK ל-Python, מריצים את הפקודה הבאה:
   pip install google-cloud-aiplatform --upgrade
   אם יש גרסה עדכנית, הפעלת הפקודה הזו תגרום להסרת הגרסה המותקנת ולהתקנת הגרסה העדכנית.

2. (אופציונלי) מתקינים את גרסה 390.0.0 ואילך של Google Cloud CLI.

3. מפעילים את Artifact Registry API.

הגדרת הרשאות

אם עדיין לא הגדרתם את פרויקט ה-CLI של gcloud ל-Vertex AI Pipelines, פועלים לפי ההוראות במאמר הגדרת פרויקט Google Cloud ל-Vertex AI Pipelines.

בנוסף, צריך להקצות את ההרשאות המוגדרות מראש הבאות לניהול זהויות והרשאות גישה (IAM) כדי להשתמש ב-Artifact Registry כמאגר התבניות:

• ‫roles/artifactregistry.admin: הקצאת התפקיד הזה מאפשרת ליצור ולנהל מאגר.
• ‫roles/artifactregistry.repoAdmin או roles/artifactregistry.writer: הקצאת אחד מהתפקידים האלה מאפשרת לנהל תבניות במאגר.
• ‫roles/artifactregistry.reader: הקצאת התפקיד הזה להורדת תבניות ממאגר.
• ‫roles/artifactregistry.reader: הקצאת התפקיד הזה לחשבון שירות שמשויך ל-Vertex AI Pipelines כדי ליצור הפעלה של צינור עיבוד נתונים מתבנית.

מידע נוסף על תפקידים מוגדרים מראש של ניהול זהויות והרשאות גישה (IAM) ב-Artifact Registry זמין במאמר תפקידים מוגדרים מראש ב-Artifact Registry.

בדוגמה הבאה מוסבר איך להקצות תפקידים:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=PRINCIPAL \
    --role=ROLE

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

• ‫PROJECT_ID: הפרויקט שבו רוצים ליצור את צינור העברת הנתונים.
• PRINCIPAL: חשבון המשתמש שרוצים להוסיף לו הרשאות.
• ‫ROLE: התפקיד בניהול זהויות והרשאות גישה (IAM) שרוצים להקצות לישות המורשית.

מידע נוסף על הנושאים הבאים מופיע במאמר תפקידים והרשאות במסמכי התיעוד של Artifact Registry:

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

יצירת מאגר ב-Artifact Registry

בשלב הבא, יוצרים מאגר בתבניות של צינורות העברת נתונים ב-Artifact Registry.

המסוף

1. פותחים את Vertex AI Pipelines במסוף Google Cloud .

   עוברים אל Vertex AI Pipelines

2. לוחצים על הכרטיסייה התבניות שלך.

3. כדי לפתוח את החלונית Select repository (בחירת מאגר), לוחצים על Select repository (בחירת מאגר).

4. לוחצים על יצירת מאגר.

5. מציינים את quickstart-kfp-repo כשם המאגר.

6. בקטע פורמט, בוחרים באפשרות Kubeflow Pipelines.

7. בקטע סוג המיקום, בוחרים באפשרות אזור.

8. ברשימה הנפתחת אזור, בוחרים באפשרות us-central1.

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

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

Google Cloud CLI

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

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

• ‫LOCATION: המיקום או האזור שבו רוצים ליצור את המאגר, לדוגמה, us-central1

מריצים את הפקודה gcloud artifacts repositories create:

‫Linux,‏ macOS או Cloud Shell

הערה: חשוב לוודא שהפעלתם את Google Cloud CLI עם אימות ופרויקט. לשם כך, מריצים את הפקודה gcloud init; או את הפקודות gcloud auth login ו- gcloud config set project.

gcloud artifacts repositories create quickstart-kfp-repo --location=LOCATION_ID --repository-format=KFP

‏Windows (PowerShell)

הערה: חשוב לוודא שהפעלתם את Google Cloud CLI עם אימות ופרויקט. לשם כך, מריצים את הפקודה gcloud init; או את הפקודות gcloud auth login ו- gcloud config set project.

gcloud artifacts repositories create quickstart-kfp-repo --location=LOCATION_ID --repository-format=KFP

Windows‏ (cmd.exe)

הערה: חשוב לוודא שהפעלתם את Google Cloud CLI עם אימות ופרויקט. לשם כך, מריצים את הפקודה gcloud init; או את הפקודות gcloud auth login ו- gcloud config set project.

gcloud artifacts repositories create quickstart-kfp-repo --location=LOCATION_ID --repository-format=KFP

 

יצירת תבנית

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

from kfp import dsl
from kfp import compiler

@dsl.component()
def hello_world(text: str) -> str:
    print(text)
    return text

@dsl.pipeline(name='hello-world', description='A simple intro pipeline')
def pipeline_hello_world(text: str = 'hi there'):
    """Pipeline that passes small pipeline parameter string to consumer op."""

    consume_task = hello_world(
        text=text)  # Passing pipeline parameter as argument to consumer op

compiler.Compiler().compile(
    pipeline_func=pipeline_hello_world,
    package_path='hello_world_pipeline.yaml')

כשמריצים את הדוגמה, ההצהרה compiler.Compiler().compile(...) מהדרת את צינור hello-world לקובץ ה-YAML המקומי שנקרא hello_world_pipeline.yaml.

העלאת התבנית

המסוף

1. פותחים את Vertex AI Pipelines במסוף Google Cloud .

   עוברים אל Vertex AI Pipelines

2. לוחצים על העלאה כדי לפתוח את החלונית צינור או רכיב להעלאה.

3. בתפריט הנפתח Repository, בוחרים את מאגר quickstart-kfp-repo.

4. מציינים שם לתבנית של צינור הנתונים.

5. בשדה File (קובץ), לוחצים על Choose (בחירה) כדי לבחור ולהעלות את קובץ ה-YAML של תבנית הצינור המהודרת ממערכת הקבצים המקומית.

6. אחרי שמעלים את תבנית הצינור, היא מופיעה בדף התבניות שלך.

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

לקוח Kubeflow Pipelines SDK

1. כדי להגדיר את לקוח הרישום של Kubeflow Pipelines SDK, מריצים את הפקודות הבאות:

   from kfp.registry import RegistryClient
   
   client = RegistryClient(host=f"https://us-central1-kfp.pkg.dev/PROJECT_ID/quickstart-kfp-repo")
   

2. מעלים את קובץ ה-YAML שעבר קומפילציה למאגר שלכם ב-Artifact Registry.

   templateName, versionName = client.upload_pipeline(
     file_name="hello_world_pipeline.yaml",
     tags=["v1", "latest"],
     extra_headers={"description":"This is an example pipeline template."})
   

3. כדי לוודא שהתבנית הועלתה:

   1. פותחים את Vertex AI Pipelines במסוף Google Cloud .

      עוברים אל Vertex AI Pipelines

   2. לוחצים על הכרטיסייה התבניות שלך.

   3. לוחצים על בחירת מאגר.

   4. ברשימה, בוחרים את מאגר quickstart-kfp-repo ולוחצים על בחירה.

   5. ברשימה אמורה להופיע חבילת התבנית שהועלתה hello-world.

   6. כדי לראות את רשימת הגרסאות של תבנית הצינור, לוחצים על התבנית hello-world.

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

שימוש בתבנית ב-Vertex AI

אחרי שמעלים את תבנית צינור עיבוד הנתונים למאגר ב-Artifact Registry, היא מוכנה לשימוש ב-Vertex AI Pipelines.

יצירת קטגוריית אחסון זמנית לתבנית

כדי להשתמש בתבנית של צינור, צריך ליצור מאגר (bucket) ב-Cloud Storage כדי להכין את ההרצה של צינורות.

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

STAGING_BUCKET="gs://BUCKET_NAME"

מחליפים את BUCKET_NAME בשם הקטגוריה שיצרתם.

יצירת הרצת פייפליין מהתבנית

אתם יכולים להשתמש ב-Vertex AI SDK ל-Python או ב Google Cloud מסוף כדי ליצור הרצה של צינור מהתבנית שלכם ב-Artifact Registry.

המסוף

1. פותחים את Vertex AI Pipelines במסוף Google Cloud .

   עוברים אל Vertex AI Pipelines

2. לוחצים על הכרטיסייה התבניות שלך.

3. כדי לפתוח את החלונית Select repository (בחירת מאגר), לוחצים על Select repository (בחירת מאגר).

4. בוחרים את מאגר quickstart-kfp-repo ולוחצים על בחירה.

5. לוחצים על החבילה hello-world.

6. לצד הגרסה 4f245e8f9605, לוחצים על יצירת הפעלה.

7. לוחצים על הגדרת זמן ריצה.

8. מזינים את הערכים הבאים בקטע מיקום Cloud Storage:

   gs://BUCKET_NAME
   

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

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

‫Vertex AI SDK ל-Python

אפשר להשתמש בדוגמה הבאה כדי ליצור הרצת צינור מהתבנית:

from google.cloud import aiplatform

# Initialize the aiplatform package
aiplatform.init(
    project="PROJECT_ID",
    location='us-central1',
    staging_bucket=STAGING_BUCKET)

# Create a pipeline job using a version ID.
job = aiplatform.PipelineJob(
    display_name="hello-world-latest",
    template_path="https://us-central1-kfp.pkg.dev/PROJECT_ID/quickstart-kfp-repo/hello-world@SHA256_TAG" + \
        versionName)

# Alternatively, create a pipeline job using a tag.
job = aiplatform.PipelineJob(
    display_name="hello-world-latest",
    template_path="https://us-central1-kfp.pkg.dev/PROJECT_ID/quickstart-kfp-repo/hello-world/TAG")

job.submit()

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

• ‫PROJECT_ID: Google Cloud הפרויקט שבו צינור הנתונים הזה פועל.

• ‫SHA256_TAG: ערך הגיבוב sha256 של גרסת התבנית.

• ‫TAG: תג הגרסה של התבנית.

צפייה בהפעלות של צינורות עיבוד נתונים שנוצרו

אתם יכולים לראות את ההרצות שנוצרו על ידי גרסה ספציפית של צינור עיבוד נתונים ב-Vertex AI SDK ל-Python.

המסוף

1. פותחים את Vertex AI Pipelines במסוף Google Cloud .

   עוברים אל Vertex AI Pipelines

2. לוחצים על הכרטיסייה התבניות שלך.

3. לוחצים על בחירת מאגר.

4. ברשימה, בוחרים את מאגר quickstart-kfp-repo ולוחצים על בחירה.

5. כדי לראות את רשימת הגרסאות של תבנית הצינור hello-world, לוחצים על התבנית hello world.

6. לוחצים על הגרסה הרצויה שרוצים לראות את ההרצות של צינור הנתונים שלה.

7. כדי לראות את ההרצות של צינורות העיבוד לגרסה שנבחרה, לוחצים על View Runs (הצגת הרצות) ואז על הכרטיסייה Runs (הרצות).

‫Vertex AI SDK ל-Python

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

  from google.cloud import aiplatform

  # To filter all runs created from a specific version
  filter = 'template_uri:"https://us-central1-kfp.pkg.dev/PROJECT_ID/quickstart-kfp-repo/hello-world/*" AND ' + \
           'template_metadata.version="%s"' % versionName
  aiplatform.PipelineJob.list(filter=filter)

  # To filter all runs created from a specific version tag
  filter = 'template_uri="https://us-central1-kfp.pkg.dev/PROJECT_ID/quickstart-kfp-repo/hello-world/latest"'
  aiplatform.PipelineJob.list(filter=filter)

  # To filter all runs created from a package
  filter = 'template_uri:"https://us-central1-kfp.pkg.dev/PROJECT_ID/quickstart-kfp-repo/hello-world/*"'
  aiplatform.PipelineJob.list(filter=filter)

  # To filter all runs created from a repo
  filter = 'template_uri:"https://us-central1-kfp.pkg.dev/PROJECT_ID/quickstart-kfp-repo/*"'
  aiplatform.PipelineJob.list(filter=filter)

שימוש בתבנית בלקוח של רישום ב-Kubeflow Pipelines SDK

אתם יכולים להשתמש בלקוח רישום של Kubeflow Pipelines SDK יחד עם Artifact Registry כדי להוריד את תבנית הצינור ולהשתמש בה.

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

  templatePackages = client.list_packages()
  templatePackage = client.get_package(package_name = "hello-world")
  
  versions = client.list_versions(package_name="hello-world")
  version = client.get_version(package_name="hello-world", version=versionName)
  
  tags = client.list_tags(package_name = "hello-world")
  tag = client.get_tag(package_name = "hello-world", tag="latest")
  

  הרשימה המלאה של השיטות והמסמכים הזמינים מופיעה protoבקבצים במאגר GitHub של Artifact Registry.

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

  # Sample 1
  filename = client.download_pipeline(
    package_name = "hello-world",
    version = versionName)
  # Sample 2
  filename = client.download_pipeline(
    package_name = "hello-world",
    tag = "v1")
  # Sample 3
  filename = client.download_pipeline(
    package_name = "hello-world",
    tag = "v1",
    file_name = "hello-world-template.yaml")
  

שימוש ב-Artifact Registry API בארכיטקטורת REST

בקטעים הבאים מוסבר איך להשתמש ב-Artifact Registry API בארכיטקטורת REST כדי לנהל את תבניות הצינור במאגר Artifact Registry.

העלאה של תבנית צינור באמצעות Artifact Registry API בארכיטקטורת REST

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

• ‫PROJECT_ID הוא הפרויקט שבו צינור הנתונים הזה פועל. Google Cloud
• ‫REPO_ID הוא המזהה של מאגר Artifact Registry.

דוגמה לבקשת curl

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -F tags=v1,latest \
    -F content=@pipeline_spec.yaml \
    https://us-central1-kfp.pkg.dev/PROJECT_ID/REPO_ID

יצירת בקשת ההעלאה

הבקשה היא בקשת HTTP או HTTPS שמורכבת מחלקים מרובים. היא חייבת לכלול את אסימון האימות בכותרת הבקשה. מידע נוסף זמין במאמר בנושא gcloud auth print-access-token.

המטען הייעודי (payload) של הבקשה הוא התוכן של קובץ pipeline_spec.yaml (או חבילת zip). המגבלה המומלצת היא 10MiB‎.

שם החבילה נלקח מהערך pipeline_spec.pipeline_info.name בקובץ pipeline_spec.yaml. שם החבילה מזהה באופן ייחודי את החבילה והוא לא משתנה בין הגרסאות. האורך יכול להיות בין 4 ל-128 תווים והוא צריך להתאים לביטוי הרגולרי הבא: ^[a-z0-9][a-z0-9-]{3,127}$.

החבילה tags היא רשימה של עד שמונה תגים שמופרדים בפסיקים. כל תג חייב להתאים לביטוי הרגולרי הבא: ^[a-zA-Z0-9\-._~:@+]{1,128}$.

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

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

העלאת תשובה

אם בקשת ההעלאה מצליחה, מוחזר סטטוס HTTP OK. גוף התגובה הוא:

{packageName}/{versionName=sha256:abcdef123456...}

כאשר versionName הוא תקציר sha256 של pipeline_spec.yaml בפורמט של מחרוזת הקסדצימלית.

הורדת תבנית של צינור באמצעות Artifact Registry API בארכיטקטורת REST

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

• ‫PROJECT_ID הוא הפרויקט שבו צינור הנתונים הזה פועל. Google Cloud
• ‫REPO_ID הוא המזהה של מאגר Artifact Registry.
• ‫PACKAGE_ID הוא מזהה החבילה של התבנית שהעליתם.
• ‫TAG הוא תג הגרסה.
• ‫VERSION היא גרסת התבנית בפורמט sha256:abcdef123456....

כדי להוריד קובץ Artifact Registry רגיל, צריך ליצור את קישור ההורדה באופן הבא:

url = https://us-central1-kfp.pkg.dev/PROJECT_ID/REPO_ID/PACKAGE_ID/VERSION
url = https://us-central1-kfp.pkg.dev/PROJECT_ID/REPO_ID/PACKAGE_ID/TAG

דוגמאות לבקשות curl

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://us-central1-kfp.pkg.dev/PROJECT_ID/REPO_ID/PACKAGE_ID/VERSION

אפשר להחליף את VERSION ב-TAG ולהוריד את אותה תבנית, כמו בדוגמה הבאה:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://us-central1-kfp.pkg.dev/PROJECT_ID/REPO_ID/PACKAGE_ID/TAG

הורדת התשובה

אם בקשת ההורדה מצליחה, מוחזר סטטוס HTTP OK. גוף התגובה הוא התוכן של הקובץ pipeline_spec.yaml.

קישורים מועילים

• Artifact Registry - Repository overview
• ‫Repository API
  • מילת המפתח format היא KFP
• Package API
• Version API
• Tag API
• הגדרות Proto ב-GitHub