Panduan konfigurasi flag MaxFrame - MaxCompute

Dokumen ini menjelaskan flag MaxCompute, flag runtime, dan parameter runtime MaxFrame, serta menyediakan contoh konfigurasi terperinci yang mencakup makna, nilai default, rentang nilai yang tersedia, skenario umum, dan pengaturan yang direkomendasikan.

Contoh parameter MaxFrame

Flag SQL MaxCompute

Di MaxFrame, semua flag terkait SQL MaxCompute dikelola dalam kamus options.sql.settings.

from maxframe import options

options.sql.settings = {
  # Contoh: Atur waktu proses maksimum pekerjaan menjadi 72 jam.
  "odps.sql.job.max.time.hours": 72,
  # Contoh: Tentukan custom image untuk pekerjaan.
  "odps.session.image": "common",
  # Contoh: Atur konkurensi menjadi 50000 untuk semua tabel input.
  "odps.sql.split.dop": '{"*":50000}',
  # Contoh: Atur ukuran batch pemrosesan data menjadi 1024 baris.
  "odps.sql.executionengine.batch.rowcount": 1024,
}

Opsi MaxFrame

Parameter runtime MaxFrame dikonfigurasi langsung menggunakan format options.xxx. Kode berikut memberikan contohnya:

from maxframe import options

# Contoh: Atur periode retensi tautan LogView menjadi 24 jam.
options.session.logview_hours = 24

# Contoh: Atur jumlah percobaan ulang klien saat terjadi error yang dapat diulang.
options.retry_times = 3

# Contoh: Aktifkan fitur optimasi kueri bawaan MaxCompute.
options.sql.enable_mcqa = True

Flag MaxCompute

Tabel berikut menjelaskan flag umum dalam kamus options.sql.settings.

Kategori parameter	Parameter	Tujuan	Rentang nilai dan nilai default	Rekomendasi
Konkurensi dan chunking	`odps.sql.split.dop`	Mengonfigurasi tingkat paralelisme (DOP) untuk pembacaan data per tabel, menggunakan informasi statistik column-store (CMF). Parameter ini memiliki prioritas lebih tinggi daripada `split.size`. Konfigurasikan parameter ini menggunakan kamus dalam format {nama_tabel: nilai}. Untuk menargetkan tabel tertentu, gunakan nama lengkapnya: `project.[schema.]table`. Untuk menentukan chunking untuk semua tabel, gunakan tanda bintang () sebagai pencocokan, seperti `{"":50000}`.	Rentang: 1 hingga 99999. Default: None.	Saat memproses tabel besar atau menjalankan tugas berskala besar, aktifkan parameter ini secara eksplisit untuk mencapai konkurensi tinggi.
Konkurensi dan chunking	`odps.stage.mapper.split.size`	Jika informasi CMF tidak tersedia, sistem melakukan chunking tugas berdasarkan ukuran tabel input dalam MB.	Rentang: ≥ 1. Default: 256 MB.	Pertahankan nilai default.
Resource dan memori	`odps.stage.mapper.mem/reducer.mem/joiner.mem`	Mengalokasikan memori dalam MB ke satu worker untuk tahap Mapper, Reducer, dan Joiner, masing-masing.	Rentang: 1024 MB hingga 12288 MB. Default: 1024 MB.	Tingkatkan nilai ini jika Anda memproses volume data besar, menghadapi hot spot data, atau mengalami error kehabisan memori (OOM) akibat join kompleks.
Resource dan memori	`odps.stage.reducer.num / odps.stage.joiner.num`	Menetapkan secara manual jumlah instans konkuren untuk tahap Reduce dan Join.	Maksimum: 10000. Default: Dihitung secara dinamis oleh sistem.	Jika suatu pekerjaan melibatkan shuffle berskala besar, seperti GROUP BY atau `JOIN`, atau memiliki kesenjangan data, tingkatkan nilai ini untuk mendistribusikan beban komputasi.
Shuffle dan keamanan output	`odps.sql.runtime.flag.fuxi_streamline_x_EnableNormalCheckpoint` & `fuxi_ShuffleService_client_CheckpointMaxCopy`	Mengaktifkan backup untuk data antara yang dihasilkan oleh Mapper dan menetapkan jumlah replika.		Untuk pekerjaan berdurasi panjang dengan shuffle berskala besar, atur jumlah replika menjadi 2: `2 ("fuxi_ShuffleService_client_CheckpointMaxCopy": 2)`, Hal ini secara signifikan meningkatkan toleransi kesalahan dan stabilitas pembacaan data.
Shuffle dan keamanan output	`odps.sql.sys.flag.fuxi_JobMaxInternalFolderSize`	Menetapkan ukuran total maksimum dalam MB untuk data shuffle antara yang dapat dihasilkan oleh satu pekerjaan.		Jika Anda mengalami error `Internal data size exceeds limit` saat melakukan operasi shuffle pada tabel yang sangat besar, tingkatkan nilai ini.
Stabilitas komputasi dan pemantauan	`odps.sql.runtime.flag.fuxi_EnableInstanceMonitor` & `fuxi_InstanceMonitorTimeout`	Kedua parameter ini harus digunakan bersama. Mereka mengaktifkan pemantauan heartbeat untuk penjadwal Fuxi tingkat dasar dan menetapkan periode timeout dalam detik. Hal ini mencegah sistem salah mengidentifikasi UDF berdurasi panjang sebagai tidak responsif dan menghentikannya.		Untuk mengubah `fuxi_InstanceMonitorTimeout`, hubungi tim dukungan teknis untuk menambahkannya ke daftar putih.
	`odps.job.instance.retry.times`	Jumlah maksimum kali sistem secara otomatis mencoba ulang satu worker (instans) setelah gagal karena error sementara, seperti kerusakan mesin.	Default: 3. Maksimum yang direkomendasikan: 100.	Untuk mengatur nilai lebih tinggi dari default, hubungi tim dukungan teknis untuk menambahkan parameter ke daftar putih.
	`odps.dag2.compound.config`	Mengonfigurasi kebijakan reuse untuk worker tingkat dasar. Atur ke `fuxi.worker.reuse.policy:NO_REUSE` untuk menonaktifkan reuse worker.		Jika UDF memiliki risiko kebocoran memori atau polusi state, nonaktifkan reuse untuk memastikan setiap tugas berjalan di lingkungan yang bersih. Hal ini sedikit meningkatkan overhead startup tugas.
