个人版 ControlNet 安装教程：升级回滚操作全流程，附 API 调用测试步骤

安装前准备：先确认运行环境

ControlNet 通常作为 Stable Diffusion WebUI 的扩展使用，个人版部署重点在于本地环境稳定、模型路径正确、版本可控。开始前建议准备一台具备独立显卡的电脑，显存 6GB 以上体验更稳；系统可使用 Windows、macOS 或 Linux，但新手更适合在 Windows 环境下操作。基础组件包括 Python、Git、Stable Diffusion WebUI 主程序，以及至少一个可正常出图的基础模型。

安装前先运行一次 WebUI，确认能够打开本地页面并生成图片。如果主程序本身无法启动，不建议直接安装扩展，否则排查范围会扩大。还要确认 Python 版本与 WebUI 要求一致，常见组合为 Python 3.10.x。路径命名尽量使用英文和数字，避免中文目录、空格和特殊符号，能减少依赖安装失败、模型读取异常等问题。

安装 ControlNet 扩展的标准流程

进入 Stable Diffusion WebUI 页面后，依次打开“Extensions”扩展管理页，选择“Install from URL”。在扩展地址栏填入 ControlNet 对应的官方仓库地址，然后点击安装。安装完成后不要急着使用，先回到“Installed”页点击“Apply and restart UI”，让 WebUI 重启并加载新组件。

如果更习惯手动安装，也可以进入 WebUI 根目录下的 extensions 文件夹，通过 Git 克隆扩展仓库。完成后重启 WebUI，页面左侧或脚本区域应出现 ControlNet 面板。若没有显示，优先检查扩展目录是否放错、仓库是否完整、控制台是否有报错信息。

扩展只是功能入口，还需要放置对应模型文件。ControlNet 常见模型包括边缘线、深度、姿态、线稿、分割等类型，不同模型负责不同控制方式。下载后的模型文件通常放在 extensions/sd-webui-controlnet/models 目录，也可根据新版扩展提示放入 models/ControlNet 目录。放置完成后刷新模型列表，或重启 WebUI 使其识别。

首次使用：确认插件与模型都可用

打开文生图或图生图页面，展开 ControlNet 面板。勾选启用，上传一张参考图，选择预处理器与模型。预处理器和模型要匹配，例如边缘类预处理器搭配边缘控制模型，姿态类预处理器搭配姿态控制模型。参数上，新手可先保持默认，只调整控制权重和启用像素完美模式。

点击生成后，如果预览图能正常显示控制图，且最终图片跟随参考结构，说明安装成功。若提示模型不存在，检查模型后缀、目录位置和文件是否完整；若提示预处理器缺失，可在扩展页更新后重启，或查看依赖是否安装成功。

更新升级：推荐先备份再操作

ControlNet 更新通常是为适配新版 WebUI、修复错误、增加预处理器或优化性能。升级前建议记录当前可用版本，备份 extensions/sd-webui-controlnet 目录，尤其是自定义配置、模型目录说明和启动参数。模型文件体积较大，备份时可只记录路径，不必重复复制全部文件。

通过页面升级时，进入“Extensions”的“Installed”页，点击“Check for updates”，待检测完成后再点击“Apply and restart UI”。如果使用命令方式，可进入扩展目录执行 git pull，完成后重启 WebUI。升级后第一次启动时间可能更长，因为系统可能重新检查依赖或缓存。

升级后应做三项验证：第一，WebUI 是否能正常打开；第二，ControlNet 面板是否出现；第三，至少用一个旧工作流重新生成测试图。如果旧参数无法复现，可能是预处理器名称、默认权重或模型路径发生变化，需要查看更新说明并重新选择。

升级回滚：出现异常时如何恢复

回滚适用于升级后无法启动、生成结果明显异常、接口调用失败、旧项目不兼容等情况。最稳妥的方法是使用安装前的备份目录直接替换当前扩展目录。替换前先关闭 WebUI，避免文件被占用；替换完成后再启动，并观察控制台日志。

