Mengemas aplikasi pelatihan

Sebelum dapat menjalankan aplikasi pelatihan dengan AI Platform Training, Anda harus mengupload kode dan dependensi apa pun ke dalam bucket Cloud Storage yang dapat diakses oleh project Google Cloud Anda. Halaman ini menunjukkan cara mengemas dan mentahap aplikasi Anda di cloud.

Anda akan mendapatkan hasil terbaik jika menguji aplikasi pelatihan secara lokal sebelum menguploadnya ke cloud. Pelatihan dengan AI Platform Training akan dikenai biaya untuk akun Anda untuk resource yang digunakan.

Sebelum memulai

Sebelum dapat memindahkan aplikasi pelatihan ke cloud, Anda harus menyelesaikan langkah-langkah berikut:

1. Konfigurasikan lingkungan pengembangan Anda, seperti yang dijelaskan dalam panduan memulai.

2. Kembangkan aplikasi pelatihan Anda dengan salah satu framework machine learning yang dihosting dari Pelatihan AI Platform: TensorFlow, scikit-learn, atau XGBoost. Atau, build container kustom untuk menyesuaikan lingkungan aplikasi pelatihan Anda. Ini memberi Anda opsi untuk menggunakan framework machine learning selain framework yang dihosting AI Platform Training.

   Jika Anda ingin men-deploy model terlatih ke AI Platform Prediction setelah pelatihan, baca panduan untuk mengekspor model Anda untuk prediksi guna memastikan paket pelatihan Anda mengekspor artefak model yang dapat digunakan AI Platform Prediction.

3. Ikuti panduan untuk menyiapkan bucket Cloud Storage tempat Anda dapat menyimpan data dan file aplikasi pelatihan.

4. Ketahui semua library Python yang diandalkan aplikasi pelatihan Anda, baik paket kustom maupun tersedia gratis melalui PyPI.

Dokumen ini membahas faktor-faktor berikut yang memengaruhi cara Anda mengemas aplikasi dan menguploadnya ke Cloud Storage:

• Menggunakan gcloud CLI (direkomendasikan) atau membuat coding solusi Anda sendiri.
• Membuat paket secara manual jika perlu.
• Cara menyertakan dependensi tambahan yang tidak diinstal oleh runtime AI Platform Training yang Anda gunakan.

Menggunakan gcloud untuk mengemas dan mengupload aplikasi Anda (direkomendasikan)

Cara paling sederhana untuk mengemas aplikasi dan menguploadnya beserta dependensinya adalah dengan menggunakan gcloud CLI. Anda menggunakan satu perintah (gcloud ai-platform jobs submit training) untuk mengemas dan mengupload aplikasi serta mengirimkan tugas pelatihan pertama Anda.

Untuk memudahkan, sebaiknya tentukan nilai konfigurasi sebagai variabel shell:

PACKAGE_PATH='LOCAL_PACKAGE_PATH'
MODULE_NAME='MODULE_NAME'
STAGING_BUCKET='BUCKET_NAME'
JOB_NAME='JOB_NAME'
JOB_DIR='JOB_OUTPUT_PATH'
REGION='REGION'

Ganti kode berikut:

• LOCAL_PACKAGE_PATH: jalur ke direktori paket Python di lingkungan lokal Anda
• MODULE_NAME: nama modul pelatihan Anda yang sepenuhnya memenuhi syarat
• BUCKET_NAME: nama bucket Cloud Storage
• JOB_NAME: nama untuk tugas pelatihan Anda
• JOB_OUTPUT_PATH: URI direktori Cloud Storage tempat Anda ingin tugas pelatihan menyimpan outputnya
• REGION: wilayah tempat Anda ingin menjalankan tugas pelatihan

Lihat detail selengkapnya tentang persyaratan untuk nilai ini dalam daftar setelah perintah berikut.

Contoh berikut menunjukkan perintah gcloud ai-platform jobs submit training yang mengemas aplikasi dan mengirimkan tugas pelatihan:

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket=$STAGING_BUCKET \
    --job-dir=$JOB_DIR  \
    --package-path=$PACKAGE_PATH \
    --module-name=$MODULE_NAME \
    --region=$REGION \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

