HunyuanVideo社区贡献者指南：代码提交与PR流程
项目地址: https://ai.gitcode.com/tencent_hunyuan/HunyuanVideo-PromptRewrite HunyuanVideo作为开源视频生成领域的领先项目，其130亿参数规模的模型架构（README.md）为开发者提供了广阔的创新空间。本指南将系统讲解从环境配置到代码合入的全流程，帮助社区贡献者高效参与项目迭代。无论你是修复modeling_hunyuan.py中的潜在bug，还是优化configuration_hunyuan.py的参数逻辑，遵循标准化流程都是贡献成功的关键。
贡献准备与环境配置
在提交代码前，需完成基础环境搭建与贡献协议签署。HunyuanVideo采用Tencent Hunyuan Community License（LICENSE），所有贡献者需确保提交内容符合开源协议要求。开发环境需满足Python 3.8+及PyTorch 1.10+，建议使用conda创建独立虚拟环境：
conda create -n hunyuan-video python=3.9
conda activate hunyuan-video
pip install -r requirements.txt # 需从主项目仓库获取依赖文件
代码仓库采用Git版本控制，贡献者需通过以下命令克隆仓库：
git clone https://gitcode.com/tencent_hunyuan/HunyuanVideo-PromptRewrite.git
cd HunyuanVideo-PromptRewrite
分支管理策略
HunyuanVideo遵循Git Flow分支模型，主要分支包括：
- main：稳定发布分支，仅通过PR从release分支合并
- develop：开发主分支，包含最新开发特性
- feature/*：功能开发分支，从develop创建，完成后合并回develop
- hotfix/*：紧急修复分支，从main创建，修复后同步至main和develop
贡献者应基于最新develop分支创建功能分支：
git checkout develop
git pull origin develop
git checkout -b feature/prompt-rewrite-optimization
代码开发规范
编码标准
项目采用PEP 8规范（Python代码），关键模块如modeling_hunyuan.py的Transformer实现需遵循以下原则：
- 类名使用CamelCase，函数名使用snake_case
- 每个函数/类需包含Google风格文档字符串
- 代码行长度控制在120字符以内
- 使用类型注解明确函数参数与返回值类型
示例代码：
def rewrite_prompt(
original_prompt: str,
mode: str = "normal" # "normal" or "master"
) -> str:
"""优化用户输入提示词以适配模型偏好
Args:
original_prompt: 用户原始输入文本
mode: 重写模式，normal模式注重语义准确性，master模式增强视觉描述
Returns:
优化后的提示词字符串
"""
if mode not in ["normal", "master"]:
raise ValueError(f"不支持的模式: {mode}")
# 实现逻辑...
文件组织结构
新增代码应遵循现有项目结构：
HunyuanVideo-PromptRewrite/
├── configuration_hunyuan.py # 模型配置类
├── modeling_hunyuan.py # 核心模型实现
├── tokenization_hy.py # 分词器实现
├── test4consistent.py # 一致性测试脚本
└── hy.tiktoken # 分词器词表
测试与验证
所有代码提交前必须通过单元测试与一致性测试。项目提供test4consistent.py脚本用于验证关键功能一致性：
python test4consistent.py --mode prompt_rewrite
测试覆盖率需达到80%以上，新增功能需补充相应测试用例。对于prompt rewrite模块的修改，建议验证以下场景：
- 短提示词扩展（Normal模式）
- 专业摄影术语处理（Master模式）
- 多语言提示词兼容性
提交与PR流程
代码提交规范
提交信息需遵循Conventional Commits规范，格式如下：
<type>(<scope>): <description>
[可选正文]
[可选脚注]
类型(type)包括：
- feat: 新功能
- fix: 错误修复
- docs: 文档更新
- style: 代码格式调整
- refactor: 代码重构
- test: 测试相关
- chore: 构建/依赖管理
示例：
feat(prompt): 添加多语言提示词重写支持
支持中英双语提示词优化，在Normal模式下保持语义准确性，
Master模式下增强光影描述。
Closes #123
PR创建流程
完成代码开发后，通过以下步骤提交PR：
- 推送分支至远程仓库
git push origin feature/prompt-rewrite-optimization
- 在GitCode平台创建Pull Request，目标分支选择develop
- 填写PR描述，包含：
- 功能/修复说明
- 实现思路
- 测试结果
- 相关Issue链接
PR评审标准
PR需通过至少2名核心开发者评审，评审重点包括：
- 代码质量：是否符合项目编码规范
- 功能完整性：是否实现预期功能
- 测试覆盖：是否包含充分测试用例
- 性能影响：对模型推理/训练性能的影响
- 兼容性：是否保持向下兼容
贡献者权益与社区互动
成功合入PR的贡献者将被添加到项目致谢名单（README.md的Acknowledgements部分）。活跃贡献者可申请成为项目维护者，参与代码评审与 roadmap 规划。社区定期举办线上研讨会，讨论generation_config.json等关键配置的优化方向，欢迎通过项目Issue区提出建议。
常见问题解决
大文件处理
项目包含80个模型权重文件（如pytorch_model-00001-of-00080.bin），提交代码时需注意：
- 不要将权重文件纳入PR
- 使用Git LFS管理大型二进制文件
冲突解决
当本地分支与develop产生冲突时：
git checkout feature/your-feature
git fetch origin develop
git rebase origin/develop
# 解决冲突后
git push --force-with-lease origin feature/your-feature
CI/CD失败处理
PR提交后将自动触发CI流程，若检查失败：
- 查看CI日志定位错误（如测试失败、代码格式问题）
- 在本地修复后使用
git commit --amend更新提交 - 强制推送更新后的分支
贡献流程总结
通过遵循以上流程，社区贡献者可以高效参与HunyuanVideo项目迭代。无论是优化tokenization_hy.py的分词逻辑，还是改进configuration_hunyuan.py的超参数设计，每一份贡献都将推动开源视频生成技术的发展。期待你的PR能够成为项目的重要组成部分！
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
