训练者：完整训练操作指南

这份指南面向“从零开始到可交付”的训练者，覆盖：

• 训练环境初始化
• 生成器工作区与素材准备
• group1 / group2 数据生成、训练、预测、测试、评估
• reviewed 试卷预标注
• 自动训练 auto-train
• 本地 solver bundle 组装与调用验证

1. 先确认你的目标

你至少要明确下面 3 件事：

1. 这次训练的任务范围：group1、group2，还是两者都做。
2. 输出目标是“训练验证”还是“交付 bundle”。
3. 训练目录与生成器目录是否固定在 Windows 盘符路径。

推荐目录约定：

D:\
  sinan-captcha-work\         # 训练目录（datasets/runs/reports/studies）
  sinan-captcha-generator\    # 生成器目录（sinan-generator.exe）
    workspace\                # 生成器工作区（materials/presets/jobs/logs）

2. 初始化训练目录

在训练机执行：

uvx --from sinan-captcha sinan env setup-train `
  --train-root D:\sinan-captcha-work `
  --generator-root D:\sinan-captcha-generator `
  --torch-backend auto `
  --yes

说明：

• env setup-train 会创建训练目录、写入 .python-version 和 pyproject.toml、执行 uv sync。
• 会自动铺入 .opencode/commands 与 .opencode/skills，供 auto-train --judge-provider opencode 使用。
• --torch-backend auto 会按 nvidia-smi 的 CUDA 版本自动选择 cpu/cu118/cu126/cu128/cu130。

然后执行环境自检：

Set-Location D:\sinan-captcha-work
uv run sinan env check

通过标准（至少）：

• torch_installed=true
• 如果是 GPU 训练，建议 torch_cuda_available=true

3. 初始化生成器工作区并导入素材

先初始化工作区：

Set-Location D:\sinan-captcha-generator
.\sinan-generator.exe workspace init --workspace D:\sinan-captcha-generator\workspace

导入本地素材包：

.\sinan-generator.exe materials import `
  --workspace D:\sinan-captcha-generator\workspace `
  --from D:\materials-pack-v3

或从 zip / URL 拉取：

.\sinan-generator.exe materials fetch `
  --workspace D:\sinan-captcha-generator\workspace `
  --source https://example.com/materials-pack.zip `
  --name official-pack-v1

如果素材包只包含单任务内容（例如只含 group1），导入时显式传 --task group1 或 --task group2。

3.1 为 exam prepare 预置训练目录素材

sinan exam prepare 默认读取训练目录下的 materials/，不是生成器工作区。

在进入第 7 节前，请确保训练目录至少包含：

D:\sinan-captcha-work\materials\
  group1\   # group1 审卷原始素材（case/icon.jpg + bg.jpg）
  result\   # group2 审卷原始素材（case/bg.jpg + gap.jpg）

如果你前面把原始素材放在其他目录（例如素材归档目录、共享盘、历史数据盘），请先同步到训练目录再继续。例如：

New-Item -ItemType Directory -Force D:\sinan-captcha-work\materials | Out-Null
Copy-Item <你的原始素材目录>\group1 D:\sinan-captcha-work\materials\group1 -Recurse -Force
Copy-Item <你的原始素材目录>\result D:\sinan-captcha-work\materials\result -Recurse -Force

sinan exam prepare 只读取训练目录 materials/，不会读取生成器工作区。

4. 生成训练数据

4.1 生成 group1 数据集

.\sinan-generator.exe make-dataset `
  --workspace D:\sinan-captcha-generator\workspace `
  --task group1 `
  --preset firstpass `
  --dataset-dir D:\sinan-captcha-work\datasets\group1\firstpass `
  --force

4.2 生成 group2 数据集

.\sinan-generator.exe make-dataset `
  --workspace D:\sinan-captcha-generator\workspace `
  --task group2 `
  --preset firstpass `
  --dataset-dir D:\sinan-captcha-work\datasets\group2\firstpass `
  --force

4.3 你应该看到的关键产物

• datasets/group1/<version>/dataset.json
• datasets/group2/<version>/dataset.json
• splits/val.jsonl（预测/测试默认输入）

5. 手动训练主线

以下命令在训练目录执行：

Set-Location D:\sinan-captcha-work

5.1 训练 group1

整链路（默认组件 all）：

uv run sinan train group1 --dataset-version firstpass --name firstpass

分组件训练：

uv run sinan train group1 --dataset-version firstpass --name g1_proposal --component proposal-detector
uv run sinan train group1 --dataset-version firstpass --name g1_embed --component icon-embedder

关键事实：

