当前位置：首页 > news >正文

FramePack 安装指南（中文）

news 来源：原创 2025/6/27 14:03:29

FramePack 安装指南（中文） -Windows

FramePack 是最前沿的 AI 视频生成框架，以极小的硬件需求颠覆视频创作！它能在仅 6GB 笔记本 GPU 内存上，驱动 13B 模型以 30 FPS 生成超长 120 秒视频，几乎无内容限制，释放无限创意可能。以下是在 Windows 系统上使用 Anaconda 安装 FramePack 的详细步骤，基于成功安装的经验整理，剔除了错误指令，并明确区分用户输入的命令行步骤与系统反馈。本指南适用于希望尝鲜 FramePack 的用户，因为官方 Windows 一键安装包尚未发布。

项目链接：官网

FramePack 亮点（官方介绍）

低资源需求：在仅 6GB 笔记本 GPU 内存上，使用 13B 模型以 30 FPS 生成数千帧视频。
高效微调：在单个 8xA100/H100 节点上以 64 的批次大小微调 13B 视频模型，适合个人或实验室实验。
快速生成：在 RTX 4090 上，未优化生成速度为 2.5 秒/帧，启用 teacache 后可达 1.5 秒/帧。

前置条件

Anaconda：确保已安装 Anaconda。可从 Anaconda 官网下载。
Windows 系统：本指南基于 Windows 64 位系统。
CUDA 支持的 GPU：建议至少 6GB 显存的 GPU。本例使用 RTX 5090，如 RTX 30/40系列也适用。
网络连接：用于下载依赖和模型文件。
Git：安装 Git for Windows 以克隆仓库。可从 Git 官网下载。

安装步骤

步骤 1：创建新的 Conda 环境

用户输入命令:


conda create -n FramePack_test python=3.10

系统反馈:


Channels:- conda-forge- Index of /anaconda/pkgs/main/ | 清华大学开源软件镜像站 | Tsinghua Open Source Mirror- Index of /anaconda/pkgs/free/ | 清华大学开源软件镜像站 | Tsinghua Open Source Mirror- defaultsPlatform: win-64Collecting package metadata (repodata.json): doneSolving environment: done## Package Plan ##environment location: E:\anaconda3\envs\FramePack_testadded / updated specs:- python=3.10The following packages will be downloaded:package | build---------------------------|-----------------bzip2-1.0.8 | h2466b09_7 54 KB conda-forge...wheel-0.45.1 | pyhd8ed1ab_1 61 KB conda-forge------------------------------------------------------------Total: 23.0 MBdone

成功标志：环境创建完成，显示 done 且列出安装的包。

用户输入命令:


conda activate FramePack_test

系统反馈:


(FramePack_test) C:\Users\username>

成功标志：命令行提示符变为 (FramePack_test)，表示环境已激活。

步骤 2：克隆 FramePack 仓库进入安装目录E:\AI\FramePack（请根据自己的情况进入对于安装目录）

用户输入命令:


git clone https://github.com/lllyasviel/FramePack.git

系统反馈:

克隆完成后，检查 FramePack 目录内容：


dir驱动器 E 中的卷***E:\AI\FramePack 的目录2025/04/18 01:08 <DIR> .2025/04/17 15:37 3,471 .gitignore2025/04/17 15:37 18,810 demo_gradio.py2025/04/18 01:08 <DIR> diffusers_helper2025/04/17 15:37 11,357 LICENSE2025/04/17 15:37 14,299 README.md2025/04/17 15:37 222 requirements.txt5 个文件 48,159 字节

成功标志：FramePack 目录创建并包含 demo_gradio.py 和 requirements.txt 等文件。

步骤 3：安装 PyTorch（带 CUDA 支持）

用户输入命令:


pip3 install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu128

系统反馈:


Looking in indexes: https://download.pytorch.org/whl/nightly/cu128Collecting torchDownloading https://download.pytorch.org/whl/nightly/cu128/torch-2.8.0.dev20250416%2Bcu128-cp310-cp310-win_amd64.whl (3331.4 MB)...Successfully installed MarkupSafe-2.1.5 filelock-3.16.1 fsspec-2024.10.0 ...

成功标志：显示 Successfully installed 且列出安装的包（如 torch-2.8.0.dev20250416+cu128）。

注意：

本例使用 RTX 5090，安装了 CUDA 12.8 版本的 PyTorch。如果您使用 RTX 3090、4090 或其他 30/40 系列显卡，请根据您的 CUDA 版本选择对应的 PyTorch 版本。参考 PyTorch 官网获取正确安装命令。
确保 GPU 驱动和 CUDA 工具包与 PyTorch 版本兼容，检查 NVIDIA CUDA GPU 兼容性。

步骤 4：安装依赖项

用户输入命令:


pip install -r requirements.txt

系统反馈:


Collecting accelerate==1.6.0 (from -r requirements.txt (line 1))Downloading accelerate-1.6.0-py3-none-any.whl (354 kB)...Successfully installed accelerate-1.6.0 aiofiles-23.2.1 annotated-types-0.7.0 ...

