OSS Connector for AI/ML推理侧常见问题-对象存储(OSS)-阿里云帮助中心

本文介绍使用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设置预取可以使用的内存缓存大小。限制内存使用可能会对加载性能产生一定影响。
使用更大内存的节点。