企业官网建设流程全解析

Civitai 生成系统（Generator System）架构解析：从表单到 Orchestrator 的端到端引擎接入指南

【免费下载链接】civitaiA repository of models, textual inversions, and more项目地址: https://gitcode.com/GitHub_Trending/ci/civitai

导读

Civitai 生成系统是一套基于模块化 orchestrator 架构的 AI 内容生成平台，支持图像（Image）与视频（Video）两大媒体类型，统一承载多引擎接入、模型资源管理与用户生成入口。本文以 docs/features/generator.md 为主线，结合当前仓库源码，系统讲解其前后端架构、图片/视频引擎配置机制、模型接入的多种途径，并给出「新增 base model 与 generation engine」时从表单更新到向 orchestrator 提交 workflow 的端到端实操路径。读完本文，你将掌握在 Civitai 代码库中定位生成链路关键文件、按步骤接入新引擎与基础模型、并理解生成覆盖（Generation Coverage）与资源兼容性判定原理的能力。

系统架构总览

生成系统的核心组织方式是 orchestrator 模式：前端表单收集参数 → 后端 router 接收请求 → 服务层解析并调用对应的引擎实现 → 提交给 orchestrator 执行。前后端通过明确的文件边界解耦。

前端组件

主入口与功能页面：

• 主入口：src/pages/generate/index.tsx，生成功能的主入口页面；
• 图像生成：src/components/ImageGeneration/目录集中存放图像生成相关组件；
• 视频生成：src/components/Generation/Video/目录存放视频生成专属组件。

核心表单与状态组件（注意：仓库中新一代表单已迁移至src/components/form-graph/generation/目录，GenerationForm2.tsx的职责由 BaseGenerationForm.tsx 承接，视频表单为 VideoGenerationForm.tsx）：

• GenerationForm2 / BaseGenerationForm：图像生成主表单，负责按所选 base model 动态决定展示哪些字段、使用哪些默认值（见下文「表单字段的条件逻辑」）；
• VideoGenerationForm：视频生成界面；
• GenerationProvider（src/components/ImageGeneration/GenerationProvider.tsx）：用 Context 管理生成状态的 Provider；
• Queue（src/components/ImageGeneration/Queue.tsx）：管理生成队列与任务状态展示；
• Feed（src/components/ImageGeneration/Feed.tsx）：展示生成结果（用户只看到自己的生成内容，而非社区内容）。

后端服务

• Generation Router：src/server/routers/generation.router.ts，生成相关 API 端点；
• Orchestrator Router：src/server/routers/orchestrator.router.ts，编排相关操作端点，并负责设置x-generation-update-required响应头（当生成客户端落后时提示刷新）；
• Generation Service：src/server/services/generation/generation.service.ts，核心业务逻辑与生成覆盖（Coverage）服务；
• Orchestrator Controller / Services：src/server/controllers/orchestrator.controller.ts与src/server/services/orchestrator/，其中按引擎拆分的实现位于 src/server/services/orchestrator/ecosystems/（如veo3.handler.ts、kling.handler.ts、vidu.handler.ts）与 src/server/services/orchestrator/form-graph/（新一代基于 form-graph 的引擎 handler）。

图片生成引擎体系（Image Gen）

图片生成引擎的配置统一集中在src/shared/orchestrator/ImageGen/目录。每个 imageGen config 都对应一个关联引擎，而每个引擎会配合一个或多个特定模型工作（原文档 @dev 注解明确指出这一点）。

引擎配置清单

仓库实际存在的引擎配置（均为.config.ts后缀，原文档列出的openAI.ts等对应为openai.config.ts等文件）：

统一配置注册表

imageGen.config.ts 是图片引擎的注册中心，核心结构：

• imageGenConfig对象：以引擎 key（openai、google、flux1、flux2、flux2klein、gemini、qwen、seedream、grok、zImage）映射到各引擎 config；
• imageGenModelVersionMap：Map<modelVersionId, ImageGenConfigKey>，把平台内具体的模型版本 ID 映射到引擎 key，这是「模型版本 → 引擎」的反查表；
• getModelVersionUsesImageGen(modelVersionId)：判断某个模型版本是否走 ImageGen 外部引擎链路；
• getImageGenConfigKey(modelVersionId)：由模型版本 ID 取出对应的引擎 key。