Efisiensi eksekusi dan optimasi	`odps.sql.executionengine.batch.rowcount`	Menetapkan ukuran batch dalam jumlah baris, yang merupakan unit dasar untuk pemrosesan data internal di MaxCompute.	1024	Nilai ini menyeimbangkan memori dan performa. Jika satu baris berisi data dalam jumlah besar dan menyebabkan error OOM, kurangi nilai ini. Jika komputasi sederhana, Anda dapat meningkatkan nilai ini untuk meningkatkan throughput.
	`odps.sql.runtime.flag.executionengine_EnableVectorizedExpr`	Mengaktifkan mesin eksekusi vektorisasi untuk ekspresi. Ini dapat secara signifikan meningkatkan performa operasi komputasi-intensif.		Aktifkan parameter ini saat Anda menggunakan fungsi rand() atau melakukan banyak operasi aritmetika.
	`odps.optimizer.enable.conditional.mapjoin` & `odps.optimizer.cbo.rule.filter.black`	Gunakan kedua parameter ini bersama untuk menonaktifkan HashJoin.		Atur cbo.rule.filter.black ke "hj". Ini adalah opsi ahli. Jangan konfigurasi kecuali Anda benar-benar memahami dampaknya terhadap rencana eksekusi.
	`odps.sql.split.cluster.parallel_explore`	Membaca informasi CMF secara konkuren selama tahap pemisahan tugas.		Aktifkan opsi ini jika tahap pemisahan pekerjaan memakan waktu terlalu lama.
	`odps.sql.jobmaster.memory`	Menetapkan ukuran memori untuk node Master pekerjaan.		Saat menjalankan pekerjaan shuffle yang melibatkan tabel sangat besar, tingkatkan nilai ini. Misalnya, atur ke 30000 MB.
Keamanan UDF dan fungsi	`odps.sql.udf.timeout` & `odps.function.timeout`	Mengontrol periode timeout dalam detik untuk eksekusi satu batch data di UDF atau fungsi.	Rentang: 1 hingga 3600 detik. Default: 1800 detik. Mengatur ke 0 tidak berpengaruh.
Keamanan UDF dan fungsi	`odps.sql.runtime.flag.executionengine_PythonStdoutMaxsize`	Membatasi panjang maksimum dalam MB log yang dioutput ke stdout oleh pernyataan print di Python UDF.	Maksimum: 100 MB. Default: 20 MB.	Untuk mengubah nilai ini, hubungi tim dukungan teknis untuk menambahkannya ke daftar putih.
Dependencies resource dan lingkungan	`odps.session.image`	Menentukan lingkungan runtime untuk pekerjaan. Nilainya harus berupa nama custom image yang ada di Proyek MaxCompute penyewa saat ini.
	`odps.task.major.version`	Mengunci pekerjaan ke versi utama MaxCompute tertentu untuk memastikan stabilitas fitur dan perilaku.		Ini adalah opsi ahli. Jangan konfigurasi kecuali Anda memahami dampaknya.
	`odps.storage.orc.row.group.stride` & `odps.storage.meta.file.version`	Mengontrol ukuran grup baris file ORC dan versi file metadata CMF, masing-masing.		Ini adalah opsi ahli. Jangan konfigurasi kecuali Anda memahami mekanisme tingkat dasarnya.