• group1 的 proposal detector 默认基模型是 yolo26n.pt。
• proposal detector 训练完成后会在验证集 scene 图上回放检测，和 scene_targets + distractors 真值框做 IoU 匹配；当前 pass 不再只是“有权重文件”，而是要求候选框召回率、整图召回率、平均 IoU 和误检数量达标。
• 如果历史 run 已经有 proposal-detector/weights/best.pt 或 last.pt，但旧 summary 没有 proposal gate，新版本会先用已有权重补跑 scene gate；只有 gate 失败时才需要重新训练 scene detector。
• embedder 由 --embedder-model 单独指定，未指定时走组件默认策略。
• icon-embedder 不应复用 detector 的大尺寸输入；当前默认会收口到小图标训练尺寸 96，并把默认 batch 提到 32，同时在训练过程中输出 epoch/batch 进度日志。
• icon-embedder 当前使用轻量残差 backbone、128 维 embedding 和 triplet loss + identity-aware in-batch contrastive loss 联合训练，目标更贴近真实检索排序。
• icon-embedder 在每个 epoch 结束后还会继续输出验证阶段日志：validation-triplet-loss、retrieval-query-embeddings、retrieval-candidate-embeddings。最后一个训练 step 打完后屏幕安静几秒到几分钟，通常是在做验证而不是挂死。
• icon-embedder 默认会根据验证集 embedding_recall_at_1 自动早停，避免无意义跑满 120 轮；最优权重仍持续写入 runs/group1/<name>/icon-embedder/weights/best.pt。
• 当 auto-train 使用 --judge-provider opencode 时，icon-embedder 当前已经切到 LLM-first：本地 guardrail 不再直接把 review 的 CONTINUE 改写成提前切阶段，而是把异常信号附加到 review context，并立即触发一次更早的 review-embedder，由大模型决定是继续、切 hardset 还是升级处理 detector。
• 当前 EMBEDDER_GATE 也不再以 global exact recall 作为主门禁；它会优先看 embedding_scene_recall_at_1/@3，并单独统计 embedding_identity_recall_at_1，而把 embedding_recall_at_1/@3 降成诊断指标。
• 如果已经切过一次 hardset，但同模板混淆仍然高，当前 hardset 构建还会额外补充“同模板但不同 identity”的 gold negatives，而不是只依赖 detector 当前预测出来的 negatives。
• 自动训练中断恢复时，如果 icon-embedder/weights/last.pt 已存在但 icon-embedder/summary.json 不完整，会按断点续训；只有完整 summary 存在时才会把已有权重视为组件已完成。

5.2 训练 group2

uv run sinan train group2 --dataset-version firstpass --name firstpass

关键事实：

• group2 默认模型是 paired_cnn_v1，不是 YOLO。
• 默认输入尺寸 imgsz=192。

5.3 续训与迁移训练

在同一 run 续训：

uv run sinan train group1 --name firstpass --resume
uv run sinan train group2 --name firstpass --resume

从上一轮最佳权重开新 run：

uv run sinan train group1 --dataset-version firstpass_v2 --name round2 --from-run firstpass
uv run sinan train group2 --dataset-version firstpass_v2 --name round2 --from-run firstpass

6. 预测、测试与评估

6.1 预测

uv run sinan predict group1 --dataset-version firstpass --train-name firstpass
uv run sinan predict group2 --dataset-version firstpass --train-name firstpass

6.2 一键测试（predict + evaluate）

uv run sinan test group1 --dataset-version firstpass --train-name firstpass
uv run sinan test group2 --dataset-version firstpass --train-name firstpass

6.3 仅评估 JSONL

uv run sinan evaluate `
  --task group1 `
  --gold-dir D:\sinan-captcha-work\reports\group1\test_firstpass\_gold `
  --prediction-dir D:\sinan-captcha-work\reports\group1\predict_firstpass `
  --report-dir D:\sinan-captcha-work\reports\group1\eval_firstpass

group2 同理，把 --task 和目录切到 group2。

7. reviewed 试卷与预标注

7.1 准备试卷目录并导出 reviewed 标注

uv run sinan exam prepare --task group1 --materials-root D:\sinan-captcha-work\materials --output-dir D:\sinan-captcha-work\materials\business_exams\group1\reviewed-v1
uv run sinan exam export-reviewed --task group1 --exam-root D:\sinan-captcha-work\materials\business_exams\group1\reviewed-v1

group2 同理，--materials-root 仍指向训练目录 materials/。

7.2 用已训练模型预标注 reviewed 试卷

uv run sinan train group1 prelabel --exam-root D:\sinan-captcha-work\materials\business_exams\group1\reviewed-v1 --dataset-version firstpass --train-name firstpass
uv run sinan train group2 prelabel --exam-root D:\sinan-captcha-work\materials\business_exams\group2\reviewed-v1 --dataset-version firstpass --train-name firstpass

7.3 group1 查询图目录预标注

uv run sinan train group1 prelabel-query-dir --input-dir D:\query-dir

关键事实：

• 当前这条命令使用内置规则式 query splitter，不依赖单独检测模型。

7.4 group1 本地 VLM 预标注

