civitai 为 LoRA 训练系统接入新 AI-Toolkit 生态add-training-support 完整操作指南【免费下载链接】civitaiA repository of models, textual inversions, and more项目地址: https://gitcode.com/GitHub_Trending/ci/civitai本指南讲解如何把一个已存在于 civitai 基础模型常量中的模型家族如 Anima、HiDream、Boogu 等 AI-Toolkit 生态接入Train a LoRA 训练流程使其在训练表单 Step 1 中作为可选基础模型出现并向编排器orchestrator提交合法的training步骤。文章以仓库内.claude/skills/add-training-support/SKILL.md为主干逐文件src/utils/training.ts、训练 schema、特性开关、训练表单组件等给出可执行的接入步骤与源码级原理读完即可独立完成一个生态的 LoRA 训练支持接入。训练子系统与生成子系统是两个独立世界在动手之前必须先建立边界意识civitai 的训练training是与**生成generation**完全分离的子系统。src/server/services/orchestrator/ecosystems/*中的生成 handler/graph 和src/shared/data-graph/generation/*不属于本次任务不要触碰。下面列出的所有文件才是训练路径角色文件仓库根相对路径训练前端核心工具src/utils/training.ts模型版本 schematrainingDetailsBaseModels*src/server/schema/model-version.schema.ts编排器训练参数校验src/server/schema/orchestrator/training.schema.ts特性开关注册src/server/services/feature-flags.service.ts训练表单 UI 参数src/components/Training/Form/TrainingParams.tsx基础模型选择器src/components/Training/Form/TrainingSubmitModelSelect.tsx基础模型/生态常量经civitai/shared导出packages/civitai-shared/src/basemodel.constants.ts接入完成后该生态会① 出现在训练表单 Step 1 的对应媒体类型分组下② 选中后 Step 3 加载正确的默认训练参数③whatif提交能返回价格且不报校验错误。何时需要执行本流程刚通过add-ecosystem添加了新的模型家族现在需要让它可被训练重新启用某个曾被注释掉/下线的生态的训练支持编排器或civitai/client新增了某个*TrainingInput类型。前置条件生态、基础模型、家族family与许可证必须已经存在于基础模型常量中即ECO.Name枚举、EcosystemRecord与BaseModelRecord都已就位。若缺失需先运行add-ecosystem。关于当前代码库的事实src/shared/constants/basemodel.constants.ts现在只是一个重导出 shimexport * from civitai/shared/basemodel.constants真实的ECO、EcosystemRecord、BaseModelRecord与ecosystemSupport定义都在 packages/civitai-shared/src/basemodel.constants.ts 中——这也是 creator-studio spoke 能解析基础模型的原因。因此本指南中修改basemodel.constants.ts实际落在packages/civitai-shared包内而src/utils/training.ts顶部import { type BaseModel } from ~/shared/constants/basemodel.constants的调用方写法无需改变。核心技巧最近添加的生态几乎全部基于AI-Toolkit引擎固定为ai-toolkit。仓库内最完整、最简洁的参考实现是anima——纯图像、仅 AI-Toolkit、无modelVariant。最高杠杆的接入方式是对下面每一个文件 grepanima照葫芦画瓢加一份并行条目。Step 0 — 先确认civitai/client有该生态的训练输入类型务必先确认 SDK 已携带该生态的训练类型它会告诉你确切的字段形状、modelVariant是否必填以及是否有固定字段grep -niE NameAiToolkitTrainingInput|ecosystem: name \ node_modules/civitai/client/dist/generated/types.gen.d.ts从类型定义中读取三类关键信息ecosystem字面量——编排器期望的确切字符串例如boogumodelVariant——存在如 flux1 的dev|schnell、wan 的2.1|2.2或不存在固定/受限字段——例如 Boogu 声明batchSize?: null | number且注明 Fixed at 1 for this ecosystemUI 参数上下界必须遵循这一点readonly输出字段defaultSteps、storageBuzzPerEpoch、maxBatchSize等——由服务端计算永远不要发送。如果已安装版本缺类型先查最新版再升级npm view civitai/client versions --json | tail pnpm add civitai/clientv若仍缺失也无碍编排器分发逻辑training.orch.ts在组装AiToolkitTrainingInput时已把ecosystem直接透传底层会做一次as unknown as类型断言功能上可以工作——但优先使用带类型的 SDK。Step 1 — 收集该生态的训练默认值从用户、模型卡片或编排器whatif示例请求中收集以下参数默认 stepsAI-Toolkit 的主要长度旋钮直接驱动定价lrunet 学习率、text encoder 是否训练通常关闭networkDim / networkAlpha、lrScheduler、optimizerType、noiseOffsetbatch size 上下界许多 AI-Toolkit 图像生态固定为 1resolution图像生态通常为 1024基础模型的 AIR——若模型尚未上传 civitai先用示例请求中的 HF 仓库 URN 占位并留注释说明后续替换为urn:air:eco:checkpoint:civitai:modelIdversionId。对于仅 AI-Toolkit 的生态该 AIR 不会发送给编排器编排器根据 ecosystem 自行解析基础模型只用于 UI 展示与getTrainingFields.getModel。同时选定稳定的base-model keytrainingModelInfo的键如boogu与baseTypeTrainingBaseModelType如boogu。两者可以不同SD 用sd_1_5/anime/… 多个 key 全部映射到 baseTypesd15但单 checkpoint 生态建议保持一致。Step 2 — 与用户确认接入计划Adding training support for: Name (baseType: baseType, key: key) Engine: ai-toolkit (mandatory) Variant: none | enum Defaults: steps n, lr n, dim/alpha n/n, scheduler x, batch n (max n), res n AIR: placeholder|civitai urn Feature flag: nameTraining / name-training (Flipt)等待确认后一次性完成全部编辑。Step 3 — 逐文件编辑3a.src/utils/training.ts核心约 7~8 处trainingBaseModelTypesImage或…Video/…Audio数组——加入baseType。当前图像数组已有anima、boogu、hidream-o1、krea2、mageflow、ideogram4等src/utils/training.ts视频数组含hunyuan、wan、ltx2/23/25、minimaxh3音频数组含acestep15、acestep15xl。aiToolkitStepDefault——若该生态默认 steps 不是 2000加一个分支。仓库现状src/utils/training.tsltx2/ltx23/ltx25/boogu/minimaxh3返回 3000anima返回 1500其余默认 2000。步骤值同时被aiToolkitSaveEveryDefaultMath.max(min, round(steps/10))联动用于每 N 步保存的初始值保证种子数量约等于默认 epoch 数。aiToolkitBatchMax——仅当最大 batch 1 时加分支默认返回 1。现状sdxl/sd15为 4zimage/ernie/flux2klein为 2src/utils/training.ts。trainingModelInfo——加入key: { label, pretty, type: baseType, description, air, baseModel: BaseModelName, isNew: true, aiToolkit: { ecosystem: eco [, modelVariant] }, }注意baseModel必须与basemodel.constants.ts中BaseModelRecord.name/生态key完全一致。仓库内hidream_o1条目src/utils/training.ts的注释就是反例教材值会流入训练完成后的ModelVersion.baseModel再被stringifyAIR消费一旦出现空格就会生成 malformed AIRURN 段以冒号分隔编排器 URN 解析回退为unknown导致 post-train 扫描以 400 失败。Boogu 条目src/utils/training.ts演示了占位 AIR 的写法urn:air:boogu:repository:huggingface:Boogu/Boogu-Image-0.1-Basemain.tar。baseTypeToEcosystem——加baseType: eco。该映射src/utils/training.ts是自定义模型用户手输 AIR回退推导 ecosystem的兜底配合getAiToolkitEcosystem使用先查trainingModelInfo[baseModel].aiToolkit.ecosystem查不到再按 baseType 回退。isAiToolkitSupported的supportedTypes——加baseType。当前支持列表含 sd15/sdxl/flux/sd35/hunyuan/wan/chroma/qwen/zimage/ernie/flux2klein/ltx 系列/minimaxh3/hidream-o1/anima/boogu/krea2/mageflow/ideogram4/acestep 系列src/utils/training.ts。isAiToolkitMandatory的mandatoryTypes——加baseType仅 AI-Toolkit 生态必做。加入后自动获得两项联动isSamplePromptsRequired对该 baseType 恒为 true强制 sample prompts且isAiToolkitEnabled直接返回 true不再依赖 per-model 开关门控完全交给生态自身的nameTraining特性开关src/utils/training.ts。getDefaultEngine——加if (baseType baseType) return ai-toolkit;。仓库现状对每个强制生态都有独立分支并附注释如if (baseType anima) return ai-toolkit; // Anima requires AI Toolkitsrc/utils/training.ts。3b.src/server/schema/model-version.schema.ts新增export const trainingDetailsBaseModelsName [key] as const;与既有条目并列现已有trainingDetailsBaseModelsAnima [anima]、trainingDetailsBaseModelsBoogu [boogu]、trainingDetailsBaseModelsHiDreamO1 [hidream_o1]等src/server/schema/model-version.schema.ts把...trainingDetailsBaseModelsName展开进对应媒体类型的聚合数组trainingDetailsBaseModelsImage/…Video/…Audio第 89 行起trainingDetailsObj中的 zod 枚举baseModel、baseModelType由上述数组 trainingBaseModelType派生自动更新无需手改。除非要把BaseModel展示名映射回 keyWan 就是这么做的否则无需新增baseModelToTraningDetailsBaseModelMap条目。3c.src/server/schema/orchestrator/training.schema.ts在aiToolkitTrainingParams判别联合discriminated union中加一个分支src/server/schema/orchestrator/training.schema.ts 展示了 sd1/sdxl/chroma/qwen/zimage/ltx 等既有分支aiToolkitBaseParams.extend({ ecosystem: z.literal(eco), modelVariant: z.undefined().optional() }),若 SDK 类型要求modelVariant则改为modelVariant: z.enum([...])。缺少此分支提交校验会直接拒绝新生态。判别联合正是用于按 ecosystem 强制modelVariant合法性如 flux1 区分dev|schnell。3d.src/server/services/feature-flags.service.ts在特性开关表中加仓库现状示例animaTraining: { availability: [mod], fliptKey: anima-training }、booguTraining: { availability: [public], fliptKey: boogu-training }src/server/services/feature-flags.service.tsnameTraining: { availability: [mod], fliptKey: name-training },同时在 Flipt 中创建对应开关可用fliptskill。新/实验性基础模型默认mod-only是常态。该开关会被前端features.nameTraining直接消费见 3f也会影响image-training/video-training之外的生态级门控。3e.src/components/Training/Form/TrainingParams.tsxtrainingSettings数组驱动 UI 与各基础模型默认值src/components/Training/Form/TrainingParams.tsx 定义了overrides的类型结构。每个 setting 的overridesmap 以 base-model keykey为键而不是 baseType。grep 参考生态 keyanima:并在每个新生态应与基础默认不同的 setting 下加平行的key: { all: { … } }条目。仓库里 anima/boogu 的既有写法示例engineanima: { all: { default: ai-toolkit } }、boogu: { all: { default: ai-toolkit } }targetStepsanima: { all: { default: 1500 } }、boogu: { all: { default: 3000 } }与aiToolkitStepDefault呼应其余常见需要覆盖的 settingmaxTrainEpochs、trainBatchSize遵循 SDK 类型的固定/上限、saveEvery、resolution、shuffleCaption禁用、keepTokens禁用、unetLR、textEncoderLR禁用、lrScheduler、minSnrGamma禁用、networkDim、networkAlpha、noiseOffset、optimizerArgs。若基础默认已一致则可跳过该 setting例如图像生态的optimizerType默认 AdamW8Bit、flipAugmentation默认 false 就无需覆盖。表单默认参数由 src/store/training.store.ts 的getDefaultTrainingParams通过trainingSettings.reduce按 key 读取这些 overrides 生成。3f.src/components/Training/Form/TrainingSubmitModelSelect.tsx导入trainingDetailsBaseModelsName新增const baseModelName !!formBaseModel (trainingDetailsBaseModelsName as ReadonlyArraystring).includes(formBaseModel) ? formBaseModel : null;在正确的mediaType分组image/video/audio下新增门控渲染块仓库现有写法如{features.qwenTraining (ModelSelector … /)}见 src/components/Training/Form/TrainingSubmitModelSelect.tsx{features.nameTraining ( ModelSelector nameName value{baseModelName} baseTypebaseType makeDefaultParams{makeDefaultParams} isNew{…} / )}挑选一个未使用的color在 experimental build 告警条件中加入selectedRun.baseType baseType ||针对新/实验性基础模型。3g.packages/civitai-shared/src/basemodel.constants.ts即basemodel.constants.ts在ecosystemSupport数组加入训练支持条目仓库现状{ ecosystemId: ECO.Anima, supportType: training, modelTypes: loraOnly }、{ ecosystemId: ECO.Boogu, supportType: training, modelTypes: loraOnly }等见 packages/civitai-shared/src/basemodel.constants.tsloraOnly [ModelType.LORA]定义在第 1003 行{ ecosystemId: ECO.Name, supportType: training, modelTypes: loraOnly },loraOnly是训练产物的标准——训练输出就是 LoRA。生成支持是独立的除非该生态同时可生成否则不要添加generation支持。无需改动的文件通用/任意生态感知文件原因src/server/services/orchestrator/training/training.orch.tscreateTrainingStep_AiToolkit通用地组装AiToolkitTrainingInputecosystem直通、modelVariant按需展开、steps 定价、storageBuzzPerEpoch等只读输出不发送仅在生态需要特殊字段时才加分支sd1/sdxl 额外发modelminSnrGammaACE-Step 发samplesOverridessrc/store/training.store.tsgetDefaultTrainingParams按 key 读取trainingSettingsoverrides仅当新生态要成为表单默认时才需要动src/components/Training/Form/TrainingSubmit.tsx/TrainingSubmitAdvancedSettings.tsx通用逻辑完成 3a 后经getAiToolkitEcosystem即可解析生态src/server/common/enums.ts的OrchEngineTypesai-toolkit已存在Step 4 — 类型检查pnpm run typecheck常见失败原因baseType/key 拼写错误字面量与TrainingBaseModelType联合不匹配、聚合数组漏了 spread、baseModel字符串不是合法的BaseModel。迭代至通过。Step 5 — 验证可选在运行 dev server见dev-serverskill且为你自己的用户打开 Flipt 开关的前提下打开训练表单 → Step 1 在对应媒体类型下出现新基础模型选中后 Step 3 加载预期的默认参数whatif提交返回价格且无校验错误。进阶要点与注意事项强制 vs 可选 AI-Toolkit强制生态常见情况仅由自身的nameTraining开关门控可选生态sd15/sdxl/flux/…会额外通过aiToolkitFlagByBaseTypesrc/utils/training.ts检查 per-model 的aiToolkitX开关——仅当你在接入一个同时支持 Kohya 的生态时才需要考虑。媒体类型差异音频生态额外受audioTraining开关门控可能发送samplesOverrides参见 ACE-Step视频生态进入trainingBaseModelTypesVideo通常禁用空间类参数resolution/clipSkip/noiseOffset。批量大小若 SDK 类型固定 batch如 Boogu 1将trainBatchSize覆盖设为{ all: { default: 1, min: 1, max: 1 } }aiToolkitBatchMax保持默认即可。占位 AIRAI-Toolkit-only 生态在基础模型上传 civitai 之前可以带着占位 AIR 上线不会发送给编排器但务必留注释以便日后替换为 civitai URN。参数上下界现状参考AI-Toolkit 步骤定价相关 UI 边界在 src/utils/training.tsepochs 默认 10、范围 1–20saveEvery默认 200、范围 50–5000、步进 50。编排器会在服务端再次 clamp因此这些只是 UX 护栏而非事实来源。【免费下载链接】civitaiA repository of models, textual inversions, and more项目地址: https://gitcode.com/GitHub_Trending/ci/civitai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考