Civitai Orchestrator 工作流查询统一化从双端点走向类型感知的单一路由【免费下载链接】civitaiA repository of models, textual inversions, and more项目地址: https://gitcode.com/GitHub_Trending/ci/civitai导读本文围绕 Civitai 主站当前仓库src/目录下的 Next.js 应用中的一份架构演进文档 docs/unified-workflow-query.md 展开剖析其提出的统一工作流查询端点Unified Workflow Query Endpoint方案将图片生成查询与提示词增强查询合并为单一 tRPC 端点并让服务端格式化层具备类型感知能力。读完本文你将理解当前双端点架构的分歧点、统一方案的四个实施步骤、其中涉及的四个关键挑战以及源码中已有的部分统一化进展queryWorkflowsByTags可以直接将该方案应用于自己的 orchestrator 集成或同类多类型查询场景。一、现状两条并行的查询路径文档首先指出当前存在两个彼此独立的查询端点它们调用的是同一个底层 orchestrator API分歧完全发生在服务端格式化层端点Tag 过滤服务端处理客户端消费方queryGeneratedImagesgenerationformatGenerationResponse2约 150200 行资源富化、遗留元数据归一化、图片 blob 格式化Queue.tsx、Feed.tsx经useGetTextToImageRequestsqueryPromptEnhancementsprompt-enhancement无queryWorkflows原始透传HistoryTab.tsx经useGetPromptEnhancementHistory在源码中可以完整印证这张表。路由定义位于 src/server/routers/orchestrator.router.tsqueryGeneratedImages第 331 行起通过queryGeneratedImageWorkflows2处理并在 green 域名下追加greentag、开启cache: true通用按 tag 查询queryWorkflowsByTags第 211 行起是提示词增强历史的实际落点其注释明确写着Generic workflow query by tags — used for prompt enhancement history, future text workflows, etc.即该端点从设计上就是类型无关的。客户端两侧的消费方式也各不相同图片侧useGetTextToImageRequestssrc/components/ImageGeneration/utils/generationRequestHooks.ts会registerSignalGroup(generation)把WORKFLOW_TAGS.GENERATION实际常量值为gen见 src/shared/constants/generation.constants.ts与筛选器 tag 拼接后调用useInfiniteQuery随后把每条 workflow 包成new WorkflowData(workflow, { domain, nsfwEnabled })提示词侧useGetPromptEnhancementHistorysrc/components/Generation/PromptEnhance/promptEnhanceHooks.ts直接以{ tags: [prompt-enhancement] }调用queryWorkflowsByTags.useInfiniteQuery再经mapWorkflowToRecord映射为PromptEnhancementRecord包含 originalPrompt、enhancedPrompt、issues、recommendations、temperature 等字段供 HistoryTab.tsx 渲染。二、共享底座类型无关的queryWorkflows两条路径之所以能统一关键在于它们最终都汇入同一个底层函数queryWorkflows。该函数位于 src/server/services/orchestrator/workflows.ts本身不关心 workflow 的具体类型它承担了三件公共职责强制注入civitaitagtags: [civitai, ...(query.tags ?? [])]确保查询始终限定在 civitai 域内读取超时兜底AbortSignal.timeout(ORCHESTRATOR_QUERY_TIMEOUT_MS)常量值为 20 秒workflows.ts防止 orchestrator 挂起时无限阻塞并占死 api 连接池触发后会被识别为可重试的 503统一文案ORCHESTRATOR_UNAVAILABLE_MESSAGE错误分类映射400 → BadRequest、401 → Authorization、403 → InsufficientFunds、429 → RateLimit、404 → NotFound其余 4xx 归为 BadRequest上游 5xx/网络故障归为可重试 503未知错误原样抛出保持真实 bug 可见。同时单条读取getWorkflow也有独立的 20 秒兜底ORCHESTRATOR_GET_TIMEOUT_MS服务于statusUpdate轮询热路径。可以推断既然底层查询天然类型无关统一化的工作重心确实如文档所说全部集中在服务端格式化层 客户端消费层。三、分歧点formatGenerationResponse2的图片假设queryGeneratedImages之所以需要专门的服务端处理是因为formatGenerationResponse2src/server/services/orchestrator/orchestration-new.service.ts假定每个 workflow 都包含图片/视频步骤。它的处理流水线包括资源富化从workflow.metadata.resources和每个 step 的getResourceRefsFromStep中收集资源 ID按(id, epoch)去重保证同一版本的不同 epoch 不被合并然后批量调用getResourceData命中数据库把模型名、版本、epoch 号等信息补全到响应中Raw-AIR 负 ID 资源跳过富化新格式归一化workflow.metadata.paramsworkflow.metadata.resources其中normalizedWfMeta是显式白名单而非展开——每个暴露给调用方的 key 都必须被命名例如remixOfId、isPrivateGeneration、modelSubstitutions都是逐项挑选的遗留格式回退无 workflow 级 metadata 时回退到steps[0].metadata标准生成或step.metadata.transformations[last]遗留增强格式步骤格式化formatStep再对每个 step 做输出归一化。formatStepOutputs内部已经是一个按step.$type分发的 switchorchestration-new.service.ts覆盖comfy、imageGen/textToImage、model3DPreview、imageUpscaler、preprocessImage、videoGen含 LTX 2.3 的additionalVideos多视频批处理、videoUpscaler/videoEnhancement/videoInterpolation、preprocessVideo、aceStepAudio、miniMaxMusic3、polyGen合并 rigged/animated 变体等类型default返回空数组。问题在于提示词增强 workflow 的 input/output 是自包含的没有资源、没有图片 blob这套流水线对它要么空转、要么产生垃圾数据。这正是文档强调必须让formatGenerationResponse2类型感知的根本原因。四、统一方案四个实施步骤文档给出的方案分四步以下是完整设计及与源码的对应关系。1. 单一 tRPC 端点将queryGeneratedImages重命名/替换为统一的queryWorkflows端点去掉硬编码的generationtag 过滤让客户端按需传 tag。从源码看这一思路的雏形其实已经落地为queryWorkflowsByTags——它接收的正是workflowQuerySchema且没有任何类型假设。2. 类型感知的服务端格式化器把formatGenerationResponse2从假定全图/视频改为按步骤类型分发switch (step.$type) { case textToImage: case videoGen: // 现有 image/video 格式化资源富化、blob 处理、遗留兼容 break; case promptEnhancement: // 透传或轻量归一化input/output 自包含 break; default: // 未知类型的通用透传 break; }这里的 switch 结构与源码中formatStepOutputs的switch (step.$type)完全同构差异在于前者目前是输出归一化层而统一方案要求把资源富化 元数据归一化也纳入类型分派。3. 判别联合Discriminated Union响应每个 workflow 携带一个type判别字段让客户端无需猜测 payload 形状type NormalizedWorkflow | { type: generation; /* 现有 image/video 字段 */ } | { type: promptEnhancement; /* input/output/issues/recommendations */ } | { type: unknown; /* 原始 step 数据 */ };可以推断promptEnhancement分支的字段应与PromptEnhancementRecordpromptEnhanceHooks.ts对齐即 workflowId、createdAt、originalPrompt、enhancedPrompt、issues、recommendations、instruction、preserveTriggerWords、temperature、status。4. 客户端过滤Queue/Feed过滤type generation历史页过滤type promptEnhancement或者干脆渲染混合内容为不同类型配各自的卡片组件。对应的客户端改造面包括useGetTextToImageRequests目前直接对全部条目执行new WorkflowData(...)generationRequestHooks.ts统一后需要先按type分流useGetPromptEnhancementHistory的mapWorkflowToRecord按$type promptEnhancement或name prompt-enhancement查找 step则可以退化为简单的类型断言。五、关键挑战详解5.1 遗留格式处理formatGenerationResponse2同时处理三种元数据格式统一时必须保证新格式workflow.metadata.paramsworkflow.metadata.resourcesorchestration-new.service.ts遗留格式step.metadata.paramsstep.metadata.resources第 3115-3124 行遗留增强格式step.metadata.transformations[last]第 3098-3114 行。这些逻辑必须对图片 workflow 保留但绝不能对提示词增强 workflow 执行——否则会失败或产生垃圾数据。文档给出的约束是类型分发发生在格式化入口遗留兼容逻辑只挂在generation分支下。5.2 资源富化的条件化图片 workflow 需要把资源 ID 富化为模型名、版本、epoch 号这一步要命中数据库getResourceData。提示词增强 workflow 没有资源富化步骤必须条件化否则每次历史查询都会产生无谓的数据库开销。文档同时点出一个细节formatGenerationResponse2的资源收集横跨 workflow 级与 step 级两处第 3010-3026 行条件化时要同时覆盖这两处入口。5.3 Signal 更新通道useTextToImageSignalUpdatesrc/components/ImageGeneration/utils/useGenerationSignalUpdate.ts订阅SignalMessages.TextToImageUpdate常量值orchestrator:text-to-image-update见 src/server/common/enums.ts经 100ms 防抖后把 statusUpdate 结果 patch 进trpc.orchestrator.queryGeneratedImages的 React Query 缓存updateWorkflowsStatus用getQueryKey(trpc.orchestrator.queryGeneratedImages)定位缓存。而提示词侧走的是另一条通道useWorkflowUpdateSignal订阅SignalMessages.WorkflowUpdateorchestrator:workflow-update通过onWorkflowSignal监听器注册表把事件分发给useGetPromptEnhancementHistory后者再以updateWorkflowInTagCache(workflowItem, PROMPT_ENHANCEMENT_TAGS)更新queryWorkflowsByTags的缓存src/components/Orchestrator/workflowHooks.ts。统一后需要二选一要么建立统一的 Signal 通道要么维护多个订阅共同更新同一个缓存。注意updateWorkflowInTagCache/addWorkflowToTagCache已经是按 tag 匹配查询键的通用实现matchesTagQuery检查 query key 的 input.tags 是否包含目标 tag可以推断这套机制天然适合迁移到统一端点。5.4WorkflowData/BlobData包装器图片侧把 workflow 包进WorkflowDatasrc/shared/orchestrator/workflow-data.ts它会把原始输出包装成BlobData子类ImageBlob、VideoBlob、AudioBlob、Model3DBlob抽象基类见 workflow-data.ts承担 NSFW 拦截与父引用BlobData.step、StepData.workflow接线。这套机制与图片输出强耦合统一查询需要多态包装器或对非图片类型跳过包装。从源码看WorkflowData的构造选项domain、nsfwEnabled、allowMatureContent都与图片的 NSFW 策略相关提示词增强记录不需要也不应走这套包装。六、统一化不可忽视的缓存维度文档未展开、但源码中必须纳入统一化评估的是queryGeneratedImages专属的短 TTL 缓存体系orchestration-new.service.tsQUERIED_WORKFLOWS_CACHE_TTL 3秒用于折叠 SignalR 重连风暴——每次重连所有标签页会同时 invalidatequeryGeneratedImages导致毫秒级的大量相同首页查询缓存键getQueriedWorkflowsCacheKey必须覆盖所有影响响应的参数take、cursor、tags、ascending、fromDate、toDate、excludeFailed、hideMatureContent并刻意排除 token以允许同一用户的多标签页共享条目失效采用每用户索引集合SMEMBERS→DELdeleteWorkflow、cancelWorkflow、updateWorkflow、patch四个变更端点都会调用bustQueriedWorkflowsCache主动清缓存orchestrator.router.ts且只缓存第一页无 cursor深翻页直接穿透。而queryWorkflowsByTags提示词增强历史目前没有这层缓存。统一端点后3 秒短 TTL 变更即失效的语义是否要覆盖全部类型需要单独决策如果对提示词增强历史也启用会让历史记录的增删改如删除一条增强记录同样依赖失效链路如果维持现状则统一端点内部将出现同端点不同缓存策略的分叉这本身也是一种复杂度。七、工作量评估与落地建议文档给出的评估为23 天拆解如下让formatGenerationResponse2类型感知且不破坏现有图片 workflow约 1 天更新客户端 hooks 与组件以处理判别联合约 1 天回归验证遗留 workflow 格式仍能正确渲染约 0.5 天。建议是作为后续项推进而不是提示词增强功能的一部分——当前双端点方案已可用且足够清晰当出现第三种 orchestrator workflow 类型时统一化才真正值得做因为届时每新增一种类型就新增一个端点的模式会开始显得冗余。从当前仓库的实际状态可以印证这一演进方向已经部分发生queryWorkflowsByTags的存在本身就是通用端点先行的落地orchestrator.router.ts提示词增强已不再需要专属端点而图片侧的queryGeneratedImages仍保留着强图片假设与专属缓存。可以推断后续真正需要做的是让formatGenerationResponse2的类型分发与queryWorkflowsByTags的通用查询能力合流再统一客户端判别与 Signal 通道即可完成文档描述的整体收敛。相关查询类型定义可在 src/types/router.ts 的QueryGeneratedImages中追根溯源。参考路径速查设计文档docs/unified-workflow-query.md路由层src/server/routers/orchestrator.router.tsqueryGeneratedImagesL331、queryWorkflowsByTagsL211底层查询src/server/services/orchestrator/workflows.tsqueryWorkflowsL127、超时兜底 L64-L88格式化与缓存src/server/services/orchestrator/orchestration-new.service.tsformatGenerationResponse2L3003、queryGeneratedImageWorkflows2L3277、缓存 TTL L3177查询入参 schemasrc/server/schema/orchestrator/workflows.schema.ts图片侧 hookssrc/components/ImageGeneration/utils/generationRequestHooks.ts、Signal 更新useGenerationSignalUpdate.ts提示词侧 hookssrc/components/Generation/PromptEnhance/promptEnhanceHooks.ts通用缓存辅助src/components/Orchestrator/workflowHooks.ts客户端包装器src/shared/orchestrator/workflow-data.tsTag 与 Signal 常量src/shared/constants/generation.constants.ts、src/server/common/enums.ts【免费下载链接】civitaiA repository of models, textual inversions, and more项目地址: https://gitcode.com/GitHub_Trending/ci/civitai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考