跳转至

数据包资源替换指南汇总

本文档说明在使用众趣 VR 模型离线数据包的场景下，当触发「一键换装」或「AI 讲房」相关异步任务后，如何将回调返回的增量资源正确替换到已部署的数据包中。

前置阅读：请先阅读 数据包部署指南，了解完整的数据包目录结构与部署方式。

一、背景说明

众趣模型离线数据包部署到您的服务器后，部分功能模块（一键换装、AI 讲房）可能会在后续产生增量资源更新。当您在众趣平台触发相关异步任务（如一键换装、AI讲房）后，任务完成时众趣会向您的服务器回调对应的增量数据包。您需要将这些增量数据包解压，并按照本文档说明的规则，替换到已部署的模型数据包对应目录中。

1.1 适用场景

场景 触发条件 回调内容
一键换装资源更新 在众趣平台对模型进行换装编辑并发布 换装相关配置文件与换装全景切图资源
AI 讲房资源更新 在众趣平台对模型配置 AI 讲房数据并发布 讲房配置文件与音频资源

1.2 已部署数据包目录结构回顾

替换操作涉及的目录层级如下（完整结构请参阅 数据包部署指南）：

{模型id}/                              # 模型数据主目录
├── version.txt                        # 模型版本信息
├── audio/                             # AI 讲房音频文件目录
├── {版本时间戳}/                       # 模型版本目录（如 2025-06-11-13-26-28）
│   ├── settings.txt                   # 模型配置文件
│   ├── settings_local.txt             # 本地化配置文件
│   ├── panoDress.txt                  # 换装配置文件（换装场景）
│   ├── locations/                     # 全景切图资源
│   ├── pano_3k/                       # 3K 全景图资源
│   ├── resources/                     # 编辑产生的资源数据
│   ├── texture_high/                  # 高分辨率纹理文件
│   └── {换装id}/                       # 换装全景切图资源目录（换装场景）
└── ...

二、一键换装 — 离线数据包资源替换

当您在众趣平台对模型触发换装流程异步任务后，任务完成时众趣会回调「换装数据相关资源」的增量数据包。收到后需要解压并替换以下文件和目录。

2.1 需替换的文件清单

替换操作涉及两个层级的目录：

模型 id 目录（{模型id}/）

序号 文件/目录 类型 说明
1 version.txt 单个文件 模型版本信息，换装发布后版本号会更新

模型版本目录（{模型id}/{版本时间戳}/）

序号 文件/目录 类型 说明
1 settings.txt 单个文件 模型配置文件，包含换装相关配置数据
2 settings_local.txt 单个文件 本地化配置文件，包含换装本地化配置
3 panoDress.txt 单个文件 换装配置文件，记录换装方案与映射关系
4 {换装id}/ 整个目录 换装全景切图资源目录，包含换装后的全景图切片

2.2 替换目录结构示意

{模型id}/
├── version.txt                        ← 替换此文件
└── {版本时间戳}/
    ├── settings.txt                   ← 替换此文件
    ├── settings_local.txt             ← 替换此文件
    ├── panoDress.txt                  ← 替换此文件
    └── {换装id}/                       ← 替换整个目录
        ├── (换装全景切图文件...)
        └── ...

2.3 替换步骤

  1. 接收回调数据包：众趣异步任务完成后，会向您配置的回调地址推送换装增量数据包（压缩包格式）。
  2. 解压数据包：将收到的压缩包解压到临时目录。
  3. 替换模型 id 目录文件：
  4. 将解压后的 version.txt 覆盖到 {模型id}/version.txt。
  5. 替换模型版本目录文件：
  6. 将解压后的 settings.txt 覆盖到 {模型id}/{版本时间戳}/settings.txt。
  7. 将解压后的 settings_local.txt 覆盖到 {模型id}/{版本时间戳}/settings_local.txt。
  8. 将解压后的 panoDress.txt 覆盖到 {模型id}/{版本时间戳}/panoDress.txt。
  9. 替换换装资源目录：
  10. 将解压后的 {换装id}/ 整个目录覆盖到 {模型id}/{版本时间戳}/{换装id}/。
  11. 注意：如果该换装 id 目录已存在，建议先删除旧目录再复制新目录，确保不残留旧文件。
  12. 验证替换结果：通过浏览器访问替换后的资源 URL，确认文件可正常加载。