• --staging-bucket menentukan bucket Cloud Storage tempat Anda ingin melakukan panggung pelatihan dan paket dependensi. Project Google Cloud Anda harus memiliki akses ke bucket Cloud Storage ini, dan bucket harus berada di region yang sama dengan tempat Anda menjalankan tugas. Lihat region yang tersedia untuk layanan Pelatihan AI Platform. Jika Anda tidak menentukan bucket staging, AI Platform Training akan menempatkan paket Anda di lokasi yang ditentukan dalam parameter job-dir.

• --job-dir menentukan lokasi Cloud Storage yang ingin Anda gunakan untuk file output tugas pelatihan. Project Google Cloud Anda harus memiliki akses ke bucket Cloud Storage ini, dan bucket harus berada di region yang sama dengan tempat Anda menjalankan tugas. Lihat region yang tersedia untuk layanan AI Platform Training.

• --package-path menentukan jalur lokal ke direktori aplikasi. Gcloud CLI membuat paket distribusi .tar.gz dari kode Anda berdasarkan file setup.py di direktori induk dengan file yang ditentukan oleh --package-path. Kemudian, Cloud Storage mengupload file .tar.gz ini ke Cloud Storage dan menggunakannya untuk menjalankan tugas pelatihan Anda.

  Jika tidak ada file setup.py di lokasi yang diharapkan, gcloud CLI akan membuat setup.py sementara yang sederhana dan hanya menyertakan direktori yang ditentukan oleh --package-path dalam file .tar.gz yang di-build.

• --module-name menentukan nama modul utama aplikasi menggunakan notasi titik namespace paket Anda. Ini adalah file Python yang Anda jalankan untuk memulai aplikasi. Misalnya, jika modul utama Anda adalah .../my_application/trainer/task.py (lihat struktur project yang direkomendasikan), maka nama modulnya adalah trainer.task.

• Jika Anda menentukan opsi di file konfigurasi (config.yaml) dan sebagai tanda command line, nilai pada command line akan menggantikan nilai dalam file konfigurasi.
• Flag -- yang kosong menandai akhir dari flag khusus gcloud dan awal dari USER_ARGS yang ingin diteruskan ke aplikasi Anda.
• Tanda khusus untuk Pelatihan AI Platform, seperti --module-name, --runtime-version, dan --job-dir, harus ditempatkan sebelum tanda -- kosong. Layanan AI Platform Training menafsirkan tanda ini.
• Flag --job-dir, jika ditentukan, harus ditempatkan sebelum flag -- kosong, karena AI Platform Training menggunakan --job-dir untuk memvalidasi jalur.
• Aplikasi Anda juga harus menangani flag --job-dir, jika ditentukan. Meskipun tanda ini ditempatkan sebelum -- kosong, --job-dir juga diteruskan ke aplikasi Anda sebagai tanda command line.
• Anda dapat menentukan USER_ARGS sebanyak yang Anda butuhkan. AI Platform Training meneruskan --user_first_arg, --user_second_arg, dan seterusnya, ke aplikasi Anda.

Anda dapat mengetahui lebih lanjut tanda pengiriman tugas dalam panduan untuk menjalankan tugas pelatihan.

Bekerja dengan dependensi

Dependensi adalah paket yang Anda import dalam kode Anda. Aplikasi Anda mungkin memiliki banyak dependensi yang diperlukannya agar berfungsi.

Saat Anda menjalankan tugas pelatihan pada AI Platform Training, tugas tersebut akan dijalankan pada instance pelatihan (virtual machine yang dikonfigurasi khusus) yang memiliki banyak paket Python umum yang telah terinstal. Periksa paket yang disertakan dalam versi runtime yang Anda gunakan untuk pelatihan, dan catat semua dependensi yang belum diinstal.

Ada 2 jenis dependensi yang mungkin perlu Anda tambahkan:

• Dependensi Standard, yang merupakan paket Python umum yang tersedia di PyPI.
• Paket kustom, seperti paket yang Anda kembangkan sendiri, atau paket internal untuk organisasi.

Bagian di bawah ini menjelaskan prosedur untuk setiap jenis data.

Menambahkan dependensi standar (PyPI)

Anda dapat menentukan dependensi standar paket sebagai bagian dari skrip setup.py. AI Platform Training menggunakan pip untuk menginstal paket Anda pada instance pelatihan yang dialokasikan untuk tugas Anda. Perintah pip install mencari dependensi yang telah dikonfigurasi dan menginstalnya.

Buat file bernama setup.py di direktori utama aplikasi Anda (satu direktori naik dari direktori trainer jika Anda mengikuti pola yang direkomendasikan).

Masukkan skrip berikut di setup.py, dengan menyisipkan nilai Anda sendiri:

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 package.'
)

Jika Anda menggunakan Google Cloud CLI untuk mengirimkan tugas pelatihan, file setup.py Anda akan otomatis digunakan untuk membuat paket.

Jika Anda mengirimkan tugas pelatihan tanpa menggunakan gcloud, gunakan perintah berikut untuk menjalankan skrip:

python setup.py sdist

Untuk informasi selengkapnya, lihat bagian tentang memaketkan aplikasi pelatihan secara manual.

Menambahkan dependensi kustom

Anda dapat menentukan dependensi kustom aplikasi dengan meneruskan jalurnya sebagai bagian dari konfigurasi tugas. Anda memerlukan URI ke paket setiap dependensi. Dependensi kustom harus berada di lokasi Cloud Storage. AI Platform Training menggunakan pip install untuk menginstal dependensi kustom, sehingga dapat memiliki dependensi standar sendiri dalam skrip setup.py.

Jika menggunakan gcloud CLI untuk menjalankan tugas pelatihan, Anda dapat menentukan dependensi pada mesin lokal, serta di Cloud Storage, dan alat tersebut akan menampilkannya di cloud untuk Anda: saat menjalankan perintah gcloud ai-platform jobs submit training, tetapkan flag --packages untuk menyertakan dependensi dalam daftar yang dipisahkan koma.

Setiap URI yang Anda sertakan adalah jalur ke paket distribusi, yang diformat sebagai tarball (.tar.gz) atau sebagai roda (.whl). AI Platform Training menginstal setiap paket menggunakan pip install di setiap mesin virtual yang dialokasikan untuk tugas pelatihan Anda.

Contoh di bawah menentukan dependensi paket dengan nama dep1.tar.gz dan dep2.whl (masing-masing dari jenis paket yang didukung) bersama dengan jalur ke sumber aplikasi:

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket $PACKAGE_STAGING_PATH \
    --package-path /Users/mluser/models/faces/trainer \
    --module-name $MODULE_NAME \
    --packages dep1.tar.gz,dep2.whl \
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

Demikian pula, contoh di bawah menentukan dependensi paket dengan nama dep1.tar.gz dan dep2.whl (masing-masing dari jenis paket yang didukung), tetapi dengan aplikasi pelatihan yang telah dibangun:

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket $PACKAGE_STAGING_PATH \
    --module-name $MODULE_NAME \
    --packages trainer-0.0.1.tar.gz,dep1.tar.gz,dep2.whl
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

Jika Anda menjalankan tugas pelatihan menggunakan AI Platform Training and Prediction API secara langsung, Anda harus menentukan sendiri paket dependensi di lokasi Cloud Storage, lalu menggunakan jalur ke paket di lokasi tersebut.

Membuat paket secara manual

Mengemas kode Python adalah topik yang sangat luas dan berada di luar cakupan dokumentasi ini. Untuk memudahkan, bagian ini menyediakan ringkasan penggunaan Setuptools untuk membuat paket Anda. Ada library lain yang dapat Anda gunakan untuk melakukan hal yang sama.

