Open-Sora教程与配套资料 夸克网盘

本模型的教程与配套资料已整理到夸克目录。先打开目录核对文件名，再按正文完成准备与运行。

Open-Sora由HPC-AI Tech发布，本教程以hpcai-tech/Open-Sora-v2为主示例，按选型、环境准备、固定版本下载、文件校验和首次运行的顺序展开。系列内其他模型的参数量、输入类型和许可可能不同，不应只把示例命令中的仓库名换掉后直接运行。

本示例属于视频生成方向。先读第1节确认任务，再完成下载与校验；只有设备、运行库和输入材料都准备好，才进入推理章节。文件下载成功只是取得了模型资料，不能据此认定该模型已在本机运行。

1 先选对模型与任务

项目	本教程示例
模型系列	Open-Sora
发布方	HPC-AI Tech
仓库ID	hpcai-tech/Open-Sora-v2
固定提交	5dd4b85059c49be387828d833060d80036cb160d
官方任务标签	text-to-video
文件数	20项
已知文件容量	69.179 GB 约64.43 GiB
访问状态	公开仓库
许可标记	apache-2.0

容量来自固定提交下的官方文件元数据加总，包含仓库中的说明、配置、不同格式副本及其他附属文件。GB按十进制，GiB按二进制；它们都不是运行内存或显存的最低要求。若文件大小字段缺失，资料清单会保留未提供标记，不把未知大小当成零容量。

本模型需要先分清的事项

Open-Sora与Open-Sora-Plan不是同一项目。

推理配置要与权重代际一致。

官方脚本优先。

2 检查设备与存储空间

下载目录建议预留至少95 GB可用空间，按当前已知整仓大小加约30%余量和5 GB基础空间估算。这只是下载规划，不包含Python环境、额外转换文件、项目依赖、临时缓存或生成结果。若只选择部分文件，需要重新按筛选后的清单计算，不能机械使用整仓估计。

1. Windows打开设置中的系统信息查看内存，在任务管理器的性能页查看GPU型号和专用显存；macOS在关于本机中查看芯片与统一内存；Linux可使用系统监视器或显卡厂商提供的工具。先记录设备信息，不根据型号名称猜测显存。

2. 确认目标磁盘支持大文件。Windows常见NTFS，Mac常见APFS；跨平台外置盘可按自身需求选择支持大文件的格式。FAT32不能保存大于4 GB的单个文件，不应为了下载而随意格式化已有资料的磁盘。

3. 运行资源取决于权重数据类型、序列长度、输入图像或音视频长度、并发数以及后端实现。普通FP16或BF16权重的基础占用可以用总参数量乘2字节作量级估计，但量化、MoE、解码器和缓存都需要另算。

4. 先选择一条最小任务完成安装验证。出现显存不足时，先减少输出长度、图像画幅或视频帧数；只有模型和后端明确支持时，再尝试量化、CPU卸载或多卡并行。不要把硬盘容量当作可用显存。

下载不要求具备模型推理所需的显卡，但后续运行有独立要求。Apple Silicon上的MPS、CPU和NVIDIA CUDA不是相同后端；项目写明只支持某类CUDA环境时，不能直接把设备字段改成mps就视为已支持Mac。

3 安装工具并创建独立环境

下载和清单脚本只依赖Python基础库，实际传输另需huggingface_hub。专用项目的Python版本以第6节和对应项目说明为准；本例建议单独准备Python 3.10环境，避免与其他模型的依赖混装。Python版本号相同也不代表PyTorch、CUDA和扩展包必然兼容。

Windows操作顺序

从Python官方发行渠道安装所需版本，重新打开PowerShell。将本模型的资料文件夹解压到路径较短的位置，然后在该文件夹打开终端。每次复制一行，等命令结束再执行下一行；不要一次粘贴多个模型的安装命令。

py --version
py -3.10 -m venv .venv
..venvScriptsActivate.ps1
python -m pip install --upgrade pip huggingface_hub
python environment_probe.py

如果系统没有py命令，先确认Python安装和路径设置，再使用已安装解释器创建环境。PowerShell若不允许激活脚本，可以直接运行.venv中的python.exe执行后续命令；无需为了一个模型长期降低系统级脚本策略。

macOS与Linux操作顺序

python3 --version
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip huggingface_hub
python environment_probe.py

