HY-Motion 1.0详细步骤从HuggingFace下载→模型加载→推理→FBX导出全链路想用一句话就让3D角色动起来吗HY-Motion 1.0让这个想法变成了现实。这是一个能听懂你文字描述然后生成高质量3D人体动作的模型。无论是“一个人在做深蹲”还是“一个人从椅子上站起来伸懒腰”它都能理解并生成对应的骨骼动画。今天我就带你走一遍完整的流程从HuggingFace下载模型到加载运行再到生成动画最后导出成游戏和动画制作中常用的FBX格式。整个过程就像搭积木一步接一步咱们一起把它跑通。1. 准备工作认识你的工具在开始动手之前我们先花几分钟了解一下HY-Motion 1.0到底是什么以及我们需要准备些什么。简单来说HY-Motion 1.0是一个“文本生成3D动作”的模型。你输入一段英文描述它就能输出一套对应的人体骨骼动作数据。这套数据可以被进一步处理变成你在游戏或动画里看到的流畅角色动画。它背后用了两项挺厉害的技术Diffusion Transformer和流匹配。你不需要深究这些术语只需要知道它们结合起来让模型生成的动作既自然又精准。更重要的是这个模型的参数规模达到了十亿级别是目前开源模型里比较大的所以它的“理解能力”和“生成质量”都相当不错。1.1 模型版本选择HY-Motion 1.0提供了两个版本你可以根据自己电脑的显卡情况来选择模型版本参数量描述最低GPU显存要求HY-Motion-1.010亿 (1.0B)标准版生成质量更高约26GBHY-Motion-1.0-Lite4.6亿 (0.46B)轻量版对硬件更友好约24GB怎么选如果你的显卡显存足够比如RTX 4090 24GB或更高强烈推荐使用标准版效果更好。如果显存紧张或者想先快速体验一下那就选Lite版。另外即使使用标准版也可以通过调整一些参数比如减少生成次数、缩短动作时长来降低显存占用。1.2 环境与硬件要求接下来我们看看跑通这个流程需要什么。硬件要求GPU这是必须的。建议使用显存24GB及以上的NVIDIA显卡例如RTX 4090、RTX 3090或A100。内存建议32GB或以上。硬盘空间预留至少20GB空间用于存放模型和生成的文件。软件与环境操作系统Linux如Ubuntu 20.04/22.04是首选部分步骤在Windows上可能遇到兼容性问题。Python需要Python 3.8到3.10版本。CUDA确保安装了与你的显卡和PyTorch版本匹配的CUDA工具包建议CUDA 11.7或11.8。基础工具git,wget,conda或pip。我们的目标很明确搭建好环境把模型下载下来写个脚本让它跑起来最后把生成的动画导出成FBX文件。下面我们就开始第一步。2. 第一步环境搭建与模型下载万事开头难但只要把环境配好了后面就一马平川。这一步我们要创建一个干净的Python环境并安装所有必需的依赖包。2.1 创建并激活Python虚拟环境使用虚拟环境是个好习惯它能避免不同项目间的包版本冲突。# 1. 使用conda创建环境如果你安装了Anaconda或Miniconda conda create -n hymotion python3.9 -y conda activate hymotion # 或者使用venv创建环境 # python -m venv hymotion_env # source hymotion_env/bin/activate # Linux/Mac # hymotion_env\Scripts\activate # Windows2.2 安装PyTorch这是深度学习的基础框架。请根据你的CUDA版本去PyTorch官网获取最准确的安装命令。例如对于CUDA 11.8pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu1182.3 安装HY-Motion项目依赖我们需要克隆官方的代码仓库并安装里面列出的依赖包。# 1. 克隆代码仓库 git clone https://github.com/Tencent-Hunyuan/HY-Motion-1.0.git cd HY-Motion-1.0 # 2. 安装项目依赖 # 通常项目会提供一个requirements.txt文件 pip install -r requirements.txt # 3. 安装一些可能额外需要的包 pip install huggingface-hub # 用于从HuggingFace下载模型 pip install smplx bvhwriter # 用于处理人体模型和BVH格式 # 注意FBX导出需要Autodesk FBX SDK安装比较复杂我们稍后专门处理。2.4 从HuggingFace下载模型模型文件比较大我们使用huggingface-hub这个工具来下载。你需要先决定下载哪个版本这里以标准版为例。# download_model.py from huggingface_hub import snapshot_download # 指定模型仓库ID和你要下载的版本 model_repo_id tencent/HY-Motion-1.0 model_subdir HY-Motion-1.0 # 如果要下载Lite版则改为 HY-Motion-1.0-Lite # 指定本地保存路径 local_dir ./models/HY-Motion-1.0 # 下载模型文件 snapshot_download( repo_idmodel_repo_id, revisionmain, # 通常使用main分支 allow_patterns[f{model_subdir}/*], # 只下载指定子目录下的文件 local_dirlocal_dir, local_dir_use_symlinksFalse # 直接复制文件而不是创建符号链接 ) print(f模型已下载到: {local_dir})运行这个脚本模型文件就会下载到本地的./models/HY-Motion-1.0/目录下。这个过程可能需要一些时间因为模型文件有好几个GB。3. 第二步编写推理脚本并生成动作模型下载好了环境也齐了现在我们来写一个核心的推理脚本。这个脚本会做三件事加载模型、输入文本描述、生成动作数据。3.1 理解项目结构在写脚本前先看看HY-Motion-1.0项目目录里有什么HY-Motion-1.0/ ├── configs/ # 模型配置文件 ├── models/ # 我们刚下载的模型放这里 ├── scripts/ # 官方提供的工具脚本 ├── src/ # 源代码 ├── requirements.txt └── README.md我们需要参考scripts/或src/里的示例代码来写自己的推理脚本。3.2 基础推理脚本下面是一个最基础的推理脚本它完成了从文本到动作数据的生成。# inference_basic.py import torch import numpy as np from omegaconf import OmegaConf import sys sys.path.append(.) # 将当前目录加入Python路径以便导入项目模块 from src.models.hy_motion import HYMotionPipeline from src.utils.motion_utils import convert_to_bvh def main(): # 1. 加载配置文件 config_path ./configs/inference/hy_motion_1.0.yaml config OmegaConf.load(config_path) # 2. 指定模型路径指向你下载的文件夹 model_dir ./models/HY-Motion-1.0 config.model.pretrained_model_path model_dir # 3. 初始化推理管道 print(正在加载模型这可能需要几分钟...) pipe HYMotionPipeline.from_pretrained(config) pipe.to(cuda) # 将模型移到GPU上 print(模型加载完成) # 4. 定义你的动作描述Prompt # 注意目前只支持英文描述尽量简洁明了 text_prompt A person walks forward, then turns around and waves hand. # 其他Prompt示例 # A person performs jumping jacks. # A person sits down on a chair and reads a book. # A person stretches and then does a backflip. # 5. 设置生成参数 generator torch.Generator(devicecuda).manual_seed(42) # 设置随机种子保证结果可复现 num_frames 120 # 生成动作的帧数约4秒按30FPS计算 # 6. 执行推理生成动作 print(f正在生成动作: {text_prompt}) with torch.no_grad(): # 关闭梯度计算节省内存 motion_data pipe( prompttext_prompt, generatorgenerator, num_framesnum_frames, guidance_scale7.5, # 指导系数影响生成结果与文本的贴合程度 num_inference_steps50 # 推理步数影响生成质量和速度 ) # motion_data 是一个包含关节旋转、位置等信息的字典或张量 print(动作生成成功) print(f生成的动作数据形状: {motion_data[joint_rotations].shape if isinstance(motion_data, dict) else motion_data.shape}) # 7. 保存生成的原始数据可选便于后续调试 output_path ./output/generated_motion.npy np.save(output_path, motion_data if not isinstance(motion_data, dict) else motion_data[joint_rotations]) print(f原始动作数据已保存至: {output_path}) return motion_data if __name__ __main__: motion_data main()运行这个脚本你就能得到对应文本描述的动作数据了。终端会显示加载进度和生成结果。3.3 进阶批量生成与参数调节一次生成一个动作不过瘾我们可以试试批量生成或者调节参数来获得不同风格的结果。# inference_advanced.py import torch from inference_basic import main as load_and_generate def batch_generation(): 批量生成不同动作 prompts [ A person is dancing hip-hop., A person slowly falls down., A person picks up an object from the ground., A person practices tai chi., ] all_motions [] for i, prompt in enumerate(prompts): print(f\n--- 正在生成动作 {i1}/{len(prompts)}: {prompt} ---) # 这里需要根据实际情况调整可能需要重新初始化管道 # 为了简化我们假设有一个可以重复使用的pipe # motion pipe(promptprompt, ...) # all_motions.append(motion) print(f提示词 {prompt} 已加入队列。) print(\n批量生成完成) # 实际应用中这里应保存或处理all_motions def explore_parameters(): 探索不同生成参数的效果 print(\n 参数探索Guidance Scale ) print(guidance_scale 控制生成动作与文本描述的贴合程度。) print(- 值较低如3.0动作更自然、多样但可能偏离描述。) print(- 值较高如10.0动作更严格遵循描述但可能显得生硬。) print(推荐从7.5开始尝试根据效果微调。) print(\n 参数探索Inference Steps ) print(num_inference_steps 影响生成质量和速度。) print(- 步数少如20步生成快质量可能较低。) print(- 步数多如100步生成慢质量更高细节更丰富。) print(推荐使用50步在质量和速度间取得平衡。) if __name__ __main__: # 生成一个基础动作 base_motion load_and_generate() # 学习参数调节 explore_parameters() # 提示批量生成实际代码需根据项目API调整 # batch_generation()通过调节guidance_scale和num_inference_steps你可以对生成动作的“听话程度”和精细度进行控制多试试找到最适合你需求的组合。4. 第三步可视化与格式转换生成了一堆数字怎么看效果呢我们需要把它变成能看、能用的格式。通常有两种方式转换成BVH文件用3D软件查看或者直接用Python进行简单渲染。4.1 保存为BVH格式BVH是一种通用的骨骼动画格式可以被Blender、Maya、Unity、Unreal等几乎所有3D软件识别。# convert_to_bvh.py import numpy as np from src.utils.motion_utils import convert_to_bvh import sys sys.path.append(.) def save_as_bvh(motion_data, output_bvh_path./output/generated_motion.bvh): 将生成的动作数据转换为BVH文件。 注意此函数依赖于项目内的convert_to_bvh工具 该工具可能需要SMPL人体模型参数。 try: # 假设motion_data是之前脚本输出的字典或数组 # 这里需要根据HY-Motion项目的实际输出结构调整 if isinstance(motion_data, dict): rotations motion_data.get(joint_rotations) # 关节旋转数据 positions motion_data.get(root_translation) # 根骨骼位移可选 else: rotations motion_data # 或者motion_data本身就是旋转数据 # 调用项目内的转换函数 # 注意你需要有人体骨骼模板如SMPL的T-poseBVH template_bvh_path ./assets/smpl_template.bvh # 你需要准备这个模板文件 # convert_to_bvh(rotations, positions, template_bvh_path, output_bvh_path) print(fBVH文件理论上应保存至: {output_bvh_path}) print(请参考项目scripts/export_bvh.py或类似脚本完成具体转换。) except Exception as e: print(f转换BVH时出错: {e}) print(建议) print(1. 检查项目是否提供了export_bvh.py脚本。) print(2. 确保你有正确的人体骨骼模板BVH文件。) print(3. 查看项目README或issue寻找BVH导出指南。) if __name__ __main__: # 这里需要传入之前生成的motion_data # 为了演示我们假设有一个数据 dummy_data np.random.randn(120, 52, 3) # 示例形状[帧数, 关节数, 旋转维度] save_as_bvh(dummy_data)关键点转换BVH通常需要一个代表标准T-pose的BVH模板文件。你需要从项目提供的资源中获取或根据SMPL模型自己生成一个。4.2 使用Blender进行可视化推荐如果你有Blender这是最直观的方法将上一步生成的BVH文件导入Blender。将BVH动作数据绑定到一个角色模型上比如一个简单的人形骨骼或SMPL模型。播放时间轴就能看到角色动起来了。4.3 简单的Python渲染可选如果不想打开大型软件也可以用matplotlib或pyrender做一个简单的3D点云动画预览。这能帮你快速检查动作的大致形态。# simple_visualize.py import numpy as np import matplotlib.pyplot as plt from mpl_toolkits.mplot3d import Axes3D import matplotlib.animation as animation def visualize_joints_3d(positions_3d, save_path./output/motion_preview.gif): 简单的3D关节位置可视化。 注意此函数需要motion_data中包含3D关节位置信息。 HY-Motion可能输出的是旋转数据需要前向运动学计算得到位置。 此处仅为示例框架。 # 假设positions_3d形状为 [帧数, 关节数, 3] num_frames, num_joints, _ positions_3d.shape fig plt.figure(figsize(10, 8)) ax fig.add_subplot(111, projection3d) # 设置坐标轴范围 all_positions positions_3d.reshape(-1, 3) max_range np.array([all_positions[:, i].max() - all_positions[:, i].min() for i in range(3)]).max() / 2.0 mid_x (all_positions[:, 0].max() all_positions[:, 0].min()) * 0.5 mid_y (all_positions[:, 1].max() all_positions[:, 1].min()) * 0.5 mid_z (all_positions[:, 2].max() all_positions[:, 2].min()) * 0.5 ax.set_xlim(mid_x - max_range, mid_x max_range) ax.set_ylim(mid_y - max_range, mid_y max_range) ax.set_zlim(mid_z - max_range, mid_z max_range) ax.set_xlabel(X) ax.set_ylabel(Y) ax.set_zlabel(Z) ax.set_title(3D Motion Preview) # 绘制第一帧 frame_idx 0 scatter ax.scatter(positions_3d[frame_idx, :, 0], positions_3d[frame_idx, :, 1], positions_3d[frame_idx, :, 2], cblue, s50) def update(frame): ax.cla() ax.set_xlim(mid_x - max_range, mid_x max_range) ax.set_ylim(mid_y - max_range, mid_y max_range) ax.set_zlim(mid_z - max_range, mid_z max_range) ax.set_xlabel(X) ax.set_ylabel(Y) ax.set_zlabel(Z) ax.set_title(fFrame: {frame}) ax.scatter(positions_3d[frame, :, 0], positions_3d[frame, :, 1], positions_3d[frame, :, 2], cblue, s50) # 可以在这里添加骨骼连线 return ax, ani animation.FuncAnimation(fig, update, framesnum_frames, interval50, blitFalse) ani.save(save_path, writerpillow, fps30) print(f动作预览GIF已保存至: {save_path}) plt.close(fig) # 注意你需要从旋转数据计算3D关节位置这里跳过计算步骤。 # visualize_joints_3d(calculated_positions)这个可视化虽然简陋但能让你在不依赖其他软件的情况下快速确认动作是否生成成功。5. 第四步导出为FBX格式FBX是游戏开发和动画制作中的行业标准格式。将动作导出为FBX意味着你可以直接在Unity、Unreal Engine、Maya、Blender等软件中使用它。5.1 为什么选择FBX通用性几乎所有3D软件和游戏引擎都支持。完整性可以包含骨骼、动画、网格、材质等信息。工作流集成方便与现有的美术和开发流程对接。5.2 通过Blender中转实用方案最可靠的方法是将BVH导入Blender再通过Blender导出FBX。Blender提供了强大的Python API我们可以用脚本自动化这个过程。# blender_export_fbx.py 这是一个需要在Blender内部运行的Python脚本Blenders Python。 假设你已经有一个绑定了动作的Armature骨骼对象。 import bpy import os def export_animation_to_fbx(armature_nameArmature, output_fbx_path./output/animation.fbx): 将指定骨骼的动画导出为FBX文件。 在Blender的脚本编辑器中运行。 # 确保选中骨骼对象 if armature_name not in bpy.data.objects: print(f错误场景中找不到名为 {armature_name} 的物体。) return obj bpy.data.objects[armature_name] bpy.context.view_layer.objects.active obj obj.select_set(True) # 设置FBX导出参数 bpy.ops.export_scene.fbx( filepathoutput_fbx_path, use_selectionTrue, # 只导出选中的物体 global_scale1.0, apply_unit_scaleTrue, apply_scale_optionsFBX_SCALE_NONE, bake_space_transformFalse, object_types{ARMATURE, MESH}, # 导出骨骼和网格 use_mesh_modifiersTrue, mesh_smooth_typeOFF, add_leaf_bonesFalse, primary_bone_axisY, secondary_bone_axisX, use_armature_deform_onlyTrue, armature_nodetypeNULL, bake_animTrue, # 导出动画 bake_anim_use_all_bonesTrue, bake_anim_use_nla_stripsFalse, bake_anim_use_all_actionsFalse, bake_anim_force_startend_keyingTrue, bake_anim_step1.0, bake_anim_simplify_factor0.0, # 不简化关键帧 path_modeAUTO, embed_texturesFalse, ) print(fFBX文件已导出至: {output_fbx_path}) # 使用示例在Blender中运行 # 1. 将BVH文件导入Blender并绑定到一个人物模型骨骼上。 # 2. 在Blender的文本编辑器中打开此脚本修改armature_name为你的骨骼名称。 # 3. 运行脚本。 # export_animation_to_fbx(MyCharacterArmature, C:/output/my_animation.fbx)操作步骤简述在Blender中导入BVH文件文件-导入-Motion Capture (.bvh)。确保你有一个角色模型带骨骼的Armature。如果没有可以简单创建一个标准人形骨骼。将BVH动作数据“应用”到你的角色骨骼上使用NLA编辑器或动作约束。运行上面的Blender Python脚本指定你的骨骼名称和输出路径。5.3 使用FBX SDK直接导出高级方案对于需要集成到自动化流水线的情况你可能想直接用Python调用Autodesk FBX SDK。但这比较复杂需要安装SDK并处理C绑定。# 注意这是一个概念性示例实际实现需要安装FBX SDK并配置Python绑定。 # import fbx # 这需要先安装FBX Python SDK def export_to_fbx_with_sdk(motion_data, skeleton_template_path, output_fbx_path): 使用FBX SDK直接创建FBX文件和动画曲线。 此代码无法直接运行仅展示逻辑。 # manager fbx.FbxManager.Create() # scene fbx.FbxScene.Create(manager, MyScene) # # # 1. 创建骨骼节点 # root_node fbx.FbxNode.Create(manager, Root) # # ... 根据skeleton_template_path创建骨骼层级 # # # 2. 创建动画栈和图层 # anim_stack fbx.FbxAnimStack.Create(scene, AnimationStack) # anim_layer fbx.FbxAnimLayer.Create(scene, BaseLayer) # anim_stack.AddMember(anim_layer) # # # 3. 为每个关节的旋转属性创建动画曲线 # for joint_idx in range(num_joints): # node joint_nodes[joint_idx] # # 获取旋转属性 # rotation node.LclRotation # # 创建动画曲线 # curve_x rotation.GetCurve(anim_layer, X, True) # curve_y rotation.GetCurve(anim_layer, Y, True) # curve_z rotation.GetCurve(anim_layer, Z, True) # # 为每一帧添加关键帧 # for frame in range(num_frames): # time fbx.FbxTime().SetFrame(frame, fbx.FbxTime.eFrames30) # rot motion_data[frame, joint_idx] # 获取该帧该关节的旋转 # curve_x.KeyAdd(time)[0].Set(rot[0]) # curve_y.KeyAdd(time)[0].Set(rot[1]) # curve_z.KeyAdd(time)[0].Set(rot[2]) # # # 4. 保存文件 # exporter fbx.FbxExporter.Create(manager, ) # exporter.Initialize(output_fbx_path, -1, manager.GetIOSettings()) # exporter.Export(scene) # exporter.Destroy() # # manager.Destroy() print(此功能需要配置Autodesk FBX SDK的Python绑定。) print(对于大多数用户通过Blender中转是更简单可靠的方法。)除非你有很强的工程需求否则建议使用Blender中转方案它更稳定、社区支持更好。6. 总结与后续步骤走完上面四步你已经完成了从文本描述到FBX动画的完整链路。我们来回顾一下关键点并看看接下来还能做什么。6.1 全流程回顾环境与模型准备好了Python环境和十亿参数的HY-Motion模型。推理生成写一个脚本输入“A person walks forward, then turns around and waves hand.”这样的英文句子模型就能输出对应的骨骼动作数据。可视化转换把数据转换成BVH格式用Blender查看确保动作是你想要的。格式导出最后通过Blender将绑定好动作的角色导出为FBX文件这样就能放进游戏引擎或动画项目里用了。整个过程的核心代码其实就集中在加载模型和调用管道那几步。难点往往在于环境配置和后续的格式处理。6.2 你可能遇到的问题与解决办法问题显存不足Out of Memory解决使用HY-Motion-1.0-Lite轻量版模型。或者在推理时减少num_seeds生成次数、缩短文本长度、减少num_frames动作时长。问题生成的动作品质不高解决优化你的Prompt。用更具体、更准确的动词和副词描述动作例如“slowly walk forward” 比 “walk” 更好。适当提高guidance_scale如调到9.0和num_inference_steps如调到80。问题BVH或FBX导出失败解决确保你使用了正确的骨骼模板文件。仔细检查HY-Motion项目里是否提供了smpl_template.bvh或类似的模板并确认其骨骼结构与模型输出数据匹配。问题动作看起来奇怪或滑步解决这是文生动作模型的常见挑战。尝试在Blender或游戏引擎中对根骨骼位移Root Motion进行后期调整或者使用动作重定向Retargeting工具适配到你的特定角色骨骼上。6.3 下一步可以探索什么现在你已经掌握了基础可以尝试更酷的事情制作角色动画集用不同的Prompt批量生成走、跑、跳、攻击等动作构建一个基础动画库。与游戏引擎集成将导出的FBX动画直接导入Unity或Unreal Engine绑定到你的游戏角色上看看实际运行效果。探索高级控制查阅HY-Motion的文档看是否支持通过关键姿势、动作风格标签等进行更精细的控制。结合其他AI工具用文生图模型生成角色外观再用HY-Motion生成动作打造完整的AI生成角色短片。HY-Motion 1.0打开了一扇新的大门用语言直接驱动3D角色。虽然目前还有局限性比如只支持单人、基础动作但它展现的潜力是巨大的。希望这篇详细的指南能帮你顺利起步创造出属于自己的动态作品。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。