新增图片引擎的标准动作即：在src/shared/orchestrator/ImageGen/新增xxx.config.ts，然后在imageGen.config.ts中注册 config 并把该引擎支持的modelVersionId汇入imageGenModelVersionMap。

引擎配置工厂：ImageGenConfig

所有图片引擎 config 都由 ImageGenConfig.ts 中的ImageGenConfig({ metadataFn, inputFn })工厂函数创建，它接收两个关键回调并返回四个方法：

• metadataFn：把统一请求参数（GenerateImageSchema的 params 与 resources）转换为引擎特定的元数据对象，其中process（txt2img / img2img / inpainting）、engine、baseModel、quantity为必含字段；seed 缺失时会在工厂内自动随机生成（上限maxRandomSeed）；
• inputFn：把元数据进一步转换成真正发给引擎的输入（ImageGenInput类型，来自@civitai/client），即引擎 API 请求体；
• 返回方法：
  • getImageMetadata/getStepMetadata：生成元数据（前者 JSON 字符串化并附 resources 的modelVersionId + strength与remixOfId）；
  • getStepInput：产出实际输入（同样兜底随机 seed）；
  • getTags：为 workflow 组装标签，使用 generation.constants.ts 中的WORKFLOW_TAGS与getProcessTagFromWorkflow（gen、img、引擎名、baseModel、process:txt2img/process:img2img等），便于后续过滤检索。

以 openai.config.ts 为例，可看到引擎适配的完整形态：

• openaiModels：支持gpt-image-1、gpt-image-1.5、gpt-image-2、gpt-image-2.5-flare、gpt-image-2.5-sunburst；
• openaiModelVersionToModelMap：把平台 modelVersionId（如1733399→gpt-image-1）映射到具体模型；
• openAISizes：定义引擎支持的尺寸集合（如 1024×1024、1536×1024、1024×1536），通过findClosestAspectRatio把用户请求吸附到最接近的合法尺寸；
• metadataFn依据是否有输入图片决定process是txt2img还是img2img，并把quantity钳制到Math.min(quantity, 10)；
• inputFn依据选中模型版本走不同分支：gpt-image-2 及 2.5 系列返回createImage/editImage操作（且 quality 枚举无auto，需把auto钳制为high），gpt-image-1 系列则返回带size: ${width}x${height}的请求体。

flux1-kontext.config.ts 则展示了另一个典型形态：定义flux1KontextAspectRatios（21:9 至 9:21 共 9 档）、模型集合['dev', 'pro', 'max']、fluxKontextModelVersionToModelMap，并用 zodschema（engine为z.literal('flux1-kontext')、model为 enum 校验等）对发给引擎的输入做运行时校验；此外whatIf（成本预估）模式下还会注入一张占位图与1:1比例。

视频生成引擎体系（Video Gen）

视频引擎的 key 联合类型集中定义在 src/server/orchestrator/generation/generation.config.ts：OrchestratorEngine2包含veo3、vidu、minimax、kling、lightricks、ltx2、haiper、mochi、hunyuan、wan、sora（原文档列出的 Wan 多版本：wan21.ts、wan22.ts、wan225b.ts，在引擎层面统一归入wankey）。

该文件头部注释说明了重要演进：旧的按生态拆分的VideoGenerationConfig2工厂与videoGenerationConfig2注册表已被移除，视频生成现在完全通过 generation graph（generateFromGraph）运行，只保留了引擎 key 联合类型。从源码结构看，视频引擎的实际 handler 位于：

• src/server/services/orchestrator/ecosystems/（如veo3.handler.ts、kling.handler.ts、vidu.handler.ts、handler-factory.ts、index.ts）；
• src/server/services/orchestrator/form-graph/（新一代 form-graph handler，同样有veo3.handler.ts、kling.handler.ts、vidu.handler.ts）。