若Linux缺少venv组件，按发行版官方包管理说明安装后重建环境。若项目明确只提供Linux和CUDA方案，Mac可用于下载与资料校验，运行环节应另选受支持设备。environment_probe.py只显示环境，不会加载大型权重或修改显卡驱动。

4 固定版本下载与访问权限

同目录model_manifest.json保存本次主示例的仓库ID、固定提交、目标目录和文件清单。download_model.py默认只预览，只有显式加--download才开始传输。脚本固定到清单中的revision，避免下载过程中main分支变化而混合不同版本。

python download_model.py --dry-run

预览应显示与第1节相同的仓库和提交、文件数、已知字节总量以及本地保存路径。先检查磁盘空间和目标目录，再开始下载。如果清单与文档不一致，先停止操作并确认是否混用了其他模型的资料包。

python download_model.py --download

公开仓库可在服务允许的范围内直接下载；标记为受限的仓库需要先用自己的账号在官方模型页完成访问申请或许可确认，再执行hf auth login。不要把读取令牌写入文章、文件清单或公开脚本。登录成功也不等于已经获得某个受限仓库的许可。

hf auth login
hf auth whoami

中断后保持原目录和同一份清单，再执行相同下载命令。huggingface_hub会按缓存和服务器信息处理已有文件；不要改动文件名、删除权重索引或把不同模型的分片放在同一目录。若确实需要重下某个文件，先在file_manifest.csv找到精确文件路径。

对同时包含多个格式、多个尺寸或多个检查点的仓库，可以用--only精确选择路径模式。筛选后执行校验时也要带相同的--only规则，否则未下载的其他文件会被报告为缺失。权重分片、索引、配置和分词器/处理器应作为一套完整组件选择，不要只下载最大的一个文件。

5 校验文件并保存版本记录

python verify_files.py
python verify_files.py --sha256

普通校验逐项检查文件是否存在以及字节大小是否匹配；--sha256只对官方元数据中提供LFS SHA256的文件计算摘要。没有SHA256的文件不会被虚构一个校验值。校验通过说明文件符合清单，仍不能证明推理环境和模型输出正确。大型权重计算摘要会花费时间，这是读取文件而不是重新下载。

缺失文件时回到下载步骤确认权限、筛选规则和保存目录；大小不符时优先对该文件重新传输。不要用空文件或改后缀代替缺失权重。浏览器下载到登录页面或错误页的同名文件，也应当作下载失败处理。

至少保留model_manifest.json、file_manifest.csv、安装后的环境版本和生成参数。后续更新模型时先新建目录，完成独立校验与短任务测试后再切换，避免覆盖当前可复现的版本。

6 安装运行组件并完成第一次输出

选择与示例相符的运行路线

本例使用项目专用路线，建议Python 3.10独立环境。代码仓库与模型权重是两套资料：先取得项目代码，再将固定版本权重放到项目能识别的位置。源码安装和第三方整合包不是同一种环境，不混用两者的依赖命令。

git clone https://github.com/hpcaitech/Open-Sora project
cd project
git rev-parse HEAD
python -m pip install -v .

v2配置与早期Open-Sora推理脚本不同；进入README的Inference小节选择v2配置，再指定同版本ckpt目录。FlashAttention、xformers等依赖按本机CUDA匹配，不同时安装互不兼容的版本。

python scripts/diffusion/inference.py --help

同目录official_run_steps.txt保留了该路线的安装与启动步骤。带--help的命令用于确认当前版本实际支持的参数；显示帮助不等于完成生成。进入图形界面后，还必须按下面的输入和验收步骤取得真实输出。

第一次任务的输入与验收

第一轮用单镜头：桌上一个陶瓷杯，镜头缓慢向前移动，光线保持稳定。图生视频另准备一张与画幅一致的输入图；没有输入图时，只运行模型明确支持的文生视频模式。

打开导出的视频文件并从头播放到尾，检查时长、画幅、帧率、运动连续性和明显闪烁。若模型不生成声音，无声不是失败；若选中音视频联合模式，再分别检查音轨和画面同步。不要只检查首帧。

7 调整参数与保存结果

视频的宽高、帧数、帧率、步数和时间一致性共同影响结果。先遵守模型要求的帧数或尺寸约束，再在受支持范围内扩展。不能通过修改容器元数据把低帧率文件变成真正更流畅的视频。

