scenario-model-training

场景模型训练

概述

当许多素材都必须保持统一的外观时，例如一套图标、一个反复出现的角色或一个产品系列，就训练自定义模型。提示词、参考图和控制图是成本更低的第一步：请参阅 scenario-consistency。在报价训练费用之前，先针对当前主题运行 scenario-consistency 中介绍的参考测试：如果要统一外观，就将获批的美术作品用作风格参考，并在提示词中说明它们仅用于设定风格；如果要统一角色或产品，就将主图用作主体参考。在撰写本文时，风格测试证明：针对相同的需求，自定义 LoRA 的效果与风格一致，单张图的价格也相近，而成本仅相当于生成一张图。只有当测试结果在整套素材中出现偏差时才进行训练，而不是提前训练；下方的实例从这一步之后开始。

判断依据见以下两份参考资料： references/base-model-selection.md（为 recommend_training 提供依据的用户访谈）和 references/dataset-curation.md（不同训练类型的数据集大小、图片规则、说明文字和审核要求）。

连接方式和核心生成流程：请参阅 scenario 技能。如果此处提到的同级技能不在你可用的技能中，请让用户安装 (npx skills add scenario-labs/skills --skill <name>)；如果无法等待，请根据工具模式继续操作，并指出这一缺失。

训练工具不包含在默认工具集中：使用 scenario_tools_search 获取模式，通过 scenario_tool_execute_read 执行读取操作（recommend_training、model_get），通过 scenario_tool_execute_write 执行写入操作（model_create、train、model_update），或者通过 ?toolsets=full 重新连接。

快速参考

步骤	工具
选择基础架构	recommend_training（由 LLM 驱动，会产生费用）
创建模型框架	model_create（data.type 使用推荐结果中的值）
上传数据集	upload_asset + upload_asset_complete
添加训练图片	train 操作 upload_images，每次调用 10 个素材 ID
估算费用	使用 dry_run: true 调用 train 操作 configure（仅报价，不创建任务）
预览每个轮次	config.sample_prompts，任何多轮次运行至少设置一个
启动	train 操作 start，使用相同的 config，或留空以使用默认值
等待	使用返回的任务 ID 调用 jobs_wait
生成	对你自己的模型 ID 调用 model_schema_get，然后调用 model_run
管理	models_list、model_get、model_update

实例：用于游戏道具的风格 LoRA

1. 使用 recommend_training，参数为 prompt: "hand-painted prop icons for a mobile RPG"、 modality: "image"、dataset_shape: "single_images"，以及访谈中确定的 subject、style 和 priority。 返回推荐的变体、备选项和 dataset_requirements（形状与大小范围）。此操作会产生成本：意图明确后调用一次即可。
2. 使用 model_create，参数为 data: {"name": "rpg-prop-icons", "type": "<type from step 1>"}。记下 返回的模型 ID。
3. 先整理数据集（数据集参考），使其符合第 1 步的 dataset_requirements，然后使用 upload_asset 和 upload_asset_complete 上传每个文件（参见 scenario 技能），并收集资源 ID。对于 image_pairs 数据集， 使用 train 操作 set_pairs 映射成对的图片。
4. 使用 train，参数为 action: "upload_images"、model_id、images: [<asset ids>]，每次最多 10 个 （参见数据集限制）；此操作会更改数据，因此请传入 team_id 和 project_id（作用范围：scenario 技能）。
5. 使用 train，参数为 action: "configure"、 config: {"epochs": 12, "sample_prompts": ["a rusty lantern icon, centered, plain field", "a blue mana potion icon, three-quarter view, plain field"]}。 dry_run: true 会返回报价，不会启动训练。epochs 是主要的成本调节项（成本随其线性增长）；其他参数应 根据数据集大小设置（数据集参考）。多轮次运行时，sample_prompts 不是可选项：训练器只会为提供了这些提示词的 运行发布逐轮检查点，因此不提供这些提示词的运行只会以最终权重结束，尽管 epochs 指定了轮次数，也只有一个 可供选择的轮次；如果模型最终过拟合，也没有更早的检查点可供回退（曾有一次 12 轮运行最终只有一个可选轮次）。 各系列的上限不同：编写本文时，Flux LoRA 系列上限为 8，Flux.2、Qwen 和 ZImage LoRA 上限为 4，因此请查阅 train schema 获取上限。提示词应按照训练类型的标注规则，在数据集之外测试概念（风格数据集应描述新的主体， 绝不能描述风格；角色数据集应以触发词开头，并指定新的姿势或场景）：这些就是你用来选择轮次的预览；通用提示词 会在每个轮次生成通用场景，这就导致有一次运行把全部报价都花在了 20 张预览图上，内容是 4 个无关的风景。 编辑系列需要 sample_source_images，按相同顺序为每个提示词提供一个资源 ID；其他所有系列都会拒绝此字段。 将报价展示给用户并征得同意，然后使用相同的 config，以 action: "start" 启动训练（无人值守时，只有在任务已 授权训练或预算足以覆盖训练费用的情况下才启动；否则停止并报告报价）。configure 始终只报价，绝不会启动； 在该操作中使用 dry_run: false 会被拒绝。只有 start 会启动训练；使用 dry_run: true 调用 start 则只会 报价。应将 start 视为会花完全部报价：不要指望 stop 能退还任何费用。
6. 启动响应会包含一个任务：将其 ID 传入 job_ids 并调用 jobs_wait。没有任务 ID 表示并未启动：应报告此情况， 不要重试。训练时间会超过服务端的等待时限，因此请使用返回的 pending_job_ids 再次调用，直到任务完成；绝不要 轮询 job_get。
7. 生成前，先根据预览选择轮次：预览位于 Web 应用的模型页面，表现最好的轮次很少是最后一轮。轮次由用户选择； 无人值守时，使用训练完成的模型进行生成，说明尚未确定轮次选择，然后继续。接着对新模型 ID 调用 model_schema_get 和 model_run；自定义模型有自己的参数约定。LoRA 只能运行在 schema 中 runs_as 和 run_with.required_arguments 指定的基础模型上，不能与其所属系列的其他变体搭配使用；只有一个 已记录的例外：Z-Image LoRA 可用于所有 Z-Image 变体（基础模型参考）。生成时出现 size mismatch 或 weight dimension 错误，表示传入了其他变体作为基础模型，并不代表训练失败：不要重新训练，应重新读取 run_with，并运行其中指定的组合。
8. 管理模型：使用 models_list，参数为 filters: {"privacy": "private", "status": "trained"}，即可列出 已就绪的模型。使用 model_get 和 include_description: true 获取完整文档；使用 model_update 编辑名称、 描述和隐私设置。