2.4 截图示意

模型 id 目录 — version.txt 文件位置

换装离线数据包-模型id目录版本文件

模型版本目录 — 需替换的文件与目录

换装离线数据包-模型版本目录资源替换

2.5 注意事项

  1. 版本时间戳目录：一个模型可能存在多个版本时间戳目录（如 2025-06-11-13-26-28），请确认替换到正确的版本目录中。可通过 version.txt 中记录的版本信息确定当前生效的版本目录。
  2. 换装 id 目录：换装 id 由众趣平台生成，每次换装任务可能产生不同的换装 id。请以回调数据包中的实际目录名为准。
  3. 文件覆盖：settings.txt、settings_local.txt、panoDress.txt 均为整体覆盖，不支持增量合并。
  4. 目录完整性：{换装id}/ 目录需整体替换或新增，不要仅替换部分文件，否则可能导致换装全景图加载异常。

三、AI 讲房 — 离线数据包资源替换

当您在众趣平台对模型配置 AI 讲房数据并发布后，众趣推送的离线数据包中会包含 AI 讲房相关资源（如讲房音频文件、配置信息等）。收到后需要解压并替换以下文件和目录。

3.1 需替换的文件清单

替换操作同样涉及两个层级的目录：

模型版本目录（{模型id}/{版本时间戳}/）

序号 文件/目录 类型 说明
1 settings.txt 单个文件 模型配置文件，包含 vr_speak_data 讲房配置数据
2 settings_local.txt 单个文件 本地化配置文件，包含讲房本地化配置

模型 id 目录（{模型id}/）

序号 文件/目录 类型 说明
1 audio/ 整个目录 AI 讲房音频资源目录，包含各段落的讲解音频文件

3.2 替换目录结构示意

{模型id}/
├── audio/                             ← 替换整个目录
│   ├── (讲房音频文件...)
│   └── ...
└── {版本时间戳}/
    ├── settings.txt                   ← 替换此文件
    └── settings_local.txt             ← 替换此文件

3.3 替换步骤

  1. 接收回调数据包：众趣异步任务完成后，会向您配置的回调地址推送讲房增量数据包（压缩包格式）。
  2. 解压数据包：将收到的压缩包解压到临时目录。
  3. 替换模型版本目录文件：
  4. 将解压后的 settings.txt 覆盖到 {模型id}/{版本时间戳}/settings.txt。
  5. 将解压后的 settings_local.txt 覆盖到 {模型id}/{版本时间戳}/settings_local.txt。
  6. 替换音频资源目录：
  7. 将解压后的 audio/ 整个目录覆盖到 {模型id}/audio/。
  8. 注意：如果 audio/ 目录已存在，建议先删除旧目录再复制新目录，确保不残留旧的音频文件。
  9. 验证替换结果：通过浏览器访问替换后的音频资源 URL，确认文件可正常加载。

3.4 截图示意

模型 id 目录 — audio 音频资源目录位置

AI讲房音频文件在离线数据包位置

模型版本目录 — settings.txt 与 settings_local.txt 文件位置

AI讲房离线数据包setting替换示意

3.5 注意事项

  1. audio 目录位置：audio/ 目录位于 {模型id}/ 根目录下，与版本时间戳目录同级，不在版本时间戳目录内部。
  2. settings.txt/setting_local.txt 包含讲房配置：settings.txt 中的 vr_speak_data 字段存储了讲房段落配置、房源信息等数据，是 SDK 判断模型是否支持讲房的关键依据。
  3. 音频文件格式：音频文件通常为 MP3 格式，文件名由众趣平台生成，请保持原文件名不变。
  4. 目录完整性：audio/ 目录需整体替换，不要仅替换部分音频文件，否则可能导致讲房过程中部分段落无声音。

四、替换文件汇总对照表

