Fooocus：极简 SDXL 本地文生图 Gradio 应用，免调参出图与三套预设一键切换｜部署与使用全指南

项目仓库： https://github.com/lllyasviel/Fooocus

开源协议：GNU GPL v3 · 运行语言：Python 3.10（界面基于 Gradio 3.41.2） · 模型架构：Stable Diffusion XL（SDXL） · 交付形态：本地桌面应用 / Linux 命令行启动 / 官方 Docker 镜像 · 本地默认端口：7860，官方 Docker 镜像端口：7865 · 官方文档：README 与 GitHub Discussions

⚠️ 项目状态前置声明（务必先读）：根据当前官方 README，Fooocus 已进入**有限长期支持（LTS，仅修复 Bug）**状态：现有功能被认为基本不存在程序缺陷，后续更新只聚焦问题修复，当前没有迁移到或接入新一代模型架构（如 Flux）的计划；该方向未来是否调整取决于开源社区是否收敛出主流方案。项目完全构建在 Stable Diffusion XL 架构之上，官方建议需要使用 Flux 等新模型的用户转而使用作者维护的 Stable Diffusion WebUI Forge 或 ComfyUI。本文用于梳理 Fooocus 的部署方式、预设体系、启动参数与常见问题排查，供本地出图与迁移对照使用。

非官方声明：本文是基于官方 README、docker.md、troubleshoot.md、预设配置文件与仓库源码整理的部署使用指南，不代表项目官方立场。Stable Diffusion XL、Gradio、PyTorch、Civitai、Hugging Face 等名称归各自权利人所有；本文提及的模型权重、LoRA 与第三方素材均遵循其自身许可协议与服务条款，使用者须自行确认合规边界。项目按现状（AS-IS）提供，本文不构成对生成内容、商用授权或平台账号安全的任何担保。

1 项目简介

Fooocus 是 lllyasviel 发布的开源图像生成软件，界面基于 Gradio 构建，定位是对图像生成器设计思路的一次“重新思考”：软件离线运行、开源、免费，同时对标 Midjourney 等在线生成器——使用者几乎不需要手工调整采样器、步数、CFG、VAE、分辨率等参数，只需把注意力放在提示词与最终图片上。官方把“从点击下载到生成第一张图所需鼠标点击次数”严格限制在 3 次以内。

Fooocus 内置一套基于 GPT-2 的离线提示词处理引擎，配合经过调优的采样改进、风格模板与默认参数，使提示词无论短到 house in garden 还是长到上千字，都倾向给出稳定美观的结果。项目本身只提供界面、调度与配套工具链，不附带任何模型权重；首次启动会按当前预设自动下载对应的 SDXL 主模型、LoRA 与配套组件，使用者也可以提前把合规获取的模型放入本地模型目录跳过自动下载。

1.1 核心信息一览

1.2 适用场景

• 在个人 Windows / Linux / macOS 工作站上搭建一套可离线使用的 SDXL 绘图环境，只想输入提示词、选择风格与比例即可出图，不需要深入采样器、调度器与 VAE 细节。
• 按任务方向快速切换三套预设：通用人像 / 场景、写实摄影、动漫插画；也可以在浏览器界面中直接切换预设，或用 --preset 参数在启动时指定。
• 基于已有图片做变体（细微 / 强烈变化）、1.5 倍 / 2 倍放大、局部重绘、向上 / 下 / 左 / 右扩图（Pan），以及图像提示（Image Prompt）、人脸交换（FaceSwap）、图片描述（Describe）等二次编辑。
• 通过 --listen 把界面开放到局域网，或用 --share 生成 Gradio 临时公网链接，在自有服务器或 Colab 上集中使用一套出图环境。
• 把 Fooocus 当作 SDXL 调参结果的对照基准：其内置的提示词扩展、单一 k-sampler 内原生 refiner 交换、Negative ADM Guidance、自注意力引导（SAG）等改进，可用于理解高质量 SDXL 出图的工程取舍。

1.3 能力边界（官方口径）

• 架构边界：Fooocus 完全构建在 SDXL 之上，官方明确表示当前不计划迁移到 Flux 等新模型架构；需要新一代模型时，官方推荐转用 WebUI Forge 或 ComfyUI，社区亦有若干 Fooocus forks 可供实验。
• 维护边界：项目处于 LTS 仅修 Bug 状态，现有功能被认为基本无程序缺陷；新版本功能、架构升级不会在 Fooocus 主线继续投入，使用时应知悉这一长期支持水平。
• 定位边界：Fooocus 是“极简出图”产品形态，界面刻意隐藏了大量高级采样参数；需要完整节点编排、自定义工作流、ControlNet 精细组合、批量训练 LoRA 等深度能力时，应使用 ComfyUI、WebUI Forge 等其他平台。
• 模型不随仓库分发：仓库只提供代码与预设配置，SDXL 主模型、LoRA、inpaint 控制模型均在首次使用时按预设自动下载，或由使用者手动放入对应目录；模型许可各自独立，详见第 11.2 节。
• 硬件边界：官方硬件表区分 NVIDIA、AMD、纯 CPU 与不同代际显卡；AMD 支持处于 Beta / 实验性状态，Apple Silicon 通过 MPS 加速但速度明显慢于独立显卡，纯 CPU 模式速度约为 NVIDIA RTX 3XXX 的 17 倍慢，仅适合调试体验（详见 5.2 节）。
• 质量口径：官方不支持为降低硬件要求而牺牲结果质量的小模型路线；出图质量同时受所选主模型、提示词、风格预设、显卡与采样条件影响，Fooocus 本身不承诺特定画面结果。

2 功能特性

以下条目整理自官方 README 特性对照表、高级功能讨论区与预设配置；具体菜单名称、默认值与可用范围以安装版本界面为准。