同时src/server/orchestrator/下还存在一批专项能力的 schema 实现，如 hunyuan3d、tripo、polygen、trellis2、video-enhancement、video-interpolation、video-upscaler、image-upscaler 等。

视频引擎配置与图片引擎的关键差异（原文档 @dev 注解）：每个视频引擎 config 接收的 schema 具有不同的默认值，这些 schema 用于保证表单默认值对被选模型是最优的。因此新增视频引擎通常会拥有自己独立的表单/config 文件（VideoGenerationForm体系下的引擎专属配置），而不是塞进一个通用表单。

模型接入的多种途径

系统支持多种把模型带入生成能力的方式，原文档梳理为四种方法：

方法一：用户上传（User Upload）

• 表单入口：ModelUpsertForm.tsx（模型信息表单）、ModelVersionUpsertForm.tsx（版本管理）；
• 流程：用户填写模型信息 → 上传模型文件（safetensors、ckpt 等）→ 设置元数据（base model、触发词等）→ 系统处理与校验 → 模型可用于生成。

Prisma schema 中支持的模型类型包括：Checkpoint（完整 SD 模型）、LORA/LoCon/DoRA（轻量适配）、TextualInversion（embedding）、Hypernetwork、Controlnet（引导生成的控制模型）、VAE（变分自编码器）、MotionModule（动画/运动模型）、Upscaler（放大模型）、Poses（姿态控制）、Wildcards（提示词通配）、Workflows（ComfyUI/A1111 工作流）、Detection（目标检测）。

注意：在用户上传的这些类型中，实际参与生成支持的只有 Checkpoint、LORA/LoCon/DoRA、VAE 与 TextualInversion。该支持定义的位置在「生成覆盖」相关逻辑中（见下文 Coverage Table 一节），如需调整支持范围应从那里入手。

方法二：训练系统集成（Training Integration）

• 训练界面：src/components/Training/；
• 训练服务：src/server/services/training.service.ts；
• 流程：用户发起训练任务 → 训练完成产出模型文件 → 系统自动创建模型条目 → 模型立即可用于生成。

发布后的训练产物与方法一的用户上传模型走完全相同的流程；在发布之前，训练产出如何进入生成器则由训练预览/epoch 链路处理（训练在整体架构中被视为近乎独立的服务）。

方法三：外部引擎集成（External Engine Integration）

• 图片模型：在src/shared/orchestrator/ImageGen/新增引擎配置 → 实现引擎专属 schema 与校验 → 注册进imageGen.config.ts→ 按需更新生成表单字段；
• 视频模型：在src/server/orchestrator/（实际 handler 在src/server/services/orchestrator/下）新增引擎实现 → 在配置中定义引擎专属参数 → 注册进 generation config → 按需更新视频表单组件。

方法四：API 集成

• 模型 router：src/server/routers/model.router.ts 支持程序化创建模型，用于批量导入与迁移。

说明：方法四本质上与方法一相同（都经由模型发布系统），文档中注明其并非独立的新链路。

资源管理与生成覆盖（Generation Coverage）

资源选择（ResourceSelect）

• 组件目录：src/components/ImageGeneration/ResourceSelect/；
• ResourceSelectCard：可视化模型选择卡片；
• ResourceSelectDropdown：下拉式模型选择；
• 搜索集成：基于 Meilisearch 索引实现快速模型发现。

需要说明的是：新增图片引擎时并不修改 ResourceSelect 组件，而是在生成表单（GenerationForm2.tsx/ 现为 form-graph 的BaseGenerationForm.tsx）中加入条件逻辑，按 baseModel / baseModel 分组决定展示哪些表单字段与默认值（原文档 @dev 注解明确纠正了这一点，并指出整个生成表单未来应重构为更易配置字段与默认值的形态）。

生成覆盖与兼容性判定

当新增一个 base model 时，典型做法是：

1. 向EcosystemCheckpoints表添加一个默认 checkpoint（含modelVersionId与名称）；
2. 要为 LORA/DoRA 等附加资源启用生成，需要更新GenerationBaseModel表，登记新的 base model。

