跳到主要内容
训练指南章节 全部文档

TrainingProject 配置参考

SDK 0.2.0 项目的模型、数据、训练、预算、恢复和评估字段、默认值与验证规则。

所有语言版本中的命令和代码均保持英文。请将大写占位符替换为您账户和付费作业中的实际值;请勿将真实密钥粘贴到共享笔记本或日志中。

从配置到可复现的运行

在付费操作或更新权重之前,解析并审核所有设置。
  1. 描述 模型、教师模型与目标
  2. 约束 数据、隐私与预算
  3. 验证 适配器与运行环境兼容性
  4. 固定计划 解析后的设置与指纹
  5. 执行 仅执行审核通过的项目

描述: 模型、教师模型与目标. 约束: 数据、隐私与预算. 验证: 适配器与运行环境兼容性. 固定计划: 解析后的设置与指纹. 执行: 仅执行审核通过的项目

定义项目并保护数据

这是 schema 1.0 项目配置。将 Automatic 示例保存为 training.json。相对路径以该文件为基准解析;填写方案中实际包含的参考模型 ID;将 API key 保存在进程的密钥环境变量中。配置会选择教师模型和可独立训练的学生模型;不会下载教师模型的私有权重。

  • 未知键会被拒绝,而不会被静默忽略。所有路径都必须位于项目根目录内。
  • 教师模型只能接收获准训练来源中的内容;验证集和最终测试集始终留在本地。
  • 现有付费作业仍可通过 TrainingClient 的会话工作流使用。
项目、模型与教师模型
字段或接口类型或结果默认值或退出码行为与验证规则
schema_version string "1.0" 必须恰好为 1.0。在明确支持其他规范版本之前,一律拒绝。
mode enum 必填 / 无默认值 必填:automatic 或 advanced。自动模式会解析兼容的默认值;高级模式提供明确的控制选项。
objective string 必填 / 无默认值 必填的任务描述,长度为 10–4000 个字符。请说明受众、能力和预期结果。
model.path string 必填 / 无默认值 必填。指定项目根目录内的本地模型目录,或与不可变版本配对的仓库标识符。不能是教师推理端点。
model.adapter string 必填 / 无默认值 必填的已注册适配器 ID。transformers-causal-lm 表示 Transformers 因果语言模型适配器。
model.revision string | null null 本地模型会计算指纹。仓库标识符必须使用不可变的 40 或 64 个字符的版本。
teacher.provider string 必填 / 无默认值 必填的服务商标识符,必须来自当前有效的付费方案。这不会转移模型所有权。
teacher.reference_model_id integer 必填 / 无默认值 必填的正整数,取自该服务商方案所含模型;必须替换占位值。
数据与隐私
字段或接口类型或结果默认值或退出码行为与验证规则
data.sources string[] [] 包含 text 字段的本地 JSONL 训练数据路径。启用 approved_only 共享时,可补充教师模型生成的课程内容。
data.teacher_sharing enum "approved_only" approved_only 允许共享已审核的训练内容;none 禁止向教师模型发送客户内容。隐藏评估数据始终排除在外。
data.validation_path string | null null 可选的独立验证 JSONL 文件。若未提供,经审核的计划会在训练前定义确定性的拆分方式。
data.test_path string 必填 / 无默认值 必填的独立最终测试文件;绝不用于教师模型准备或优化。
data.deduplicate boolean true 删除不同数据拆分之间重复或重叠的示例;报告排除情况时不得泄露私密文本。
data.seed integer 42 非负整数;在后端支持的情况下,用于确定性拆分和可复现的初始化。
示例 · json
{
  "schema_version": "1.0",
  "mode": "automatic",
  "objective": "Classify support messages as billing, account_access or technical_issue.",
  "model": {"path": "./models/student", "adapter": "transformers-causal-lm", "revision": null},
  "teacher": {"provider": "openai", "reference_model_id": 123},
  "data": {
    "sources": ["./data/train.jsonl"], "teacher_sharing": "none",
    "validation_path": "./data/validation.jsonl", "test_path": "./data/test.jsonl",
    "deduplicate": true, "seed": 42
  },
  "runtime": {"target": "customer_datacenter", "devices": "auto"},
  "training": {"method": "auto"},
  "curriculum": {"topics": ["intent", "ambiguous_requests", "class_balance"], "max_improvement_cycles": 3, "stop_on_regression": true},
  "budgets": {"max_training_minutes": 120, "max_teacher_requests": 1000, "max_storage_gib": 20},
  "checkpoints": {"keep_last": 3},
  "evaluation": {"rubric": "./rubric.json", "baseline_required": true},
  "output": {"directory": "./runs/german-001", "format": "safetensors"}
}

选择自动或高级训练模式