2.1 极简出图与离线提示词扩展

• 免调参出图：界面默认隐藏采样器、步数、CFG、VAE 等底层旋钮，使用者主要填写正向提示词、负向提示词，选择风格、比例与生成数量即可；官方对标 Midjourney 的体验设计。
• 离线 GPT-2 提示词扩展：内置一套基于 GPT-2 的本地提示词处理引擎，作为动态风格 “Fooocus V2” 工作，类似 Midjourney 的隐藏预处理 / raw 模式与 LeonardoAI 的 Prompt Magic；提示词会在本地被扩充与规范化，不依赖云端大模型。
• 采样改进集合：官方在 README “Hidden Tricks” 中列出若干内置工程改进，包括单一 k-sampler 内原生 refiner 交换、Negative ADM Guidance、低权重自注意力引导（SAG，各向异性高斯核）、cinematic-default 风格模板、SDXL offset LoRA（权重低于 0.5）、DPM 家族采样器与 karras 调度器组合、CFG Scale 大于 10 时的 TSNR 校正等；这些参数对使用者默认透明。

2.2 变体、放大与局部重绘 / Pan

2.3 图像提示、人脸交换与图片描述

• Image Prompt：上传参考图后作为图像条件参与生成，配合 Advanced 中的参数控制参考强度；Fooocus 自研算法在提示理解与结果质量上区别于标准 IP-Adapter。
• FaceSwap：在 Image Prompt 的 Advanced 面板中调用 InsightFace 完成人脸替换；相关模型按需下载。
• Describe：上传图片后由模型反推提示词，便于在已有画面基础上改写复现。
• Advanced → ControlNets：在 Input Image → Image Prompt → Advanced 中接入用户友好的 ControlNet 组合，对应 LeonardoAI 侧的高级控制能力。

2.4 三套预设与 Civitai SDXL 模型

• 通用预设（default / run.bat）：主模型 juggernautXL_v8Rundiffusion.safetensors，默认风格 Fooocus V2、Fooocus Enhance、Fooocus Sharp，默认比例 1152*896，CFG Scale 4.0。
• 写实预设（realistic / run_realistic.bat / --preset realistic）：主模型 realisticStockPhoto_v20.safetensors，默认风格 Fooocus V2、Fooocus Photograph、Fooocus Negative，默认比例 896*1152，自带写实负向提示词，搭配胶片摄影风格 LoRA。
• 动漫预设（anime / run_anime.bat / --preset anime）：主模型 animaPencilXL_v500.safetensors，默认风格 Fooocus V2、Fooocus Semi Realistic、Fooocus Masterpiece，默认比例 896*1152，CFG Scale 6.0。
• 三套预设各自的模型、LoRA、采样器、调度器、风格、比例与下载地址固化在仓库 presets/default.json、presets/realistic.json、presets/anime.json 中；Fooocus 2.3.0 之后可直接在浏览器界面切换预设，切换时按 --always-download-new-model 决定是否下载缺失模型，否则回退到预设中记录的 previous_default_models。
• 除内置预设外，Fooocus 支持使用 Civitai 上的 SDXL 模型；把合规获取的模型放入 models/checkpoints 后在界面选择即可。

2.5 提示词内联语法

• 提示词权重：沿用 Automatic1111 的权重算法，例如 I am (happy:1.5)；直接从 Civitai 复制提示词时，权重表达兼容性优于 ComfyUI 文本权重写法。
• Embedding 内嵌：(embedding:file_name:1.1) 引用文本反演文件。
• 通配符（Wildcards）：__color__ flower 会从 wildcards/color.txt 中随机选取一个颜色；通配符支持嵌套与组合；在 Developer Debug Mode 勾选 Read wildcards in order 后按文件顺序逐行替换，而不是随机。
• 数组处理：[[red, green, blue]] flower 从左到右为每个元素各生成一张图（示例共 3 张）；提高 Image Number 可生成全部变体；数组不可嵌套，但同一提示词中可出现多个数组；数组元素支持内嵌 LoRA。
• 内嵌 LoRA：flower <lora:sunflowers:1.2>；LoRA 文件须位于 models/loras 目录。
• 多行多提示词：直接换行即可表达多段提示，无需专用分隔符。

2.6 高级参数与界面能力

