通过对象存储加速持久化模型缓存

1. 场景

在弹性部署服务中，模型文件通常体积较大。如果将模型文件直接打包进镜像，虽然服务启动链路相对简单，但会带来以下问题：

• 镜像体积过大，构建、推送和拉取耗时较长。
• 模型版本更新时，需要重新构建镜像并重新发布。
• 多个服务使用同一模型时，容易出现模型文件随镜像重复存储的问题。
• 镜像和模型强绑定，不利于模型版本管理和快速切换。
• 大模型文件更新频繁时，镜像维护成本较高。

为了解决上述问题，可以将镜像和模型文件解耦：

• 镜像中只保留服务运行环境、依赖库和启动逻辑。
• 模型文件单独存放在对象存储中。
• 通过对象存储加速将模型目录挂载到任务容器中。
• 通过缓存预热减少服务启动时读取模型文件的等待时间。

本文主要介绍如何通过对象存储加速挂载模型文件，实现模型与镜像解耦，并提升模型读取效率。

2. 重要说明

当前对象存储加速以只读方式挂载到任务容器中，适合读取已经提前准备好的模型文件。用户需要先将模型文件上传到对象存储指定目录，再通过对象存储加速进行配置、预热和挂载使用。

例如，将对象存储加速配置挂载到容器内 /root/data 后，服务可以从该路径读取模型文件，但不能向该路径写入新文件。若尝试写入，系统会提示 Read-only file system。

因此，对象存储加速不会自动下载模型，也不会将容器运行过程中产生的新模型文件、下载结果或缓存文件写回对象存储加速目录。请勿将该目录作为模型在线下载或运行时缓存的写入目录。

3. 使用前提

使用对象存储加速持久化模型缓存前，需要满足以下前提：

• 已准备好对象存储 Bucket。
• 已将模型文件上传到对象存储指定目录。
• 已获取对象存储访问凭证，例如 Endpoint、AccessKey、SecretKey、Bucket 名称等。
• 已确认模型服务启动时需要读取的容器内路径。
• 已确认任务运行区域与对象存储加速区域一致。

对象存储接入、权限准备、加速目录填写、区域配置、预热缓存、删除缓存等通用操作，详见《对象存储加速使用说明》文档：操作流程。

4. 整体操作流程

通过对象存储加速持久化模型缓存的整体流程如下：

5. 确认模型目录

使用对象存储加速前，需要先确认模型文件在对象存储中的目录结构，以及服务启动时需要从哪个容器路径读取模型。

例如，可以将模型文件按模型名称和版本组织为以下结构，将/models/qwen/ 作为 Bucket 内加速目录：

models/
  qwen/
    Qwen3-Coder-30B-A3B-Instruct-FP8/
      config.json
      tokenizer.json
      model-00001-of-00004.safetensors
      model-00002-of-00004.safetensors
      model-00003-of-00004.safetensors
      model-00004-of-00004.safetensors

任务容器启动后，可以将对象存储中的模型目录挂载到容器内指定路径，例如：

/mnt/models

此时模型服务可以从以下路径读取模型：

/mnt/models/Qwen3-Coder-30B-A3B-Instruct-FP8

如果镜像内的模型服务默认从 Hugging Face 缓存目录读取模型，也可以根据实际镜像逻辑，将对象存储加速配置挂载到：

/root/.cache/huggingface

具体挂载路径需要结合镜像内模型服务的读取逻辑确定。对象存储加速目录为只读挂载，只适合读取已经准备好的模型文件，不适合作为在线下载模型或运行时缓存写入目录。

6. 准备对象存储中的模型文件

在创建对象存储加速配置前，请先将模型文件上传到对象存储指定目录中。

推荐目录示例：

oss://demo-bucket/models/qwen/
oss://demo-bucket/models/deepseek/
oss://demo-bucket/models/llama/

不推荐直接使用：

oss://demo-bucket/

建议将模型文件按模型名称、模型版本或业务场景进行目录组织，例如：

models/
  qwen/
    Qwen3-Coder-30B-A3B-Instruct-FP8/
  deepseek/
    DeepSeek-R1/
  llama/
    Llama-3-8B/

不建议直接选择 Bucket 根目录作为模型加速目录。根目录下可能包含多个业务目录或无关文件，后续目录加载、缓存预热和缓存删除的范围都会变大，不利于区分不同模型或业务数据。

7. 新增对象存储配置

进入「对象存储加速」页面，点击「新增对象存储配置」，填写对象存储相关信息。

需要填写的主要信息包括：

• 配置名称
• 云服务商
• 地域
• Endpoint
• AccessKey
• SecretKey
• Bucket 名称
• 加速目录

填写对象存储配置，包括 Endpoint、AK/SK、Bucket 和加速目录，填写完成后点击「创建配置」。

创建配置时，系统会自动校验对象存储配置是否可用。配置校验通过后，该对象存储配置才会成功保存。

对象存储配置的详细操作步骤、云厂商 AccessKey 获取方式、权限说明和桶策略配置，详见《对象存储加速使用说明》文档：操作流程。