自动模式会解析兼容的设置,并将结果记录在计划中。高级模式可显式指定训练设置,但架构、方法、精度和硬件必须彼此兼容。默认值不代表适用于所有设备的内存或性能保证。对于不受支持的组合,SDK 会在更新权重前通过兼容性检查报错。

  • 训练方法包括 SFT、LoRA 和 QLoRA;自动模式也可以将方法设为 auto。
  • 分布式 DDP 由获准的 launcher 提供节点 rank 和 rendezvous 设置;多节点运行必须使用明确且可信的 torchrun 环境。
  • 模型架构、分词器和上下文长度限制仍然适用。此适配器并不支持所有模型系列。
运行环境与分布式执行
字段或接口类型或结果默认值或退出码行为与验证规则
runtime.target enum 必填 / 无默认值 必填:fusionpointai_hosting、customer_datacenter 或 colab。选择现有运行环境;不会购买硬件。
runtime.devices "auto" | integer[] "auto" auto 会选择兼容且获准的设备;显式列表必须包含互不重复、非负且可见的 GPU 索引。
runtime.distributed.backend enum "none" 单进程使用 none;使用 ddp 则需要受支持的适配器和获准的多 worker launcher。
runtime.distributed.nodes integer 1 正整数。大于 1 时需要 DDP、已协商的节点访问权限、rank 和安全 rendezvous;设置此值不会提供计算容量。
训练设置
字段或接口类型或结果默认值或退出码行为与验证规则
training.method enum "auto" 可选 auto、SFT、LoRA 或 QLoRA。自动模式会解析 auto;Advanced 模式需要明确指定受支持的方法。
training.epochs number | "auto" "auto" 有限的正数,或仅在自动模式下使用 auto;有效步数也受获准的时间与资源预算约束。
training.learning_rate number | "auto" "auto" 小于 1 的有限正数,或仅在自动模式下使用 auto。适配器和商业政策可能规定更严格的限制。
training.batch_size integer | "auto" "auto" 正的每设备整数,或仅在自动模式下使用 auto;执行前会检查内存是否适用。
training.gradient_accumulation_steps integer | "auto" "auto" 正整数,或仅在自动模式下使用 auto。有效 batch size 还包括 worker 数和累积步数。
training.max_sequence_length integer | "auto" "auto" 不超过分词器和模型限制的正整数,或仅在自动模式下使用 auto;绝不静默扩展模型上下文。
training.precision enum "auto" 根据硬件和后端支持选择 auto、fp32、fp16 或 bf16;高级模式下必须明确指定。
training.lora.rank integer 16 正的适配器 rank。仅用于具备合格目标模块的 LoRA/QLoRA。
training.lora.alpha number 32 有限的正适配器缩放值。仅用于 LoRA/QLoRA。
training.lora.dropout number 0.05 大于或等于 0 且小于 1 的有限值。仅用于 LoRA/QLoRA。
training.lora.target_modules "auto" | string[] "auto" auto 会将支持的模块名解析到计划中;也可以提供非空的合格模块名列表。
课程控制
字段或接口类型或结果默认值或退出码行为与验证规则
curriculum.topics string[] [] 按顺序排列的主题名称。留空时自动模式可提出先决知识;高级模式要求明确且已审核的顺序。
curriculum.max_improvement_cycles integer 3 正整数,最大值为 10。如预算耗尽、没有进展或出现回归,应提前停止。
curriculum.stop_on_regression boolean true 为 true 时,达到评估标准定义的回归即停止改进;为 false 时,回归仍会导致最终验收失败。
示例 · json
{
  "schema_version": "1.0",
  "mode": "advanced",
  "model": {"path": "./models/student", "adapter": "transformers-causal-lm", "revision": null},
  "teacher": {"provider": "openai", "reference_model_id": 123},
  "objective": "Classify support messages as billing, account_access or technical_issue.",
  "data": {"sources": ["./data/train.jsonl"], "teacher_sharing": "none", "validation_path": "./data/validation.jsonl", "test_path": "./data/test.jsonl"},
  "runtime": {"target": "customer_datacenter", "devices": [0, 1], "distributed": {"backend": "ddp", "nodes": 1}},
  "training": {
    "method": "LoRA",
    "epochs": 3,
    "learning_rate": 0.0002,
    "batch_size": 1,
    "gradient_accumulation_steps": 16,
    "max_sequence_length": 2048,
    "precision": "bf16",
    "lora": {"rank": 16, "alpha": 32, "dropout": 0.05}
  },
  "curriculum": {
    "topics": ["intent", "ambiguous_requests", "class_balance"],
    "max_improvement_cycles": 3,
    "stop_on_regression": true
  },
  "checkpoints": {"every_steps": 100, "keep_last": 3, "resume_validation": "strict"},
  "budgets": {"max_training_minutes": 120, "max_teacher_requests": 1000, "max_storage_gib": 20},
  "evaluation": {"rubric": "./rubric.json", "baseline_required": true},
  "output": {"directory": "./runs/german-advanced-001", "format": "safetensors"}
}

设置有限预算和可衡量的验收标准