成功标志：显示 Successfully installed 且列出所有依赖包（如 accelerate-1.6.0、diffusers-0.33.1 等）。

步骤 5：运行 Demo

用户输入命令:


python demo_gradio.py

重要提示：

运行时可能会出现短暂卡顿，这是正常现象，因为脚本需要初始化模型并分配显存。
首次运行会触发长时间的模型下载（约 15GB，包括 hunyuanvideo-community/HunyuanVideo 等模型），视网络速度可能需数分钟至数小时。请耐心等待。

系统反馈（模型下载部分） :


config.json: 100%|████████████████████████████████████████████████████████████████████████████| 766/766 [00:00<?, ?B/s]model-00001-of-00004.safetensors: 100%|███████████████████████████████████████████| 4.98G/4.98G [01:09<00:00, 72.1MB/s]model-00002-of-00004.safetensors: 100%|███████████████████████████████████████████| 5.00G/5.00G [01:06<00:00, 75.2MB/s]model-00003-of-00004.safetensors: 100%|███████████████████████████████████████████| 4.92G/4.92G [01:06<00:00, 74.2MB/s]model-00004-of-00004.safetensors: 100%|█████████████████████████████████████████████| 117M/117M [00:01<00:00, 74.1MB/s]Downloading shards: 100%|████████████████████████████████████████████████████████████████| 4/4 [03:24<00:00, 51.12s/it]...* Running on local URL: http://0.0.0.0:7860...Decoded. Current latent shape torch.Size([1, 16, 37, 88, 68]); pixel shape torch.Size([1, 3, 145, 704, 544])

成功标志：Gradio 界面启动，显示 Running on local URL: http://0.0.0.0:7860，且日志显示视频帧解码完成（如 pixel shape torch.Size([1, 3, 145, 704, 544])）。

步骤 6：验证安装

在浏览器中访问 http://localhost:7860。
测试视频生成功能，检查是否能正常生成视频。成功标志：Gradio 界面加载成功，且能生成视频。

初次生成视频的建议

在尝试自定义输入前，强烈建议按照以下 Sanity Check 进行测试，以确保硬件和软件配置无误。以下内容来自 FramePack 官方 GitHub.

Sanity Check

目的：验证硬件和软件是否正常运行。
背景：下一帧预测模型对噪声和硬件差异非常敏感。不同设备上结果可能略有差异，但整体应相似。在某些情况下，若配置一致，可获得完全相同的结果。

Image-to-5-seconds 示例

下载测试图片：从 FramePack GitHub 下载指定图片。
设置提示词：


The man dances energetically, leaping mid-air with fluid arm swings and quick footwork.

配置参数：

使用默认参数，关闭 teacache。
在 Gradio 界面中上传下载的图片。

预期结果：

生成视频文件（如 0.mp4），可能因 GitHub 压缩而略有失真。
重要说明：FramePack 是基于下一帧或分段预测的模型。若 UI 中初始生成视频较短（如仅 1 秒），属正常现象。请耐心等待，后续分段将逐步生成完整视频。

生成过程的控制台反馈：

运行 Sanity Check 时，控制台会显示视频分段生成的过程。以下是清洗后的关键反馈，展示了视频逐步生成的情况：


Moving DynamicSwap_HunyuanVideoTransformer3DModelPacked to cuda:0 with preserved memory: 6 GB100%|██████████████████████████████████████████████████████████████████████████████████| 25/25 [02:10<00:00, 5.20s/it]Offloading DynamicSwap_HunyuanVideoTransformer3DModelPacked from cuda:0 to preserve memory: 8 GBDecoded. Current latent shape torch.Size([1, 16, 9, 88, 68]); pixel shape torch.Size([1, 3, 33, 704, 544])Moving DynamicSwap_HunyuanVideoTransformer3DModelPacked to cuda:0 with preserved memory: 6 GB100%|██████████████████████████████████████████████████████████████████████████████████| 25/25 [02:14<00:00, 5.40s/it]Offloading DynamicSwap_HunyuanVideoTransformer3DModelPacked from cuda:0 to preserve memory: 8 GBDecoded. Current latent shape torch.Size([1, 16, 18, 88, 68]); pixel shape torch.Size([1, 3, 69, 704, 544])Moving DynamicSwap_HunyuanVideoTransformer3DModelPacked to cuda:0 with preserved memory: 6 GB100%|██████████████████████████████████████████████████████████████████████████████████| 25/25 [02:10<00:00, 5.21s/it]Offloading DynamicSwap_HunyuanVideoTransformer3DModelPacked from cuda:0 to preserve memory: 8 GBDecoded. Current latent shape torch.Size([1, 16, 27, 88, 68]); pixel shape torch.Size([1, 3, 105, 704, 544])Moving DynamicSwap_HunyuanVideoTransformer3DModelPacked to cuda:0 with preserved memory: 6 GB100%|██████████████████████████████████████████████████████████████████████████████████| 25/25 [02:09<00:00, 5.18s/it]Offloading DynamicSwap_HunyuanVideoTransformer3DModelPacked from cuda:0 to preserve memory: 8 GBDecoded. Current latent shape torch.Size([1, 16, 37, 88, 68]); pixel shape torch.Size([1, 3, 145, 704, 544])

