CargoForge3D：港口件杂货生成式三维重建系统

业务动机

为什么它不是一个简单的图生 3D Demo

件杂货码头的实际需求是把现场货物快速转成数字孪生系统中的可用资产，服务于资产归档、吊装仿真、场景可视化和尺度还原。因此系统必须覆盖采集、分割、重建、尺度校准、资产导出、任务审计和资源监控，而不是只跑通一次单图生成。

吊装触发后的快速占位

港口现场不一定先等纹理。白膜可以先用于包围盒估计、孪生场景占位、后续尺度对齐和资产入库，纹理阶段再异步补齐。

消费级双 4080 的显存约束

单张 RTX4080 16GB 可以稳定跑白膜，但 shape 与 texture 同进程同显卡容易显存不足。因此必须把两个阶段拆开并常驻不同 GPU。

开源模型的领域差距

Hunyuan3D-2.1 对港口长条钢构、堆叠管束、覆盖货物和异形件杂货的先验不足，需要用领域数据和教师模型蒸馏提升几何质量。

系统蓝图

从港口图像采集到数字孪生资产入库的完整闭环

这个项目不是把 Hunyuan3D 跑起来就结束，而是把每个阶段都工程化：输入是什么，输出是什么，占用哪块硬件，如何记录状态，失败后如何恢复，以及如何用指标证明系统容量。

01

现场采集

输入来自港口现场相机、手机、云台或吊装事件触发采集。目标不是实验室棚拍，而是在真实堆场背景中获得可重建的货物图像。

输出：原始图像、采集元信息、可选尺度参考。

02

图像预处理

背景剔除和图像筛选用于降低地面、车辆、货架、天空等干扰，让模型关注货物主体，而不是把港口环境也重建进去。

输出：source condition 图像和清理后的输入图像。

03

快速白膜

GPU0 运行 Hunyuan3D-2.1 shape pipeline，并接入 HiCache++。白膜是业务上第一个可用结果，可用于孪生占位和尺度对齐。

输出：白膜 Mesh、包围盒、面数统计、shape profile。

04

纹理生成

GPU1 运行低显存 PBR 纹理管线。纹理阶段耗时长、显存重，因此单独作为第二级队列，避免阻塞白膜吞吐。

输出：带纹理 Mesh、PBR 贴图、texture profile。

05

资产打包

系统把 GLB/OBJ、贴图、预览图和 profile.json 放入统一 job 目录，并把 artifact 元信息写入 PostgreSQL。

输出：可下载 GLB 和可审计资产记录。

06

评测迭代

运行时指标、排队时间、P95 延迟、显存峰值、失败率、mesh 统计和 LoRA 验证指标共同反馈到系统调优。

输出：Dashboard 指标和训练/评测记录。

面试叙事重点

一个 Demo 只能说明模型能跑一次；CargoForge3D 说明的是如何把生成式三维模型适配到受限工业场景：显存有限、纹理耗时长、多请求并发、任务可恢复、吞吐可量化、特定领域几何可微调。

基础模型

Hunyuan3D-2.1 在本项目中的角色

本项目把 Hunyuan3D-2.1 拆成两个工程阶段理解：第一阶段是单图白膜生成，第二阶段是基于白膜的 PBR 纹理生成和 GLB 打包。

CargoForge3D 算法总览：Hunyuan3D-2.1、HiCache++ 与领域 LoRA — 算法总览。HiCache++ 插入 Hunyuan3D-2.1 的 Shape DiT 采样循环中；件杂货领域 LoRA 由教师模型生成的 GLB 伪标签监督训练，并回接到 shape 模型以增强港口货物几何先验。

图像到三维资产链路 从现场图像到可部署 GLB

现场输入图像

→

DINOv2 图像编码

→

Shape DiT 流匹配采样

→

Shape VAE 与网格提取

→

白膜 Mesh

法线 / 位置条件视图

→

Texture Diffusion

→

PBR 烘焙与 GLB 打包

→

带纹理 GLB

Windows 与本地模型适配

针对官方工程偏 Linux 的问题，修复 CUDA 设备绑定、TorchVision 兼容、本地 HuggingFace/hy3dgen 模型路径、动态模块缓存、纹理管线设备硬编码和 shape/texture 显存释放等问题，使其能在 Windows 双 4080 工作站稳定运行。

能力边界

Hunyuan3D-2.1 仍然是单图白膜生成模型。本项目不宣称实现多视角白膜生成；双 GPU 是工程上的阶段并行，不是把同一个 DiT 模型强行拆到两张卡上做张量并行。

Shape 阶段内部发生了什么

输入图像先被编码为视觉条件，shape DiT 在 latent shape feature 上进行迭代式流匹配采样；采样完成后，shape VAE 解码 latent 表征，网格提取模块再将其转换为白膜 Mesh。对港口业务而言，这一阶段决定货物轮廓、粗拓扑、尺寸比例和是否足够可信地进入孪生场景。

Texture 阶段内部发生了什么