覆盖服务位于 src/server/services/generation/generation.service.ts，负责实时模型可用性检查。其底层兼容性判定逻辑（从源码结构看）由@civitai/shared包的 packages/civitai-shared/src/basemodel.constants.ts 承载（src/shared/constants/basemodel.constants.ts只是指向该包的 re-export shim）：

• getResourceGenerationSupport(primaryBaseModelOrEcosystem, resourceBaseModel, resourceModelType)：返回'full' | 'partial' | null，判定某资源（如 LORA）与主生态的生成兼容性；
• getGenerationSupport(checkpointEcosystemId, addonEcosystemId, addonModelType)：核心兼容规则——同一生态内资源天然 Full；跨生态兼容完全由显式规则（crossEcosystemRules）驱动，不依赖 parent-chain 关系推断（因为 parent 链还承担 AIR URN 生态、分类等身份职责，例如 Flux2Klein 变体虽以 Flux2 为 parent，但其训练的 LoRA 并不跨变体兼容）；
• areResourcesCompatible/filterCompatibleResources：校验/过滤一组资源是否都与给定生态兼容。

模型文件管理

文件存储走 S3/CloudFlare R2 集成，支持的文件类型包括 safetensors、ckpt、pt、bin、zip；元数据（模型卡片、config、样例图）随模型条目存储。

数据库架构

核心表

• Model：模型基础信息与元数据；
• ModelVersion：模型的版本化发布；
• ModelFile：与版本关联的物理文件；
• GenerationCoverage：记录生成可用性；
• GenerationBaseModel：支持的 base model（SD1.5、SDXL 等）；
• EcosystemCheckpoints：各生态的默认 checkpoint（原文档 @dev 注解补充的关键表）。

关键枚举

• ModelStatus：Draft、Published、Scheduled 等；
• ModelModifier：Archived、TakenDown 等；
• ImageGenerationProcess：txt2img、img2img、inpainting 等；
• GenerationSchedulers：各种采样方法。

关于调度器（schedulers）：除枚举外，还存在重要的映射关系，定义于 src/server/common/constants.ts（该文件同时定义了generation、generationConfig、getGenerationConfig、maxUpscaleSize、minDownscaleSize、maxRandomSeed等生成常量）。此外 generation.constants.ts 中还有一组关键状态映射：generationStatusColors（unassigned/preparing/scheduled/processing → yellow，succeeded → green，failed → red，expired/canceled → gray）、orchestratorRefundableStatuses（failed/expired/canceled）、orchestratorCompletedStatuses、orchestratorPendingStatuses（unassigned/preparing/scheduled），以及 seed 上限常量MAX_SEED = 4294967295与MAX_RANDOM_SEED。

前端状态管理

• 基于 Zustand 的 store：src/store/generation.store.ts 管理生成状态；src/store/training.store.ts管理训练状态（训练被视为独立服务，仅在其产物进入生成流程时才与生成 store 交互）；
• 资源 store 管理被选中的资源；
• 表单持久化：通过usePersistFormhook 把生成参数持久化到 LocalStorage，保存用户偏好与会话级生成参数。

集成点：成本、审核与实时更新

• 成本管理（Buzz 虚拟货币）：生成消耗 Buzz 积分，按模型/引擎分级定价。需要特别说明的是（原文档 @dev 纠正）：成本计算并非由buzz.service.ts完成，而是来自 orchestrator API 的whatIf请求——这正是上文图片引擎inputFn中whatIf分支存在的意义（预估成本时不真正发起生成）。src/server/services/buzz.service.ts负责 Buzz 账务本身。
• 内容审核：blocked-generation.service.ts 提供生成阻断；实际更关键的是对请求的 NSFW 等级限制、以及产出图像的 NSFW 分级结果如何展示/隐藏的处理链路。
• 实时更新：队列状态通过类 WebSocket 机制推送生成进度；通知系统在生成完成时实时提醒；Feed 仅展示用户本人的生成内容（原文档 @dev 纠正：用户看不到社区生成流）。

Workflow 系统（ComfyUI / A1111）

