Mengemas aplikasi pelatihan

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

Anda akan mendapatkan hasil terbaik jika menguji aplikasi pelatihan secara lokal sebelum menguploadnya ke cloud. Pelatihan dengan AI Platform Training akan menimbulkan biaya pada 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 AI Platform Training: TensorFlow, scikit-learn, atau XGBoost. Atau, build penampung kustom untuk menyesuaikan lingkungan aplikasi pelatihan Anda. Hal 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 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 menjadi dependensi aplikasi pelatihan Anda, baik berupa paket kustom maupun yang tersedia secara gratis melalui PyPI.

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

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

Menggunakan gcloud untuk memaketkan dan mengupload aplikasi Anda (direkomendasikan)

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

Untuk memudahkan, sebaiknya tentukan nilai konfigurasi Anda 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 yang sepenuhnya memenuhi syarat dari modul pelatihan Anda
• 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 output-nya
• REGION: region 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 memaketkan 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 menyusun paket pelatihan dan 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 melakukan staging 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 Pelatihan AI Platform.

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

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

• --module-name menentukan 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), nama modulnya adalah trainer.task.

• Jika Anda menentukan opsi dalam file konfigurasi (config.yaml) dan sebagai tanda command line, nilai pada command line akan menggantikan nilai dalam file konfigurasi.
• Flag -- kosong menandai akhir flag spesifik gcloud dan awal USER_ARGS yang ingin Anda teruskan ke aplikasi.
• Flag khusus untuk AI Platform Training, seperti --module-name, --runtime-version, dan --job-dir, harus ditempatkan sebelum flag -- kosong. Layanan AI Platform Training menafsirkan flag ini.
• Flag --job-dir, jika ditentukan, harus berada sebelum flag -- kosong, karena AI Platform Training menggunakan --job-dir untuk memvalidasi jalur.
• Aplikasi Anda juga harus menangani flag --job-dir, jika ditentukan. Meskipun flag muncul sebelum -- kosong, --job-dir juga diteruskan ke aplikasi Anda sebagai flag 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 flag pengiriman tugas dalam panduan untuk menjalankan tugas pelatihan.

Menggunakan 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 di AI Platform Training, tugas tersebut akan berjalan di instance pelatihan (virtual machine yang dikonfigurasi secara khusus) yang memiliki banyak paket Python umum yang sudah diinstal. Periksa paket yang disertakan dalam versi runtime yang Anda gunakan untuk pelatihan, dan catat setiap dependensi yang belum diinstal.

Ada 2 jenis dependensi yang mungkin perlu Anda tambahkan:

• Dependensi Standar, yang merupakan paket Python umum yang tersedia di PyPI.
• Paket kustom, seperti paket yang Anda kembangkan sendiri, atau yang bersifat internal dalam 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-nya. AI Platform Training menggunakan pip untuk menginstal paket Anda di 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 di atas 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, CLI tersebut akan otomatis menggunakan file setup.py untuk membuat paket.

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

python setup.py sdist

Untuk mengetahui 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-nya.

Jika menggunakan gcloud CLI untuk menjalankan tugas pelatihan, Anda dapat menentukan dependensi di komputer lokal, serta di Cloud Storage, dan alat ini akan menyiapkannya 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 wheel (.whl). AI Platform Training menginstal setiap paket menggunakan pip install di setiap virtual machine yang dialokasikan untuk tugas pelatihan Anda.

Contoh di bawah menentukan dependensi paket bernama dep1.tar.gz dan dep2.whl (masing-masing jenis paket yang didukung) beserta 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 bernama dep1.tar.gz dan dep2.whl (masing-masing jenis paket yang didukung), tetapi dengan aplikasi pelatihan yang telah di-build:

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 menjalankan tugas pelatihan menggunakan AI Platform Training and Prediction API secara langsung, Anda harus mem-build paket dependensi di lokasi Cloud Storage sendiri, lalu menggunakan jalur ke paket di lokasi tersebut.

Mem-build paket secara manual

Mengemas kode Python adalah topik luas yang sebagian besar di luar cakupan dokumentasi ini. Untuk mempermudah, bagian ini menyediakan ringkasan penggunaan Setuptools untuk mem-build paket Anda. Ada library lain yang dapat Anda gunakan untuk melakukan hal yang sama.

Catatan: Anda tidak perlu mem-build paket secara manual meskipun 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 dan mengupload paket. Jika Anda menyertakan --package-path saat menjalankan perintah gcloud ai-platform jobs submit, alat ini akan otomatis mencari file __init__.py yang akan digunakan.

Ikuti langkah-langkah berikut untuk mem-build paket secara manual:

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

2. Di direktori induk dari semua kode yang ingin Anda sertakan dalam paket distribusi .tar.gz (satu direktori di atas 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.

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

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

     • _include_package_data_ disetel ke True.

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

Struktur project yang direkomendasikan

Anda dapat menyusun aplikasi pelatihan sesuai keinginan Anda. Namun, struktur berikut biasanya digunakan dalam contoh AI Platform Training, dan dengan mengatur project Anda agar mirip dengan contoh, Anda dapat lebih mudah mengikuti contoh.

• 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 Anda.

• Beri nama modul aplikasi utama Anda task.py.

• Buat subdirektori lain apa pun di direktori project utama yang Anda perlu untuk menerapkan aplikasi.

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

Dalam contoh AI Platform Training, 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. Hal ini menyebabkan gcloud CLI mencari file setup.py di induk 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 Anda mengikuti struktur yang direkomendasikan dari bagian sebelumnya, modul utama Anda adalah task.py. Karena berada di dalam paket impor (direktori dengan file __init__.py) bernama trainer, nama yang sepenuhnya memenuhi syarat untuk modul ini adalah trainer.task. Jadi, jika Anda mengirimkan tugas dengan gcloud ai-platform jobs submit training, tetapkan tanda --module-name ke trainer.task.

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

Menggunakan gcloud CLI untuk mengupload paket yang ada

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

• Tetapkan tanda --packages ke jalur ke aplikasi yang dipaketkan.

• Tetapkan tanda --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), nama modulnya adalah trainer.task.

Contoh di bawah menunjukkan cara menggunakan paket tarball yang di-zip (disebut trainer-0.0.1.tar.gz di sini) yang berada di direktori yang sama dengan tempat Anda menjalankan perintah. Fungsi utama berada dalam modul yang disebut 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 menggunakan paket yang sudah ada di cloud

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

• Tetapkan tanda --packages ke jalur ke aplikasi yang dipaketkan.

• Tetapkan tanda --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), nama modulnya adalah trainer.task.

Contoh di bawah menunjukkan cara menggunakan paket tarball yang di-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 sudah ada di cloud. Misalnya, jalur tersebut dapat mengarah ke lokasi Cloud Storage berikut, yang berisi paket tarball yang dikompresi bernama 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 mengupload paket secara manual jika ada alasan untuk melakukannya. Alasan 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 dengan menggunakan alat perintah gcloud storage:

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

Namun, jika Anda dapat menggunakan command line untuk operasi ini, Anda hanya perlu menggunakan 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 berjalan.
• Pelajari lebih lanjut cara kerja pelatihan.