每次只改变一个条件并保留原片。对人物、物体和镜头运动分别观察，必要时缩短动作和减少主体。长视频拼接还需要转场、色彩和音频处理，不能把单段生成能力当作完整剪辑能力。

成功生成后立即记录本次模型目录、固定提交、Python和主要库版本、设备、参数与结果文件名。生成结果先保存到outputs子目录，再从本地打开检查，避免只看终端最后一行就判断成功。若后续换模型或换精度，重新做一次最小任务验证。

python -m pip freeze > environment_versions.txt

8 常见问题逐项排查

找不到命令或导入了错误的环境

先运行python --version和python -m pip --version，确认二者属于本模型的独立环境。安装包时使用python -m pip，避免把依赖装到另一个解释器。切换终端或重启后需要重新进入对应环境。

访问失败或下载结果不完整

先区分网络超时、限流、登录和仓库权限问题。401或403不应通过反复换文件名解决；确认自己的账号确有访问权限。下载后执行文件校验，不把保存成功的网页错误提示当作权重。

模型类型或处理器不被识别

检查仓库ID、配置文件、固定提交和安装的框架版本。原生新架构需要后端明确支持，专用架构可能依赖项目代码；不要盲目把model_type改成别的模型，也不要删除配置项来绕过错误。

显存或系统内存不足

先关闭其他占用较大的进程并降低本次任务规模，再核对精度、缓存和卸载配置。若完整权重本就超过设备能力，应改用更小的正式版本或受支持服务器方案；磁盘还有空位不能解决显存不足。

结果为空或与任务不一致

先检查输入文件是否能正常打开、参数是否属于当前模型版本、生成预算是否足够，以及基础版与指令版是否选错。对照最小样例一次只改变一项。运行无报错但没有满足验收条件，仍应继续排查。

更新依赖后原来能用的流程失效

回到已记录的环境版本和固定提交，新建环境复现原任务。不要直接在唯一可用环境上连续升级全部库。若项目接口发生变化，按对应发行版说明迁移，并重新核对本模型的专用步骤。

9 配套资料文件怎么使用

文件	用途
model_manifest.json	固定提交、任务与完整文件元数据
file_manifest.csv	所有文件的字节大小、LFS SHA256与固定版本地址
download_model.py	默认预览，--download才传输
verify_files.py	文件存在、大小和可选摘要核对
environment_probe.py	显示Python、磁盘与设备信息，不加载模型
来源核对清单.json	官方来源和本次取样时间
official_run_steps.txt	本模型专用安装与运行路线

本资料包不包含模型权重。CSV中的固定文件地址用于定位与核对，下载仍受原服务的访问权限、限流和许可约束。本模型的夸克资料入口见文档开头。网盘目录提供教程与配套文件，按实际目录内容选择所需资料。

10 主示例文件清单与来源

文件路径	字节大小	SHA256信息
.gitattributes	1519	未提供
Open_Sora_v2.safetensors	23782901392	d57baa23f6ad…
README.md	12802	未提供
flux1-dev-ae.safetensors	335304388	afc8e28272cd…
flux1-dev.safetensors	23802932552	4610115bb0c8…
google/t5-v1_1-xxl/config.json	752	未提供
google/t5-v1_1-xxl/pytorch_model-00001-of-00002.bin	9452285635	2f71ad062409…
google/t5-v1_1-xxl/pytorch_model-00002-of-00002.bin	9597031749	4f68f8067829…
google/t5-v1_1-xxl/pytorch_model.bin.index.json	19957	未提供
google/t5-v1_1-xxl/special_tokens_map.json	1786	未提供
google/t5-v1_1-xxl/spiece.model	791656	d60acb128cf7…
google/t5-v1_1-xxl/tokenizer_config.json	1857	未提供
hunyuan_vae.safetensors	492986446	003e7c25ea79…
openai/clip-vit-large-patch14/config.json	4519	未提供
openai/clip-vit-large-patch14/merges.txt	524619	未提供
openai/clip-vit-large-patch14/model.safetensors	1710540580	a2bf730a0c7d…

以上展示前16项用于识别仓库结构；完整20项均在file_manifest.csv中。不要根据这张节选表判断已经下载了整个模型。