יצירת אפליקציית אימון ב-Python לקונטיינר מוכן מראש

כדי לאמן מודל ב-Gemini Enterprise Agent Platform בלי שרת (serverless) באמצעות קונטיינר מובנה, צריך ליצור הפצה של קוד מקור ב-Python שמכילה את אפליקציית האימון, ולהעלות אותה לקטגוריה של Cloud Storage שלפרויקט ב- Google Cloud יש גישה אליה.

חלופות ליצירת הפצת מקור

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

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

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

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

  1. מפתחים את אפליקציית האימון באמצעות מסגרת למידת מכונה (ML) שזמינה באחד מהקונטיינרים המוגדרים מראש לאימון ב-Agent Platform. מוודאים שאפליקציית האימון עומדת בדרישות של קוד האימון.

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

  2. יוצרים קטגוריה של Cloud Storage באותו פרויקט ב- Google Cloud שבו אתם מתכננים להשתמש ב-Agent Platform. בקטגוריה הזו תאחסנו את אפליקציית האימון. (אפשר להשתמש בקטגוריה ב-Google Cloud bucket אחר, אבל זה דורש הגדרה נוספת שלא נכללת במדריך הזה).

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

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

מבנה האפליקציה

כשמבצעים אימון בלי שרת (serverless) באמצעות קונטיינר מובנה, צריך לציין את קוד האימון בהתאם לדרישות הבאות:

  • צריך לספק את הקוד כהפצה אחת או יותר של קוד מקור ב-Python.

    אם אתם משתמשים ב-Agent Platform API כדי להתחיל אימון בלי שרת (serverless), ציינו את הפרטים האלה בשדה packageUris.

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

    אם אתם משתמשים ב-Agent Platform API כדי להתחיל אימון בהתאמה אישית, ציינו את זה בשדה pythonModule.

כל עוד אתם עומדים בדרישות האלה, אתם יכולים לבנות את אפליקציית האימון בכל דרך שתרצו. עם זאת, מומלץ ליצור הפצה אחת של קוד מקור ב-Python על ידי ארגון הקוד במבנה הבא (שמשמש לעיתים קרובות בדוגמאות של Agent Platform):

  • משתמשים בספריית הפרויקט הראשית, שמכילה את הקובץ setup.py. בקטע הבא מוסבר מה צריך להיות בקובץ הזה.

  • בספריית הפרויקט הראשית, יוצרים ספריית משנה בשם trainer/ שתשמש כחבילה הראשית של קוד האימון.

  • בתוך trainer/, יוצרים מודול בשם task.py שמשמש כנקודת הכניסה לקוד האימון.

  • כדי לתמוך ב-trainer/task.py, יוצרים מודולים נוספים של Python שרוצים בחבילה trainer/, ויוצרים תיקיות משנה נוספות עם הקוד הנוסף שרוצים בתיקיית הפרויקט הראשית.

  • יוצרים קובץ __init__.py בכל ספריית משנה כדי להפוך אותה לחבילה.

ההנחה בשאר המדריך היא שהקוד שלכם מאורגן לפי המבנה הזה.

יצירת הפצה של מקורות

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

  1. יוצרים קובץ setup.py שמנחה את Setuptools איך ליצור את הפצת המקור. setup.py בסיסי כולל:

    • הצהרות ייבוא של setuptools.find_packages ו-setuptools.setup.

    • קריאה ל-setuptools.setup עם הפרמטרים הבאים (לפחות):

      • ‫name מוגדר לשם של הפצת המקור.

      • version מוגדר למספר הגרסה של ה-build הזה של הפצת המקור.

      • install_requires מוגדר לרשימה של יחסי תלות שנדרשים לאפליקציה, עם דרישות גרסה, כמו 'docutils>=0.3'.

      • packages הוגדרה לערך find_packages(). הפקודה הזו מורה ל-Setuptools לכלול את כל תיקיות המשנה של תיקיית האם שמכילות קובץ __init__.py בתור חבילות.

      • include_package_data הוגדרה לערך True.

    הדוגמה הבאה מציגה קובץ setup.py בסיסי לאפליקציית אימון:

    from setuptools import find_packages
from setuptools import setup

setup(
    name='trainer',
    version='0.1',
    packages=find_packages(),
    include_package_data=True,
    description='My training application.'
)

  2. מריצים את הפקודה הבאה כדי ליצור הפצת מקור, dist/trainer-0.1.tar.gz:

    python setup.py sdist --formats=gztar

יחסי תלות של אפליקציות ב-Python

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

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