以下汇总两个功能模块涉及的所有替换文件，便于快速查阅：

文件/目录 所在层级 一键换装 AI 讲房 说明
version.txt 模型 id 目录 ✅ — 模型版本信息
audio/ 模型 id 目录 — ✅ 讲房音频资源（整个目录）
settings.txt 模型版本目录 ✅ ✅ 模型配置文件
settings_local.txt 模型版本目录 ✅ ✅ 本地化配置文件
panoDress.txt 模型版本目录 ✅ — 换装配置文件
{换装id}/ 模型版本目录 ✅ — 换装全景切图资源（整个目录）

提示：settings.txt 和 settings_local.txt 在两个功能模块中均需替换。如果同时收到换装和讲房的回调数据包，请注意替换顺序，以最新的回调数据包为准。

五、通用替换流程

无论是换装还是讲房的资源替换，建议遵循以下通用流程：

5.1 标准替换流程

接收回调数据包 → 解压到临时目录 → 备份原文件 → 执行替换 → 验证资源可访问 → 清理临时文件

5.2 详细步骤

  1. 接收回调：在您的服务端配置回调接口，接收众趣推送的增量数据包。
  2. 解压数据包：将压缩包解压到服务器临时目录。
  3. 备份原文件（推荐）：在覆盖前，将原有文件备份到独立目录，便于出现问题时快速回滚。
  4. 执行替换：
  5. 对于单个文件（如 settings.txt）：直接覆盖目标路径的同名文件。
  6. 对于整个目录（如 audio/、{换装id}/）：先删除目标路径的旧目录，再将新目录复制到目标路径。
  7. 验证资源：替换完成后，通过浏览器或 curl 访问关键资源 URL，确认可正常加载。
  8. 清理临时文件：验证无误后，删除临时解压目录和备份文件（或按策略保留备份）。

5.3 注意事项

  1. CORS 配置：替换后的资源需确保 CORS 配置正确，允许前端域名跨域访问。详见 数据包部署指南 — 注意事项。
  2. CDN 缓存刷新：如果使用了 CDN 加速，替换文件后需要刷新 CDN 缓存，否则用户可能仍加载到旧资源。
  3. 并发替换：如果同时收到多个回调（如同一模型的换装和讲房同时完成），建议按回调时间顺序串行处理，避免文件写入冲突。
  4. 目录结构不可修改：替换时必须保持原有目录结构和文件名，不可重命名或调整层级，否则 SDK 将无法正确加载资源。

六、常见问题

6.1 替换后换装功能不生效

  • 检查 panoDress.txt 是否已正确替换到模型版本目录下。
  • 检查 {换装id}/ 目录是否完整复制，目录名是否与 panoDress.txt 中记录的换装 id 一致。
  • 检查 settings.txt 是否已替换，其中应包含 has_decoration 相关配置。
  • 检查 version.txt 是否已更新。

6.2 替换后讲房功能不生效

  • 检查 settings.txt 是否已正确替换，其中应包含 vr_speak_data 字段。
  • 检查 audio/ 目录是否已完整替换到模型 id 目录下（注意：是模型 id 目录，不是版本目录）。
  • 检查音频文件是否可正常访问，URL 路径是否正确。

6.3 替换后部分资源加载失败（404）

  • 确认替换的目标目录路径正确，特别注意模型 id 目录与模型版本目录的区别。
  • 确认文件名未被修改（包括大小写）。
  • 确认云存储（如 OSS）上的文件已成功上传，可通过管理控制台核实。

6.4 替换后 CDN 仍返回旧资源

  • 替换文件后需刷新 CDN 缓存，可通过云服务商控制台提交 URL 刷新或目录刷新。
  • 建议对频繁更新的资源设置较短的缓存过期时间。

6.5 同时收到换装和讲房的回调数据包

  • 两个功能模块的 settings.txt 和 settings_local.txt 可能存在重叠，请以时间戳较新的回调数据包中的文件为准。
  • 建议按回调时间顺序串行处理，避免旧数据覆盖新数据。

七、相关文档