HOMIE：香港科技大学开源的基于Wan2.1的参考图转视频框架

简介

HOMIE是由香港科技大学团队开源的参考图驱动视频生成（R2V）项目，基于Wan2.1‑T2V‑14B文生视频底座二次开发，借助Qwen3‑VL‑2B‑Thinking多模态模型完成视觉特征提取，专门解决AI视频生成过程中人物、物体跨帧漂移、多主体交互失真、LOGO与文字细节丢失等现实痛点。

该项目于2026年7月21日开源推理代码与配套权重，开源协议为Apache License 2.0，面向学术研究与二次开发，可输入多张参考图片结合文本提示词，生成主体身份高度稳定的自定义视频。

一、HOMIE是什么

现有文生视频模型普遍存在主体一致性缺陷：生成视频过程中人物五官、物体外形、包装文字会随着帧变化不断变形，多个人或物体同时出现时交互逻辑错乱，很难完成定制化的人‑物主题视频。

HOMIE属于多模态增强参考图转视频框架，核心目标是实现人‑物为中心的视频个性化生成。它把参考图像的身份信息解耦编码，将细粒度多模态特征注入视频扩散模型，支持单主体多张参考图、多组不同主体同时参与视频生成，在视频序列中维持人物、商品、标识、文字OCR细节不发生畸变，输出高一致性的生成视频。

项目定位：推理级开源R2V视频生成方案，不提供WebUI界面，以脚本命令行方式运行，面向开发者、科研人员进行本地部署推理。

二、功能特色

1. 多主体身份稳定生成：支持同时传入多组参考图，区分不同人物、物体主体，跨帧维持主体外观，支持同一主体多张参考图片输入提升还原度。

2. 人‑物复杂交互还原：可生成多人、多物体互动镜头，物体姿态变换、视角切换过程中主体不会发生身份漂移。

3. LOGO与OCR文字保留：对商标、包装印刷文字、标识图案实现跨帧保留，改善传统视频生成文字乱码错乱问题。

4. 两种主体工作模式

• 主体内模式：同一个主体使用多张不同角度参考图，实现多角度镜头生成；

• 主体间模式：多个完全不同的人/物体，共同出现在同一段视频完成交互。

5. 多分辨率输出：原生支持480p（832×480）与720p两套推理脚本，可自定义视频帧数、帧率参数。

6. 特征缓存加速：支持提前提取Qwen3‑VL多模态特征保存为.pt缓存文件，多次推理无需重复执行特征提取，节省算力耗时。

三、技术细节

HOMIE整体基于DiT架构的Wan2.1‑T2V‑14B视频模型做轻量化改造，新增两大核心模块MRE与GMG，整体流程：参考图+文本提示词输入 → Qwen3‑VL‑2B‑Thinking提取细粒度多模态特征 → MRE模态参考嵌入编码主体信息 → GMG全局多模态引导自注意力注入DiT扩散块 → 潜空间扩散采样 → VAE解码输出视频。

核心模块说明

1. MRE 模态参考嵌入 Modality‑reference Embedding
   对视频帧、参考图片、MLLM多模态三类输入模态做解耦处理，为每一个独立主体分配专属嵌入向量，区分“同一主体多参考”“多个不同主体”，避免不同主体特征互相混淆干扰，实现主体身份绑定。

2. GMG 全局多模态引导自注意力 Self‑attention with Global Multimodal Guidance
   在DiT扩散块内部自注意力层增加轻量化融合分支，将大模型输出的细粒度视觉、语义特征注入视频潜空间。不改动底座模型主体权重，以增量引导方式，强制扩散生成过程贴合参考图外观细节以及文本prompt描述。

依赖模型组件

• Wan2.1‑T2V‑14B‑Diffusers：视频生成基础底座，包含VAE、T5文本编码器、DiT主干网络

• homie‑r2v‑wan2.1：HOMIE项目微调权重，包含MRE、GMG模块、Qwen连接器

• Qwen3‑VL‑2B‑Thinking：多模态大模型，专门用来提取参考图细粒度视觉特征

硬件与软件依赖

• Python环境，PyTorch≥2.4.0，适配对应CUDA版本；

• 显存需求高，720p推理建议使用多卡环境；支持FSDP分布式多卡推理加速；

• 项目提供set_env.sh一键环境配置脚本，requirements.txt管理第三方Python依赖。

文件目录简要说明

• homie_wan：模型核心实现代码；

• eval_examples：官方测试样例、参考图片、元数据示例；