Catatan: Tidaklah penting untuk mem-build paket secara manual meskipun Anda perlu melakukan beberapa operasi penyiapan saat paket aplikasi diinstal. Sebagai gantinya, Anda dapat menyertakan file __init__.py kustom di direktori utama paket dan menggunakan Google Cloud CLI untuk membuat serta mengupload paket. Jika Anda menyertakan --package-path saat menjalankan perintah gcloud ai-platform jobs submit, alat ini akan otomatis mencari file __init__.py untuk digunakan.

Ikuti langkah-langkah berikut untuk membuat paket Anda secara manual:

1. Di setiap direktori paket aplikasi, sertakan file bernama __init__.py, yang mungkin kosong atau berisi kode yang berjalan saat paket tersebut (modul apa pun dalam direktori tersebut) diimpor.

2. Dalam direktori induk semua kode yang ingin Anda sertakan dalam paket distribusi .tar.gz (satu direktori naik dari direktori trainer jika Anda mengikuti pola yang direkomendasikan), sertakan file Setuptools bernama setup.py yang menyertakan:

   • Pernyataan impor untuk setuptools.find_packages dan setuptools.setup.

   • Panggilan ke setuptools.setup dengan (setidaknya) parameter berikut ditetapkan:

     • _name_ ditetapkan ke nama namespace paket Anda.

     • _version_ ditetapkan ke nomor versi build paket Anda ini.

     • _install_requires_ ditetapkan ke daftar paket yang diperlukan oleh aplikasi Anda, dengan persyaratan versi, seperti 'docutils>=0.3'.

     • _packages_ ditetapkan ke find_packages(). Tindakan ini akan memberi tahu Setuptools untuk menyertakan semua subdirektori direktori induk yang berisi file __init__.py sebagai "impor paket" (Anda import modul dari ini di Python dengan pernyataan seperti from trainer import util) dalam "paket distribusi" Anda (file `.tar.gz yang berisi semua kode).

     • _include_package_data_ ditetapkan ke True.

3. Jalankan python setup.py sdist untuk membuat paket distribusi .tar.gz Anda.

Struktur project yang direkomendasikan

Anda dapat menyusun aplikasi pelatihan dengan cara apa pun sesuai keinginan. Namun, struktur berikut biasanya digunakan dalam contoh Pelatihan AI Platform, dan memiliki organisasi project yang mirip dengan contoh dapat mempermudah Anda mengikuti contoh tersebut.

• Gunakan direktori project utama, yang berisi file setup.py Anda.

  Gunakan fungsi find_packages() dari setuptools dalam file setup.py untuk memastikan semua subdirektori disertakan dalam paket distribusi .tar.gz yang Anda build.

• Gunakan subdirektori bernama trainer untuk menyimpan modul aplikasi utama.

• Beri nama modul aplikasi utama Anda task.py.

• Buat subdirektori lain dalam direktori project utama yang diperlukan untuk mengimplementasikan aplikasi Anda.

• Buat file __init__.py di setiap subdirektori. File ini digunakan oleh Setuptools untuk mengidentifikasi direktori dengan kode yang akan dikemas, dan mungkin kosong.

Dalam contoh Pelatihan AI Platform, direktori trainer biasanya berisi file sumber berikut:

• task.py berisi logika aplikasi yang mengelola tugas pelatihan.

• model.py berisi logika model.

• util.py jika ada, berisi kode untuk menjalankan aplikasi pelatihan.

Saat Anda menjalankan gcloud ai-platform jobs submit training, tetapkan --package-path ke trainer. Dengan demikian, gcloud CLI mencari file setup.py dalam parent trainer, direktori project utama Anda.

Modul Python

Paket aplikasi Anda dapat berisi beberapa modul (file Python). Anda harus mengidentifikasi modul yang berisi titik entri aplikasi Anda. Layanan pelatihan menjalankan modul tersebut dengan memanggil Python, sama seperti Anda menjalankannya secara lokal.

Misalnya, jika mengikuti struktur yang direkomendasikan dari bagian sebelumnya, modul utama Anda adalah task.py. Karena modul tersebut berada di dalam paket impor (direktori dengan file __init__.py) bernama trainer, nama modul ini yang sepenuhnya memenuhi syarat adalah trainer.task. Jadi, jika Anda mengirimkan tugas dengan gcloud ai-platform jobs submit training, setel flag --module-name ke trainer.task.

Lihat panduan Python untuk paket guna mengetahui informasi selengkapnya tentang modul.

Menggunakan gcloud CLI untuk mengupload paket yang sudah ada

Jika mem-build paket sendiri, Anda dapat menguploadnya dengan gcloud CLI. Jalankan perintah gcloud ai-platform jobs submit training:

• Tetapkan flag --packages ke jalur ke aplikasi terpaket Anda.

• Tetapkan flag --module-name ke nama modul utama aplikasi Anda, menggunakan notasi titik namespace paket Anda. Ini adalah file Python yang Anda jalankan untuk memulai aplikasi. Misalnya, jika modul utama Anda adalah .../my_application/trainer/task.py (lihat struktur project yang direkomendasikan), maka nama modulnya adalah trainer.task.

Contoh di bawah ini menunjukkan cara menggunakan paket tarball yang di-zip (di sini disebut trainer-0.0.1.tar.gz) yang berada di direktori yang sama tempat Anda menjalankan perintah. Fungsi utama berada dalam modul bernama task.py:

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket $PACKAGE_STAGING_PATH \
    --job-dir $JOB_DIR \
    --packages trainer-0.0.1.tar.gz \
    --module-name $MODULE_NAME \
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

Menggunakan gcloud CLI untuk memakai paket yang ada di cloud

Jika membangun paket sendiri dan menguploadnya ke lokasi Cloud Storage, Anda dapat menguploadnya dengan gcloud. Jalankan perintah gcloud ai-platform jobs submit training:

• Tetapkan flag --packages ke jalur ke aplikasi terpaket Anda.

• Tetapkan flag --module-name ke nama modul utama aplikasi Anda, menggunakan notasi titik namespace paket Anda. Ini adalah file Python yang Anda jalankan untuk memulai aplikasi. Misalnya, jika modul utama Anda adalah .../my_application/trainer/task.py (lihat struktur project yang direkomendasikan), maka nama modulnya adalah trainer.task.

Contoh di bawah ini menunjukkan cara menggunakan paket tarball ber-zip yang ada di bucket Cloud Storage:

gcloud ai-platform jobs submit training $JOB_NAME \
    --job-dir $JOB_DIR \
    --packages $PATH_TO_PACKAGED_TRAINER \
    --module-name $MODULE_NAME \
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

Dengan $PATH_TO_PACKAGED_TRAINER adalah variabel lingkungan yang mewakili jalur ke paket yang ada yang sudah ada di cloud. Misalnya, jalurnya dapat mengarah ke lokasi Cloud Storage berikut, yang berisi paket tarball zip yang disebut trainer-0.0.1.tar.gz:

PATH_TO_PACKAGED_TRAINER=gs://$CLOUD_STORAGE_BUCKET_NAME/trainer-0.0.0.tar.gz

Mengupload paket secara manual

Anda dapat mengunggah paket Anda secara manual jika ada alasan untuk melakukannya. Alasan yang paling umum adalah Anda ingin memanggil AI Platform Training and Prediction API secara langsung untuk memulai tugas pelatihan. Cara termudah untuk mengupload paket dan dependensi kustom apa pun ke bucket Cloud Storage secara manual adalah menggunakan alat gsutil:

gsutil cp /local/path/to/package.tar.gz  gs://bucket/path/

Namun, jika Anda dapat menggunakan command line untuk operasi ini, cukup gunakan gcloud ai-platform jobs submit training untuk mengupload paket sebagai bagian dari penyiapan tugas pelatihan. Jika tidak dapat menggunakan command line, Anda dapat menggunakan library klien Cloud Storage untuk mengupload secara terprogram.

Langkah selanjutnya

• Mengonfigurasi dan menjalankan tugas pelatihan.
• Pantau tugas pelatihan Anda saat tugas tersebut berjalan.
• Pelajari lebih lanjut cara kerja pelatihan.