Parameter umum lainnya	`odps.sql.allow.fullscan`	Menentukan apakah akan mengizinkan pemindaian tabel penuh pada tabel partisi tanpa kondisi filter partisi.		Aktifkan dengan hati-hati untuk mencegah biaya tinggi tak terduga dan durasi proses yang panjang.
	`odps.sql.cfile2.field.maxsize`	Menentukan ukuran penyimpanan maksimum yang diizinkan dalam byte untuk satu bidang (kolom).	Default: 8388608 (8 MB). Maksimum: 268435456 (256 MB).	Tingkatkan nilai ini saat memproses bidang yang berisi konten sangat besar, seperti teks panjang, HTML, atau data Base64.
	`odps.sql.job.max.time.hours`	Menetapkan waktu proses maksimum dalam jam untuk seluruh pekerjaan SQL.	Maksimum: 72 jam. Default: 24 jam.
	`odps.sql.always.commit.result` & `odps.sql.runtime.flag.executionengine_EnableWorkerCommit`	Gunakan kedua parameter ini bersama untuk mengaktifkan fitur commit parsial. Bahkan jika pekerjaan gagal karena sebagian pemrosesan data gagal, hasil yang berhasil tetap di-commit.		Ini cocok untuk skenario ekstrak, transformasi, dan muat (ETL) di mana keberhasilan parsial dapat diterima.
Penulisan tabel dan CMF (kombinasi tetap)	`{ "odps.task.merge.enabled": "false", "odps.sql.reshuffle.dynamicpt": "false", "odps.sql.enable.dynaparts.stats.collection": "true", "odps.optimizer.dynamic.partition.is.first.nth.value.split.enable": "false", "odps.sql.stats.collection.aggressive": "true", }`			Ini adalah kombinasi tetap flag. Kombinasi ini memastikan bahwa informasi statistik column-store (CMF) dihasilkan dengan cepat dan akurat saat Anda menulis data ke tabel partisi dinamis. Hal ini sangat penting agar pekerjaan downstream dapat melakukan pemisahan data secara tepat menggunakan odps.sql.split.dop.

Opsi MaxFrame

Tabel berikut menjelaskan opsi bawaan utama untuk MaxFrame. Anda dapat mengonfigurasi opsi ini langsung menggunakan format options.xxx.

Nama parameter	Tujuan	Tipe	Nilai default
`options.local_timezone`	Menetapkan zona waktu lokal. Ini memengaruhi perilaku default fungsi tanggal dan waktu.	STR/None	None
`options.session.logview_hours`	Menetapkan periode retensi dalam jam untuk tautan LogView yang dihasilkan.	INT	24
`options.sql.enable_mcqa`	Menentukan apakah akan mengaktifkan fitur optimasi dan akselerasi kueri cerdas bawaan MaxCompute.	BOOL	TRUE
`options.sql.generate_comments`	Menentukan apakah akan secara otomatis menambahkan komentar ke pernyataan SQL yang dihasilkan untuk pelacakan.	BOOL	TRUE
`options.sql.auto_use_common_image`	Menentukan apakah akan secara otomatis mengonfigurasi gambar publik umum saat sistem mendeteksi bahwa kode menggunakan library dengan dependensi tambahan.	BOOL	TRUE
`options.session.max_alive_seconds` `options.session.max_idle_seconds`	Mengontrol siklus hidup sesi. `max_alive_seconds` adalah masa hidup maksimum untuk sesi. `max_idle_seconds` adalah waktu idle maksimum yang diizinkan untuk sesi. Jika waktu idle terlampaui, sesi dicabut. Nilai `max_idle_seconds` harus kurang dari atau sama dengan nilai `max_alive_seconds`.
`options.session.temp_table_lifecycle`	Menetapkan siklus hidup default dalam hari untuk tabel temporary yang dibuat menggunakan MaxFrame.	INT	1
`options.session.auto_purge_temp_tables`	Menentukan apakah akan secara otomatis membersihkan semua tabel temporary yang dibuat dalam sesi saat ini ketika sesi berakhir.	BOOL	FALSE
`options.function.default_running_options`	Menetapkan konfigurasi resource default untuk fungsi yang didaftarkan dengan dekorator `@remote`.	dict. Kunci dapat mencakup `cpu`, `memory`, dan `gpu`.

Penting

Penggunaan banyak flag khusus bergantung pada prasyarat tertentu, seperti permintaan daftar putih, manajemen custom image, dan ketergantungan pada informasi statistik CMF. Sebelum mengonfigurasi opsi lanjutan ini, hubungi tim dukungan teknis MaxCompute untuk memastikan konfigurasi Anda benar dan efektif.