OSS Connector for AI/ML推理側常見問題 - Object Storage Service

本文介紹使用OSS Connector for AI/ML推理加速功能時的常見問題及解決方案。

在Connector使用過程中遇到問題時，通常可以在Connector作業記錄中擷取更多資訊。作業記錄的預設路徑為/var/log/oss-connector/connector.log。

初始化錯誤

程式運行後立即結束，在stderr列印failed to launch oss connector: xxx報錯資訊。這是Connector在初始化過程中遇到錯誤。具體錯誤原因如下：

報錯資訊	說明
MODEL_DIR not set	未設定`MODEL_DIR`環境變數。
OSS_PATH not set	未設定`OSS_PATH`環境變數。
OSS_ENDPOINT not set	未設定`OSS_ENDPOINT`環境變數。
OSS_AUTHORIZATION_FILE_PATH not accessible	通過`OSS_AUTHORIZATION_FILE_PATH`設定了訪問憑證檔案路徑，但是檔案不可訪問。
OSS_ACCESS_KEY_SECRET not set	設定了`OSS_ACCESS_KEY_ID`環境變數，但是未設定`OSS_ACCESS_KEY_SECRET`環境變數。
failed to infer region from endpoint	未設定`OSS_REGION`環境變數，且無法從已設定的`OSS_ENDPOINT`環境變數中擷取OSS Region ID。
failed to parse config file	JSON格式設定檔解析失敗，請檢查格式。
failed to initialize log path	初始化記錄檔失敗。
invalid uri	`OSS_PATH`格式不正確，格式為oss://bucketname/path/。
failed to list objects	OSS ListObjects失敗，確認OSS訪問憑證正確，對目標Bucket對應目錄有oss:ListObjects許可權。
failed to download metadata	下載資料到`MODEL_DIR`目錄時遇到錯誤。
failed to acquire uds lock	擷取UDS檔案鎖失敗，檢查是否有多個Connector主進程正在運行。如果確實有運行多個Connector主進程的需要，可以通過`CONNECTOR_UDS_PATH`環境變數給每個Connector主進程設定不同的UDS檔案路徑。
failed to initialize connector	其他Connector初始化錯誤。

詳細的錯誤資訊可以從Connector作業記錄中擷取，預設路徑為/var/log/oss-connector/connector.log。

載入模型檔案報錯

huggingface_hub報Repo id錯誤，如：

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模型檔案報incomplete metadata錯誤，如：

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

可能的問題原因：

Connector運行異常：若模型載入失敗，請優先檢查Connector作業記錄以定位具體錯誤，日誌預設路徑為/var/log/oss-connector/connector.log。
未開啟Connector功能：若需通過MODEL_DIR目錄載入模型，需要通過設定環境變數LD_PRELOAD和ENABLE_CONNECTOR開啟Connector功能。
多模型掛載路徑衝突：在同一MODEL_DIR下先後切換不同的OSS_PATH啟動模型時，可能會因舊緩衝導致衝突報錯。在切換不同模型啟動前，請務必先清空MODEL_DIR目錄再進行重試。

非root賬戶運行

以非root賬戶運行Connector可能會遇到如下報錯：

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

原因是非root賬戶在Connector預設日誌、配置和UDS檔案路徑沒有寫入權限，可以通過環境變數CONNECTOR_CONFIG_PATH和CONNECTOR_UDS_PATH將設定檔和UDS檔案設定到可寫目錄，並在設定檔中設定可寫的日誌路徑。

模型檔案大小超過節點記憶體

在預設配置中，Connector會全量地將模型檔案預取到記憶體。當模型檔案大小超過可使用記憶體，可能會遇到載入模型過程中異常退出，具體可表現為Segment Fault或OOM Kill。

使用者可以根據實際情況選擇：

通過環境變數CONNECTOR_MAX_CACHE_ADVISE_GB或設定檔中pretech.maxCacheAdviseGB設定預取可以使用的記憶體緩衝大小。限制記憶體使用量可能會對載入效能產生一定影響。
使用更大記憶體的節點。