InvokeAI 默认工作流Default Workflows机制全解析同步原理、JSON 规范与发布校验【免费下载链接】InvokeAIInvoke is a leading creative engine for Stable Diffusion models, empowering professionals, artists, and enthusiasts to generate and create visual media using the latest AI-driven technologies. The solution offers an industry leading WebUI, and serves as the foundation for multiple commercial products.项目地址: https://gitcode.com/GitHub_Trending/in/InvokeAIInvokeAI 的默认工作流是随应用一起内置在invokeai/app/services/workflow_records/default_workflows目录中的一组官方工作流 JSON应用启动时会自动将其同步进用户的工作流库workflow_library供所有用户在工作流库Workflow Library→ Default Workflows标签页中直接加载使用。本文以该目录下的 README.md 为主线结合同步实现源码、数据模型与测试用例完整讲解默认工作流的同步机制、文件编写规范、资源约束以及发布前的校验流程帮助开发者为 InvokeAI 贡献或维护官方内置工作流。一、什么是默认工作流默认工作流Default Workflows是一批由 InvokeAI 官方维护、随安装包一起分发的.json工作流文件。它们与用户自己创建的工作流在数据层面共享同一个workflow_library数据库表但通过category default字段与用户工作流category user区分开来。核心定位体现在三方面开机即用用户无需手工导入启动应用后即可在Default Workflows标签页看到全部内置工作流只读共享它们不属于任何单个用户对数据库中的查询而言默认工作流会始终包含在每个用户的列表结果中见下文 SQL 逻辑稳定基准作为官方示例它们演示了 InvokeAI 各种模型与节点组合的推荐用法。二、目录结构与内置工作流清单默认工作流的存放位置是固定目录invokeai/app/services/workflow_records/default_workflows/。当前仓库中该目录包含一份README.md和 26 个 JSON 工作流文件覆盖了 InvokeAI 主要能力面能力方向内置工作流示例文生图Text to Image - SDXL.json、Text to Image - SD1.5.json、SD3.5 Text to Image.json、Flux Text to Image.json、CogView4_TextToImage.json、Wan 2.2 Text to Image.json图生图 / 编辑FLUX Image to Image.json、Wan 2.2 Image to Image.json、Extend Video to Image - Wan 2.2 Lightning.jsonLoRA / 细节增强Text to Image with LoRA.json、Face Detailer with IP-Adapter Canny (See Note in Details).jsonControlNetMulti ControlNet (Canny Depth).json、ESRGAN Upscaling with Canny ControlNet.json视频生成Wan 2.2Text to Video - Wan 2.2 Lightning.json、Image to Video - Wan 2.2 Lightning.json、Extend Video - Wan 2.2 Lightning.json、Interpolate 2 Images to Video - Wan 2.2 Lightning.json以及带 Concept LoRAs 和 TI2V-5B 的变体图像增强 / 放大Tiled Upscaling (Beta).json、MultiDiffusion SD1.5.json、MultiDiffusion SDXL.json、Prompt from File.json这些 JSON 文件构成了应用的出厂工作流集。测试 test_default_workflows_registry.py 中专门有一个守卫用例断言 Wan/Video 相关工作流 glob 能匹配到恰好 12 个文件防止重命名或误删后目录静默为空。三、同步机制启动时的三步增删改默认工作流并非静态资源而是在应用启动时被主动同步进数据库。核心实现位于 workflow_records_sqlite.py 的_sync_default_workflows()方法它由存储层的start(invoker)钩子触发workflow_records_sqlite.py。同步算法完整流程如下扫描目录通过workflows_dir.glob(*.json)收集default_workflows目录下所有 JSON 文件校验并解析用WorkflowValidator.validate_json()对每个文件做严格 schema 校验随后断言id必须以default_开头、meta.category必须为default任一不满足即抛出断言异常整个启动同步失败差异比对对每个文件尝试按id从数据库读取已有记录若数据库中没有该 id → 加入workflows_to_add新增若数据库中已存在但内容与文件不一致 → 加入workflows_to_update更新若内容完全一致 → 跳过清理过期项查询数据库中所有category default的记录凡是 id 不在当前文件集合中的直接删除意味着从目录中移除某个 JSON重启后它就会从工作流库中消失执行写库对workflows_to_add执行INSERT对workflows_to_update执行UPDATE对过期项执行DELETE——注意这些操作都绕过公有的create/update/delete方法因为后者被设计为仅处理用户工作流见下文数据库层的硬约束。源码注释明确指出了该设计的一个取舍出于实现简单每次启动都会用目录内容整体替换默认工作流而非按版本增量更新因此默认工作流的updated_at、opened_at时间戳没有参考价值每次启动都会被覆盖。从 SQL 查询层面也能看到默认工作流的永久可见特性。在get_many、counts_by_tag、counts_by_category、get_all_tags等方法中当传入user_id做范围限定多用户模式时条件统一拼接为(user_id ? OR category default)workflow_records_sqlite.py即默认工作流永远出现在任何用户的列表、标签计数与分类统计中。四、编写默认工作流的四条硬性规范README 明确了默认工作流必须满足的规则结合数据模型代码可逐一拆解1. ID 必须以default_开头且保持稳定id 示例default_5e8b008d-c697-45d0-8883-085a954c6aceWorkflow模型的id字段被用于数据库主键workflow_idworkflow_records_common.py。同步时按 id 判断新增/更新/删除因此更新工作流时必须保留原 id否则会被当作一个全新工作流插入旧 id 对应的记录则在清理过期项阶段被删除。由于普通编辑工具保存时可能重新生成 idREADME 特别提醒你可能需要手动保留该 id。2.meta.category必须为defaultmeta字段由 WorkflowMeta 定义包含version工作流 schema 版本必须是合法的 semver 语义化版本号与category两项。WorkflowCategory枚举只有两个取值user和defaultworkflow_records_common.py。同步时若 category 不是default会直接抛出断言异常中断启动assert workflow_from_file.meta.category is WorkflowCategory.Default, ( fInvalid default workflow category: {workflow_from_file.meta.category} )3. 默认工作流不可被用户编辑用户加载默认工作流后无法直接保存回原位。这在数据库层有双重保障create()与update()方法开头即检查workflow.meta.category is WorkflowCategory.Default是则抛出ValueError(Default workflows cannot be created/updated)workflow_records_sqlite.pydelete()同样拒绝删除默认工作流workflow_records_sqlite.py。用户在 UI 中加载并保存默认工作流时行为是另存为一份副本以用户自己的 id 落库为category user记录原默认工作流保持不变——这正是 README 所述they will save as a copy of the default workflow的底层原因。4. 默认工作流出现在Default Workflows标签页前端工作流库按category过滤展示category default的记录集中显示在Default Workflows标签页用户可随时加载、复制、另存但永远无法覆盖其原始内容。五、资源约束不要引用用户安装的模型与图片默认工作流是出厂配置必须对任何环境都成立。README 强调默认工作流不应引用任何用户创建或安装的资源包括图片和模型。原因在于资源对象的引用方式。以模型为例工作流中的模型节点如main_model_loader、lora_loader、vae_loader通过模型的UUID关联具体模型实例。模型 UUID 是模型安装时生成的唯一标识不同用户/不同安装环境中即使同一个 Juggernaut 模型也会有不同的 UUID。因此若默认工作流硬编码了某个 SDXL 模型如 Juggernaut的 UUID用户加载时即使本地安装了同名模型UUID 也对不上结果就是节点上出现模型缺失警告用户必须手动重新选择模型违背了开箱即用的初衷。同样的逻辑适用于图片默认工作流中若引用了某个固定的输入图片资源该资源在其他用户环境中并不存在。正确做法默认工作流中的模型/图片类输入一律保持未赋值状态工作流 JSON 中不写死 UUID由用户加载后自行选择或仅使用 InvokeAI 自带的、随仓库分发的资源例如invokeai/assets/data目录下的示例数据。从实际文件看Text to Image - SDXL 的exposedFields恰好把model、vae_model、board等字段暴露给前端表单让用户在加载后自己填入模型——这就是规避 UUID 问题的最佳实践示范。六、工作流 JSON 的结构剖析以 Text to Image - SDXL.json 为例默认工作流文件的顶层字段由Workflow模型严格约束workflow_records_common.py顶层字段类型说明idstring必须default_开头如default_5e8b008d-...name/author/description/version/contactstring工作流元信息author通常为InvokeAItagsstring逗号分隔标签如SDXL, text to image用于库内搜索notesstring补充说明exposedFieldsarray暴露给工作流设置表单的字段每项为{nodeId, fieldName}用于让用户直接修改关键参数提示词、模型、步数等metaobject{version: 3.0.0, category: default}version为 schema 版本semvercategory固定defaultnodesarray图中的所有节点type: invocationdata.type为调用类型如compel、denoise_latents、l2idata.inputs记录输入连线与默认值edgesarray节点间的连线定义formobject | null前端表单布局历史工作流可能缺失前端会自动补充默认表单注意WorkflowWithoutID的nodes校验器一个工作流最多只能包含一个workflow_return节点workflow_records_common.py这是 schema 层面的红线。七、发布前的校验测试与手工验证自动化测试节点与调用注册表一致性新增或修改默认工作流时最容易被忽略的问题是节点类型或版本过期。仓库为此提供了专门的测试 test_default_workflows_registry.py它针对所有 Wan/Video 相关默认工作流逐一断言每个节点的data.type必须是InvocationRegistry中已注册的调用类型不能引用已移除的节点每个节点data.version必须与对应调用类的UIConfig.version完全一致防止嵌入了过期版本号每个data.inputs中的输入名必须真实存在于该调用的model_fields中防止拼写错误或字段已改名。测试文件头注释说明了背景旧有的 SD1.5/SDXL/FLUX 默认工作流允许携带过期版本号编辑器会显示node needs update徽标容忍但新发布的工作流不允许带病出生——该测试正是为了捕获如wan_ref_image_encoder版本嵌入错误这类问题。运行测试可定位到该测试模块若新增工作流涉及 Wan/Video应确保通过pytest tests/app/services/workflow_records/test_default_workflows_registry.py。手工验证必须真实启动应用README 强调添加或更新默认工作流之后必须启动应用并实际加载以确认工作流能无警告、无错误地加载——如果节点引用了不存在的调用、缺失输入或非法版本加载时会出现警告或直接失败工作流能成功运行——仅能加载还不够还要真实执行一遍例如跑一次完整的文生图确保节点连线、参数默认值在真实运行环境中成立。这两步验证无法被静态检查替代因为运行期才会暴露节点间数据流、模型选择交互等动态问题。考虑到同步机制是启动时整体替换验证时若发现问题并修改 JSON重启应用后新内容会以更新路径自动覆盖旧记录无需手动清理数据库。八、小结InvokeAI 的默认工作流机制可以概括为一条清晰的分工链路目录即真源invokeai/app/services/workflow_records/default_workflows/下的 JSON 是唯一事实来源启动时由_sync_default_workflows()全量同步双校验防线文件必须满足default_id 前缀与meta.category default两个硬性断言新增 Wan/Video 类工作流还要通过注册表一致性测试只读共享语义数据库层禁止对category default记录执行创建/更新/删除用户只能另存为副本资源中立原则不得引用用户安装的模型或图片避免 UUID 失配导致的警告与体验降级发布流程闭环修改后必须启动应用验证无警告加载与成功运行两步。对于希望为 InvokeAI 贡献官方工作流的开发者遵循上述规范即可让自己的工作流在应用启动后自动、稳定地出现在所有用户的Default Workflows标签页中。【免费下载链接】InvokeAIInvoke is a leading creative engine for Stable Diffusion models, empowering professionals, artists, and enthusiasts to generate and create visual media using the latest AI-driven technologies. The solution offers an industry leading WebUI, and serves as the foundation for multiple commercial products.项目地址: https://gitcode.com/GitHub_Trending/in/InvokeAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
InvokeAI 默认工作流（Default Workflows）机制全解析：同步原理、JSON 规范与发布校验
InvokeAI 默认工作流Default Workflows机制全解析同步原理、JSON 规范与发布校验【免费下载链接】InvokeAIInvoke is a leading creative engine for Stable Diffusion models, empowering professionals, artists, and enthusiasts to generate and create visual media using the latest AI-driven technologies. The solution offers an industry leading WebUI, and serves as the foundation for multiple commercial products.项目地址: https://gitcode.com/GitHub_Trending/in/InvokeAIInvokeAI 的默认工作流是随应用一起内置在invokeai/app/services/workflow_records/default_workflows目录中的一组官方工作流 JSON应用启动时会自动将其同步进用户的工作流库workflow_library供所有用户在工作流库Workflow Library→ Default Workflows标签页中直接加载使用。本文以该目录下的 README.md 为主线结合同步实现源码、数据模型与测试用例完整讲解默认工作流的同步机制、文件编写规范、资源约束以及发布前的校验流程帮助开发者为 InvokeAI 贡献或维护官方内置工作流。一、什么是默认工作流默认工作流Default Workflows是一批由 InvokeAI 官方维护、随安装包一起分发的.json工作流文件。它们与用户自己创建的工作流在数据层面共享同一个workflow_library数据库表但通过category default字段与用户工作流category user区分开来。核心定位体现在三方面开机即用用户无需手工导入启动应用后即可在Default Workflows标签页看到全部内置工作流只读共享它们不属于任何单个用户对数据库中的查询而言默认工作流会始终包含在每个用户的列表结果中见下文 SQL 逻辑稳定基准作为官方示例它们演示了 InvokeAI 各种模型与节点组合的推荐用法。二、目录结构与内置工作流清单默认工作流的存放位置是固定目录invokeai/app/services/workflow_records/default_workflows/。当前仓库中该目录包含一份README.md和 26 个 JSON 工作流文件覆盖了 InvokeAI 主要能力面能力方向内置工作流示例文生图Text to Image - SDXL.json、Text to Image - SD1.5.json、SD3.5 Text to Image.json、Flux Text to Image.json、CogView4_TextToImage.json、Wan 2.2 Text to Image.json图生图 / 编辑FLUX Image to Image.json、Wan 2.2 Image to Image.json、Extend Video to Image - Wan 2.2 Lightning.jsonLoRA / 细节增强Text to Image with LoRA.json、Face Detailer with IP-Adapter Canny (See Note in Details).jsonControlNetMulti ControlNet (Canny Depth).json、ESRGAN Upscaling with Canny ControlNet.json视频生成Wan 2.2Text to Video - Wan 2.2 Lightning.json、Image to Video - Wan 2.2 Lightning.json、Extend Video - Wan 2.2 Lightning.json、Interpolate 2 Images to Video - Wan 2.2 Lightning.json以及带 Concept LoRAs 和 TI2V-5B 的变体图像增强 / 放大Tiled Upscaling (Beta).json、MultiDiffusion SD1.5.json、MultiDiffusion SDXL.json、Prompt from File.json这些 JSON 文件构成了应用的出厂工作流集。测试 test_default_workflows_registry.py 中专门有一个守卫用例断言 Wan/Video 相关工作流 glob 能匹配到恰好 12 个文件防止重命名或误删后目录静默为空。三、同步机制启动时的三步增删改默认工作流并非静态资源而是在应用启动时被主动同步进数据库。核心实现位于 workflow_records_sqlite.py 的_sync_default_workflows()方法它由存储层的start(invoker)钩子触发workflow_records_sqlite.py。同步算法完整流程如下扫描目录通过workflows_dir.glob(*.json)收集default_workflows目录下所有 JSON 文件校验并解析用WorkflowValidator.validate_json()对每个文件做严格 schema 校验随后断言id必须以default_开头、meta.category必须为default任一不满足即抛出断言异常整个启动同步失败差异比对对每个文件尝试按id从数据库读取已有记录若数据库中没有该 id → 加入workflows_to_add新增若数据库中已存在但内容与文件不一致 → 加入workflows_to_update更新若内容完全一致 → 跳过清理过期项查询数据库中所有category default的记录凡是 id 不在当前文件集合中的直接删除意味着从目录中移除某个 JSON重启后它就会从工作流库中消失执行写库对workflows_to_add执行INSERT对workflows_to_update执行UPDATE对过期项执行DELETE——注意这些操作都绕过公有的create/update/delete方法因为后者被设计为仅处理用户工作流见下文数据库层的硬约束。源码注释明确指出了该设计的一个取舍出于实现简单每次启动都会用目录内容整体替换默认工作流而非按版本增量更新因此默认工作流的updated_at、opened_at时间戳没有参考价值每次启动都会被覆盖。从 SQL 查询层面也能看到默认工作流的永久可见特性。在get_many、counts_by_tag、counts_by_category、get_all_tags等方法中当传入user_id做范围限定多用户模式时条件统一拼接为(user_id ? OR category default)workflow_records_sqlite.py即默认工作流永远出现在任何用户的列表、标签计数与分类统计中。四、编写默认工作流的四条硬性规范README 明确了默认工作流必须满足的规则结合数据模型代码可逐一拆解1. ID 必须以default_开头且保持稳定id 示例default_5e8b008d-c697-45d0-8883-085a954c6aceWorkflow模型的id字段被用于数据库主键workflow_idworkflow_records_common.py。同步时按 id 判断新增/更新/删除因此更新工作流时必须保留原 id否则会被当作一个全新工作流插入旧 id 对应的记录则在清理过期项阶段被删除。由于普通编辑工具保存时可能重新生成 idREADME 特别提醒你可能需要手动保留该 id。2.meta.category必须为defaultmeta字段由 WorkflowMeta 定义包含version工作流 schema 版本必须是合法的 semver 语义化版本号与category两项。WorkflowCategory枚举只有两个取值user和defaultworkflow_records_common.py。同步时若 category 不是default会直接抛出断言异常中断启动assert workflow_from_file.meta.category is WorkflowCategory.Default, ( fInvalid default workflow category: {workflow_from_file.meta.category} )3. 默认工作流不可被用户编辑用户加载默认工作流后无法直接保存回原位。这在数据库层有双重保障create()与update()方法开头即检查workflow.meta.category is WorkflowCategory.Default是则抛出ValueError(Default workflows cannot be created/updated)workflow_records_sqlite.pydelete()同样拒绝删除默认工作流workflow_records_sqlite.py。用户在 UI 中加载并保存默认工作流时行为是另存为一份副本以用户自己的 id 落库为category user记录原默认工作流保持不变——这正是 README 所述they will save as a copy of the default workflow的底层原因。4. 默认工作流出现在Default Workflows标签页前端工作流库按category过滤展示category default的记录集中显示在Default Workflows标签页用户可随时加载、复制、另存但永远无法覆盖其原始内容。五、资源约束不要引用用户安装的模型与图片默认工作流是出厂配置必须对任何环境都成立。README 强调默认工作流不应引用任何用户创建或安装的资源包括图片和模型。原因在于资源对象的引用方式。以模型为例工作流中的模型节点如main_model_loader、lora_loader、vae_loader通过模型的UUID关联具体模型实例。模型 UUID 是模型安装时生成的唯一标识不同用户/不同安装环境中即使同一个 Juggernaut 模型也会有不同的 UUID。因此若默认工作流硬编码了某个 SDXL 模型如 Juggernaut的 UUID用户加载时即使本地安装了同名模型UUID 也对不上结果就是节点上出现模型缺失警告用户必须手动重新选择模型违背了开箱即用的初衷。同样的逻辑适用于图片默认工作流中若引用了某个固定的输入图片资源该资源在其他用户环境中并不存在。正确做法默认工作流中的模型/图片类输入一律保持未赋值状态工作流 JSON 中不写死 UUID由用户加载后自行选择或仅使用 InvokeAI 自带的、随仓库分发的资源例如invokeai/assets/data目录下的示例数据。从实际文件看Text to Image - SDXL 的exposedFields恰好把model、vae_model、board等字段暴露给前端表单让用户在加载后自己填入模型——这就是规避 UUID 问题的最佳实践示范。六、工作流 JSON 的结构剖析以 Text to Image - SDXL.json 为例默认工作流文件的顶层字段由Workflow模型严格约束workflow_records_common.py顶层字段类型说明idstring必须default_开头如default_5e8b008d-...name/author/description/version/contactstring工作流元信息author通常为InvokeAItagsstring逗号分隔标签如SDXL, text to image用于库内搜索notesstring补充说明exposedFieldsarray暴露给工作流设置表单的字段每项为{nodeId, fieldName}用于让用户直接修改关键参数提示词、模型、步数等metaobject{version: 3.0.0, category: default}version为 schema 版本semvercategory固定defaultnodesarray图中的所有节点type: invocationdata.type为调用类型如compel、denoise_latents、l2idata.inputs记录输入连线与默认值edgesarray节点间的连线定义formobject | null前端表单布局历史工作流可能缺失前端会自动补充默认表单注意WorkflowWithoutID的nodes校验器一个工作流最多只能包含一个workflow_return节点workflow_records_common.py这是 schema 层面的红线。七、发布前的校验测试与手工验证自动化测试节点与调用注册表一致性新增或修改默认工作流时最容易被忽略的问题是节点类型或版本过期。仓库为此提供了专门的测试 test_default_workflows_registry.py它针对所有 Wan/Video 相关默认工作流逐一断言每个节点的data.type必须是InvocationRegistry中已注册的调用类型不能引用已移除的节点每个节点data.version必须与对应调用类的UIConfig.version完全一致防止嵌入了过期版本号每个data.inputs中的输入名必须真实存在于该调用的model_fields中防止拼写错误或字段已改名。测试文件头注释说明了背景旧有的 SD1.5/SDXL/FLUX 默认工作流允许携带过期版本号编辑器会显示node needs update徽标容忍但新发布的工作流不允许带病出生——该测试正是为了捕获如wan_ref_image_encoder版本嵌入错误这类问题。运行测试可定位到该测试模块若新增工作流涉及 Wan/Video应确保通过pytest tests/app/services/workflow_records/test_default_workflows_registry.py。手工验证必须真实启动应用README 强调添加或更新默认工作流之后必须启动应用并实际加载以确认工作流能无警告、无错误地加载——如果节点引用了不存在的调用、缺失输入或非法版本加载时会出现警告或直接失败工作流能成功运行——仅能加载还不够还要真实执行一遍例如跑一次完整的文生图确保节点连线、参数默认值在真实运行环境中成立。这两步验证无法被静态检查替代因为运行期才会暴露节点间数据流、模型选择交互等动态问题。考虑到同步机制是启动时整体替换验证时若发现问题并修改 JSON重启应用后新内容会以更新路径自动覆盖旧记录无需手动清理数据库。八、小结InvokeAI 的默认工作流机制可以概括为一条清晰的分工链路目录即真源invokeai/app/services/workflow_records/default_workflows/下的 JSON 是唯一事实来源启动时由_sync_default_workflows()全量同步双校验防线文件必须满足default_id 前缀与meta.category default两个硬性断言新增 Wan/Video 类工作流还要通过注册表一致性测试只读共享语义数据库层禁止对category default记录执行创建/更新/删除用户只能另存为副本资源中立原则不得引用用户安装的模型或图片避免 UUID 失配导致的警告与体验降级发布流程闭环修改后必须启动应用验证无警告加载与成功运行两步。对于希望为 InvokeAI 贡献官方工作流的开发者遵循上述规范即可让自己的工作流在应用启动后自动、稳定地出现在所有用户的Default Workflows标签页中。【免费下载链接】InvokeAIInvoke is a leading creative engine for Stable Diffusion models, empowering professionals, artists, and enthusiasts to generate and create visual media using the latest AI-driven technologies. The solution offers an industry leading WebUI, and serves as the foundation for multiple commercial products.项目地址: https://gitcode.com/GitHub_Trending/in/InvokeAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