如果通过 Git 管理扩展，也可以在扩展目录查看提交记录，选择之前稳定的提交版本进行回退。操作思路是先查看历史版本，再切换到目标版本，最后重启 WebUI。回滚后不要立即再次更新，建议先完成出图测试和接口测试，确认问题确实由版本变化引起。

需要注意，扩展回滚不等于模型回滚。若同时更换过模型文件、预处理器文件或 WebUI 主程序，也要分别排查。个人用户常见误区是只回退插件，却忽略基础程序升级带来的兼容问题。建议建立简单的版本记录表，写明 WebUI 版本、ControlNet 版本、模型名称、显卡驱动版本和最近一次可用时间。

API 配置：开启接口能力

如果需要通过脚本或第三方前端调用 ControlNet，需要先让 WebUI 开启 API。常见做法是在启动参数中加入 --api，然后重新启动 WebUI。启动成功后，本地服务会提供接口端点，默认地址通常为 http://127.0.0.1:7860。个人电脑使用时建议只在本机调用，不要随意开放到外部网络。

API 调用的核心是向图像生成接口提交请求，并在参数中附带 ControlNet 控制单元。请求内容一般包括提示词、反向提示词、采样步数、尺寸、种子、基础模型设置，以及 ControlNet 的输入图、预处理器、模型名称、控制权重、起止步比例等。输入图通常需要转为 base64 字符串，模型名称应与 WebUI 下拉框显示一致。

API 调用测试步骤

第一步，确认 WebUI 已带 --api 启动，并在浏览器访问本地地址能打开页面。第二步，准备一张尺寸适中的参考图，建议先使用 512×512 或 768×768，降低显存压力。第三步，用接口工具或脚本向 txt2img 或 img2img 接口发送测试请求。请求中先使用最少参数，确保基础出图成功，再逐步加入 ControlNet 参数。

第四步，检查返回结果。正常情况下，接口会返回生成图的 base64 数据和生成信息。若返回空值或错误提示，先看 WebUI 控制台日志，通常能定位到模型名称错误、预处理器不可用、图片编码格式不正确或显存不足。第五步，将同一组参数在 WebUI 页面手动测试一次，如果页面可用而 API 不可用，问题多半在请求字段；如果页面也失败，则优先检查扩展和模型。

测试时不要一开始就并发请求，也不要设置过大的分辨率和批量数量。个人电脑更适合单任务验证，确认稳定后再增加复杂度。接口调用涉及本地文件和生成内容，建议只处理自己有权使用的素材，不要上传敏感照片或包含隐私信息的图片。

常见问题与处理建议

问题一：安装后页面没有 ControlNet。处理方式是确认扩展目录是否正确，重启是否完成，控制台是否提示依赖安装失败。必要时删除扩展目录重新安装。问题二：模型列表为空。优先检查模型是否放在正确目录，文件名是否被系统隐藏后缀影响，刷新列表后仍无效再重启。

问题三：预处理器报错。可能是依赖缺失、版本不匹配或缓存异常。可先更新扩展并重启；若升级后才出现，则尝试回滚到稳定版本。问题四：生成速度明显变慢。ControlNet 会额外占用显存和计算资源，可降低分辨率、减少控制单元数量、关闭高分辨率修复或使用轻量模型。

问题五：API 返回 404 或连接失败。通常是没有开启 --api、端口不一致、服务未启动或请求地址写错。问题六：接口返回模型找不到。复制 WebUI 下拉框里的完整模型名称最稳，不要凭文件名手写。

安全边界与实用习惯

个人版 ControlNet 适合学习、创作辅助、构图控制、草图上色和产品原型验证，但不应把未经确认的扩展、模型和脚本随意放入生产环境。下载组件尽量选择可信来源，更新前保留可用版本，遇到异常先看日志再改配置，不要同时修改多个变量。

长期使用建议形成三套习惯：一是稳定版本不频繁更新，除非需要新功能或修复关键问题；二是每次升级前记录版本和备份配置；三是 API 测试先小图、单次、低参数，确认无误后再接入自动化流程。这样既能享受 ControlNet 带来的可控生成能力，也能在升级失败时快速恢复工作环境。