• Style（风格）：Advanced → Style，可在内置风格模板中叠加；内置风格集合见 presets/*.json 的 default_styles。
• Guidance / Quality / Image Number：分别对应提示词服从度、生成质量与一次出图数量，在 Advanced 面板调节。
• Negative Prompt：Advanced → Negative Prompt 填写负向提示词；写实预设内置了一长串负向提示词（见 8.2 节）。
• Aspect Ratios：Advanced → Aspect Ratios，预设比例为 SDXL 训练位置编码较友好的固定分辨率，UI 中硬编码推荐比例。
• 主题、语言与元数据：启动参数支持 --theme、--language、--disable-metadata 等；历史记录与输出排序可通过 --disable-enhance-output-sorting 等参数调整。

3 官方界面预览

3.1 主界面与一次出图结果

下图为官方 README 头图：在提示框输入 forest elf，主界面一次生成四张森林精灵主题结果，下方缩略图选择器用于选定当前查看与复用的图片，右下角为 Generate 按钮；左侧为 Advanced 折叠面板。

3.2 模型检查点目录

下图为 models/checkpoints 目录结构：put_checkpoints_here 为占位说明文件，SDXL Base 与 Refiner 权重放置于该目录；Fooocus 当前三套预设均不使用 Refiner（default_refiner 为 None）。

3.3 低显存笔记本性能测试

官方 README 给出一组低配笔记本实测：16GB 系统内存、NVIDIA RTX 3060 Laptop（6GB 显存），单次迭代约 1.35 秒；下图为浏览器 127.0.0.1:7860 生成猫图时的界面与任务管理器显存 / 内存占用情况。

4 官方跳转链接汇总

以上链接以官方仓库当前 README、docker.md 与 troubleshoot.md 为准；第三方模型站、模型权重与 fork 项目的许可、条款与安全性由对应发布方负责。

5 前置要求与服务器配置

5.1 软件前提

Docker / 自托管路线（方式一）

• 一台硬件规格足以运行 Fooocus 的主机，并安装专有 NVIDIA 显卡驱动。
• 安装 Docker 与 Docker Compose，或使用 Podman；官方镜像基于 NVIDIA CUDA 12.4 与 PyTorch 2.1 构建（详见 Dockerfile 与 requirements_docker.txt）。
• 服务器需要能访问 Hugging Face 以下载模型；国内网络可通过 HF_MIRROR 环境变量指定镜像站点（见 8.4 节）。

本地桌面 / 命令行路线（方式二）

• Python 3.10：Linux 原生与 venv 路线要求系统已安装 Python 3.10；Conda 路线由 environment.yaml 固定 python=3.10、pip=23.0、packaging。官方故障排查明确提示 subprocess-exited-with-error 时应使用 Python 3.10，不要采用其他版本。
• Git：源码克隆、自动更新与 pygit2 依赖需要 Git 环境；Windows 便携包内置 python_embeded，不依赖系统 Python。
• 显卡驱动：NVIDIA 方案需安装与 CUDA 版本匹配的显卡驱动；AMD 方案按官方 Linux ROCm / Windows DirectML 路径准备；纯 CPU 无需显卡驱动，但速度显著变慢。
• 模型与网络：首次启动需要按预设下载主模型、LoRA、提示词扩展模型，局部重绘首次使用时下载 inpatch 控制模型；网络不通时可手动从 8.2 节列出的地址下载到对应目录。
• 磁盘空间：三个预设主模型、LoRA、inpaint 模型与历史输出需要预留充足空间；模型文件单个体积通常在数 GB 量级，输出图会持续累积，建议定期清理或迁移。

5.2 硬件与系统建议

下表整理自官方 README “Minimal Requirement” 硬件表，显存、内存与系统交换口径以当前官方说明为准：

补充口径：

• 系统交换（虚拟内存）：4GB 显存方案借助 Windows 虚拟内存技术在显存与内存之间交换权重；官方建议确保至少 40GB 系统交换（不一定要实际占用 40GB，但 40GB 是 100% 成功运行的安全值）；若系统内存超过 64GB，可能不需要系统交换，但官方并不确定。系统交换位于 HDD 时模型加载会很慢，应尽量放在 SSD；Linux / macOS 按发行版 / 系统指引配置 Swap Space，Windows 10 / 11 默认自动管理分页文件，未手动关闭即可。
• 驱动版本：官方 README 提示部分场景下 NVIDIA 532 以上驱动可能比 531 慢约 10 倍；若生成时间异常长，可参考官方说明评估驱动版本（驱动下载与兼容性以 NVIDIA 官方渠道为准）。
• 实测参考：16GB 内存 + RTX 3060 Laptop（6GB）机型可正常生成，单次迭代约 1.35 秒（见图 3.3）。
• 纯 CPU：仅用于调试与体验，不适合日常出图；32GB 内存是官方纯 CPU 最低口径。

5.3 端口与目录分配

注意：--listen 或 --share 暴露的界面默认无鉴权；局域网 / 公网使用时应通过 auth.json 配置基本认证，或在反向代理层叠加登录校验（见 8.4 节）。

6 方式一：官方 Docker 镜像 / Compose 部署（服务器与自托管推荐）

官方提供基于 NVIDIA CUDA 12.4 与 PyTorch 2.1 的 Docker 镜像 ghcr.io/lllyasviel/fooocus，适合在自有服务器、工作站上集中部署一套出图环境；镜像基线、依赖清单见仓库 Dockerfile 与 requirements_docker.txt。

6.1 准备条件

• 主机硬件规格足以运行 Fooocus（见 5.2 节硬件表），并安装专有 NVIDIA 显卡驱动与容器运行时支持（NVIDIA Container Toolkit / --gpus all 所需组件）。
• 安装 Docker 与 Docker Compose，或使用 Podman。
• 服务器网络可访问 Hugging Face 以下载模型；国内网络可通过 HF_MIRROR 指定镜像站点（见 8.4 节）。

6.2 Docker Compose 快速启动

1. 克隆官方仓库：

git clone https://github.com/lllyasviel/Fooocus.git
cd Fooocus

2. 在仓库目录执行：

docker compose up

3. 控制台出现 Use the app with http://0.0.0.0:7865/ 后，在浏览器打开 http://<宿主机地址>:7865（本机即 http://127.0.0.1:7865）进入界面。

后台常驻运行：

docker compose up -d
docker compose logs -f

6.3 docker run 完整启动命令

不使用 Compose 时，可直接用官方镜像启动；下面命令把模型、配置与输出持久化到命名卷 fooocus-data，并按 docker.md 给出的环境变量映射各模型目录：

docker run -p 7865:7865 -v fooocus-data:/content/data -it \
  --gpus all \
  -e CMDARGS=--listen \
  -e DATADIR=/content/data \
  -e config_path=/content/data/config.txt \
  -e config_example_path=/content/data/config_modification_tutorial.txt \
  -e path_checkpoints=/content/data/models/checkpoints/ \
  -e path_loras=/content/data/models/loras/ \
  -e path_embeddings=/content/data/models/embeddings/ \
  -e path_vae_approx=/content/data/models/vae_approx/ \
  -e path_upscale_models=/content/data/models/upscale_models/ \
  -e path_inpaint=/content/data/models/inpaint/ \
  -e path_controlnet=/content/data/models/controlnet/ \
  -e path_clip_vision=/content/data/models/clip_vision/ \
  -e path_fooocus_expansion=/content/data/models/prompt_expansion/fooocus_expansion/ \
  -e path_outputs=/content/app/outputs/ \
  ghcr.io/lllyasviel/fooocus

• -p 7865:7865：把容器内 7865 端口映射到宿主机 7865；需要改宿主机端口时写成 -p <宿主机端口>:7865。
• -v fooocus-data:/content/data：模型、配置与输出持久化到命名卷；容器重建后不丢失。
• --gpus all：把宿主机 NVIDIA 显卡透传给容器。
• CMDARGS=--listen：等价于本地启动时传入 --listen，允许容器内服务监听 0.0.0.0。

6.4 Podman 运行

Podman 按安全基线去掉特权与新增能力，并通过设备接口暴露 NVIDIA 显卡：

podman run -p 7865:7865 -v fooocus-data:/content/data -it \
  --security-opt=no-new-privileges \
  --cap-drop=ALL \
  --security-opt label=type:nvidia_container_t \
  --device=nvidia.com/gpu=all \
  -e CMDARGS=--listen \
  -e DATADIR=/content/data \
  -e config_path=/content/data/config.txt \
  -e config_example_path=/content/data/config_modification_tutorial.txt \
  -e path_checkpoints=/content/data/models/checkpoints/ \
  -e path_loras=/content/data/models/loras/ \
  -e path_embeddings=/content/data/models/embeddings/ \
  -e path_vae_approx=/content/data/models/vae_approx/ \
  -e path_upscale_models=/content/data/models/upscale_models/ \
  -e path_inpaint=/content/data/models/inpaint/ \
  -e path_controlnet=/content/data/models/controlnet/ \
  -e path_clip_vision=/content/data/models/clip_vision/ \
  -e path_fooocus_expansion=/content/data/models/prompt_expansion/fooocus_expansion/ \
  -e path_outputs=/content/app/outputs/ \
  ghcr.io/lllyasviel/fooocus

6.5 容器内路径、持久化与模型导入

容器内关键路径（来自官方 docker.md）：

模型与输出存放在 fooocus-data 命名卷：Docker 默认位于 /var/lib/docker/volumes/，Podman 位于 ~/.local/share/containers/storage/volumes/。

需要把已有模型或历史输出导入容器时，可在 docker-compose.yml（或 docker run 参数）中临时加入绑定挂载：

# 仅导入时临时启用；导入完成后可移除挂载
# - ./models:/import/models
# - ./outputs:/import/outputs

容器启动后，这些文件会被复制进 /content/data/models 与 /content/data/outputs；由于 /content/data 是持久化卷，移除临时挂载后文件仍然保留。

6.6 本地构建镜像与版本更新

从仓库源码本地构建：

# Docker
docker build . -t fooocus

# Podman
podman build . -t fooocus

使用 docker compose up 持续运行时，容器不会自动更新到最新 Fooocus 版本；手动更新流程：

git pull
docker compose build --no-cache
docker compose up

6.7 Docker 部署注意事项

• 输出路径约束：path_outputs 应保持在 /content/app 之下；放到其他位置可能导致历史记录日志报错（官方 docker.md 说明）。
• 优先使用命名卷：Docker on Mac / Windows 使用绑定挂载（bind mount）存在访问慢的问题，官方建议使用命名卷，参考 Docker 官方 Volumes 文档。
• 不支持 Apple Silicon MPS：Docker 内的 MPS（Metal Performance Shaders）后端尚未支持，问题跟踪见 PyTorch issue #81224；Apple Silicon 请走 7.6 节本地 Conda / 命令行路径。
• 网络与镜像：模型默认从 Hugging Face 下载；网络受限时设置 HF_MIRROR 指定镜像站点（见 8.4 节）。

7 方式二：Windows 便携包与本地源码运行（桌面日常使用）

除 Docker 外，官方为桌面日常使用提供 Windows 便携包，并为 Linux（Conda / venv / 原生 Python）、Apple Silicon、AMD 显卡与 Colab 提供本地启动路径。

7.1 Windows 便携包一键启动（NVIDIA 推荐）

1. 下载官方 Release 便携包：Fooocus_win64_2-5-0.7z（v2.5.0）；版本号以 Releases 页面最新发布为准。
2. 解压到目标目录，目录内包含 Fooocus 程序目录、python_embeded 内嵌运行时与 run.bat 启动脚本：

3. 双击 run.bat 启动；首次启动会按当前预设自动下载模型到 Fooocus\models\checkpoints；需要局部重绘时，首次使用会下载专用 inpaint 控制模型到 Fooocus\models\inpaint\inpaint_v26.fooocus.patch（约 1.28GB）。
4. 日志出现本地访问地址后，在浏览器打开 http://127.0.0.1:7860 进入界面。

预设启动器：

• run.bat：通用预设；
• run_anime.bat：动漫预设（2.1.60 之后提供）；
• run_realistic.bat：写实预设。

三个启动器对应不同模型，首次运行时按需自动下载；Fooocus 2.3.0 之后也可以直接在浏览器界面中切换预设。相关启动器说明见 Discussion #679。

浏览器切换预设的补充参数：

• --disable-preset-selection：禁用浏览器内预设选择；
• --always-download-new-model：切换预设时下载缺失模型；默认回退到对应预设 previous_default_models 中记录的旧模型，具体以终端输出为准。

7.2 Linux：Anaconda / Miniconda 环境

仓库 environment.yaml 固定 Python 3.10 与基础依赖：

# 克隆仓库
git clone https://github.com/lllyasviel/Fooocus.git
cd Fooocus

# 创建并激活 Conda 环境
conda env create -f environment.yaml
conda activate fooocus

# 安装固定版本依赖
pip install -r requirements_versions.txt

启动通用预设：

conda activate fooocus
python entry_with_update.py

开放局域网访问：

conda activate fooocus
python entry_with_update.py --listen

切换预设：

# 动漫预设
python entry_with_update.py --preset anime

# 写实预设
python entry_with_update.py --preset realistic

7.3 Linux：Python venv 虚拟环境

要求系统已安装 Python 3.10，且 python3 与 venv 系统包可用：

git clone https://github.com/lllyasviel/Fooocus.git
cd Fooocus

python3 -m venv fooocus_env
source fooocus_env/bin/activate
pip install -r requirements_versions.txt

# 本地启动
python entry_with_update.py

# 开放远程端口
python entry_with_update.py --listen

切换预设同样使用 --preset anime 或 --preset realistic。

7.4 Linux：原生系统 Python

确认系统 Python 为 3.10、python3 与 pip3 可用后：

git clone https://github.com/lllyasviel/Fooocus.git
cd Fooocus
pip3 install -r requirements_versions.txt

# 本地启动
python3 entry_with_update.py

# 开放远程端口
python3 entry_with_update.py --listen

模型下载位置与手动放置方式见 5.3 节目录表与 8.2 节预设模型清单。

7.5 AMD 显卡方案（实验性）

Linux AMD（ROCm）：先卸载默认 torch 系列包，再安装 ROCm 5.6 索引下的 PyTorch：

pip uninstall torch torchvision torchaudio torchtext functorch xformers
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm5.6

AMD 支持未经过密集测试，处于 Beta 状态；启动同样使用 python entry_with_update.py --preset anime 或 --preset realistic。

Windows AMD（DirectML）：下载便携包后编辑 run.bat 内容，卸载默认 torch 系列包、安装 torch-directml，并以 --directml 启动：

.\python_embeded\python.exe -m pip uninstall torch torchvision torchaudio torchtext functorch xformers -y
.\python_embeded\python.exe -m pip install torch-directml
.\python_embeded\python.exe -s Fooocus\entry_with_update.py --directml

启动动漫 / 写实预设：

.\python_embeded\python.exe Fooocus\entry_with_update.py --directml --preset anime
.\python_embeded\python.exe Fooocus\entry_with_update.py --directml --preset realistic

AMD 在 Windows 上支持同样处于实验性状态；遇到显存不足时参见 10.10 节。

7.6 Apple Silicon（M1 / M2，MPS 加速）

macOS Catalina 及以上版本的 Apple Silicon 机型可通过 PyTorch MPS 设备加速运行；Apple Silicon 没有独立显卡，出图时间明显长于独显机型。准备步骤：

1. 安装 Conda 包管理器与 PyTorch nightly，确认 PyTorch 能识别 MPS 设备；安装指引参考 Apple Developer Accelerated PyTorch training on Mac。
2. 克隆仓库：

git clone https://github.com/lllyasviel/Fooocus.git
cd Fooocus

3. 创建 Conda 环境并安装依赖：

conda env create -f environment.yaml
conda activate fooocus
pip install -r requirements_versions.txt

4. 启动：

python entry_with_update.py

部分 M2 机型在模型加载 / 卸载阶段较慢，可追加参数提速：

python entry_with_update.py --disable-offload-from-vram

首次启动会自动下载 SDXL 模型，耗时取决于网络。Mac 上支持状态为实验性；若体验不佳，官方同时推荐 macOS 专属的 DiffusionBee、Drawingthings 等应用（见 10.8 节）。Docker 路线不支持 MPS，不要在容器内运行 Apple Silicon 本地模型。

7.7 Google Colab 官方笔记本

官方提供 fooocus_colab.ipynb（最后测试 2024-08-12，由 mashb1t 完成）。在笔记本最后一行改用对应预设启动：

# 通用预设
!python entry_with_update.py --share --always-high-vram

# 动漫预设
!python entry_with_update.py --share --always-high-vram --preset anime

# 写实预设
!python entry_with_update.py --share --always-high-vram --preset realistic

补充说明：

• 也可以在界面内切换预设；切换后若出现 60 秒超时，等待模型下载完成，把预设切回初始项再切回目标预设，或刷新页面。
• Colab 免费资源有限，笔记本默认关闭 refiner；图像提示等较大功能可能导致免费层断线，官方保证基础文生图在免费层可用。
• --always-high-vram 把资源分配从内存转移到显存，在默认 T4 实例上取得性能、灵活性与稳定性的最佳平衡（参见 PR #1710 评论）。

8 配置项说明

8.1 配置文件 config.txt

首次运行 Fooocus 后，会在程序根目录生成 config.txt；同目录生成 config_modification_tutorial.txt，记录全部可配置键名、格式与示例。config.txt 可用于修改模型路径与默认参数，典型结构如下：

{
    "path_checkpoints": "D:\\Fooocus\\models\\checkpoints",
    "path_loras": "D:\\Fooocus\\models\\loras",
    "path_embeddings": "D:\\Fooocus\\models\\embeddings",
    "path_vae_approx": "D:\\Fooocus\\models\\vae_approx",
    "path_upscale_models": "D:\\Fooocus\\models\\upscale_models",
    "path_inpaint": "D:\\Fooocus\\models\\inpaint",
    "path_controlnet": "D:\\Fooocus\\models\\controlnet",
    "path_clip_vision": "D:\\Fooocus\\models\\clip_vision",
    "path_fooocus_expansion": "D:\\Fooocus\\models\\prompt_expansion\\fooocus_expansion",
    "path_outputs": "D:\\Fooocus\\outputs",
    "default_model": "realisticStockPhoto_v10.safetensors",
    "default_refiner": "",
    "default_loras": [["lora_filename_1.safetensors", 0.5], ["lora_filename_2.safetensors", 0.5]],
    "default_cfg_scale": 3.0,
    "default_sampler": "dpmpp_2m",
    "default_scheduler": "karras",
    "default_negative_prompt": "low quality",
    "default_positive_prompt": "",
    "default_styles": ["Fooocus V2", "Fooocus Photograph", "Fooocus Negative"]
}

常用键说明：

修改配置前先备份 config.txt；若改坏导致异常，直接删除 config.txt，Fooocus 会在下次启动时回到默认配置。旧版 user_path_config.txt 已废弃并移除，不要再使用。

8.2 三套预设模型与默认参数

下表整理自仓库 presets/default.json、presets/realistic.json、presets/anime.json；模型权重不随仓库分发，首次使用按预设自动下载，也可手动下载到 models/checkpoints。

模型下载地址（来自预设 checkpoint_downloads / lora_downloads）：

• 通用主模型：juggernautXL_v8Rundiffusion.safetensors
• 写实主模型：realisticStockPhoto_v20.safetensors
• 动漫主模型：animaPencilXL_v500.safetensors
• 通用 LoRA：sd_xl_offset_example-lora_1.0.safetensors
• 写实 LoRA：SDXL_FILM_PHOTOGRAPHY_STYLE_V1.safetensors

预设中 previous_default_models 记录了历史主模型文件名；切换预设时若新模型缺失，默认回退到这些旧模型，终端会输出对应提示。

8.3 常用命令行参数

以下参数整理自 README “All CMD Flags”；完整清单以 entry_with_update.py 启动帮助与当前版本为准。

监听、端口与网络

路径、输出与缓存

设备与精度

界面、预设与调试

官方故障排查特别提示：不要轻信第三方教程中 --lowvram、--gpu-only、--bf16 等错误参数；多数情况下这些参数会让情况更糟（见 10.11 节）。

8.4 Docker 环境变量与界面鉴权

Docker 环境变量（由 entrypoint.sh 读取，优先级高于 config.txt，取值会写入 config_modification_tutorial.txt）：

也可以把 config_modification_tutorial.txt 中说明的同名 JSON 配置键直接作为环境变量传入；示例见仓库 docker-compose.yml。

基本认证 auth.json：--listen 或 --share 暴露的界面默认无鉴权。在程序主目录创建 auth.json，写入账号密码列表即可启用基本认证，格式参考 auth-example.json：

[
    {
        "user": "your-username",
        "pass": "your-strong-password"
    }
]

需要多组账号时在数组中追加对象。凭据只保存在本机 auth.json 或反向代理配置中，不要提交到公开仓库，也不要写入文章、截图与分享链接。

9 常用运维命令

9.1 启动、停止与重启

Docker / Compose

# 前台启动（查看实时日志）
docker compose up

# 后台常驻启动
docker compose up -d

# 查看后台日志
docker compose logs -f

# 停止并移除容器
docker compose down

Windows 便携包

:: 通用预设
run.bat

:: 动漫预设
run_anime.bat

:: 写实预设
run_realistic.bat

Linux / macOS 命令行（已激活环境）

# 本地启动
python entry_with_update.py

# 开放局域网访问
python entry_with_update.py --listen

# 指定端口
python entry_with_update.py --listen --port 8888

# 临时公网链接
python entry_with_update.py --share

9.2 切换预设与模型

# 启动时指定预设
python entry_with_update.py --preset anime
python entry_with_update.py --preset realistic

# 浏览器内切换：2.3.0 之后支持；切换时是否下载缺失模型由参数控制
# 下载缺失模型
python entry_with_update.py --always-download-new-model

# 禁用浏览器内预设切换
python entry_with_update.py --disable-preset-selection

手动更换主模型：把合规获取的 .safetensors 放入 models/checkpoints，在界面模型下拉框选择；或在 config.txt 修改 default_model 与 default_loras（见 8.1 节）。

9.3 更新版本

Docker Compose 路线：容器不会随 docker compose up 自动更新到最新版本，需要手动拉取源码并重建镜像：

git pull
docker compose build --no-cache
docker compose up

源码 / Conda / venv 路线：

git pull
conda activate fooocus          # 或 source fooocus_env/bin/activate
pip install -r requirements_versions.txt
python entry_with_update.py

Windows 便携包：以 Release 页面最新便携包为准；替换前先备份 models/ 与 outputs/ 目录，避免模型与历史图片被覆盖。

9.4 日志、环境检查与配置备份

# Docker 查看实时日志
docker compose logs -f

# Docker 查看最近 200 行日志
docker compose logs --tail=200

# 查看 Python 版本（本地路线应为 3.10.x）
python --version

# 确认模型目录与输出目录
ls models/checkpoints
ls outputs

配置备份：在改动 config.txt、更换模型或预设前，复制一份 config.txt 与 models/ 清单；outputs/ 中的历史图片与内嵌生成参数建议定期归档到其他磁盘。

9.5 模型与输出目录维护

• 主模型、LoRA、embedding、inpaint、ControlNet、CLIP Vision 等模型分别放入 5.3 节目录表对应子目录；目录缺失时由首次启动自动创建。
• outputs/ 持续累积生成图，定期清理或迁移；Docker 环境下模型与输出都在 fooocus-data 持久化卷中，重建容器不丢失。
• 模型文件损坏时不要反复重试启动，先按 10.2 节删除损坏文件并重新下载。

10 常见故障排查

以下问题整理自官方 troubleshoot.md、README 硬件与安装小节；排查时先以默认预设、单张图片、最小提示词复现，再逐项加回模型、LoRA、参考图与参数定位。

10.1 系统交换不足导致的启动与生成异常

官方 troubleshoot.md 把下列现象归为同一根因——系统交换（虚拟内存 / Swap）不足：

• RuntimeError: CPUAllocator；
• 模型加载后停顿、随后无任何反应；
• 段错误（Segmentation Fault）、Aborted、core dumped、Killed、^C 后退出；
• 终端停在 adm 2816 后卡住；
• Connection errored out、Error 1006、WinError 10060、Read timed out；
• 控制台无报错但窗口一闪而过；
• 模型加载超过 1 分钟仍未完成。

处理口径：

• 确保系统交换至少 40GB（实际不一定要占满 40GB，40GB 是官方给出的 100% 成功运行安全值）；若系统内存超过 64GB，或许不需要系统交换，但官方并不确定。
• 交换分区位于 HDD 时模型加载会很慢，应尽量放在 SSD。
• Linux / macOS 按发行版或系统官方指引配置 Swap Space；Windows 10 / 11 默认自动管理分页文件，确保每个磁盘至少预留 40GB 空闲空间即可；若使用非官方精简版系统，其可能改动了默认分页文件设置，需要手动核对。
• 修改系统交换后重启计算机才能生效。

Windows 分页文件设置路径：此电脑右键 Properties → Advanced system settings → 高级（Advanced）→ 性能 Settings → 高级（Advanced）→ 虚拟内存 Change → 勾选自动管理或自定义大小 → 确定，对应官方指引八步如下图：

10.2 模型损坏（MetadataIncompleteBuffer / PytorchStreamReader）

• 现象：报错 MetadataIncompleteBuffer 或 PytorchStreamReader failed ...。
• 口径：这是模型文件损坏的标志，不是代码 bug。
• 处理：网络通畅时 Fooocus 会自动重新下载损坏模型；无法自动重下时手动下载。每次请求下载模型时，控制台都会输出模型 URL 与本地存放位置，按该地址重新获取后替换 models/checkpoints（或对应模型目录）中的损坏文件；下载后核对文件大小，避免半截文件。

10.3 “Torch not compiled with CUDA enabled”

• 口径：出现该提示说明没有遵循官方安装指南，安装了与显卡不匹配的 torch 版本。
• 处理：不要轻信网络上的第三方教程；Windows 使用官方便携包，Linux 按 7.2–7.4 节安装固定版本依赖，AMD 按 7.5 节对应方案准备；NVIDIA 环境确认显卡驱动与 torch CUDA 版本匹配。

10.4 subprocess-exited-with-error

• 口径：优先确认 Python 版本是否为 3.10；该报错同样常见于未按官方指南安装依赖。
• 处理：Conda 路线由 environment.yaml 固定 Python 3.10；venv / 原生路线先执行 python3 --version 核对版本，再重新 pip install -r requirements_versions.txt；不要混用其他 Python 版本创建的虚拟环境。

10.5 SSL: CERTIFICATE_VERIFY_FAILED

• 若处于国内网络环境，可先关闭 VPN 后重试，或改为手动下载模型（见 10.2 节控制台给出的模型地址）。
• 其他地区出现证书错误时，按本机证书链、系统时间与代理配置排查；官方无法给出统一修复步骤。

10.6 CUDA kernel errors 异步上报

• 现象：报错 “CUDA kernel errors might be asynchronously reported at some other API call”，仅少数设备出现，成因较复杂。
• 处理（按官方顺序）：
  1. 确认使用官方最新版本，不要使用 fork 或其他改版；
  2. 把 NVIDIA 驱动升级到最新版本（通常应为 53X，而不是 3XX / 4XX）；
  3. 仍未解决时，可能是 CUDA 12 兼容问题，可改用 CUDA 11 与 xformers：备份并删除便携包内 python_embeded 文件夹，从 Release 页面 下载 previous_old_xformers_env.7z，解压后把新的 python_embeded 文件夹放回 run.bat 旁，再启动 Fooocus；
  4. 以上步骤均无效时，按官方指引提交 Issue 并附上设备、驱动与日志信息。

10.7 找不到 NVIDIA 驱动 / 驱动版本过旧

• 现象：Found no NVIDIA driver on your system 或提示驱动过旧。
• 处理：升级 NVIDIA 显卡驱动；AMD 显卡不要走 NVIDIA 驱动路径，按 7.5 节官方 DirectML / ROCm 方案准备环境。

10.8 Apple Silicon 运行速度很慢

• 部分 Mac 用户可通过 --disable-offload-from-vram 加快模型加载与卸载。
• 当前 macOS 支持仍属实验性；官方同时推荐尝试仅面向 Mac 开发的 DiffusionBee、Drawingthings 等应用。
• Docker 路线不支持 MPS，不要在容器内运行 Apple Silicon 本地模型（见 6.7 节）。

10.9 NVIDIA 显存不足（CUDA Out Of Memory）

• 8GB 显存、6GB 显存、4GB 显存且支持 Float16（如 RTX 3050）出现 OOM，官方判断大概率属于 Bug，建议尽快提交 Issue 并附上设备型号、预设、分辨率与日志。
• 4GB 显存且不支持 Float16（如 GTX 960）的显卡很难运行 SDXL；仍可反馈 Issue，或在该设备上改用其他软件运行 SD 1.5 模型。
• 降低分辨率、生成数量与参考图强度，先以单张、默认预设验证流程；不要盲目叠加第三方低显存参数（见 10.11 节）。

10.10 AMD 显卡显存不足

• Windows 上 AMD 支持非常实验性，出现 OOM 时该设备可能无法在 Windows 运行 Fooocus；Linux 通过 ROCm 支持略好。
• 如果同一设备在其他软件上能够运行 SDXL，应及时向官方反馈以便后续支持；其他软件同样无法运行时，官方可提供的帮助有限。

10.11 误用第三方低显存参数反而加重问题

• 现象：按错误教程添加 --lowvram、--gpu-only、--bf16 等参数后，速度更慢、报错更多。
• 处理：移除这些参数；官方明确指出多数情况下这类参数会让问题恶化并引入新故障。显存档位请使用 8.3 节列出的 --always-gpu / --always-high-vram / --always-normal-vram / --always-low-vram / --always-no-vram / --always-cpu 等官方参数。

10.12 运行中突然变慢且未改动配置

• 先检查是否同时启动了两个 Fooocus 实例（两个 run.bat / 两个 entry_with_update.py 进程）；关闭多余实例后重新启动。

10.13 DirectML 警告可忽略

• Windows AMD DirectML 环境下出现 UserWarning: The operator 'aten::std_mean.correction' is not currently supported on the DML，属于可忽略的警告，不影响主要流程。

11 风险与合规说明

以下条款整理自官方 LICENSE、README、docker.md、troubleshoot.md 与通用合规口径；如与官方原文不一致，以仓库 LICENSE、README 与官方 Discussions 最新版本为准。

11.1 开源协议（GPL v3）

Fooocus 源码采用 GNU General Public License v3（仓库 LICENSE）。GPL v3 属于强 copyleft 许可证：

• 允许自由使用、研究、修改与再分发；分发修改版本时必须以相同许可证开源，并保留版权声明与许可证副本。
• 通过网络对外提供修改后的程序服务时，需按 GPL v3 与相关司法辖区要求评估开源义务；把 Fooocus 修改后嵌入自有产品或对外提供服务前，应咨询法务确认义务范围。
• 仓库依赖的 PyTorch、Gradio、transformers、rembg、GroundingDINO、Segment Anything、xformers 等第三方组件各自遵循其原始许可，使用与再分发时应分别核对。

11.2 项目状态与后继方向

• Fooocus 当前处于 LTS 仅修 Bug 状态：后续更新只处理缺陷，不再规划新功能，也没有迁移到 Flux 等新一代模型架构的计划；长期使用前应知悉这一维护水平。
• 需要 Flux 或其他新模型时，官方推荐转用 Stable Diffusion WebUI Forge 或 ComfyUI；社区维护的若干 Fooocus forks 可用于实验，但不属于官方主线，稳定性与安全更新由 fork 维护方负责。
• 官方提示 Google 搜索结果中存在多个假冒 “fooocus” 网站；获取软件只应使用 GitHub 官方仓库与 Release 页面，不要从第三方打包站下载。

11.3 模型权重与第三方素材许可

• 仓库不附带模型权重；SDXL 主模型、写实 / 动漫微调模型、LoRA、inpaint 控制模型、提示词扩展模型分别来自不同发布方，许可各异：有的仅允许非商用，有的要求署名，有的限制使用平台与人群。下载前必须阅读模型卡或模型站说明，不要默认“能下载即可商用”。
• 从 Civitai、Hugging Face 等站点获取模型时，核对发布者、许可条款、训练素材来源与年龄限制；来历不明的模型文件可能被植入恶意代码，加载前确认来源与社区评价。
• 使用他人照片、插画、角色形象作为参考图、图像提示或人脸交换素材时，涉及肖像权、著作权与商标权；公开发布、商用或参赛前应取得授权或确认素材处于可训练许可范围。

11.4 生成内容版权与平台标注

• 各司法辖区对 AI 生成图像的可版权性规定不同；Fooocus 不保证生成内容可注册版权、不保证内容原创，也不替代人工审核。
• 商业使用生成图前，核对所用模型 / LoRA 许可、训练素材来源与目标市场法规；在电商、广告、出版、社交平台发布时，遵守平台关于 AI 生成内容标注、审核与限流的规则。
• 提示词、参考图与生成结果不会自动上传云端（本机模式下）；启用 --share、Colab、API 远程调用或接入第三方组件后，数据流向由对应服务决定。

11.5 界面暴露、代码与模型安全

• --listen、--share 或 Docker 对外暴露的界面默认无鉴权；局域网 / 公网使用前必须通过 auth.json 配置基本认证，或在 Nginx / Caddy 等反向代理层叠加登录校验，避免出图能力被任意访问者使用。
• 模型文件、提示词扩展、inpaint 组件等价于可执行资源；只从官方仓库、模型卡与可信模型站获取，不运行来历不明的打包版本、python_embeded 替换包与第三方脚本。
• 服务端部署应使用普通用户权限运行，不要以 root 长期承载图形界面环境；定期更新镜像与依赖，关闭不再使用的端口与临时公网链接。

11.6 数据隐私

• 默认本机运行模式下，提示词、参考图与生成图保存在本机磁盘；生成图片内嵌生成参数元数据，公开发布前如需去除参数信息，应使用专门工具剥离元数据。
• 使用 --share、Colab、第三方镜像或云端部署时，提示词与参考图会离开本机网络；敏感人物照片、未公开产品图与商业素材不要通过此类渠道生成。
• auth.json 账号密码、模型站 Token、代理口令只保存在本机配置文件或环境变量中，不要写入公开仓库、截图、文章、文档或聊天记录。

11.7 免责声明

项目按现状（AS-IS）提供，官方不保证在特定硬件、系统版本、模型组合下持续可用，不保证生成结果正确、合规或无侵权风险；使用者自行承担出图质量、模型许可、内容版权、数据泄露与业务损失风险。如认为仓库内特定文件侵犯合法权益，请通过 GitHub Issues 提交说明，不要在公开 Issue 中上传账号凭据、模型 Token、未公开图片或敏感配置。