• assets：项目素材资源；

• generate_mllm_feature.py：多模态特征提取脚本；

• generate.py：视频生成主推理脚本；

• infer.sh / infer_720p.sh：480p、720p开箱即用推理脚本。

四、应用场景

1. 科研实验：AI视频生成领域的主体一致性、多模态引导方向的算法复现与对比实验。

2. 商品物料生成：电商商品参考图输入，生成商品多角度动态展示短视频，保留包装LOGO印刷文字。

3. 人物定制视频原型开发：输入多张人物参考图片，生成人物动作、视角变化的测试视频素材，用于下游二次开发。

4. 数字内容研发：AIGC开发者做R2V视频工具二次开发，基于HOMIE封装Web界面、API接口。

5. 创意内容原型验证：多角色互动视频原型、IP形象动态化，测试IP跨帧稳定性效果。

注意：项目仅用于研究，输出内容需要使用者自行遵守生成内容合规要求。

五、使用方法

前置说明：全部操作基于命令行，无可视化界面。

1. 环境部署
   执行项目内置脚本bash set_env.sh，自动安装依赖，确认PyTorch、CUDA版本匹配硬件环境。

2. 下载全部三份模型权重
   通过HuggingFace CLI分别下载Wan2.1底座、HOMIE微调权重、Qwen3‑VL‑2B‑Thinking模型至本地磁盘。

3. 准备元数据jsonl文件
   构造jsonl元数据，填写reference_paths参考图片路径、prompt生成提示词，给每一组主体分配独立ID；支持多个主体同时配置。

4. 提取多模态特征（可缓存复用）
   运行generate_mllm_feature.py读取jsonl元文件，调用Qwen3‑VL模型提取视觉特征，输出.pt缓存文件以及更新后的元数据。后续多次推理可直接复用pt缓存，跳过特征提取步骤节约时间。

5. 执行视频推理生成

• 单卡运行：调用generate.py，设置分辨率、帧数、帧率参数，也可以直接运行infer.sh（480p）、infer_720p.sh（720p）；

• 多卡分布式：使用torchrun启动FSDP分布式推理，实现DiT、T5模型分片，降低单卡显存压力。

6. 输出结果：VAE解码完成后输出mp4格式视频文件。

六、竞品对比

七、常见问题解答

Q：HOMIE可以训练微调吗？是否提供训练脚本？

A：开源仓库仅开放推理相关代码，没有放出训练脚本，只支持加载官方提供的微调权重做视频生成，无法自行做二次微调训练。

Q：运行报错显存不足如何处理？

A：720p分辨率对显存消耗很高，可以优先切换为480p脚本；有硬件条件时使用多卡FSDP分布式推理，开启模型分片，能够显著降低单卡显存占用。

Q：必须使用Qwen3‑VL‑2B‑Thinking吗，可以替换其他多模态模型？

A：模型模块做了耦合绑定，当前版本只能使用Qwen3‑VL‑2B‑Thinking提取特征，直接替换其他VL模型会出现特征维度不匹配，生成效果异常。

Q：为什么生成视频里面参考物体依旧出现变形？

A：需要检查jsonl元数据主体ID配置，不同对象分配独立ID；同时建议增加同主体多角度参考图片数量，提示词避免大量冲突描述；硬件算力不足采样质量下降也会带来漂移。

Q：HOMIE是否有网页界面可以直接使用？

A：官方仓库没有内置WebUI，全部通过shell脚本、python脚本命令行运行；开发者可以基于推理接口自行封装前端页面。

Q：生成的视频可以商用吗？

A：代码遵循Apache‑2.0协议，但底层Wan2.1基座、Qwen系列模型各自有自身许可约束，需要同时遵守各个依赖模型的许可证，自行评估商用可行性。

八、相关链接

GitHub项目仓库：https://github.com/YIYANGCAI/HOMIE
arXiv论文地址：https://arxiv.org/abs/2607.18217

九、总结

HOMIE是一套面向人‑物主体一致性的开源参考图转视频推理框架，依托Wan2.1视频底座与Qwen多模态模型，通过MRE与GMG两个创新模块解决传统AI视频生成中主体漂移、多主体交互失真、LOGO文字错乱的痛点，以命令行脚本的方式完成本地视频生成，适合科研人员和AIGC开发者进行算法复现、原型开发与二次封装，受硬件条件限制，项目对显存要求较高，暂不提供训练脚本与可视化操作界面。