8. 配置加速区域

对象存储配置保存成功后，需要为该配置选择加速区域。

在对象存储加速列表中，点击「配置区域」，选择需要启用的加速区域。

配置加速区域主要用于准备对象存储挂载和缓存能力。配置完成后，该区域具备后续任务挂载和缓存预热能力。

需要注意：

配置加速区域不等于缓存预热。首次配置完成后，区域显示为「未同步」状态。此时已经可以挂载使用，但首次访问模型文件时可能仍需要从对象存储读取。为了提升首次访问速度，建议继续执行「预热缓存」。

区域状态说明、异常状态处理和可预热状态判断，详见《对象存储加速使用说明》文档：区域状态说明。

9. 预热模型缓存

区域配置完成后，点击「预热缓存」，选择需要提前缓存的模型目录。

预热缓存的前提是：对象存储目录中已经存在模型文件。

预热缓存需要同时选择：

• 预热区域
• 预热目录

例如，如果模型文件已经上传到：

/models/qwen/Qwen3-0.6B/

可以选择该目录进行预热。系统会将该目录下的模型文件提前加载到指定加速区域。

预热完成后，后续任务在相同区域访问该模型目录时，可以减少从远端对象存储读取模型文件的等待时间。

预热缓存的具体弹窗操作、目录树加载规则、元数据更新中状态说明，详见《对象存储加速使用说明》文档：预热缓存。

10. 在任务中挂载使用

创建或编辑任务时，打开「存储配置」开关，在「对象存储加速挂载」区域选择需要挂载的对象存储配置，并填写容器挂载路径。

操作流程如下：

打开「存储配置」开关 → 选择需要挂载的对象存储配置 → 输入容器挂载路径 → 点击「新增挂载」

常见挂载路径示例：

/mnt/models
/root/.cache/huggingface
/root/.cache/modelscope
/root/data

如果希望模型服务从指定模型目录读取模型，可以将对象存储加速配置挂载到：

/mnt/models

如果镜像内模型服务默认从 Hugging Face 缓存目录读取模型，也可以根据镜像实际逻辑挂载到：

/root/.cache/huggingface

如果只需要验证对象存储加速是否成功挂载，也可以挂载到测试路径，例如：

/root/data

建议任务运行区域与对象存储加速区域保持一致。如果任务区域与对象存储加速区域不一致，可能无法使用对应区域的缓存能力，首次访问模型时仍可能从对象存储读取。

由于对象存储加速目录为只读挂载，请确保模型服务启动时只读取该目录，不要将模型下载目录或运行时写入目录配置到对象存储加速挂载路径下。

任务挂载对象存储加速配置的完整操作步骤，详见《对象存储加速使用说明》文档：任务发布时挂载。

11. 模型读取路径示例

对象存储加速挂载完成后，服务需要从容器内的挂载路径读取模型文件。不同镜像或模型服务的启动方式不同，用户需要根据镜像内服务的实际要求，配置模型读取路径。

例如，对象存储加速配置挂载到容器内：

/mnt/models

对象存储中的模型目录为：

/models/qwen/Qwen3-0.6B/

挂载后，容器内可读取的模型路径为：

/mnt/models/qwen/Qwen3-0.6B

此时，模型服务启动时应将模型路径配置为上述容器内路径。具体参数名称和启动方式请以所使用镜像或服务框架为准。

如果对象存储目录中尚未准备模型文件，服务启动时可能无法正常加载模型。部分服务会尝试在线下载模型，但下载结果无法写入对象存储加速挂载目录，因此不建议依赖服务启动时自动下载模型。

建议在启动服务前完成以下检查：

• 模型文件已经上传到对象存储指定目录。
• 对象存储配置已经完成加速区域配置。
• 已对模型目录执行缓存预热。
• 任务中已经将对象存储加速配置挂载到服务实际读取的容器路径。
• 进入容器后，可以通过 ls 命令查看到模型文件。

12. 效果验证

任务启动后，可以进入容器查看挂载目录是否存在模型文件。

例如：

ls /mnt/models/qwen/Qwen3-0.6B/

如果能够看到对象存储中对应目录下的模型文件，说明挂载成功。

模型文件读取速度会受到模型大小、对象存储访问速度、网络环境、缓存是否完成预热、GPU 初始化耗时等因素影响，请以实际运行结果为准。

13. 删除缓存与重新预热

如果某些模型目录不再需要加速，可以在对象存储加速页面点击「删除缓存」，选择需要删除缓存的目录。

删除缓存会移除所选目录对应的数据记录，并更新加速用量。该操作不会删除对象存储中的模型源文件，也不会删除对象存储配置。

删除缓存后，如果后续任务再次访问这些模型文件，可能需要重新从对象存储读取，或重新执行缓存预热。

如果模型文件已经在对象存储中更新，建议重新执行「预热缓存」，确保后续任务读取到最新模型内容。

删除缓存的弹窗操作、加速用量变化、元数据更新中状态和 4KB 基础目录占用说明，详见《对象存储加速使用说明》文档：删除缓存。