纹理管线会从白膜渲染法线、位置等几何条件视图，再通过 paint model 生成多视角纹理图，最后进行反投影、PBR 烘焙和 GLB 打包。它慢的原因不是单一 UNet，而是扩散推理、渲染、补洞、纹理融合和导出链路叠加。

为什么必须拆分

白膜和纹理在业务上代表不同价值。白膜偏运营，可以先用于占位、包围盒和尺度校准；纹理偏归档和展示，用于提升可识别性。拆分后，系统可以先返回中间可用结果，而不是等完整 PBR 链路结束。

技术点一

HiCache++ 白膜推理加速

港口业务中，白膜越快出来，越早能完成孪生占位、包围盒估计和后续尺度校准。HiCache++ 针对 shape 阶段的 DiT 采样循环，通过历史速度场缓存和外推减少完整前向次数。

缓存外推式采样 关键步刷新 DiT，中间步预测状态

DiT

forecast

refresh

forecast

DiT

在刷新步正常执行 DiT 前向，在缓存步用历史轨迹预测下一状态，减少最昂贵的网络调用。这个优化不改变业务输入输出，适合先生成白膜占位、后续再补纹理的港口流水线。

30 步采样40.0 s7.0 s5.7x

白膜端到端67.3 s24.0 s2.8x

服务模式串行单请求GPU0 常驻 worker低冷启动

插入位置

HiCache++ 插在 shape 采样循环内部，不改 VAE、不改网格提取、不改纹理模型和渲染器。这样下游仍然接收同样类型的 latent 输出，服务接口和资产导出格式不会改变。

服务参数

并发服务默认以 hicache 模式启动 shape worker，并暴露 shape acceleration 参数。本地脚本中 HiCache++ 采用 cache interval 3、history length 5；DMD 保留为实验选项，但不作为稳定服务默认。

验证纪律

加速不是只看秒数，还要同时看采样耗时、白膜端到端耗时、显存峰值、面数/顶点数、水密性、视觉质量，以及该白膜是否还能稳定进入纹理生成和数字孪生占位流程。

技术点二

双 GPU 异步推理服务

这个系统的核心不是“用了 Redis”，而是把 Hunyuan3D 的长耗时、重显存 Pipeline 变成可排队、可审计、可恢复、可压测的服务。

CargoForge3D FastAPI Redis PostgreSQL 双 RTX 4080 推理服务架构 — 服务架构。系统采用流水线并行而不是模型并行：GPU0 常驻白膜 worker，GPU1 常驻纹理 worker， Redis 负责阶段队列调度，PostgreSQL 负责可恢复的任务状态、事件和指标记录。

客户端Web UI、批量上传、API 调用

→

FastAPI 网关提交、查询、取消、下载、指标接口

→

Redis 优先级队列shape: high / normal / batchtexture: high / normal / batch

GPU0 白膜 WorkerHunyuan3D-2.1 shape pipelineHiCache++ 加速

GPU1 纹理 WorkerPBR paint pipeline4 views, 512 px, 低显存模式

PostgreSQL 状态库jobs、events、artifacts、profiles、heartbeats

可观测与恢复Dashboard、Prometheus 指标、watchdog、清理脚本

任务生命周期

任务状态包含 submitted、queued shape、running shape、queued texture、running texture、packing、completed、 failed、cancelled 和 retrying。每次状态迁移都会落 PostgreSQL event，便于追踪失败原因。

背压与优先级

纹理是瓶颈阶段。系统显示 backlog 和 ETA，并通过优先级队列、排队上限和降级策略避免请求无限堆在 Redis 中。

鲁棒性

Worker 持续写心跳，watchdog 检测 stale worker 和僵尸任务；停止脚本支持优雅退出、队列清理和未完成任务丢弃，避免显存长期被占用。

45.4 s白膜 P95

321.3 s纹理 P95，系统瓶颈

269P95 折算带纹理资产/天

1903P95 折算白膜资产/天

并发版仓库与一键启动

当前能够启动 Redis 并发服务的本地主目录为：

D:\tencent Hunyuan3D-2.1(new version)\Hunyuan3D-2.1-main\Hunyuan3D-2.1-main

启动脚本会检查 Hunyuan3D conda Python、8091 端口、Redis 6379、PostgreSQL、GPU 空闲显存，然后启动白膜 worker、纹理 worker、watchdog 和 FastAPI。

powershell.exe -ExecutionPolicy Bypass -File "D:\tencent Hunyuan3D-2.1(new version)\Hunyuan3D-2.1-main\Hunyuan3D-2.1-main\start_hy3d_concurrent.ps1"

状态库与可观测设计

Redis 只做队列，PostgreSQL 存长期状态，包括 job、event、artifact、profile、worker heartbeat 和用户限额。这样服务异常后能恢复，也能给 Dashboard 提供可靠的数据源。

Logs: C:\Users\admin\Documents\New project\hy3d_concurrent_logs
Jobs: C:\Users\admin\Documents\New project\hy3d_concurrent_jobs
UI:   http://127.0.0.1:8091

延迟Shape P50/P95/P99、Texture P50/P95/P99、E2E P95、queue wait定位真实瓶颈，避免只凭单次运行感受判断。

