# Nunchaku FLUX.1-dev ComfyUI插件开发：Python SDK接入自定义功能 ## 1. 引言：从使用到定制，解锁更多可能 如果你已经成功在ComfyUI里用上了Nunchaku FLUX.1-dev模型，体验过它生成高清图片的惊艳效果，那么恭喜你，你已经迈出了第一步。但你可能也发现了，ComfyUI的节点式操作虽然直观，但在处理一些复杂、批量的任务时，或者当你想要把AI生图能力集成到自己的应用里时，手动点点划划就显得有些力不从心了。 这时候，Python SDK的价值就体现出来了。它就像给你的FLUX.1-dev模型装上了一套“遥控器”和“自动化脚本”，让你能通过代码来精准控制每一个生成步骤，实现批量处理、参数动态调整、甚至与其他系统无缝对接。今天，我们就来聊聊如何通过Nunchaku的Python SDK，将FLUX.1-dev的强大能力接入到你自己的项目中，开发出真正属于你的自定义功能。 **学习目标**：读完本文，你将掌握如何使用Nunchaku Python SDK来调用FLUX.1-dev模型，并基于此构建一个简单的自动化文生图工具。 **前置知识**：你需要对Python有基本了解，并且已经按照之前的教程在本地部署好了ComfyUI和Nunchaku FLUX.1-dev插件。如果你还没完成这一步，建议先回头看看环境搭建部分。 ## 2. 理解Nunchaku Python SDK：你的代码“遥控器” 在开始写代码之前，我们先搞清楚Nunchaku Python SDK到底是什么，以及它能帮我们做什么。 简单来说，Nunchaku插件不仅提供了ComfyUI的图形界面节点，还封装了一套Python接口（SDK）。这套接口允许你绕过ComfyUI的Web界面，直接通过Python代码来构建工作流、设置参数、触发推理并获取结果。这带来了几个核心优势： - **自动化与批处理**：你可以写个循环，一次性生成几百张不同主题的图片，而不用在界面上重复操作。 - **集成与扩展**：将生图能力作为后端服务，轻松集成到你的网站、APP或其他自动化流程中。 - **参数化与实验**：方便地进行A/B测试，比如系统性地测试不同采样器、步数对出图效果的影响。 - **自定义逻辑**：在生图前后加入你自己的处理逻辑，比如自动分析提示词、对生成的图片进行二次筛选或后处理。 ### 2.1 SDK核心概念速览 Nunchaku SDK的设计思想与ComfyUI的节点工作流一脉相承，主要包含以下几个关键对象： 1. **`NunchakuSDK`**：这是总入口，用于连接和管理你的ComfyUI服务。 2. **`Workflow`**：代表一个完整的工作流，由多个节点（Node）连接而成。 3. **`Node`**：工作流中的基本单元，对应ComfyUI中的一个功能节点（如加载模型、输入提示词、执行推理）。 4. **`Connection`**：定义节点之间的连接关系，即数据如何从一个节点流向另一个节点。 我们的目标，就是用代码“画”出之前在ComfyUI界面上用鼠标连接的那个工作流。 ## 3. 环境准备与SDK安装 确保你的ComfyUI服务正在运行（通常通过 `python main.py` 启动，默认地址是 `http://127.0.0.1:8188`）。我们将在这个服务的基础上，通过SDK进行远程调用。 首先，在你的Python开发环境中安装Nunchaku SDK包： ```bash # 建议在ComfyUI相同的Python环境下操作，以避免依赖冲突 pip install nunchaku ``` 安装完成后，可以通过以下命令快速验证SDK是否可用，以及查看已安装的节点类型： ```python import nunchaku # 列出所有可用的节点类型（这需要连接到一个运行的ComfyUI实例） # 我们先初始化SDK，连接到本地服务 client = nunchaku.NunchakuSDK(base_url="http://127.0.0.1:8188") print(client.node_types) # 这会打印一长串列表，包含所有已注册的节点 ``` 如果你看到输出中包含 `NunchakuLoader`， `NunchakuKSampler` 等与Nunchaku相关的节点类型，说明SDK连接成功。 ## 4. 实战：用Python SDK构建FLUX.1-dev文生图工作流 理论说再多不如动手试。我们现在就来用代码完整复现一个基础的FLUX.1-dev文生图流程。 ### 4.1 初始化SDK与创建工作流 ```python import nunchaku import json from PIL import Image import io import requests # 1. 初始化SDK，连接到你的ComfyUI服务器 client = nunchaku.NunchakuSDK( base_url="http://127.0.0.1:8188", # ComfyUI服务地址 # 如果需要认证，可以添加api_key等参数 ) # 2. 创建一个新的工作流对象 workflow = client.create_workflow() ``` ### 4.2 添加并连接节点 接下来，我们要像搭积木一样，把需要的节点添加到工作流中，并正确连接它们。我们以使用 `nunchaku-flux.1-dev.json` 工作流为蓝本，构建一个简化版本。 ```python # 3. 添加节点 # 3.1 加载Nunchaku FLUX.1-dev主模型 loader_node = workflow.add_node( node_type="NunchakuLoader", title="Load FLUX.1-dev Model" ) # 设置模型路径（确保路径与你在ComfyUI中设置的一致） loader_node.set_input("ckpt_name", "svdq-int4_r32-flux.1-dev.safetensors") # 3.2 加载CLIP文本编码器 clip_node = workflow.add_node( node_type="CLIPTextEncode", title="Encode Positive Prompt" ) # 设置正面提示词 positive_prompt = "A beautiful landscape with mountains and lakes, ultra HD, realistic, 8K" clip_node.set_input("text", positive_prompt) # 连接：将Loader节点的CLIP输出连接到CLIPTextEncode节点的CLIP输入 workflow.connect(loader_node.outputs("CLIP"), clip_node.inputs("clip")) # 3.3 加载T5文本编码器 (FLUX模型需要双编码器) t5_node = workflow.add_node( node_type="T5TextEncode", title="Encode Prompt with T5" ) t5_node.set_input("text", positive_prompt) # 连接：将Loader节点的T5输出连接到T5TextEncode节点的T5输入 workflow.connect(loader_node.outputs("T5"), t5_node.inputs("t5")) # 3.4 设置空提示词（负面提示词） clip_neg_node = workflow.add_node( node_type="CLIPTextEncode", title="Encode Negative Prompt" ) clip_neg_node.set_input("text", "") # 可以填入你不希望出现的元素，如“blurry, bad anatomy” workflow.connect(loader_node.outputs("CLIP"), clip_neg_node.inputs("clip")) t5_neg_node = workflow.add_node( node_type="T5TextEncode", title="Encode Negative Prompt with T5" ) t5_neg_node.set_input("text", "") workflow.connect(loader_node.outputs("T5"), t5_neg_node.inputs("t5")) # 3.5 使用Nunchaku专用的采样器 ksampler_node = workflow.add_node( node_type="NunchakuKSampler", title="Sample Image" ) # 设置采样参数 ksampler_node.set_input("steps", 20) ksampler_node.set_input("cfg", 7.0) ksampler_node.set_input("sampler_name", "euler") ksampler_node.set_input("scheduler", "simple") ksampler_node.set_input("denoise", 1.0) # 连接多个输入： # 模型 workflow.connect(loader_node.outputs("MODEL"), ksampler_node.inputs("model")) # 正面条件（CLIP + T5） workflow.connect(clip_node.outputs("CONDITION"), ksampler_node.inputs("positive")) workflow.connect(t5_node.outputs("CONDITION"), ksampler_node.inputs("positive_t5")) # 负面条件 workflow.connect(clip_neg_node.outputs("CONDITION"), ksampler_node.inputs("negative")) workflow.connect(t5_neg_node.outputs("CONDITION"), ksampler_node.inputs("negative_t5")) # 随机种子 ksampler_node.set_input("seed", 42) # 3.6 加载VAE解码器 vae_node = workflow.add_node( node_type="VAEDecode", title="Decode Latent to Image" ) workflow.connect(loader_node.outputs("VAE"), vae_node.inputs("vae")) workflow.connect(ksampler_node.outputs("LATENT"), vae_node.inputs("samples")) # 3.7 保存图片节点（这是为了获取输出） save_node = workflow.add_node( node_type="SaveImage", title="Save Generated Image" ) workflow.connect(vae_node.outputs("IMAGE"), save_node.inputs("images")) ``` ### 4.3 执行工作流并获取结果 节点和连接都设置好后，就可以触发执行了。 ```python # 4. 执行工作流 print("开始执行工作流...") result = workflow.execute() print("工作流执行完成！") # 5. 处理输出结果 # SaveImage节点的输出中包含生成图片的信息 if result and 'output' in result: # 找到SaveImage节点的输出 for node_id, node_output in result['output'].items(): if 'images' in node_output: for img_info in node_output['images']: print(f"图片已生成: {img_info['filename']}") # 图片数据在img_info['subfolder']和img_info['filename']中 # 实际文件保存在ComfyUI的output目录下 # 我们可以直接通过HTTP请求获取它 image_url = f"http://127.0.0.1:8188/view?filename={img_info['filename']}&subfolder={img_info['subfolder']}&type=output" response = requests.get(image_url) if response.status_code == 200: # 用PIL打开图片 image = Image.open(io.BytesIO(response.content)) # 可以在这里进行后续处理，比如保存到自定义路径、显示、分析等 custom_save_path = f"./my_generated_{img_info['filename']}" image.save(custom_save_path) print(f"图片已保存至: {custom_save_path}") # 显示图片（如果在Jupyter等环境中） # image.show() break else: print("未找到生成的图片输出。") else: print("工作流执行失败或没有输出。") ``` 运行这段代码，如果一切顺利，你会在终端看到执行日志，并在当前目录下找到生成的图片。恭喜你，你已经成功用代码驱动FLUX.1-dev完成了一次文生图！ ## 5. 进阶：封装成自定义函数与批量处理 上面的代码虽然能跑通，但作为模块还不太方便。我们把它封装成一个更易用的函数。 ### 5.1 封装核心生成函数 ```python class FluxImageGenerator: def __init__(self, comfyui_url="http://127.0.0.1:8188"): """初始化生成器，连接到ComfyUI服务""" self.client = nunchaku.NunchakuSDK(base_url=comfyui_url) print(f"已连接到ComfyUI服务: {comfyui_url}") def generate_image(self, positive_prompt: str, negative_prompt: str = "", model_name: str = "svdq-int4_r32-flux.1-dev.safetensors", steps: int = 20, cfg_scale: float = 7.0, seed: int = None, width: int = 1024, height: int = 1024, sampler: str = "euler", scheduler: str = "simple"): """ 使用FLUX.1-dev模型生成单张图片 参数: positive_prompt: 正面提示词 negative_prompt: 负面提示词 model_name: 模型文件名 steps: 推理步数 cfg_scale: 提示词相关性 seed: 随机种子，None则为随机 width: 图片宽度 height: 图片高度 sampler: 采样器名称 scheduler: 调度器名称 返回: PIL.Image对象 或 None """ import random if seed is None: seed = random.randint(0, 2**32 - 1) workflow = self.client.create_workflow() # --- 省略节点创建和连接的详细代码，与第4节类似 --- # 这里需要将第4.2节的代码逻辑封装进来 # 关键改动：需要添加一个EmptyLatentImage节点来设置尺寸 # ... # --- 封装代码结束 --- # 为简化示例，这里省略完整的节点构建代码。 # 实际使用时，你需要将第4.2节的逻辑完整地封装在这个函数里。 # 重点是处理好尺寸参数（width, height）的传入。 print(f"正在生成: {positive_prompt[:50]}...") result = workflow.execute() # 图片获取逻辑（与4.3节类似） # ... # return image print("【提示】此示例省略了完整的节点构建代码。请参考第4节完成函数封装。") return None def batch_generate(self, prompt_list, **kwargs): """批量生成图片""" images = [] for i, prompt in enumerate(prompt_list): print(f"批量生成进度: {i+1}/{len(prompt_list)}") # 可以为每一张图设置不同的seed current_kwargs = kwargs.copy() if 'seed' not in current_kwargs: current_kwargs['seed'] = None # 使用随机种子 img = self.generate_image(positive_prompt=prompt, **current_kwargs) if img: images.append(img) return images ``` ### 5.2 使用封装类进行批量创作 假设我们想为一系列商品生成宣传图： ```python # 初始化生成器 generator = FluxImageGenerator() # 定义一系列提示词 product_prompts = [ "A sleek modern smartphone on a marble table, product photography, studio lighting, 8K", "A pair of running shoes on a mountain trail at sunrise, dynamic angle, detailed texture, advertisement style", "A ceramic coffee cup with steam rising, on a wooden desk next to a laptop, cozy morning atmosphere, photorealistic", ] # 批量生成（这里由于函数未完整实现，仅展示调用方式） # generated_images = generator.batch_generate(product_prompts, steps=25, cfg_scale=7.5) # 对每张图片进行后续处理，例如上传到CMS、添加水印等 # for idx, img in enumerate(generated_images): # img.save(f"./batch_output/product_{idx}.png") # # ... 你的自定义逻辑 ``` ## 6. 更进一步的探索：SDK高级用法与自定义节点 通过SDK，你不仅能调用现有节点，还能探索更高级的用法。 ### 6.1 动态工作流与条件生成 你可以根据输入参数动态改变工作流结构。例如，根据用户选择决定是否加载LoRA模型： ```python def generate_with_optional_lora(prompt, use_lora=False, lora_name=None, lora_strength=0.8): workflow = client.create_workflow() loader = workflow.add_node("NunchakuLoader", title="Loader") loader.set_input("ckpt_name", "svdq-int4_r32-flux.1-dev.safetensors") # ... 添加CLIP, T5编码器等节点 ... if use_lora and lora_name: # 动态添加LoRA加载和应用节点 lora_loader = workflow.add_node("LoraLoader", title=f"Load {lora_name}") lora_loader.set_input("lora_name", lora_name) lora_loader.set_input("strength_model", lora_strength) lora_loader.set_input("strength_clip", lora_strength) # 将LoRA节点连接到主模型和CLIP workflow.connect(loader.outputs("MODEL"), lora_loader.inputs("model")) workflow.connect(loader.outputs("CLIP"), lora_loader.inputs("clip")) # 后续节点应连接LoRALoader的输出，而非原始Loader的输出 # ... else: # 不使用LoRA，直接连接原始Loader输出 # ... # ... 执行工作流 ... ``` ### 6.2 与外部系统集成 SDK让FLUX.1-dev可以轻松成为你应用后端的一部分： - **Web API服务**：使用FastAPI或Flask包装上面的 `FluxImageGenerator` 类，提供一个 `/generate` 接口。 - **自动化内容管道**：从数据库读取内容需求，自动生成配图，并上传到图床或内容管理系统。 - **交互式应用**：构建一个带有简单前端的工具，让团队成员可以提交提示词，后台自动排队生成。 ## 7. 总结 通过本文，我们走通了使用Nunchaku Python SDK驱动FLUX.1-dev模型的完整流程。从最基础的连接、构建工作流，到封装成可复用的类，再到展望更复杂的集成场景，你会发现，一旦掌握了用代码控制这个“AI画师”的方法，创意的边界就被大大拓宽了。 **核心收获回顾**： 1. **SDK是桥梁**：它连接了你的Python代码与ComfyUI中运行的Nunchaku FLUX.1-dev模型。 2. **工作流即代码**：用 `Node` 和 `Connection` 对象，以编程方式精确复现图形界面上的操作。 3. **自动化是核心价值**：无论是批量生成、参数扫描还是系统集成，SDK都将你从重复的鼠标操作中解放出来。 4. **从脚本到服务**：你可以将生成逻辑封装成函数、类，乃至一个独立的微服务，赋能更多业务场景。 **下一步建议**： - **动手实践**：将第4节的示例代码在你的环境中完整跑通，这是理解一切的基础。 - **阅读官方文档**：Nunchaku和ComfyUI的SDK可能有更详细的参数说明和高级特性。 - **尝试自定义节点**：如果你有独特的需求，甚至可以研究如何为ComfyUI开发自己的自定义节点，并通过SDK调用它。 - **关注性能与队列**：对于生产环境，需要考虑ComfyUI的队列管理、生成状态查询和错误处理。 释放代码的力量，让Nunchaku FLUX.1-dev的创造力在你的指尖流淌，去构建那些曾经只存在于想象中的智能应用吧。 --- > **获取更多AI镜像** > > 想探索更多AI镜像和应用场景？访问 [CSDN星图镜像广场](https://ai.csdn.net/?utm_source=mirror_blog_end)，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。