每个项目都必须明确设置时间、教师请求次数和存储预算。任一预算耗尽、完整性检查失败、出现回归或没有进展时,都应立即停止。保存有效的恢复状态,并说明未达成的标准。评估标准定义独立的验收任务;示例分数不代表已经取得相应结果。

  • 示例评估标准采用归一化的 0–1 量表,并分别列出必需标准。所有必需标准都必须通过。
  • 如需更改数据、模型、评估、拓扑或预算,应制定并审核新的计划,而不是强行恢复不匹配的运行。
  • 导出内容应包括通过验证的模型或适配器文件、分词器和清单,不得包含凭据、无关缓存数据或未经审核的模型代码。
预算、恢复与输出
字段或接口类型或结果默认值或退出码行为与验证规则
budgets.max_training_minutes number 必填 / 无默认值 必填的有限正数执行时间预算,以分钟计;包括运行开始后的准备和评估墙钟时间。
budgets.max_teacher_requests integer 必填 / 无默认值 必填的正整数;准备、审核和重试请求都计入。超出前必须安全失败并停止。
budgets.max_storage_gib number 必填 / 无默认值 必填的有限正数存储预算,以 GiB 计,涵盖数据、检查点和制品;绝不删除无关文件。
checkpoints.every_steps integer 100 正整数检查点间隔。成功暂停时也必须保存有效的原子检查点。
checkpoints.keep_last integer 3 1 到 5 之间的整数。较新的检查点验证通过后,只清理已过时且由本次运行拥有的检查点。
checkpoints.resume_validation enum "strict" 仅允许 strict。若模型、数据、配置、评估器或分布式拓扑指纹发生变化,则拒绝恢复。
evaluation.rubric string 必填 / 无默认值 必填的有效评估标准文件路径,其中的评估器已固定版本,且包含可衡量的必需标准。
evaluation.baseline_required boolean true 此契约中必须为 true。更新权重前先评估未经修改的基线。
output.directory string 必填 / 无默认值 必填的新建运行目录,由本次运行拥有。可检查或恢复已有运行,但 run 绝不覆盖它。
output.format enum "safetensors" 仅在受支持时使用 safetensors 或 adapters。导出适配器需要固定版本的基础模型和分词器。
评估标准字段
字段或接口类型或结果默认值或退出码行为与验证规则
schema_version string "1.0" 评估标准规范 1.0;与软件包发行版本不同。
name string 必填 / 无默认值 必填的非空评估标准名称,会用于报告。
scale.minimum number 0 归一化分数的下限:此规范中为 0。
scale.maximum number 1 归一化分数的上限:此规范中为 1。
criteria object[] 必填 / 无默认值 非空列表。每项必需标准都必须通过;ID 必须唯一。
criteria[].id string 必填 / 无默认值 必填且稳定的标准标识符,会保留在报告中。
criteria[].description string | null null 可选的补充说明。描述本身不是语义评估器。
criteria[].metric string 必填 / 无默认值 必填的已注册 metric:exact_match、macro_f1、text_similarity、chrf 或已注册的自定义评分器。
criteria[].minimum_score number 必填 / 无默认值 必填的 0 到 1 之间的有限阈值。示例阈值不代表承诺结果。
regression.maximum_score_drop number 0.02 相对于未经修改基线所允许的归一化分数绝对降幅,范围为 0 到 1;逐项评估保留的标准。
final_test.path string 必填 / 无默认值 必填;必须指向与 data.test_path 相同的独立文件。
final_test.allow_training_use boolean false 只能为 false。拒绝允许留出测试答案进入训练或教师模型输入的配置。
示例 · text
SDK 0.2.0 CONFIGURATION RULES
Unknown fields, duplicate IDs, nonfinite numbers and unsafe paths are rejected.
All model, data, rubric and output paths must resolve inside the project root.
Automatic mode resolves "auto" once; save all resolved values in the plan manifest.
Advanced mode requires explicit method, epochs, learning_rate, batch_size,
gradient_accumulation_steps, max_sequence_length and precision.
SFT does not consume LoRA options. LoRA/QLoRA require a compatible adapter.
Model files and pinned revisions are verified within the project root.
Use the CLI for explicit GPU indexes; Python callers can set CUDA_VISIBLE_DEVICES
before starting Python and keep runtime.devices set to auto.
No automatic execution of untrusted model code, shell commands or plugins.
All three budgets must be finite, positive and explicitly supplied.
Storage includes owned checkpoints, datasets and artifacts, not unrelated files.
Held-out test data must not be sent to the teacher or used for weight updates.
CLI overrides are limited to the documented flags; never silently override a plan.
RUBRIC RULES
Every criterion requires a registered metric and minimum_score; descriptions are not semantic evaluators.
Built-in metrics: exact_match, macro_f1, text_similarity and chrf.
Custom deterministic scorers use register_evaluator(name, scorer, version="...").
Evaluator versions and scoring configuration are pinned in the plan.
0 <= minimum_score <= 1 for the example's normalized scale.
All required criteria must pass; do not average away a failed criterion.
The final_test.path must match data.test_path; allow_training_use must be false.
Scores and budgets in examples are requested settings, not measured results.