uv run sinan train group1 prelabel-vlm `
  --pair-root D:\vlm-pairs `
  --model qwen2.5vl:7b `
  --ollama-url http://127.0.0.1:11434

8. 自动训练（auto-train）

建议顺序：先 rules，后 opencode。

8.1 rules 路线

uv run sinan auto-train run group1 `
  --study-name study_group1_v1 `
  --train-root D:\sinan-captcha-work `
  --generator-workspace D:\sinan-captcha-generator\workspace `
  --dataset-version v1 `
  --judge-provider rules `
  --max-steps 12 `
  --max-hours 2 `
  --max-new-datasets 1

8.2 opencode 路线

先在训练目录启动：

opencode serve --port 4096

再运行：

uv run sinan auto-train run group1 `
  --study-name study_group1_llm `
  --train-root D:\sinan-captcha-work `
  --generator-workspace D:\sinan-captcha-generator\workspace `
  --dataset-version v1 `
  --judge-provider opencode `
  --judge-model gemma4 `
  --opencode-attach-url http://127.0.0.1:4096 `
  --max-steps 12

关键事实：

• opencode 路线当前不只是做 judge-trial。当 trial 进入 RETUNE 时，控制器会先本地生成 trial_analysis.json，再调用 plan-retune，让大模型基于错误样本和当前参数决定下一轮怎么训。
• group1 的 trial_analysis.json 当前会把 query-detector、proposal-detector、icon-embedder 三个组件的 gate 结果、错误样本统计、review 结果和当前参数一起交给大模型，避免下一轮无方向乱调。
• 如果 group1 icon-embedder 还在训练中、trial 尚未进入 SUMMARIZE，当前也会先写：
• studies/<task>/<study-name>/trials/<trial-id>/interim_result_summary.json
• studies/<task>/<study-name>/trials/<trial-id>/interim_trial_analysis.json 这样即使训练还没结束，也能直接看到当前 epoch、代理主指标、失败模式和 failure_audit 摘要，不用再等完整 trial 收尾。
• group1 的 retune_plan.json 可以同时给出：
• 哪些组件继续 train
• 哪些组件直接 reuse
• 每个组件单独的 model / epochs / batch / imgsz 覆盖
• group1 当前商业测试标准是：
• 默认从 reviewed 试卷池稳定抽样 50 题
• 默认要求 success_rate >= 0.90
• 单题必须同时满足：目标数量一致、点击顺序正确、每个点击点都落在对应标准图标方框内
• 当前 group1 商业门不看 IoU，只看最终点选结果
• 商业测试当前会额外保存以下可排查工件：
• modeltest/predict_*/labels.jsonl：模型完整输出
• evaluation/failures.jsonl：评估失败明细
• case_results.jsonl：逐题完整判卷明细
• failed_cases.jsonl：失败题明细
• case_summary.csv：业务可读汇总表
• group1 商业测试报告当前会明确区分：
• 图标没找出来
• 点击顺序不对
• 疑似找错图标
• 点击点落在图标框外
• group1 icon-embedder 当前在 TRAIN_EMBEDDER_BASE / TRAIN_EMBEDDER_HARD 仍保留本地 guardrail，但口径已经改成：
• 启用 opencode review 时：guardrail 只会写 guardrail-alert 并立即触发额外 review，不再直接替大模型下结论
• 未启用 LLM review 时：guardrail 继续作为 deterministic 兜底，避免明显无效的长时间空跑
• 只有当下一步仍然明确是 REGENERATE_DATA 时，控制器才会继续走 plan-dataset -> dataset_plan.json。如果当前只是先在同一数据集上做定向重训，本轮不会生成新的数据计划。
• 训练机上排查自主训练方向时，优先看：
• studies/<task>/<study-name>/trials/<trial-id>/interim_result_summary.json
• studies/<task>/<study-name>/trials/<trial-id>/interim_trial_analysis.json
• studies/<task>/<study-name>/trials/<trial-id>/result_summary.json
• studies/<task>/<study-name>/trials/<trial-id>/trial_analysis.json
• studies/<task>/<study-name>/trials/<trial-id>/retune_plan.json

9. 组装并验证本地 solver bundle

用已训练 run 构建 bundle：

uv run sinan solve build-bundle `
  --bundle-dir D:\sinan-captcha-work\bundles\solver\current `
  --group1-run firstpass `
  --group2-run firstpass `
  --train-root D:\sinan-captcha-work `
  --force

校验 bundle：

uv run sinan solve validate-bundle --bundle-dir D:\sinan-captcha-work\bundles\solver\current

运行单次请求：

uv run sinan solve run `
  --bundle-dir D:\sinan-captcha-work\bundles\solver\current `
  --request D:\sinan-captcha-work\requests\group2_req.json `
  --output D:\sinan-captcha-work\requests\group2_resp.json

solve run 请求/响应合同见： 训练者：Solver Bundle CLI 参考

10. 完成判定（建议作为交付前 gate）

• env check 通过（训练环境可用）。
• 至少 1 轮 group1 + group2 手动训练成功。
• test group1 / test group2 均生成报告并达成业务阈值。
• 若要交付本地 bundle：solve build-bundle + solve validate-bundle + solve run 三步通过。
• 所有关键命令和参数沉淀到你的运行脚本或作业记录中，避免人工记忆执行。