会导致训练运行失败的数据集限制

几乎所有 train 失败都与数据集处理有关，而非超参数。

• 每次调用最多 10 个 ID。 upload_images 一次最多接受 10 个资源 ID；超过后会返回 400 Too many assetIds provided in a single request。每 10 个 ID 分成一组调用一次：模型会累积 整个数据集。
• 分组之间不能重叠。 重新发送已添加的 ID 会返回 400 The provided assetId is already a training image of this model。部分失败后，只重新发送 尚未成功添加的分组。
• 两个独立的套餐上限。 每个团队的数据集大小都有上限：超过后，upload_images 会返回 429，指出 add-training-image，并在 actionLimit 中列出上限。分组上传无法绕过此限制：筛选出质量最高的图片，或提示升级套餐。并发训练次数则受另一个名为 parallel-training 的上限限制，某些套餐将其设为 0。
• 先添加图片，再配置。 空数据集上调用 configure 或 start 会因训练图片数量不符合要求而无法通过验证。配对数据集必须包含完整配对，且某些模型系列的最低数量大于 1。
• 一次只启动一个训练。 运行开始后，再次启动会返回 400 Model is already training：使用 jobs_wait 等待，或通过 train action: "stop" 停止。重复启动还会触发冷却期，429 响应中会列出 remainingSeconds。

常见错误

• 为一次性任务训练模型。只需生成一张符合风格的图片时，用提示词加参考图即可；公开目录中有许多已训练的 LoRA，先用 search 搜索。
• 把每张输出都出现同一张错误的脸当作普通偏差。如果模型始终生成同一个陌生人的脸，说明它学到了说明文字，而不是图片：图片中的身份特征信号太弱，通常是因为图片都源自同一张源图，只是看起来有所变化，因此数据集呈现为近乎重复的同一构图。应修正数据集（使用真正不同的照片、说明文字只写明变化项、添加触发词），而不是调整轮数（参见数据集参考）。
• 使用 recommend_training 选择生成模型：它只选择训练基础模型；请使用 recommend 或 search。
• 将本地路径或 URL 传给 train：先用 upload_asset 上传，再传入资源 ID；否则会出现指出 assetId 的请求体格式错误。
• 把 400 Custom models only are supported for this endpoint 当作参数问题：此路由只接受你自己训练的模型；请从 models_list 重新读取 ID。
• 启动多个轮次却不提供 sample_prompts：运行会完成，但只训练一个轮次且没有预览，因此报价无法用于比较。
• 把报价当作启动操作。configure 会返回 training_started: false 且不返回任务；只有获得批准后才通过 start 启动，并且必须先确认取得任务 ID，再等待。
• 使用 status: "ready" 筛选 models_list：自由格式值会被静默忽略，导致返回所有模型，包括已删除的模型。请使用 "trained"。
• model_update 的 data.tags 会替换整个标签集；要只修改差异，请使用 model_add_tags / model_remove_tags。
• 期望 recommend_training 返回较早的基础模型：默认会排除旧版系列；只有项目必须使用同一个系列时才设置 legacy_ok: true。

声音克隆

声音克隆从同一个 recommend_training 调用开始，设置 modality: "voice" 和 dataset_shape: "short_audio" 或 "long_audio"；返回的 type 与其他情况一样传给 model_create。