Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
Menggunakan lingkungan virtual Python dengan AWS Lem
Dimulai dengan AWS Glue 5.0, Anda dapat menjalankan pekerjaan ETL Anda di lingkungan virtual Python (venv). Lingkungan virtual menghapus resolusi ketergantungan runtime dari proses pekerjaan Anda, memastikan bahwa setiap proses menggunakan paket yang sama, dan mencegah kegagalan yang disebabkan oleh perubahan paket upstream.
AWS Lem mendukung dua cara untuk menggunakan lingkungan virtual:
-
Service-generated lingkungan virtual - Tersedia di AWS Glue 6.0 dan yang lebih baru. Anda menambahkan
--python-virtual-env-storage-prefixparameter, dan AWS Glue membuat lingkungan virtual untuk Anda dan menyimpannya di Amazon S3 untuk menjalankan tugas nanti. Tidak diperlukan pembangunan lokal. -
Lingkungan virtual yang dibangun secara manual - Tersedia di AWS Glue 5.0 dan yang lebih baru. Anda membangun lingkungan virtual di mesin lokal Anda atau dalam CI/CD pipeline, mengunggahnya ke Amazon S3, dan merujuknya dengan
--python-virtual-envparameter.
Topik ini menjelaskan cara memigrasi pekerjaan yang digunakan --additional-python-modules untuk salah satu pendekatan. Untuk informasi tentang metode lain dalam mengelola dependensi Python, lihatMenggunakan pustaka Python dengan AWS Lem.
Perbedaan utama dari --additional-python-modules
Tabel berikut membandingkan --additional-python-modules dengan lingkungan virtual yang dibangun secara manual.
Fitur |
|
|
|---|---|---|
Pustaka wadah dasar (boto3numpy,pandas,, dan lainnya) |
Tersedia secara otomatis |
Tidak tersedia. Anda harus menyertakan semua paket yang diperlukan di venv. |
Resolusi ketergantungan |
Terjadi saat runtime |
Terjadi pada waktu pembuatan pada mesin Anda |
Isolasi runtime |
Sebagian. Paket diinstal di atas pustaka dasar. |
Penuh. Mengganti lingkungan Python sepenuhnya. |
penting
Saat Anda bermigrasi ke--python-virtual-env, Anda harus menyertakan setiap paket Python yang dibutuhkan pekerjaan Anda di lingkungan virtual. Ini termasuk paket yang sebelumnya tersedia dari wadah dasar AWS Glue, sepertiboto3,numpy, danpandas. Paket-paket ini tidak lagi tersedia secara implisit.
Memilih pendekatan
Gunakan tabel berikut untuk memutuskan pendekatan mana yang sesuai dengan pekerjaan Anda.
Skenario |
Pendekatan yang disarankan |
|---|---|
Pekerjaan sederhana dengan beberapa paket pip, di mana Anda tidak menginginkan overhead build |
Service-generated venv (tambahkan |
Pohon ketergantungan kompleks, reproduktifitas penuh, atau CI/CD pipa yang membangun venv |
Venv ( |
Bermigrasi dari |
Service-generated venv (tambahkan |
PyPIIndeks pribadi dengan paket khusus |
Salah satu pendekatan. Venv yang dihasilkan layanan membutuhkan AWS Glue 6.0 atau lebih baru dan berfungsi dengan. --python-modules-installer-option |
Menggunakan lingkungan virtual yang dihasilkan layanan dengan caching Amazon S3
Dimulai dengan AWS Glue 6.0, Anda dapat menggunakan --python-virtual-env-storage-prefix parameter untuk membuat AWS Glue membangun lingkungan virtual dan menyimpannya di Amazon S3. Pendekatan ini menggabungkan kesederhanaan --additional-python-modules dengan manfaat kinerja dari lingkungan virtual yang di-cache.
Cara kerjanya
Saat Anda menyediakan--python-virtual-env-storage-prefix, AWS Glue melakukan hal berikut:
-
Pada proses pertama (cache miss) - AWS Glue menciptakan lingkungan virtual dengan
--system-site-packages, yang mewarisi paket kontainer sepertinumpy,pandas, danpyarrow. AWS Glue kemudian menginstal paket dari --additional-python-modules dengan pip, mengemas lingkungan virtual sebagai.tar.gzfile, dan mengunggahnya ke awalan Amazon S3 Anda untuk digunakan kembali nanti. -
Saat dijalankan nanti (cache hit) — AWS Glue mengunduh
.tar.gzfile yang di-cache dari Amazon S3, mengekstraknya, dan mengonfigurasi driver Spark dan pelaksana untuk menggunakan lingkungan virtual. Tidak ada instalasi pip yang terjadi.
Perbedaan dari lingkungan virtual yang dibangun secara manual
Tabel berikut membandingkan lingkungan virtual yang dihasilkan layanan dengan pendekatan yang dibuat secara manual.
Fitur |
Service-generated venv |
Venv yang dibangun secara manual |
|---|---|---|
Bangun tanggung jawab |
AWS Lem membangun venv secara otomatis |
Anda membangun venv di Docker |
Paket kontainer |
Diwarisi melalui |
Anda harus menyertakan semua paket secara eksplisit |
First-run latensi |
Waktu tambahan untuk instalasi pip, pengemasan, dan unggahan Amazon S3 |
Tidak ada, karena venv sudah dibangun sebelumnya |
Later-run latensi |
Waktu tambahan untuk pengunduhan dan ekstraksi Amazon S3 |
Waktu tambahan untuk unduhan dan ekstraksi Amazon S3 |
Determinisme |
Kami menyarankan Anda menyematkan versi paket |
Sepenuhnya deterministik, karena versi dikunci pada waktu pembuatan |
PyPIakses |
Diperlukan pada putaran pertama |
Tidak diperlukan, karena venv dibangun secara offline |
Mengkonfigurasi lingkungan virtual yang dihasilkan layanan
--python-virtual-env-storage-prefixParameter menentukan lokasi Amazon S3 tempat AWS Glue menyimpan lingkungan virtual yang dibangunnya, dalam formulirs3://. AWS Glue menyimpan lingkungan virtual pada awalan ini pada pekerjaan pertama yang dijalankan dan menggunakannya kembali saat dijalankan nanti.path/
Untuk mengaktifkan lingkungan virtual yang dihasilkan layanan, tambahkan --python-virtual-env-storage-prefix parameter ke pekerjaan Anda dan simpan parameter yang ada--additional-python-modules.
"--additional-python-modules": "requests==2.32.3,scikit-learn==1.5.0" "--python-virtual-env-storage-prefix": "s3://amzn-s3-demo-bucket/venv-cache/"
Anda juga dapat menggunakan parameter opsional berikut:
-
--python-virtual-env-version— Pengidentifikasi versi untuk lingkungan virtual yang di-cache. Ubah nilai ini untuk membatalkan cache dan memaksa AWS Glue untuk membangun kembali lingkungan virtual. Nilainya adalah string, sehingga Anda dapat menggunakan skema versi mana pun yang sesuai dengan alur kerja Anda, seperti nomor inkrementasi, tanggal, atau pengidentifikasi build. Nilai default-nya adalah0. -
--python-modules-installer-option— Berikan opsi ke pip, seperti
--no-depsatau--index-url.
Untuk mengaktifkan caching untuk pekerjaan yang sudah ada, tambahkan parameter awalan penyimpanan. Proses pertama membutuhkan waktu lebih lama karena AWS Glue membangun dan mengunggah lingkungan virtual, tetapi kemudian dijalankan menggunakan lingkungan virtual yang di-cache dan tidak melakukan resolusi pip.
# Before "--additional-python-modules": "requests==2.32.3" # After "--additional-python-modules": "requests==2.32.3" "--python-virtual-env-storage-prefix": "s3://amzn-s3-demo-bucket/venv-cache/"
Bagaimana AWS Lem menyimpan lingkungan virtual
AWS Rekatkan kunci cache dengan konfigurasi pekerjaan Anda. Konfigurasi mencakup modul dari--additional-python-modules, nilai--python-modules-installer-option, versi AWS Glue, dan nilai--python-virtual-env-version.
Konfigurasi yang tidak berubah menghasilkan hit cache. Jika Anda mengubah salah satu nilai ini, AWS Glue membangun lingkungan virtual baru dan membuat entri cache baru.
AWS Glue menyimpan setiap lingkungan virtual yang di-cache di bawah kunci terpisah di awalan penyimpanan Anda. Pekerjaan yang menggunakan modul dan opsi penginstal yang sama berbagi entri cache yang sama.
Batasan
-
Membutuhkan AWS Glue 6.0 atau yang lebih baru.
-
Proses pertama memerlukan akses kePyPI, atau ke indeks pribadi Anda, untuk resolusi ketergantungan.
-
Paket kontainer seperti numpy dan pandas diwariskan tetapi tidak disematkan versi. Jika pekerjaan Anda memerlukan versi paket kontainer yang tepat, gunakan sebagai
--python-virtual-envgantinya. -
Cache dikunci oleh konfigurasi. Mengubah modul atau versi apa pun membuat entri cache baru, dan entri sebelumnya tetap ada di Amazon S3 sampai Anda menghapusnya.
Membangun lingkungan virtual Anda sendiri
Di AWS Glue 5.0 dan yang lebih baru, Anda dapat membangun lingkungan virtual sendiri dan mereferensikannya dengan --python-virtual-env parameter. Gunakan pendekatan ini saat Anda membutuhkan reproduktifitas penuh, versi paket kontainer yang tepat, atau build yang berjalan dalam pipeline. CI/CD
Prasyarat
Sebelum Anda mulai, pastikan Anda memiliki yang berikut:
-
Docker
dari Docker situs web, diinstal pada mesin lokal Anda, sehingga Anda dapat membangun lingkungan virtual di AWS Glue-compatible lingkungan -
Bucket Amazon S3 untuk mengunggah lingkungan virtual yang dikemas
-
AWS CLI dikonfigurasi dengan izin untuk mengunggah ke Amazon S3 dan memperbarui parameter pekerjaan AWS Glue
Untuk versi Python dan detail kompatibilitas platform untuk setiap versi AWS Glue, lihatLampiran B: AWS Detail lingkungan lem.
Langkah 1: Buat file persyaratan Anda
Buat dua file persyaratan yang menentukan paket untuk lingkungan virtual Anda.
-
Unduh
base-requirements.txtuntuk versi AWS Glue Anda dari aws-glue-libs repositori di GitHub situs web. File ini mencantumkan paket yang disediakan wadah AWS Glue standar. Untuk daftar yang sama dalam panduan ini, lihatModul Python sudah disediakan di AWS Lem.-
AWS Lem 5.0 - base-requirements.txt
di situs GitHub web -
AWS Lem 5.1 - base-requirements.txt
di situs GitHub web -
AWS Lem 6.0 - base-requirements.txt
di situs GitHub web
-
-
Buat
additional-requirements.txt. Tambahkan paket dari--additional-python-modulesparameter yang ada, satu per baris. Contoh:cryptography requests-oauthlib sqlalchemy
penting
Jika pekerjaan Anda menggunakan pust AWS aka Glue Python, seperti GlueContext atauDynamicFrame, Anda juga harus menyertakan AWSGlueDataplanePython
AWS Versi lem |
Versi paket |
|---|---|
5.0 |
|
5.1 |
|
6.0 |
|
Langkah 2: Buat Dockerfile
Buat Dockerfile yang cocok dengan lingkungan versi AWS Glue target Anda. Untuk detail platform dan versi Python, lihatLampiran B: AWS Detail lingkungan lem.
AWS Glue 5.0 dan 5.1 menggunakan Python 3.11 di Amazon Linux 2023.
FROM --platform=linux/amd64 public.ecr.aws/amazonlinux/amazonlinux:2023-minimal RUN dnf install -y python3.11 zip && \ dnf clean all WORKDIR /build
AWS Glue 6.0 menggunakan Python 3.13 di Amazon Linux 2023.
FROM --platform=linux/amd64 public.ecr.aws/amazonlinux/amazonlinux:2023-minimal RUN dnf install -y python3.13 zip && \ dnf clean all WORKDIR /build
Langkah 3: Bangun dan mulai wadah
Bangun Docker gambar. Kemudian mulai wadah dengan file persyaratan Anda dan skrip pekerjaan terpasang.
docker build --platform linux/amd64 -t glue-venv-builder . docker run --platform linux/amd64 \ -v $(pwd)/base-requirements.txt:/working_dir/base-requirements.txt:ro \ -v $(pwd)/additional-requirements.txt:/working_dir/additional-requirements.txt:ro \ -v $(pwd)/my_glue_script/:/working_dir/my_glue_script/:ro \ -v $(pwd):/output \ -w /working_dir \ -it glue-venv-builder bash
Perintah ini memasang file persyaratan Anda dan direktori skrip pekerjaan AWS Glue Anda. Langkah berikut menggunakan direktori skrip untuk analisis impor.
Langkah 4: Buat venv sementara dan temukan paket yang diperlukan
Di dalam wadah, buat venv sementara yang mencerminkan runtime AWS Glue. Kemudian gunakan analisis statis untuk menemukan set paket minimal yang dibutuhkan pekerjaan Anda.
Untuk AWS Glue 5.0 dan 5.1, yang menggunakan Python 3.11, jalankan perintah berikut.
# Create a temporary venv to reproduce the AWS Glue runtime environment python3.11 -m venv temp_venv source temp_venv/bin/activate python3.11 -m pip install --upgrade pip # Install base container libraries (mirrors what the AWS Glue container provides) python3.11 -m pip install -r base-requirements.txt # Install additional Python modules on top (mirrors how AWS Glue installs them at runtime) python3.11 -m pip install -r additional-requirements.txt # Freeze the full resolved environment pip freeze > full-requirements.txt # Install analysis tools python3.11 -m pip install pipreqs pip-tools # Use pipreqs to discover what the script actually imports # --mode no-pin outputs package names without versions pipreqs --mode no-pin --savepath discovered-requirements.txt /working_dir/my_glue_script # Remove packages provided by the Spark runtime sed -i '/pyspark/d' discovered-requirements.txt sed -i '/py4j/d' discovered-requirements.txt # Remove awsglue - install AWSGlueDataplanePython in Step 5 instead sed -i '/awsglue/d' discovered-requirements.txt # Use pip-compile to resolve the full dependency tree of the discovered packages, # constrained to the versions from the temporary venv pip-compile discovered-requirements.txt -c full-requirements.txt -o final-requirements.txt echo "=== Final requirements.txt ===" cat final-requirements.txt # Deactivate and discard the temporary venv deactivate rm -rf temp_venv
Untuk AWS Glue 6.0, yang menggunakan Python 3.13, jalankan perintah berikut.
# Create a temporary venv to reproduce the AWS Glue runtime environment python3.13 -m venv temp_venv source temp_venv/bin/activate python3.13 -m pip install --upgrade pip # Install base container libraries (mirrors what the AWS Glue container provides) python3.13 -m pip install -r base-requirements.txt # Install additional Python modules on top (mirrors how AWS Glue installs them at runtime) python3.13 -m pip install -r additional-requirements.txt # Freeze the full resolved environment pip freeze > full-requirements.txt # Install analysis tools python3.13 -m pip install pipreqs pip-tools # Use pipreqs to discover what the script actually imports # --mode no-pin outputs package names without versions pipreqs --mode no-pin --savepath discovered-requirements.txt /working_dir/my_glue_script # Remove packages provided by the Spark runtime sed -i '/pyspark/d' discovered-requirements.txt sed -i '/py4j/d' discovered-requirements.txt # Remove awsglue - install AWSGlueDataplanePython in Step 5 instead sed -i '/awsglue/d' discovered-requirements.txt # Use pip-compile to resolve the full dependency tree of the discovered packages, # constrained to the versions from the temporary venv pip-compile discovered-requirements.txt -c full-requirements.txt -o final-requirements.txt echo "=== Final requirements.txt ===" cat final-requirements.txt # Deactivate and discard the temporary venv deactivate rm -rf temp_venv
catatan
Tinjau final-requirements.txt untuk memverifikasi bahwa itu terlihat benar. Jika pekerjaan Anda menggunakan impor dinamis atau impor bersyarat, pipreqs mungkin tidak mendeteksi mereka. Tambahkan paket tersebut ke file secara manual.
Langkah 5: Bangun venv produksi
Buat venv terakhir hanya dengan paket yang dibutuhkan pekerjaan Anda. Kemudian kemas sebagai tarball.
Untuk AWS Glue 5.0 dan 5.1, yang menggunakan Python 3.11, jalankan perintah berikut.
python3.11 -m venv pyspark_venv source pyspark_venv/bin/activate python3.11 -m pip install --upgrade pip python3.11 -m pip install -r final-requirements.txt # Install the AWS Glue Python library that matches your AWS Glue version (see the version # table in Step 1). Use 5.0.0 for AWS Glue 5.0, or 5.1.0 for AWS Glue 5.1. python3.11 -m pip install AWSGlueDataplanePython==5.0.0python3.11 -m pip install venv-pack venv-pack -f -o pyspark_venv.tar.gz cp pyspark_venv.tar.gz /output/ exit
Untuk AWS Glue 6.0, yang menggunakan Python 3.13, jalankan perintah berikut.
python3.13 -m venv pyspark_venv source pyspark_venv/bin/activate python3.13 -m pip install --upgrade pip python3.13 -m pip install -r final-requirements.txt # Install the AWS Glue Python library (see version table in Step 1) python3.13 -m pip install AWSGlueDataplanePython==6.0.0 python3.13 -m pip install venv-pack venv-pack -f -o pyspark_venv.tar.gz cp pyspark_venv.tar.gz /output/ exit
Langkah 6: Unggah ke Amazon S3
Unggah lingkungan virtual yang dikemas ke bucket Amazon S3 Anda.
aws s3 cp pyspark_venv.tar.gz s3://amzn-s3-demo-bucket/path/pyspark_venv.tar.gz
Langkah 7: Perbarui parameter pekerjaan
Perbarui konfigurasi pekerjaan AWS Glue Anda untuk digunakan --python-virtual-env sebagai pengganti--additional-python-modules.
Hapus --additional-python-modules parameter dan tambahkan --python-virtual-env parameter yang menunjuk ke tarball yang Anda unggah.
# Before "--additional-python-modules": "cryptography" # After (remove --additional-python-modules entirely) "--python-virtual-env": "s3://amzn-s3-demo-bucket/path/pyspark_venv.tar.gz"
Mengotomatiskan migrasi dengan Kiro
Jika Anda lebih suka pendekatan otomatis, Anda dapat menggunakan Kiro
Cara kerjanya
Saat Anda meminta Kiro untuk memigrasikan pekerjaan AWS Glue Anda dari --additional-python-modules ke--python-virtual-env, Kiro melakukan hal berikut:
-
Mengekstrak versi AWS Glue, nilai
--additional-python-modules, dan skrip pekerjaan Anda dari permintaan Anda. -
Mengambil daftar modul wadah dasar untuk versi AWS Glue Anda dari dokumentasi AWS Glue.
-
Membuat artefak build di direktori kerja, termasuk
base-requirements.txt,additional-requirements.txt, aDockerfile, dan skrip build. -
Membangun Docker citra untuk AWS Glue-compatible lingkungan.
-
Menjalankan alur kerja penemuan dan pengemasan dalam wadah non-interaktif.
-
Menghasilkan
pyspark_venv.tar.gz, meminta Anda untuk tujuan Amazon S3, dan mengunggah tarball. -
Menunjukkan parameter pekerjaan yang diperbarui.
Contoh permintaan
Berikan versi AWS Glue Anda, modul Python tambahan Anda, dan skrip pekerjaan Anda. Contoh:
I have a Glue 5.1 job with the following: --additional-python-modules: ephem, awscli Glue job script: import awscli import ephem Help me migrate to using --python-virtual-env.
Mendapatkan skill Kiro
File venv-migration keterampilan dipertahankan di aws-glue-libs repositori daripada di panduan ini. Untuk file keterampilan dan instruksi instalasi, lihat keterampilan venv-migration
Batasan
-
Kiro Docker harus tersedia di lingkungan baris perintah.
-
Impor dinamis dan impor bersyarat yang tidak terlihat di sumber skrip Anda tidak terdeteksi secara otomatis. Tinjau
final-requirements.txtfile yang dihasilkan dan tambahkan paket yang hilang secara manual. -
Jika pekerjaan Anda menggunakan indeks pip pribadi dengan
--index-url, Anda harus mengonfigurasi akses jaringan ke indeks tersebut di Docker wadah. -
Konflik pip selama pembuatan mungkin memerlukan resolusi manual. Untuk informasi selengkapnya, lihat Pemecahan masalah.
Pemecahan masalah
Gunakan bagian berikut untuk menyelesaikan masalah umum saat menggunakan lingkungan virtual Python dengan AWS Glue.
Menyelesaikan konflik versi pip
Konflik versi pip berarti bahwa dua paket memerlukan versi yang tidak kompatibel dari ketergantungan yang sama. Untuk menemukan dan memperbaiki konflik, lakukan hal berikut:
-
Baca output kesalahan pip. Ketika resolusi gagal secara langsung, output menamai setiap persyaratan yang saling bertentangan dan paket yang memperkenalkannya.
-
Pratinjau apa yang akan diselesaikan pip tanpa menginstal apa pun. Tambahkan
--dry-run --report install-report.jsonke perintah install Anda, seperti pada contoh berikut.pip install -r additional-requirements.txt --dry-run --report install-report.json -
Periksa
install-report.json. Laporan mencantumkan setiap paket yang dipilih pip, yang mengungkapkan penurunan nilai diam. -
Relakskan pin versi pada paket non-kritis, atau hapus kendala.
Menyelesaikan ModuleNotFoundError
Kesalahan ini menunjukkan bahwa lingkungan virtual Anda tidak menyertakan paket yang diperlukan. Penyebab umum meliputi:
-
Anda tidak menyertakan pustaka kontainer dasar yang dibutuhkan pekerjaan Anda. Lingkungan virtual yang dibuat secara manual tidak mewarisi paket dari wadah AWS Glue.
-
Pekerjaan Anda menggunakan impor dinamis yang tidak pipreqs dapat mendeteksi selama analisis statis.
-
Pekerjaan Anda membutuhkan PySpark ketergantungan pada node eksekutor.
Untuk mengatasi masalah ini, tambahkan paket yang hilang dan bangun kembali lingkungan virtual. Langkah-langkah tergantung pada pendekatan mana yang digunakan pekerjaan Anda.
-
Venv yang dibuat secara manual — Tambahkan paket ke
final-requirements.txt, lalu bangun kembali lingkungan virtual dan unggah lagi. -
Service-generated venv - Tambahkan paket ke
--additional-python-modules. Daftar modul baru mengubah kunci cache, jadi AWS Glue membangun lingkungan virtual baru pada pekerjaan yang dijalankan berikutnya.
Mengurangi ukuran tarball venv
Jika lingkungan virtual paket Anda terlalu besar, kurangi ukurannya dengan pendekatan berikut:
-
Hapus paket yang tidak perlu yang tidak diimpor oleh skrip Anda, seperti kerangka kerja pengujian dan alat pengembangan.
-
Gunakan
pip install --no-depsuntuk paket di mana Anda ingin mengontrol dependensi transitif secara manual. -
Sertakan hanya paket yang langsung diimpor skrip Anda, dan biarkan pip-compile menyelesaikan dependensi transitif minimum yang diperlukan.
Menyelesaikan kesalahan kompatibilitas platform
Kesalahan ini terjadi ketika paket di venv dibangun untuk sistem operasi atau arsitektur yang berbeda. Untuk menghindari kesalahan ini:
-
Selalu bangun lingkungan virtual di dalam Docker wadah menggunakan ben
--platform linux/amd64dera. -
Pastikan tag platform roda cocok dengan versi AWS Lem target Anda. Misalnya, AWS Glue 5.0 dan 5.1 memerlukan
manylinux2014_x86_64atau tag platform yang kompatibel. -
Jangan membangun lingkungan virtual langsung di macOS atau Windows tanpaDocker.