331 lines
9.0 KiB
Markdown
331 lines
9.0 KiB
Markdown
# ComfyUI 扩展开发手册
|
||
|
||
## 1. 项目结构
|
||
|
||
一个标准的ComfyUI扩展项目应包含以下文件：
|
||
|
||
```
|
||
├── README.md # 项目说明文档
|
||
├── __init__.py # 扩展入口文件
|
||
├── [主要功能文件].py # 核心功能实现
|
||
└── requirements.txt # 依赖项配置
|
||
```
|
||
|
||
## 2. 节点开发规范
|
||
|
||
### 2.1 基本结构
|
||
|
||
每个节点类需要定义以下基本属性：
|
||
|
||
```python
|
||
class YourNode:
|
||
RETURN_TYPES = ("IMAGE",) # 返回值类型
|
||
FUNCTION = "process" # 处理函数名称
|
||
CATEGORY = "image/pattern" # 节点分类
|
||
```
|
||
|
||
### 2.2 输入参数定义
|
||
|
||
使用 `INPUT_TYPES` 类方法定义节点的输入参数：
|
||
|
||
```python
|
||
@classmethod
|
||
def INPUT_TYPES(cls):
|
||
return {
|
||
"required": { # 必需参数
|
||
"param_name": ("TYPE", {
|
||
"default": default_value,
|
||
"min": min_value, # 数值类型可选
|
||
"max": max_value, # 数值类型可选
|
||
"step": step_value # 数值类型可选
|
||
})
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.3 最小化节点功能原则
|
||
|
||
为了确保节点的可维护性和复用性，应遵循以下原则：
|
||
|
||
1. 单一职责：
|
||
- 每个节点应专注于单一的功能或转换
|
||
- 避免在一个节点中实现多个不相关的功能
|
||
- 功能应该是原子的，不可再分
|
||
|
||
2. 参数精简：
|
||
- 只暴露必要的参数
|
||
- 参数应具有明确的用途和合理的默认值
|
||
- 避免冗余或相互依赖的参数
|
||
|
||
3. 输入输出清晰：
|
||
- 明确定义输入和输出的数据类型
|
||
- 保持数据流的简单性和直观性
|
||
- 避免复杂的数据转换和状态管理
|
||
|
||
4. 错误处理：
|
||
- 提供清晰的错误信息
|
||
- 对异常情况进行适当处理
|
||
- 保护节点不受无效输入的影响
|
||
|
||
### 2.4 图像处理注意事项
|
||
|
||
1. 输入图像格式处理：
|
||
```python
|
||
# 处理输入图像格式（从Tensor转为NumPy数组）
|
||
if isinstance(image, torch.Tensor):
|
||
img = (image[0] * 255).cpu().numpy().astype(np.uint8)
|
||
else:
|
||
img = (image[0] * 255).astype(np.uint8)
|
||
|
||
# 检查图像维度
|
||
if len(img.shape) != 3:
|
||
raise ValueError("输入图像必须是3通道RGB图像")
|
||
height, width, channels = img.shape
|
||
if channels != 3:
|
||
raise ValueError(f"输入图像必须是3通道RGB图像，当前通道数：{channels}")
|
||
```
|
||
|
||
2. 输出图像格式转换：
|
||
```python
|
||
# 创建新图像，确保尺寸与输入图像一致
|
||
result_img = Image.new('RGB', (width, height), 'black')
|
||
# ... 图像处理逻辑 ...
|
||
|
||
# 转换为ComfyUI标准格式
|
||
result_array = np.array(result_img) / 255.0
|
||
result_tensor = torch.from_numpy(result_array).float()
|
||
# 确保输出张量的维度与ComfyUI期望的格式一致
|
||
result_tensor = result_tensor.unsqueeze(0)
|
||
return (result_tensor,)
|
||
```
|
||
|
||
### 2.5 参数定义常见问题与解决方案
|
||
|
||
1. 参数类型不匹配问题：
|
||
- 问题描述：在定义节点参数时，如果参数类型与实际处理函数中的期望类型不匹配，可能导致运行时错误
|
||
- 解决方案：
|
||
- 在INPUT_TYPES中明确定义参数类型和范围
|
||
- 在处理函数中添加类型检查和转换
|
||
- 使用适当的默认值和范围限制
|
||
|
||
2. 参数范围设置：
|
||
- 问题描述：参数范围设置不当可能导致功能异常或性能问题
|
||
- 解决方案：
|
||
- 根据实际需求设置合理的最小值和最大值
|
||
- 考虑性能影响，避免过大的参数范围
|
||
- 添加参数验证逻辑
|
||
|
||
3. 参数依赖关系：
|
||
- 问题描述：某些参数可能相互依赖，需要确保它们的值在合理范围内
|
||
- 解决方案：
|
||
- 在处理函数中添加参数关系验证
|
||
- 使用条件判断确保参数组合有效
|
||
- 提供清晰的错误提示
|
||
|
||
示例代码：
|
||
```python
|
||
def process(self, image, min_radius, max_radius):
|
||
# 参数验证
|
||
if min_radius >= max_radius:
|
||
raise ValueError("最小半径必须小于最大半径")
|
||
|
||
# 类型转换和范围检查
|
||
min_radius = int(min_radius)
|
||
max_radius = int(max_radius)
|
||
if min_radius < 1:
|
||
raise ValueError("最小半径不能小于1")
|
||
|
||
# 处理逻辑
|
||
...
|
||
```
|
||
|
||
4. 最佳实践：
|
||
- 在INPUT_TYPES中使用描述性的参数名称
|
||
- 为每个参数提供合理的默认值
|
||
- 添加参数验证和错误处理
|
||
- 在文档中清晰说明参数的用途和限制
|
||
- 定期测试边界条件和异常情况
|
||
|
||
3. 图像格式转换最佳实践：
|
||
- 始终检查输入图像类型，确保正确处理Tensor和NumPy数组
|
||
- 在进行图像处理操作前，确保将图像数据范围调整到合适的区间（如0-255）
|
||
- 使用astype()明确指定数据类型，避免精度问题
|
||
- 在返回结果前，确保转换为ComfyUI期望的格式（通常是float32类型的Tensor）
|
||
- 保持输入输出图像尺寸的一致性，避免意外的尺寸变化
|
||
- 在创建新图像时，显式指定尺寸参数，确保与输入图像匹配
|
||
|
||
4. 常见错误处理：
|
||
- 检查图像维度是否正确（通常需要[batch, height, width, channels]格式）
|
||
- 注意数据类型转换可能带来的精度损失
|
||
- 处理图像格式转换时的内存使用问题
|
||
- 确保正确处理GPU和CPU之间的数据传输（使用.cpu()方法）
|
||
- 对图像尺寸和通道数进行明确的验证，提供清晰的错误信息
|
||
- 在进行图像变换操作时，验证坐标是否在有效范围内
|
||
|
||
## 3. 依赖管理
|
||
|
||
### 3.1 requirements.txt
|
||
|
||
明确指定依赖版本，避免兼容性问题：
|
||
|
||
```
|
||
numpy>=1.21.0
|
||
opencv-python>=4.5.0
|
||
torch>=1.7.0
|
||
Pillow>=8.0.0
|
||
```
|
||
|
||
## 4. 最佳实践
|
||
|
||
### 4.1 代码组织
|
||
|
||
1. 功能模块化：将不同功能的代码分离到不同的文件中
|
||
2. 使用类封装：将相关的功能和数据封装在类中
|
||
3. 提供清晰的文档注释
|
||
|
||
### 4.2 错误处理
|
||
|
||
1. 对输入参数进行验证
|
||
2. 使用适当的异常处理机制
|
||
3. 提供有意义的错误信息
|
||
|
||
### 4.3 性能优化
|
||
|
||
1. 避免不必要的数据转换
|
||
2. 合理使用内存资源
|
||
3. 考虑批处理操作
|
||
|
||
## 5. 调试技巧
|
||
|
||
1. 使用print语句或日志记录中间结果
|
||
2. 检查图像格式和数值范围
|
||
3. 验证参数有效性
|
||
|
||
## 6. 文档编写
|
||
|
||
### 6.1 README.md
|
||
|
||
包含以下内容：
|
||
|
||
1. 功能说明
|
||
2. 安装方法
|
||
3. 使用说明
|
||
4. 参数说明
|
||
5. 示例展示
|
||
|
||
### 6.2 代码注释
|
||
|
||
1. 函数和类的文档字符串
|
||
2. 关键算法步骤说明
|
||
3. 参数说明和返回值说明
|
||
|
||
## 7. 发布注意事项
|
||
|
||
1. 版本号管理
|
||
2. 更新日志维护
|
||
3. 许可证说明
|
||
4. 兼容性测试
|
||
|
||
## 8. 常见问题解决
|
||
|
||
1. 图像格式转换问题
|
||
2. 参数范围验证
|
||
3. 性能优化建议
|
||
4. 依赖冲突处理
|
||
|
||
## 9. 错误处理与最佳实践
|
||
|
||
### 9.1 图像处理错误
|
||
|
||
1. 图像格式转换错误：
|
||
- 确保在转换前检查图像类型（Tensor/NumPy）
|
||
- 验证图像维度和通道数
|
||
- 注意数据类型转换时的精度损失
|
||
|
||
2. 内存管理问题：
|
||
- 及时释放大型图像数据
|
||
- 避免不必要的数据复制
|
||
- 使用适当的数据类型减少内存占用
|
||
|
||
### 9.2 参数配置错误
|
||
|
||
1. 参数范围验证：
|
||
- 明确指定参数的有效范围
|
||
- 提供合理的默认值
|
||
- 添加参数类型检查
|
||
|
||
2. 配置文件错误：
|
||
- 使用标准的配置文件格式
|
||
- 提供配置模板和示例
|
||
- 添加配置验证机制
|
||
|
||
### 9.3 OpenCV函数参数处理
|
||
|
||
1. 数据类型转换：
|
||
- 确保输入数组类型正确（如uint8、float32等）
|
||
- 注意数值范围的转换（如0-255到0-1的归一化）
|
||
- 处理特殊值（如NaN、Inf）的检查
|
||
|
||
2. 参数验证：
|
||
- 检查矩阵维度和通道数
|
||
- 验证核大小的奇偶性要求
|
||
- 确保阈值范围的合法性
|
||
|
||
3. 错误处理：
|
||
- 捕获并处理OpenCV异常
|
||
- 提供详细的错误信息和建议
|
||
- 实现优雅的降级处理
|
||
|
||
4. 性能优化：
|
||
- 避免频繁的数据类型转换
|
||
- 合理使用就地操作（in-place operation）
|
||
- 注意内存管理和资源释放
|
||
|
||
### 9.3 Git操作规范
|
||
|
||
1. Commit信息规范：
|
||
- **必须使用引号包裹commit信息**，这是强制要求：
|
||
```bash
|
||
# 正确示例
|
||
git commit -m "feat: 添加新功能"
|
||
git commit -m "fix: 修复图像处理bug"
|
||
|
||
# 错误示例
|
||
git commit -m feat: 添加新功能 # 没有使用引号
|
||
git commit -m 'fix: 修复bug' # 使用了单引号
|
||
```
|
||
|
||
- 采用统一的commit前缀：
|
||
* feat: 新功能
|
||
* fix: 修复bug
|
||
* docs: 文档更新
|
||
* style: 代码格式调整
|
||
* refactor: 代码重构
|
||
* test: 测试相关
|
||
* chore: 构建过程或辅助工具的变动
|
||
|
||
2. 分支管理：
|
||
- 主分支保持稳定
|
||
- 功能开发使用feature分支
|
||
- 版本发布使用release分支
|
||
|
||
3. 代码提交前检查：
|
||
- 运行测试确保功能正常
|
||
- 检查代码格式
|
||
- 更新文档和注释
|
||
|
||
## 10. 社区贡献
|
||
|
||
1. 代码风格规范
|
||
2. Pull Request流程
|
||
3. Issue提交指南
|
||
|
||
## 10. 参考资源
|
||
|
||
1. ComfyUI官方文档
|
||
2. 相关技术文档
|
||
3. 示例项目
|
||
|
||
## 许可证
|
||
|
||
MIT License |