• ComfyUI 集成：数据库支持存储 workflow JSON，经 orchestrator 系统执行，支持动态参数注入。这是遗留方案，不再扩展（原文档 @dev 明确标注）。
• A1111 集成：兼容 A1111 API 格式与扩展，原生支持 A1111 模型格式。

新增 base model 与引擎的分步指南

以下步骤融合了原文档的「Step by Step」与 @dev 注解给出的仓库实际做法，是本文最核心的实战部分。

新增图片模型/引擎

1. 若涉及全新的模型类型，先在 Prisma schema 中定义（新增类型需扩展ModelType枚举）；
2. 在src/shared/orchestrator/ImageGen/创建引擎实现文件xxx.config.ts：用ImageGenConfig({ metadataFn, inputFn })工厂定义引擎适配，包括模型版本映射（xxxModelVersionToModelMap）、尺寸/比例约束、zod 输入 schema；
3. 注册进 imageGen.config.ts 的imageGenConfig与imageGenModelVersionMap；
4. 在生成表单中加入条件逻辑，按新 base model / 分组决定展示哪些字段与默认值（不需要改ModelUpsertForm.tsx或 ResourceSelect 组件）；
5. 添加/复用校验 schema（引擎输入校验 + 生成请求校验）；
6. 往EcosystemCheckpoints表添加默认 checkpoint（modelVersionId + 名称）；如需 LORA/DoRA 等支持，更新GenerationBaseModel表登记新 base model；
7. 端到端测试生成管线（含whatIf成本预估与真实提交）。

新增视频模型/引擎

1. 在src/server/services/orchestrator/（ecosystems / form-graph）创建引擎 handler 实现，并把引擎 key 加入 generation.config.ts 的OrchestratorEngine2联合类型；
2. 定义引擎专属配置与 schema（每个引擎有独立的 form/config 文件，schema 默认值针对该模型最优）；
3. 在VideoGenerationForm体系下创建/更新对应引擎的表单文件；
4. 添加模型专属参数；
5. 加入生成 router 端点（现有 generation.router 已覆盖通用流程，通常无需新增端点）；
6. 测试视频生成 workflow 全链路。

新增模型类别（完整新类别）

原文档提供了完整类别的扩展路径：扩展 PrismaModelType枚举 → 在src/components/建专属 UI → 在src/server/routers/加端点 → 在src/server/services/实现服务层 → 创建 orchestrator 集成 → 增加状态管理 → 更新搜索索引 → 实现审核规则。（此部分为扩展新类别时的全量参考，日常新增 base model 无需走完全部步骤。）

关键文件索引（引擎/模型接入时常需更新）

原文档 @dev 总结的生成流程关键文件清单如下，它们是新增 base model 类型与生成引擎时的「高频改动面」：

• src/shared/constants/basemodel.constants.ts：base model 常量（re-export 自@civitai/shared包，实际实现在 packages/civitai-shared/src/basemodel.constants.ts）；
• src/shared/constants/generation.constants.ts：workflow 标签、process 类型、状态映射、seed 上限；
• src/server/common/constants.ts：generation 配置、调度器映射、尺寸上限；
• src/components/form-graph/generation/BaseGenerationForm.tsx（原GenerationForm2.tsx）：表单字段的条件逻辑；
• src/server/services/orchestrator/common.ts：偶尔更新；
• src/server/services/generation/generation.service.ts：偶尔更新（覆盖服务）。

总结

Civitai 生成系统的设计核心可以概括为三点：引擎与模型解耦（每个引擎通过 config 适配一个或多个模型版本）、统一编排入口（图片走 ImageGen 工厂，视频走 generation graph，成本预估统一由whatIf提供）、覆盖驱动接入（新增 base model 是否可用取决于EcosystemCheckpoints与GenerationBaseModel登记，兼容性由@civitai/shared的生态规则判定）。对开发者而言，接入新引擎的路径是清晰且可复制的：新增 config/handler → 注册进统一注册表 → 在表单中配置字段与默认值 → 登记覆盖表 → 端到端验证。

【免费下载链接】civitaiA repository of models, textual inversions, and more项目地址: https://gitcode.com/GitHub_Trending/ci/civitai