GPU显存峰值、利用率、worker busy/idle、CUDA OOM保护双 4080 服务不被隐藏显存压力拖垮。

Redis队列长度、ops/sec、latency、clients、slowlog、error replies验证 Redis 是健康队列，而不是新的系统瓶颈。

任务completed、failed、cancelled、retrying、artifact、profile JSON让每个重建请求都可审计、可复现。

技术点三

教师模型蒸馏与领域 LoRA 微调

Hunyuan3D-3.1 效果更强但不可本地开源部署，因此本项目把它作为教师模型，生成件杂货图像对应的高质量 GLB 伪标签，再把 GLB 转换为 Hunyuan3D-2.1 shape LoRA 可训练的数据格式。

数据蒸馏与预处理 教师 GLB 到 shape 监督信号

港口件杂货图像

+

教师模型 GLB

→

网格审计与清洗

→

Blender 24 视角条件渲染

→

水密化与 SDF 采样

→

Rank-16 LoRA 微调

数据格式

每个样本会生成 geometry arrays、水密 OBJ、多视角 render conditions、source_condition.png、mesh.ply 和 transforms.json。这一步把官网下载的 GLB 变成 Hunyuan3D-2.1-mesh-quality 项目可直接读取的训练样本。

A100 训练设置

训练使用 bf16、DINOv2-Large、Hunyuan3D-2.1 DiT 权重、LoRA rank 16、alpha 16、dropout 0.05、 TensorBoard loss 曲线、周期性 adapter 保存和 100 step 间隔验证。

教师数据100 组真实堆场图像 + 高质量 GLB 伪标签

适配方式Rank-16 LoRA参数高效微调

Chamfer-L10.0511 → 0.0327下降 36.0%

F-score@0.050.670 → 0.793提升 12.3 个百分点

样本审计input image、teacher GLB、split_manifest.json保证一个图像对应一个三维伪标签，并固定训练/验证划分。

Blender 渲染24 视角 RGBA render、mesh.ply、transforms.json重建原训练管线需要的多视角视觉条件。

几何转换watertight.obj、surface.npz、sdf.npz把教师 GLB 转换为 SDF 和表面监督信号。

训练选择LoRA adapters、TensorBoard logs、validation GLBs记录 loss，验证 checkpoint，并结合指标和视觉检查选择 adapter。

LoRA 实际改变什么

LoRA 只更新 shape 模型中的部分线性投影，基础模型大部分冻结。目标不是记住某一个货物，而是让模型更偏向港口领域几何：长条钢构、堆叠货物、大平面结构和异形工业件。

为什么用教师蒸馏

港口真实三维扫描成本高，难以大规模采集。更强的商业模型可以提供可扩展伪监督，但这些 GLB 不直接当作真值，而是先过滤、清洗、水密化、采样和校验后再用于训练。

如何判断有效

验证不只看 loss。Chamfer-L1 和 F-score 衡量几何对齐，GLB 可视化检查用于发现数值指标掩盖不了的失败模式，例如细长结构塌陷、工业边缘过度平滑或局部几何粘连。

交互式结果

生成式件杂货三维资产展示

页面把白膜和带纹理结果分开展示。面试时可以直接说明：白膜质量、纹理可行性、显存峰值、耗时 profile 和 GLB 打包是分阶段评估的。

Shape 25.3 s Texture 61.7 s 617k faces

LoRA 可视化检查

Base 模型与领域 Adapter 对比

LoRA 结果不是只看 loss 曲线，还要看验证样本的几何形态。这里保留可旋转 GLB，便于检查不同 checkpoint 的形状变化。

Hunyuan3D-2.1 Base

LoRA step 1500

LoRA step 2000

代码地图

面试时值得展开讲的工程模块

hy3d_concurrent/api_server.pyFastAPI 网关、任务提交、健康检查、指标接口、Prometheus 风格输出。

hy3d_concurrent/worker.pyGPU0 白膜 worker、GPU1 纹理 worker、HiCache++ 参数、CUDA 显存清理。

hy3d_concurrent/db.pyPostgreSQL 任务状态、事件日志、产物记录、profile 与 worker heartbeat。

hy3d_concurrent/watchdog.py僵尸任务检测、stale worker 判断、失败恢复、队列清理与取消逻辑。

prepare_hunyuan_cargo_dataset.pyGLB/图像清点、训练验证划分、Blender 渲染、水密化、SDF 采样和数据校验。

a100_train_cargo_lora.shA100 LoRA 训练入口、本地权重路径、TensorBoard 日志、adapter 周期保存。

项目产出

从模型适配到可运营的三维重建服务

CargoForge3D 覆盖现场采集、目标分割、白膜加速、低显存纹理生成、GLB/PBR 导出、任务审计、压测指标和领域微调。项目面向烟台港件杂货数字孪生资产生成需求设计，重点解决真实港口场景中的吞吐、显存、鲁棒性和领域适配问题。

面向件杂货码头的生成式三维重建与多 GPU 推理服务系统。