יש 2 סוגים של יחסי תלות שאולי תצטרכו להוסיף:

  • יחסי תלות רגילים, שהם חבילות הפצה נפוצות שזמינות ב-PyPI
  • תלויות בהתאמה אישית, כמו חבילות שפיתחתם בעצמכם או חבילות פנימיות בארגון.

בקטעים הבאים מתואר התהליך לכל סוג.

יחסי תלות רגילים (PyPI)

אפשר לציין את יחסי התלות הרגילים של האפליקציה כחלק מהסקריפט setup.py שלה. פלטפורמת הסוכן משתמשת ב-pip כדי להתקין את אפליקציית האימון ברפליקות שהיא מקצה למשימה. הפקודה pip install מחפשת את יחסי התלות שהוגדרו ומתקינה אותם.

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

from setuptools import find_packages
from setuptools import setup

REQUIRED_PACKAGES = ['some_PyPI_package>=1.0']

setup(
    name='trainer',
    version='0.1',
    install_requires=REQUIRED_PACKAGES,
    packages=find_packages(),
    include_package_data=True,
    description='My training application.'
)

יחסי תלות בהתאמה אישית

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

כל URI שאתם כוללים הוא הנתיב להפצת מקור, בפורמט של קובץ tar‏ (.tar.gz) או wheel‏ (.whl). פלטפורמת הסוכנים מתקינה כל תלות באמצעות pip install בכל רפליקה שהיא מקצה למשימת האימון.

אם אתם משתמשים ב-Agent Platform API כדי להתחיל אימון ללא שרת (serverless), ציינו את ה-URIs של Cloud Storage ליחסי התלות האלה, יחד עם אפליקציית האימון, בשדה packageUris.

מודולים של Python

האפליקציה יכולה להכיל כמה מודולים (קובצי Python). אתם צריכים לזהות את המודול שמכיל את נקודת הכניסה של האפליקציה. שירות האימון מריץ את המודול הזה על ידי הפעלת Python, בדיוק כמו שהייתם מריצים אותו באופן מקומי.

לדוגמה, אם פעלתם לפי המבנה המומלץ בקטע הקודם, המודול הראשי הוא task.py. מכיוון שהוא נמצא בתוך חבילת ייבוא (ספרייה עם קובץ __init__.py) בשם trainer, השם המלא של המודול הזה הוא trainer.task. לכן, אם אתם משתמשים ב-Agent Platform API כדי להתחיל אימון בהתאמה אישית, הגדירו את השדה moduleName לערך trainer.task.

מידע נוסף על מודולים זמין במדריך של Python לחבילות.

העלאת הפצת המקור ל-Cloud Storage

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

gcloud storage cp dist/trainer-0.1.tar.gz CLOUD_STORAGE_DIRECTORY

מחליפים את CLOUD_STORAGE_DIRECTORY ב-URI (שמתחיל ב-gs:// ומסתיים ב-/) של ספריית Cloud Storage בקטגוריה שלפרויקטGoogle Cloud יש גישה אליה.

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

מעבר מ-python_package_spec ל-container_spec

ההגדרה PythonPackageSpec (executorImageUri) מקבלת רק קונטיינרים לאימון שנבנו מראש ונתמכים באופן רשמי. אם המסגרת או סביבת זמן הריצה הגיעו לסוף הזמינות (EOA), כמו scikit-learn או XGBoost, או אם אתם צריכים גרסאות חדשות יותר של Python (כמו Python 3.11 ואילך) וספריות מערכת חיצוניות, העבירו את עומס העבודה של האימון לשימוש ב-ContainerSpec.

בניגוד ל-python_package_spec, ב-ContainerSpec אין שדות של package_uris או python_module.

כדי להעביר את עומס העבודה ל-container_spec, בוחרים באחת מהגישות הבאות:

  • שמירת החבילות ב-Cloud Storage: מעבירים את ה-URI של החבילה דרך args או env לסקריפט של נקודת כניסה בקונטיינר שמוריד את החבילה, מתקין אותה באמצעות pip ומריץ את python -m <module>.

    לדוגמה, בסקריפט של נקודת הכניסה של הקונטיינר:

    #!/usr/bin/env bash
set -e

PACKAGE_URI="$1"
MODULE_NAME="$2"
shift 2

gcloud storage cp "${PACKAGE_URI}" ./package.tar.gz
pip install --no-cache-dir ./package.tar.gz
python -m "${MODULE_NAME}" "$@"

  • הטמעת הקוד בקובץ האימג': לחלופין, אתם יכולים להעתיק את קובצי אפליקציית האימון ואת יחסי התלות ישירות לקובץ האימג' של Docker בזמן היצירה (לדוגמה, באמצעות COPY ו-pip install ב-Dockerfile) ולהגדיר את נקודת הכניסה ישירות בקובץ האימג'.

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