Sentence Transformers 训练助手
为检索、相似度与稀疏搜索训练 Sentence Transformers 模型。
文档明确要求使用 HF_TOKEN、支持写权限的 hf auth login，并默认在训练结束后公开推送到 Hub；这使数据、凭证和模型发布边界可见，但未要求每次推送前确认，也未提供敏感数据处理、最小权限、回滚或发布前检查，因此扣分。
路由、损失与数据形状、评估器命名、冒烟测试、日志和故障排查要求较为一致，并说明多项已知不兼容性；但关键生产模板和脚本未包含在所给材料中，且没有静态可验证的关键路径测试，因此受静态上限限制并扣分。
覆盖 SentenceTransformer、CrossEncoder 和 SparseEncoder，并给出触发词、任务映射及非英语模型选择提示；但“任何 sentence-transformers 训练任务”过于宽泛，非适用边界、中文质量和中国大陆网络可达性未充分说明，依赖海外 Hub/Jobs 时尤其存在环境限制。
信息架构清晰，采用路由加分层 references/scripts，提供前置依赖、示例、默认值、限制和故障排查；但选定技能没有明确维护责任、版本策略、变更记录或更新路径，且核心模板未随证据提供，因此扣分。
文档能覆盖训练配置、损失选择、评估、硬负例、冒烟测试及 Hub 发布，理论上可减少手工试错；但输出仍依赖未提供的生产模板、脚本和其他 references，缺少可核验的代表性结果，直接可用性和边际收益证据有限。
内容包含具体命令、参数、指标键和失败模式，具备一定审计性；但本次仅静态阅读，没有执行结果、提交测试套件或第三方复现证据，且多数关键文件未提供，因此不能给予更高分。
- 默认公开推送模型到 Hugging Face Hub，并要求写权限令牌；处理私有或敏感数据前应人工确认目标仓库、令牌权限和发布策略。
- 技能依赖 Hugging Face Hub、模型/数据下载及可选 HF Jobs；中国大陆网络、代理、限流或凭证不可用时，核心流程可能无法完成。
- 不要仅依据本 SKILL.md 自行生成脚本；必须核对其引用的生产模板、完整 references 和实际 sentence-transformers 版本。
- 本次未执行代码或测试，可靠性、效果和证据分数均为静态保守估计。
这个 Skill 能做什么，适合哪些场景？
该技能指导智能体训练或微调 SentenceTransformer、CrossEncoder 和 SparseEncoder 模型。它覆盖损失函数选择、数据格式、评估器、难负例挖掘、蒸馏、LoRA、Matryoshka 训练及 Hugging Face Hub 发布。SKILL.md 主要负责路由，实际训练细节位于 references/ 和 scripts/ 中。它适合需要可复现训练流程和运行前检查的机器学习任务，但不应仅依据该文件自行合成训练脚本。
根据任务选择双编码器、交叉编码器或 SPLADE 稀疏编码器；要求读取对应的损失、评估器、模型架构、训练参数、数据格式、模型选择和故障排查参考资料；从 scripts/train_<type>_example.py 模板开始配置模型、数据集、损失和评估器；执行 max_steps=1 的冒烟测试后运行训练；记录日志、比较训练前后的评估分数，并将模型尝试发布到 Hugging Face Hub。
- 需要为向量检索或语义相似度任务微调 SentenceTransformer 的团队。
- 需要对双编码器召回结果进行二阶段重排的检索工程师。
- 需要训练 SPLADE 等学习型稀疏检索模型并连接倒排索引后端的团队。
- 需要通过难负例挖掘、蒸馏、LoRA 或 Matryoshka 训练改进模型的研究人员。
- 需要在训练前进行冒烟测试并保留基线、指标和日志的工程团队。
这个 Skill 有哪些优点和局限？
- 同时覆盖密集双编码器、交叉编码器和 SPLADE 稀疏编码器。
- 包含损失、评估器、数据格式、硬件和故障排查等训练前检查路径。
- 强制使用生产模板、冒烟测试、基线指标和结构化 verdict 日志。
- 支持 LoRA、蒸馏、Matryoshka、难负例挖掘和 Hugging Face Hub 发布。
- SKILL.md 是路由文件，完整训练信息不在该文件本身。
- GPU 强烈推荐，CPU 仅适合演示和 SentenceTransformer 的 StaticEmbedding。
- 源材料没有提供测试套件、平台兼容性测试结果或具体硬件性能数据。
- 模型发布需要 Hugging Face Hub 写入权限；HF Jobs 等云端运行需要额外参考配置。
如何安装这个 Skill？
将仓库中 skills/train-sentence-transformers/ 文件夹复制或符号链接到 Codex 的标准 .agents/skills 目录，例如 $REPO_ROOT/.agents/skills 或 $HOME/.agents/skills。安装训练依赖：pip install "sentence-transformers[train]>=5.0"。如需发布模型，执行 hf auth login，或设置具有写入权限的 HF_TOKEN。
如何使用这个 Skill？
在已安装该技能的编码代理中提出明确任务，例如："使用 SentenceTransformer 为我的问答数据训练一个语义检索模型，并先运行 max_steps=1 的冒烟测试。" 若任务类型不明确，应先说明是双编码器、交叉编码器还是稀疏编码器。具体参数和模板使用方式由 references/ 与 scripts/ 中的文件定义。