FAQ untuk OSS Connector untuk inferensi AI/ML - Object Storage Service

Topik ini menjelaskan isu umum dan solusinya saat menggunakan fitur akselerasi inferensi OSS Connector untuk AI/ML.

Jika Anda mengalami masalah saat menggunakan connector, informasi lebih lanjut dapat ditemukan di log waktu proses connector. Jalur log default adalah /var/log/oss-connector/connector.log.

Initialization errors

Program langsung keluar setelah startup dengan pesan error failed to launch oss connector: xxx yang dicetak ke stderr. Hal ini menunjukkan adanya error selama inisialisasi connector. Tabel berikut menjelaskan error umum.

Error message	Description
MODEL_DIR not set	Variabel lingkungan `MODEL_DIR` belum diatur.
OSS_PATH not set	Variabel lingkungan `OSS_PATH` belum diatur.
OSS_ENDPOINT not set	Variabel lingkungan `OSS_ENDPOINT` belum diatur.
OSS_AUTHORIZATION_FILE_PATH not accessible	Jalur file kredensial akses yang ditentukan oleh `OSS_AUTHORIZATION_FILE_PATH` tidak dapat diakses.
OSS_ACCESS_KEY_SECRET not set	Variabel lingkungan `OSS_ACCESS_KEY_ID` telah diatur, tetapi variabel lingkungan `OSS_ACCESS_KEY_SECRET` belum diatur.
failed to infer region from endpoint	Variabel lingkungan `OSS_REGION` belum diatur, dan Wilayah tidak dapat diinfer dari variabel lingkungan `OSS_ENDPOINT`.
failed to parse config file	Gagal mengurai file konfigurasi JSON. Periksa format file tersebut.
failed to initialize log path	Gagal menginisialisasi file log.
invalid uri	Format `OSS_PATH` tidak valid. Format yang benar adalah oss://bucketname/path/.
failed to list objects	Operasi OSS ListObjects gagal. Verifikasi bahwa kredensial akses OSS benar dan Anda memiliki izin oss:ListObjects pada direktori bucket target.
failed to download metadata	Terjadi error saat mengunduh data ke direktori `MODEL_DIR`.
failed to acquire uds lock	Gagal mendapatkan lock file UDS. Periksa apakah terdapat beberapa proses utama connector yang sedang berjalan. Jika Anda perlu menjalankan beberapa proses utama connector, gunakan variabel lingkungan `CONNECTOR_UDS_PATH` untuk mengatur jalur file UDS yang berbeda untuk setiap proses utama connector.
failed to initialize connector	Error inisialisasi connector lainnya.

Untuk detail lebih lanjut, periksa log waktu proses connector di jalur default /var/log/oss-connector/connector.log.

Model file loading errors

huggingface_hub melaporkan error Repo id. Contoh:

raise HFValidationError(
huggingface_hub.errors.HFValidationError: Repo id must be in the form 'repo_name' or 'namespace/repo_name': '/var/model/qwen/Qwen3-32B/'. Use `repo_type` argument if needed.

safe_open melaporkan error incomplete metadata saat memuat file model. Contoh:

[rank0]:     with safe_open(st_file, framework="pt") as f:
[rank0]:          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[rank0]: safetensors_rust.SafetensorError: Error while deserializing header: MetadataIncompleteBuffer

Kemungkinan penyebab:

Connector runtime error: Jika pemuatan model gagal, periksa terlebih dahulu log waktu proses connector untuk mengidentifikasi error spesifik. Jalur log default adalah /var/log/oss-connector/connector.log.
Connector feature not enabled: Untuk memuat model dari direktori MODEL_DIR, Anda harus mengaktifkan fitur connector dengan mengatur variabel lingkungan LD_PRELOAD dan ENABLE_CONNECTOR.
Mount path conflict for multiple models: Saat beralih antara nilai OSS_PATH yang berbeda di bawah MODEL_DIR yang sama, cache lama dapat menyebabkan konflik. Kosongkan direktori MODEL_DIR sebelum beralih ke model yang berbeda.

Running as a non-root user

Menjalankan connector sebagai pengguna non-root dapat menyebabkan error berikut:

ERROR|log_output_file:Fail to open log file /var/log/oss-connector/default.log
ERROR|log_output_file:Fail to open log file /var/log/oss-connector/connector.log.1845009
ERROR|new_log_output_file:Failed to open log file /var/log/oss-connector/audit.log
ERROR|bind:failed to bind to '/run/modelconnector.sock'  errno=13(Permission denied)
ERROR|operator():failed to bind to path /run/modelconnector.sock errno=13(Permission denied)
ERROR|init:failed to init uds server errno=13(Permission denied)
ERROR|init_library:failed to create connector

Hal ini terjadi karena pengguna non-root tidak memiliki izin menulis pada jalur log default, konfigurasi, dan file UDS. Anda dapat menggunakan variabel lingkungan CONNECTOR_CONFIG_PATH dan CONNECTOR_UDS_PATH untuk mengatur file konfigurasi dan file UDS ke direktori yang dapat ditulis, serta menetapkan jalur log yang dapat ditulis dalam file konfigurasi.

Model file size exceeds node memory

Secara default, connector melakukan pra-ambil seluruh file model ke dalam memori. Jika ukuran file model melebihi memori yang tersedia, proses pemuatan model dapat keluar secara tak terduga dengan error Segment Fault atau OOM Kill.

Anda dapat mengambil tindakan berikut sesuai skenario Anda:

Gunakan variabel lingkungan CONNECTOR_MAX_CACHE_ADVISE_GB atau parameter pretech.maxCacheAdviseGB dalam file konfigurasi untuk membatasi ukuran cache memori untuk pra-ambil. Pembatasan penggunaan memori dapat berdampak pada performa pemuatan.
Gunakan node dengan memori lebih besar.