ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

SANA 安装指南:从零搭建环境到 Diffusers 快速推理实战

SANA 安装指南:从零搭建环境到 Diffusers 快速推理实战 SANA 安装指南从零搭建环境到 Diffusers 快速推理实战【免费下载链接】SanaSANA: Efficient High-Resolution Image Synthesis with Linear Diffusion Transformer项目地址: https://gitcode.com/GitHub_Trending/sana/Sana本指南是 SANAEfficient High-Resolution Image Synthesis with Linear Diffusion Transformer仓库的官方安装文档 docs/installation.md 的完整实战化解读覆盖环境依赖、一键安装脚本、硬件选型、Diffusers 管线推理、Docker 容器化部署以及安装后的验证与下一步学习路径。读完本文你将能够独立完成 SANA 的 Python 环境搭建、模型权重加载与 1024px 图像生成并了解仓库源码中底层依赖管理的设计逻辑。环境依赖先确认你的 Python 与 PyTorch安装 SANA 之前需要确认两个基础软件环境满足官方要求Python 3.10.0官方建议使用 Anaconda 实际会创建Python 3.11的 conda 环境且 pyproject.toml 中声明requires-python 3.11。原因在脚本注释中有明确说明triton 3.5 的triton.jit装饰器依赖inspect.getsource并用正则匹配^def\s\w\s*\(在 Python 3.10 上对 fla 库中带装饰器的 kernel 取源码会返回 None。因此强烈建议直接用 Python 3.11。PyTorch 2.5.1cu12.4需从 PyTorch 官网 与 pyproject.toml 的依赖锁定。如果只是查阅本文档docs 目录依赖更轻量见 docs/requirements.txt包含mkdocs1.5.0、mkdocs-material9.0.0、mkdocstrings[python]0.24.0、pymdown-extensions10.0等文档构建组件与模型运行环境相互独立。快速安装一键脚本environment_setup.sh官方推荐的安装方式非常简洁git clone https://gitcode.com/GitHub_Trending/sana/Sana.git cd Sana bash ./environment_setup.sh sana # 或者不指定环境名直接在当前已激活的 conda 环境中安装其中sana是传入的 conda 环境名。如果省略该参数即直接bash ./environment_setup.sh脚本会安装到当前已激活的环境中。脚本背后的完整安装流水线environment_setup.sh是官方维护的「单一事实来源」安装脚本它遵循依赖的真相在 pyproject.toml脚本只处理无法放进 pyproject.toml 的部分这一设计原则见脚本头部注释。整条流水线如下创建 conda 环境conda create -n sana python3.11 -y并安装cuda-toolkit12.8。安装 CUDA toolkit 是为了让 flash-attn 等从源码编译的库能匹配 torch wheel 的 CUDA 主次版本——运行时 torch 自带 CUDA 库但编译期 nvcc 必须对齐。固定 setuptools 版本pip install setuptools80。原因是 mmcv 1.7.2 的 setup.py 会import pkg_resources而 setuptools 80 已不再将其作为可导入模块提供。预装 torch 全家桶cu128从https://download.pytorch.org/whl/cu128安装 torch 2.9.1、torchvision 0.24.1、torchaudio 2.9.1随后安装xformers0.0.33.post2。预装版本与 pyproject.toml 锁定一致后续pip install -e .会将其视为已满足而不再重复下载。编译 mmcvpip install --no-build-isolation mmcv1.7.2。必须禁用 PEP 517 隔离让 mmcv 的 setup.py 能看到环境中已预装的 torch 与 setuptools80。可编辑安装项目本体pip install -e .其余所有依赖diffusers、transformers、flash-linear-attention、liger_kernel、peft、gradio 等均从 pyproject.toml 解析安装并自动注册sana-run与sana-upload两个命令行入口对应 sana/cli/run.py 与 sana/cli/upload2hf.py。安装 Pi3Xpip install githttps://github.com/yyfz/Pi3.git --no-deps用于 SANA-WM 的相机内参估计--no-deps避免其误降级 torch/numpy。编译 flash-attnMAX_JOBS${MAX_JOBS:-8} NVCC_THREADS${NVCC_THREADS:-2} pip install --no-build-isolation flash-attn2.7.0。可通过环境变量控制并行编译任务数以调节内存/时间开销。安装 NVIDIA Transformer Enginebest-effort用于 SANA-WM 的 fp8/fp4 量化流式推理--stage1_precision/--refiner_precision。该步骤失败不会中断安装bf16 推理不依赖它可显式设置SANA_SKIP_TE1跳过控制编译并行度的同样是MAX_JOBS/NVCC_THREADS。脚本是幂等的对已存在的同名环境会复用重复执行会调和版本。另外两个实用的环境变量开关SKIP_ENV_SETUPtrue跳过全部环境搭建步骤CI 中使用见 tests/bash/entry.sh此时必须自行保证当前 conda 环境已装齐所有依赖SANA_SKIP_TE1仅跳过 Transformer Engine。安装完成后激活环境即可使用conda activate sana硬件要求显存规划模型所需显存VRAMSana-0.6B9GBSana-1.6B12GB4-bit 量化版 8GB注意官方所有测试均在 A100 GPU 上完成不同型号 GPU 的实际表现可能存在差异。其中 4-bit 量化推理由 SVDQuant-Nunchaku 引擎支持可将 1.6B 模型压到 8GB 显存以内运行仓库还提供了 4bit_sana.md 与 8bit_sana.md 两份专门的量化部署指南。若目标分辨率提升到 2K / 4K官方在 docs/model_zoo.md 中建议为 4K 模型开启VAE tiling以避免 OOM详见下文 Diffusers 章节并提示 DC-AE tiling 可将 4096×4096 推理控制在 22GB 显存内。使用 Diffusers升级到最新版本SANA 已深度集成进 HuggingFacediffusers生态提供SanaPipeline、SanaPAGPipeline、DPMSolverMultistepScheduler 等组件官方要求升级到最新版pip install githttps://github.com/huggingface/diffusers注意仓库 pyproject.toml 中的diffusers0.37.0是最低版本约束实际使用 diffusers 管线时仍建议按官方指引升级到最新开发版以获取对 Sana 系列模型含 SANA-1.5、SANA-Video的最新支持。仓库 app/sana_pipeline.py 也展示了 SanaPipeline 在本仓库内部的封装用法app/app_sana.py 则提供 Gradio 交互界面。快速开始生成你的第一张图import torch from diffusers import SanaPipeline pipe SanaPipeline.from_pretrained( Efficient-Large-Model/SANA1.5_1.6B_1024px_diffusers, torch_dtypetorch.bfloat16, ) pipe.to(cuda) pipe.vae.to(torch.bfloat16) pipe.text_encoder.to(torch.bfloat16) prompt a cyberpunk cat with a neon sign that says Sana image pipe( promptprompt, height1024, width1024, guidance_scale4.5, num_inference_steps20, generatortorch.Generator(devicecuda).manual_seed(42), )[0] image[0].save(sana.png)对关键参数的实战解读精度torch_dtypeSANA 同时发布 fp16 与 bf16 权重务必让variant与torch_dtype匹配所选模型仓库的精度见 docs/model_zoo.md 的「Make sure to use correct precision」章节。上例使用的是 SANA1.5 的 bf16 权重from_pretrained默认即取 bf16 变体若加载 fp16 权重则应写为variantfp16, torch_dtypetorch.float16。VAE 与文本编码器单独显式.to(torch.bfloat16)是为了固定这些子模块的精度避免默认 fp32 占用过多显存。guidance_scale无分类器引导强度官方示例取 4.55.0。使用 PAGPerturbed Attention Guidance管线时还会叠加pag_scale2.0与pag_applied_layers参数。num_inference_steps默认 20 步配合 Flow Matching / DPM-Solver 采样即可获得高质量结果。generatormanual_seed(42)用于固定随机种子保证结果可复现。采样步数与采样器仓库原生推理脚本 scripts/inference.py 中的默认步数映射为{dpm-solver: 20, sa-solver: 25, flow_dpm-solver: 20, flow_euler: 28}与 Diffusers 的 20 步默认一致。2K / 4K 高分辨率推理若加载 2K / 4K 模型如Efficient-Large-Model/Sana_1600M_4Kpx_BF16_diffusers官方建议对 4K 场景开启 VAE tiling 防止 OOMif pipe.transformer.config.sample_size 128: pipe.vae.enable_tiling( tile_sample_min_height1024, tile_sample_min_width1024, tile_sample_stride_height896, tile_sample_stride_width896, )tile 尺寸可按显存自由调整。生成 4096×4096 图像时配合guidance_scale5.0、20 步采样即可完整示例见 docs/model_zoo.md 的 2K 4K 章节。int4 量化推理int4 模型由 SVDQuant-Nunchaku 引擎量化mit-han-lab/svdq-int4-sana-1600m需要先按其指引安装 Nunchaku 引擎再通过NunchakuSanaTransformer2DModel替换默认 Transformerfrom nunchaku.models.transformer_sana import NunchakuSanaTransformer2DModel transformer NunchakuSanaTransformer2DModel.from_pretrained(mit-han-lab/svdq-int4-sana-1600m) pipe SanaPipeline.from_pretrained( Efficient-Large-Model/Sana_1600M_1024px_BF16_diffusers, transformertransformer, variantbf16, torch_dtypetorch.bfloat16, ).to(cuda)这样即可在 8GB 显存内完成 1024px 图像生成详见 docs/model_zoo.md 的 int4 章节与 docs/4bit_sana.md。可选Docker 容器化部署仓库提供了开箱即用的 Dockerfile基于 NVIDIA 官方镜像nvcr.io/nvidia/pytorch:24.06-py3构建# 构建 Docker 镜像 docker build -t sana . # 用 Docker 运行推理 docker run --gpus all -it sana python scripts/inference.py解读 Dockerfile 的关键设计基础镜像已内置 CUDA 生态随后补装libgl1-mesa-glx、libglib2.0-0OpenCV 等图像库的运行依赖并安装 Miniconda 到/opt/conda只拷贝运行所需的源码目录diffusion、configs、sana、app、tools与 pyproject.toml、environment_setup.sh避免把测试、脚本等非运行时内容带入镜像构建阶段执行./environment_setup.sh不指定环境名直接装入镜像默认 conda 环境默认CMD启动的是 Gradio 演示应用 app/app_sana.pypython app/app_sana.py --share --configconfigs/sana_config/1024ms/Sana_1600M_img1024.yaml --model_pathhf://Efficient-Large-Model/Sana_1600M_1024px/checkpoints/Sana_1600M_1024px.pth即加载 1024px 的 1.6B 模型并开启--share公网分享链接。因此直接docker run时传python scripts/inference.py会覆盖 CMD执行批量化命令行推理。安装验证与命令行推理环境搭建完成后可通过仓库自带的命令行推理脚本验证安装是否成功。脚本 scripts/inference.py 以pyrallis解析配置默认配置为configs/sana_config/1024ms/Sana_1600M_img1024.yaml、默认模型路径为hf://Efficient-Large-Model/Sana_1600M_1024px/checkpoints/Sana_1600M_1024px.pthhf://前缀表示从 HuggingFace Hub 自动下载、默认提示词文件为asset/samples/samples_mini.txtpython scripts/inference.py \ --config configs/sana_config/1024ms/Sana_1600M_img1024.yaml \ --model_path hf://Efficient-Large-Model/Sana_1600M_1024px/checkpoints/Sana_1600M_1024px.pth \ --txt_file asset/samples/samples_mini.txt \ --sampling_algo flow_dpm-solver \ --cfg_scale 4.5 \ --seed 0脚本内部的推理链路build_model→ 采样器DPMS/FlowEuler/SASolverSampler→vae_decode→save_image与官方论文描述一致Flow-DPM-Solver 采样器默认 20 步采样器选择与引导策略classifier-free PAG见 scripts/inference.py。此外装好的环境还提供sana-run命令SLURM 训练/推理任务启动器见 sana/cli/run.py与sana-upload命令模型上传见 sana/cli/upload2hf.py。下一步官方推荐的进阶路线安装并跑通基础推理后官方文档建议按以下顺序深入Model Zoo——按分辨率与精度挑选合适的模型权重内含 fp16/bf16 精度匹配、2K/4K VAE tiling、int4 量化与.pth→ diffusers.safetensor转换脚本tools/convert_scripts/convert_sana_to_diffusers.py等完整指引SANA-Sprint——14 步的超快推理模式sCM 蒸馏适合低延迟场景SANA-Video——基于线性注意力与线性块 KV-Cache 的视频生成含 SANA-Video 2.0 的 5B/14B 架构与 720p 推理说明更多主题ControlNet、LoRA/DreamBooth、量化、推理缩放、SGLang 服务化等可在 docs 索引中按需查阅。【免费下载链接】SanaSANA: Efficient High-Resolution Image Synthesis with Linear Diffusion Transformer项目地址: https://gitcode.com/GitHub_Trending/sana/Sana创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表