DiffSynth-Studio 环境变量完全指南模型下载、注意力实现与显存调优【免费下载链接】DiffSynth-StudioEnjoy the magic of Diffusion models!项目地址: https://gitcode.com/GitHub_Trending/dif/DiffSynth-StudioDiffSynth-Studio通过一组以DIFFSYNTH_为前缀的环境变量为模型下载、注意力机制实现选择和磁盘映射缓冲等核心行为提供了零代码的全局配置入口。本文以官方文档 docs/en/Pipeline_Usage/Environment_Variables.md 为骨架逐条讲解每个环境变量的取值、默认值、优先级与底层实现逻辑帮助你离线部署模型、切换 Attention 加速方案以及平衡显存与速度。如何设置环境变量在Python代码中可以通过os.environ设置环境变量。环境变量必须在import diffsynth之前设置因为diffsynth在导入阶段就会读取其中的一部分例如DIFFSYNTH_ATTENTION_IMPLEMENTATION会在模块加载时决定全局注意力实现。import os os.environ[DIFFSYNTH_MODEL_BASE_PATH] ./path_to_my_models import diffsynth在 Linux 操作系统上也可以临时在命令行中设置环境变量后运行脚本效果等价DIFFSYNTH_MODEL_BASE_PATH./path_to_my_models python xxx.py环境变量总览环境变量作用可选值默认值DIFFSYNTH_SKIP_DOWNLOAD是否跳过模型下载True/true/False/falseFalse未设置时DIFFSYNTH_MODEL_BASE_PATH模型下载根目录任意本地路径./modelsDIFFSYNTH_DOWNLOAD_SOURCE远程模型下载源modelscope/huggingfacemodelscopeDIFFSYNTH_ATTENTION_IMPLEMENTATION注意力机制实现方式flash_attention_3/flash_attention_2/sage_attention/xformers/torch等按环境自动探测详见下文DIFFSYNTH_DISK_MAP_BUFFER_SIZE磁盘映射缓冲区大小任意正整数字节数100000000010 亿字节下文逐条展开说明。DIFFSYNTH_MODEL_BASE_PATH控制模型下载根目录DIFFSYNTH_MODEL_BASE_PATH指定模型下载根目录可设置为任意本地路径。如果ModelConfig中没有设置local_model_path模型文件会下载到该环境变量指向的路径如果两者都未设置模型文件会下载到./models。优先级关系从高到低ModelConfig.local_model_path显式赋值 DIFFSYNTH_MODEL_BASE_PATH环境变量 默认值./models。从源码 diffsynth/core/loader/config.py 的reset_local_model_path方法可以看到这一优先级逻辑def reset_local_model_path(self): if os.environ.get(DIFFSYNTH_MODEL_BASE_PATH) is not None: self.local_model_path os.environ.get(DIFFSYNTH_MODEL_BASE_PATH) elif self.local_model_path is None: self.local_model_path ./models下载时实际的存放路径为local_model_path/model_id即模型 ID 会作为子目录追加在根目录之后。例如设置DIFFSYNTH_MODEL_BASE_PATH./models且model_idDiffSynth-Studio/Qwen-Image-Blockwise-ControlNet-Canny时文件将落在./models/DiffSynth-Studio/Qwen-Image-Blockwise-ControlNet-Canny/下。具体见 diffsynth/core/loader/config.py 中download方法对local_dir的拼接逻辑。典型应用场景将全部预训练模型集中管理在一个磁盘路径如数据盘或 NAS 挂载点避免默认下载到当前工作目录的./models中也可配合DIFFSYNTH_SKIP_DOWNLOADTrue实现完全离线推理。DIFFSYNTH_SKIP_DOWNLOAD跳过模型下载DIFFSYNTH_SKIP_DOWNLOAD决定是否跳过模型下载可设置为True、true、False、false解析时统一转为小写比较。如果ModelConfig中未设置skip_download则由该环境变量决定是否跳过模型下载两者都未设置时默认为不跳过即False。底层解析逻辑位于 diffsynth/core/loader/config.py 的parse_skip_downloaddef parse_skip_download(self): if self.skip_download is None: if os.environ.get(DIFFSYNTH_SKIP_DOWNLOAD) is not None: if os.environ.get(DIFFSYNTH_SKIP_DOWNLOAD).lower() true: return True elif os.environ.get(DIFFSYNTH_SKIP_DOWNLOAD).lower() false: return False else: return False else: return self.skip_download重要限制skip_downloadTrue只支持通过ModelConfig(pathxxx)指定本地路径的加载方式。源码 diffsynth/core/loader/config.py 中check_input明确抛出异常提示若path与model_id均为空会报ValueError若path为空而只有model_id在require_downloading返回False即跳过下载时后续无法定位任何本地文件。因此离线场景下请务必使用path参数。require_downloading的逻辑diffsynth/core/loader/config.pydef require_downloading(self): if self.path is not None: return False skip_download self.parse_skip_download() return not skip_download也就是说一旦path已显式给出无论环境变量如何设置都不会触发下载只有走model_id下载路线时DIFFSYNTH_SKIP_DOWNLOADTrue才会生效。典型应用场景离线环境、内网环境或已经完整下载过模型的情况下完全禁止任何网络请求默认行为即使模型已存在仍会查询远程是否有缺失文件见 docs/en/API_Reference/core/loader.md。DIFFSYNTH_DOWNLOAD_SOURCE选择远程下载源DIFFSYNTH_DOWNLOAD_SOURCE控制远程模型下载来源可设置为modelscope或huggingface默认值为modelscope。该值同样遵循ModelConfig.download_source优先、其次环境变量、最后默认值的优先级解析逻辑见 diffsynth/core/loader/config.pydef parse_download_source(self): if self.download_source is None: if os.environ.get(DIFFSYNTH_DOWNLOAD_SOURCE) is not None: return os.environ.get(DIFFSYNTH_DOWNLOAD_SOURCE).lower() else: return modelscope else: return self.download_source.lower()实际下载时modelscope分支调用modelscope.snapshot_downloadhuggingface分支调用huggingface_hub.snapshot_download两者均配合allow_file_pattern/ignore_file_pattern进行按需下载且ignore_file_pattern会传入已下载文件列表以实现断点续传diffsynth/core/loader/config.py。如果传入其他值会抛出ValueError: \download_source should be modelscope or huggingface。相关辅助变量当下载源为modelscope时还可以通过MODELSCOPE_ENDPOINT或MODELSCOPE_DOMAIN指向https://modelscope.ai来切换 ModelScope 的访问端点。这一判断体现在 diffsynth/core/loader/config.py 的check_download_source中该函数还会在启动时打印一个下载器配置提示框DOWNLOADING_TIPS用[√]标出当前生效的行为编号0ModelScope 默认端点1ModelScopemodelscope.ai端点2HuggingFace3跳过下载。Linux 下示例# 从 HuggingFace 下载 export DIFFSYNTH_DOWNLOAD_SOURCEHuggingFace # 或使用 ModelScope 的另一个端点 export MODELSCOPE_ENDPOINThttps://modelscope.aiDIFFSYNTH_ATTENTION_IMPLEMENTATION切换注意力实现DIFFSYNTH_ATTENTION_IMPLEMENTATION指定注意力机制的实现方式可设置为flash_attention_3、flash_attention_2、sage_attention、xformers或torch。详细原理参见 docs/en/API_Reference/core/attention.md。注意该环境变量在模块导入阶段即被读取因此必须置于import diffsynth之前。源码 diffsynth/core/attention/attention.py 在导入时通过initialize_attention_priority()决定全局的ATTENTION_IMPLEMENTATIONdef initialize_attention_priority(): if os.environ.get(DIFFSYNTH_ATTENTION_IMPLEMENTATION) is not None: return os.environ.get(DIFFSYNTH_ATTENTION_IMPLEMENTATION).lower() elif CUSTOMIZED_FA_KERNEL_AVAILABLE: return customized_fa_kernel elif FLASH_ATTN_4_AVAILABLE: return flash_attention_4 elif FLASH_ATTN_3_AVAILABLE: return flash_attention_3 elif FLASH_ATTN_2_AVAILABLE: return flash_attention_2 elif SAGE_ATTN_AVAILABLE: return sage_attention elif XFORMERS_AVAILABLE: return xformers else: return torch关键事实显式设置优先一旦设置了DIFFSYNTH_ATTENTION_IMPLEMENTATION直接以其小写值作为最终实现不再探测环境。自动探测回退链未设置时按customized_fa_kernel→flash_attention_4→flash_attention_3→flash_attention_2→sage_attention→xformers→torch的优先级选择第一个可用实现。各实现可用性在导入时通过try/except探测对应 Python 包flash_attn_interface、flash_attn、sageattention、xformers等见 diffsynth/core/attention/attention.py。选择 FlashAttention 3 需要安装flash-attn3.x 及对应 CUDA 环境Sage Attention 需要sageattention包xFormers 需要xformers包这些都需要自行按对应项目的安装说明安装。实际路由发生在attention_forwarddiffsynth/core/attention/attention.py当传入attn_mask、window_size或is_causal等受限条件或显式指定torch时会退回torch_sdpaPyTorch 的scaled_dot_product_attention因为部分加速实现如 Sage Attention、xFormers不支持掩码或因果注意力参数其他实现则按名称分发到flash_attention_3、flash_attention_2、sage_attention、xformers等函数。官方最佳实践出自 docs/en/API_Reference/core/attention.md大多数情况下直接使用原生 PyTorch 实现即可无需额外安装任何包其他注意力实现的加速效果相对有限少数场景下可能引入兼容性与精度问题。此外 PyTorch 2.9.0 的scaled_dot_product_attention已内置 Flash Attention 2高效实现正在逐步融入 PyTorch 本身。相关变量源码中还存在DIFFSYNTH_FLASH_ATTN_KERNEL_REPO_ID与DIFFSYNTH_FLASH_ATTN_KERNEL_VERSION用于从远程仓库加载自定义 Flash Attention kerneldiffsynth/core/attention/attention.py属于高级定制用法仅在确实需要特定 kernel 版本时使用。DIFFSYNTH_DISK_MAP_BUFFER_SIZE磁盘映射缓冲区大小DIFFSYNTH_DISK_MAP_BUFFER_SIZE控制磁盘映射DiskMap的缓冲区大小默认值为 1B1000000000字节。取值越大占用的内存越多但速度越快。DiskMap是diffsynth.core.vram提供的按需加载模型参数组件也是 Disk Offload磁盘卸载的基础组件用于safetensors文件的惰性读取。缓冲区的作用是当累计读取的参数元素数超过buffer_size时触发flush_files()重新打开文件句柄从而避免一次性缓存过多参数占用内存。相关实现见 diffsynth/core/vram/disk_map.pyclass DiskMap: def __init__(self, path, device, torch_dtypeNone, state_dict_converterNone, buffer_size10**9): ... if os.environ.get(DIFFSYNTH_DISK_MAP_BUFFER_SIZE) is not None: self.buffer_size int(os.environ.get(DIFFSYNTH_DISK_MAP_BUFFER_SIZE)) else: self.buffer_size buffer_sizedef __getitem__(self, name): ... if isinstance(param, torch.Tensor): self.num_params param.numel() if self.num_params self.buffer_size: self.flush_files() return param调优建议若显存紧张但内存充足可调大该值以获得更快的参数读取速度若内存有限例如同时加载多个大模型则应适当调小。注意DiskMap依赖.safetensors文件格式的特性使用.bin、.pth、.ckpt等二进制格式时参数会被完整加载Disk Offload 对这些格式不生效官方不推荐继续使用这类格式见 docs/en/API_Reference/core/vram.md。综合示例离线加载本地模型将上述环境变量组合使用即可实现完全离线的本地模型加载。假设模型已下载到/data/models目录import os os.environ[DIFFSYNTH_MODEL_BASE_PATH] /data/models # 模型根目录 os.environ[DIFFSYNTH_SKIP_DOWNLOAD] True # 禁止任何网络请求 os.environ[DIFFSYNTH_ATTENTION_IMPLEMENTATION] torch # 使用 PyTorch 原生注意力 import diffsynth from diffsynth.core import ModelConfig # 走本地 path 加载配合 skip_downloadTrue 完全离线 config ModelConfig(path/data/models/DiffSynth-Studio/Qwen-Image-Blockwise-ControlNet-Canny/model.safetensors)命令行等价形式DIFFSYNTH_MODEL_BASE_PATH/data/models \ DIFFSYNTH_SKIP_DOWNLOADTrue \ DIFFSYNTH_ATTENTION_IMPLEMENTATIONtorch \ python my_pipeline.py常见问题排查环境变量未生效确认os.environ[...]赋值发生在import diffsynth之前其中DIFFSYNTH_ATTENTION_IMPLEMENTATION与DIFFSYNTH_FLASH_ATTN_KERNEL_*在模块导入阶段即被读取无法在导入后动态改变。skip_downloadTrue报ValueErrorModelConfig必须提供path参数仅填model_id时无法在跳过下载的情况下定位模型文件见 diffsynth/core/loader/config.py。下载源报错DIFFSYNTH_DOWNLOAD_SOURCE只接受modelscope或huggingface大小写不敏感其他取值会在下载时抛出ValueError。注意环境变量的全局性环境变量是进程级全局配置会作用于所有ModelConfig若需要对单个模型差异化配置应优先在ModelConfig中显式设置local_model_path、skip_download、download_source等字段其优先级高于环境变量。【免费下载链接】DiffSynth-StudioEnjoy the magic of Diffusion models!项目地址: https://gitcode.com/GitHub_Trending/dif/DiffSynth-Studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考