解释：日志显示视频分段生成，每段约需 2 分钟（25 次迭代）。latent_padding_size 从 27 逐渐减小至 0，表示从初始帧到最终完整视频（145 帧，约 5 秒）。pixel shape 显示分辨率逐步增加，最终为 704x544。

其他建议

首次生成可能较慢，后续会因缓存优化而加快。
若生成结果与预期差异较大，检查显卡驱动、CUDA 版本或重新运行 Sanity Check。

故障排查

路径错误：确保正确导航到 E:\AI\FramePack，用 dir 检查目录。
显存不足：若提示内存错误，降低批次大小或使用更高显存 GPU。
模型下载失败：检查网络，重新运行 python demo_gradio.py 继续下载。
依赖冲突：若 pip install -r requirements.txt 失败，重建环境：


conda env remove -n FramePack_testconda create -n FramePack_test python=3.10

Hugging Face 缓存警告：可忽略，或设置：


set HF_HUB_DISABLE_SYMLINKS_WARNING=1

ConnectionResetError：日志中的 [WinError 10054] 为网络中断，可忽略。

额外说明

性能优化：启用 teacache 可将生成速度提升至 1.5 秒/帧，参考 FramePack 文档。
Windows Symlink 支持：为优化 Hugging Face 缓存，可启用开发者模式或以管理员身份运行 Anaconda Prompt（参考微软开发者模式指南）。
社区支持：加入 FramePack GitHub 社区获取帮助。

关于作者

FramePack 的核心开发者是 Lvmin Zhang 和 Maneesh Agrawala，两位在计算机视觉与图形学领域的杰出研究者。以下是他们的主要履历：

Lvmin Zhang

背景：来自中国的博士生，现就读于斯坦福大学计算机科学系，自 2022 年起师从 Maneesh Agrawala 教授。他在图像处理和扩散模型领域有深入研究，累计发表 13 篇高影响力论文，获 340 次高影响力引用。
重要贡献：
ControlNet（2023）：与 Maneesh Agrawala 和 Anyi Rao 合作开发，提出了一种神经网络架构，为文本到图像扩散模型（如 Stable Diffusion）添加空间条件控制，显著提升生成精度。该论文在 ICCV 2023 发表，影响深远。
Transparent Image Layer Diffusion（2024）：提出“潜在透明度”概念，使预训练扩散模型生成透明图像，广泛应用于层生成和结构控制，发表在 ACM Transactions on Graphics。
Style2Paints：开发了先进的图像生成软件，专注于动漫风格转换和线稿上色，成果包括 2017 年的 Style Transfer for Anime Sketches 和 2018 年的 Two-stage Sketch Colorization。
其他成就：Lvmin Zhang 曾开发 SmartShadow 等数字绘画工具，并在 ECCV 2020 提出优化图像平滑方法，创建了大规模插画数据集 DanbooRegion。

Maneesh Agrawala

背景：斯坦福大学计算机科学系 Forest Baskett 教授，兼任布朗媒体创新研究所主任。他在计算机图形学、人机交互和可视化领域有超过 30 年的研究经验，谷歌学术引用量超 31,664 次。
重要履历：
学术成就：1994 年获斯坦福大学数学学士学位，2002 年获计算机科学博士学位。2005-2015 年任加州大学伯克利分校教授，2015 年返回斯坦福。
奖项：2006 年获 Okawa Foundation 研究资助，2007 年获 Sloan 奖学金和 NSF CAREER 奖，2008 年获 SIGGRAPH 新研究员奖，2009 年获 MacArthur 基金会天才奖。
早期荣誉：1990 年参加 Westinghouse Science Talent Search，提交的蛋白质建模项目入围决赛；1988 年在 SuperQuest 竞赛中与团队赢得超级计算机。
研究贡献：
LineDrive（2002）：开发了基于认知设计的路线地图渲染系统，生成类似手绘的简洁地图，源自其博士论文。
ControlNet（2023）：与 Lvmin Zhang 合作，提出条件控制扩散模型，革新图像生成技术。
可视化工具：开发了 EMPHASISCHECKER（2023），帮助图表作者对齐图表与标题的重点；以及 VisiBlends（2019），简化视觉混合创作。
视频与动画：领导 Vid2Player（2021），生成可控网球运动员视频；以及 Puppet Dubbing（2019），优化视频配音流程。
影响力：Agrawala 的研究结合认知心理学，设计用户友好的视觉界面，广泛应用于地图导航、机器装配说明和 3D 模型交互，改变了我们处理复杂数字信息的方式。

两位作者的合作将中国学者的创新力与国际顶尖研究相结合，为 FramePack 的突破性技术奠定了基础。Lvmin Zhang 的中国背景也为项目增添了多元文化视角。