train-sentence-transformers 数据集格式全解列匹配规则、数据重塑与难负例挖掘实战指南【免费下载链接】skillsGive your agents the power of the Hugging Face ecosystem项目地址: https://gitcode.com/GitHub_Trending/skills7/skills导读本指南基于 train-sentence-transformers 技能仓库中的核心参考文档 dataset_formats.md系统讲解 sentence-transformers 训练中最容易踩坑、也最影响模型质量的一环数据集的形状与格式。读完本文你将掌握「列名与列序如何决定 loss 能否正常工作」「数据形状不匹配时如何重塑」「如何用mine_hard_negatives挖掘难负例并过滤假负例」以及如何在训练前用 Hub 侧命令快速验证数据集从而避免数小时训练因列序错误而报废。适用前提本文针对sentence-transformers5.0的SentenceTransformerbi-encoder、CrossEncoderreranker与SparseEncoderSPLADE训练流程配套的完整参考文档与生产模板均在本仓库 train-sentence-transformers 目录下。一、两条铁律label 靠列名识别输入靠列序定位sentence-transformers 的数据集格式规则可以浓缩成两句话这也是整个训练框架判断「哪个列是标签、哪些列是输入」的唯一依据如果 loss 需要标签数据集必须有一个名为label、labels、score或scores的列。凡是叫这几个名字之一的列一律被视为标签列。其余所有列都是输入。loss 会明确声明自己需要多少个输入列输入列的列名无关紧要但顺序至关重要。以CoSENTLoss为例它期望 2 个输入列加上 1 个浮点标签列。因此一个[premise, hypothesis, score]的数据集可以直接使用而[score, premise, hypothesis]虽然数据内容完全相同却会因为score排在第一位被误判为输入、打乱输入顺序而无法使用——必须先把列重排。这条规则在 losses_sentence_transformer.md 的决策表中体现得淋漓尽致「挑选与数据形状匹配的 loss而不是反过来」。训练失败时最常见的排查动作就是对照本仓库 troubleshooting.md 中ValueError: The dataset has ... columns but the loss expects N一节列数不匹配时优先检查是否有多余列用remove_columns删掉或顺序错误用select_columns重排列名从来不是判断依据列数与列序才是。二、各 loss 期望的数据形状速查每种 loss 的数据形状映射以 losses_sentence_transformer.md、losses_cross_encoder.md 与 losses_sparse_encoder.md 为准。除此之外还有几个跨 loss 的配方细节值得单独列出数据形状推荐 loss关键约束(anchor, positive)对MultipleNegativesRankingLoss或 Cached 变体需BatchSamplers.NO_DUPLICATES批次越大越好(anchor, positive, negative)三元组MultipleNegativesRankingLoss原生支持额外列即显式负例(text1, text2, score)score ∈ [-1,1]或[0,1]CoSENTLoss强烈推荐仅关注排序关系忽略绝对量纲(text1, text2, label)label ∈ {0,1}OnlineContrastiveLoss比ContrastiveLoss更抗标签噪声(text, class_id)单列 整数标签BatchAllTripletLoss等 batch-triplet 家族需BatchSamplers.GROUP_BY_LABEL保证同标签同批(query, positive, negative, score_diff)MarginMSELoss蒸馏标签需预先由教师模型算好(text, teacher_embedding)MSELoss蒸馏标签是完整的嵌入向量而非标量分数(query, passages[], labels[])LambdaLoss/ListNetLoss/ListMLELoss列表型数据可来自output_formatlabeled-list需要特别注意的细节CosineSimilarityLoss要求score归一化到[0, 1]。例如在stsb原始分数 0–5上只有当使用余弦相似度类 loss 时才需要除以 5CoSENTLoss/AnglELoss这类成对排序 loss 忽略绝对量纲直接使用原始分数即可。BatchAllTripletLoss/BatchHardTripletLoss/BatchSemiHardTripletLoss在批内挖掘三元组必须在训练参数中设置batch_samplerBatchSamplers.GROUP_BY_LABEL否则每个批次里同一标签没有多个样本批内挖掘无从谈起。MSELoss蒸馏的标签是教师模型的完整嵌入向量一个浮点列表不是标量分数MarginMSELoss蒸馏的标签是teacher_score(q, pos) - teacher_score(q, neg)必须逐行预先计算好loss 本身不会在内部调用教师模型。这一点在 losses_cross_encoder.md 的 Gotchas 中同样被强调。N-tuple 形状(anchor, positive, negative_1, negative_2, ..., negative_N)1 起始编号由mine_hard_negatives(..., output_formatn-tuple)生成而output_formatlabeled-list生成的是 CrossEncoder listwise 系列 loss如LambdaLoss所需的(query, documents[], scores[])列表形状。三、数据形状不匹配四种重塑操作当数据集列序、列名、多余列或 dtype 与 loss 期望不符时按照下面的操作逐项修正。以下示例均使用datasets库的DatasetAPI。3.1 重排列顺序列内容都对只是顺序不对# 现有列序是 [hypothesis, premise, score]但 CoSENTLoss 期望 premise 在前。 dataset dataset.select_columns([premise, hypothesis, score])3.2 重命名标签列你的标签列叫relevance但框架只认label/labels/score/scores# 标签列名为 relevance需要改成 label。 dataset dataset.rename_column(relevance, label)3.3 删除多余列记住第二铁律除标签列外的每一列都会被当作输入。带上元数据列如source_id、created_at、language会让输入列数量超限直接报「列数不匹配」# 框架会把所有非标签列视为输入元数据列必须删掉。 dataset dataset.remove_columns([source_id, created_at, language])3.4 转换 dtype从 CSV 加载的数据集默认把所有列存成字符串详见第五节 Gotchas而CoSENTLoss需要浮点标签# 标签是 str 类型需要转成 float 供 CoSENTLoss 使用。 dataset dataset.map(lambda x: {label: float(x[label])})这四种操作也是 troubleshooting.md 中「Metrics dont improve / are at baseline」一节给出的第一排查手段先用 dataset inspector--loss your-loss检查最常见的原因就是列序错误、标签列未被识别或形状不匹配。四、难负例挖掘检索模型质量的最大杠杆mine_hard_negatives位于sentence_transformers.util利用一个检索器retriever为(anchor, positive)对挖掘难负例产出一个可直接用于对比损失如MultipleNegativesRankingLoss的训练集。在 dataset_formats.md 中这是提升检索模型质量单一最高杠杆的操作losses_cross_encoder.md 也强调「对任何对比式 reranker 而言难负例挖掘都是必需的——随机负例什么都教不会模型」。4.1 基础用法from sentence_transformers import SentenceTransformer from sentence_transformers.util import mine_hard_negatives retriever SentenceTransformer(sentence-transformers/all-MiniLM-L6-v2) mined mine_hard_negatives( datasettrain_pairs, # 数据集需含 (anchor, positive) 或 (q, a) 列 modelretriever, num_negatives5, range_min0, range_max100, # 从检索排名的哪个区间内采样难负例 sampling_strategytop, # top 取排名第 1 的最难负例random 区间内随机 output_formatn-tuple, # triplet | n-tuple | labeled-pair | labeled-list use_faissTrue, )各参数含义与 mine_hard_negatives.py CLI 的--help一一对应dataset(anchor, positive)对数据集是挖掘的起点model负责对候选文档打分排序的检索器/双编码器可以是你当前的基座模型也可以换更强的模型num_negatives每个 anchor 挖掘的难负例数量库默认 3CLI 默认也是 3range_min/range_max从检索排序结果的哪个排名窗口内采样sampling_strategytop永远取窗口内排名第 1最难的random在窗口内随机选output_format控制输出数据集的形状见 4.2use_faiss是否用 FAISS 加速近似最近邻检索。4.2 四种输出格式output_format决定产出数据集的形状必须与后续训练选择的 loss 匹配triplet—(anchor, positive, negative)三元组。每个(query, negative)对一行。n-tuple—(anchor, positive, negative_1, negative_2, ..., negative_N)1 起始编号每个 query 一行所有负例在同一行。labeled-pair—(anchor, text, label)正例label1、负例label0。适合BinaryCrossEntropyLoss。labeled-list—(anchor, texts, labels)每个 query 一行携带候选文档列表与对应标签列表。适合 listwise 系列 lossLambdaLoss、ListNetLoss、ListMLELoss。4.3 用 cross-encoder 过滤假负例如果检索器返回的「负例」其实与 query 相关就形成了假负例会污染训练信号。可以传入一个 cross-encoder 作为「oracle」对候选重新打分再按分数阈值与边际条件剔除mined mine_hard_negatives( datasettrain_pairs, modelretriever, cross_encoderCrossEncoder(cross-encoder/ms-marco-MiniLM-L-6-v2), # 对候选重新打分 num_negatives5, max_score0.9, # 丢弃打分超过 0.9 的候选疑似假负例 relative_margin0.05, # 要求 neg_score pos_score * (1 - 0.05) absolute_margin0.2, # 要求 neg_score pos_score - 0.2 output_formatn-tuple, use_faissTrue, )使用原则relative_margin与absolute_margin通常二选一不要同时使用max_score作为硬性上限可以独立使用。这与 CLI 中--max-score、--min-score、--absolute-margin、--relative-margin的可选参数设计完全一致。4.4 CLI 一键挖掘scripts/mine_hard_negatives.py 是mine_hard_negatives的 CLI 包装器开箱即用。它支持从输入数据集的正例池挖掘也支持从独立的文档语料库挖掘生产环境推荐做法——典型检索语料如 Wikipedia、MS MARCO 远大于训练对池能挖出更难的负例# 基本用法从 (anchor, positive) 对挖掘 python mine_hard_negatives.py \ --dataset sentence-transformers/gooaq \ --model sentence-transformers/all-MiniLM-L6-v2 \ --num-negatives 5 \ --output-path data/gooaq-hard-negatives # 从独立语料库挖掘生产环境推荐 python mine_hard_negatives.py \ --dataset sentence-transformers/gooaq \ --model sentence-transformers/all-MiniLM-L6-v2 \ --corpus-dataset sentence-transformers/wikipedia-en-passages \ --corpus-column text \ --num-negatives 5 \ --output-path data/gooaq-hn-wiki # 配合 cross-encoder 过滤假负例 python mine_hard_negatives.py \ --dataset sentence-transformers/gooaq \ --model sentence-transformers/all-MiniLM-L6-v2 \ --cross-encoder cross-encoder/ms-marco-MiniLM-L-6-v2 \ --num-negatives 5 \ --max-score 0.9 \ --relative-margin 0.05 \ --output-path data/gooaq-hn-filtered # 挖掘完成后直接推送到 Hub python mine_hard_negatives.py \ --dataset sentence-transformers/gooaq --model ... --num-negatives 5 \ --push-to-hub your-username/gooaq-hard-negatives从源码可以看到该 CLI 的完整参数面--anchor-column/--positive-column指定输入列名、--output-format限定四种形状、--batch-size控制检索批大小、--use-faiss开启 FAISS、--output-scores把负例得分写入输出、--private控制推送仓库的可见性。脚本内部对--corpus-column做了存在性校验若指定列不在语料中会直接报错退出见 mine_hard_negatives.py。本地结果通过save_to_disk保存推送到 Hub 时使用push_to_hub(..., privateargs.private)。五、如何选择range_min/range_max与采样策略range_maxNone是库的默认值传入整数即可限制从检索排序列表中向下采样的范围。配置含义适用场景range_min0, range_max100从前 100 名检索结果中采样良好的默认配置range_min10, range_max100跳过前 10 名常含真正例没有 cross-encoder 过滤时的更安全选择range_min0, range_max1000更宽的采样网负例更多样但更慢sampling_strategytop永远选排名第 1 的最难负例追求每行最大训练信号sampling_strategyrandom在窗口内随机选取检索器本身噪声较大时更稳健从源码结构看range_min跳过的正是排序靠前的候选——这些位置最可能出现与 query 真正相关的文档在缺少 cross-encoder 把关时容易引入假负例因此文档建议至少从range_min10起步。六、训练前的 Hub 侧数据集快速检查在启动完整训练前用 Hugging Face Hub 的 CLI 快速核对列名与 loss 是否匹配是最省时的做法。本仓库的 huggingface-datasets 技能与 hf-cli 提供了配套工具# 流式读取数据集前 5 行走 DuckDB无需 load_dataset # 这是确认列名与 loss 匹配的最快方式。 hf datasets sql SELECT * FROM hf://datasets/id/split LIMIT 5 # 查看 config / splits / 大小 hf datasets info id # 渲染数据集 README hf datasets card id --text注意hf datasets sql依赖 DuckDBpip install duckdb。如果没有安装可以退回 Python 一行命令python -c from datasets import load_dataset; ds load_dataset(id, ...); print(ds.column_names, ds[0])另外本仓库 base_model_selection.md 提醒datasets 4会拒绝基于脚本的数据集加载器RuntimeError: Dataset scripts are no longer supported优先选择 parquet 支撑的镜像数据集。七、Gotchas训练脚本里的隐藏陷阱7.1remove_unused_columnsTrue默认开启Trainer 会丢弃未传给模型 forward 的列。大多数情况下这是合理行为但如果你依赖自定义 collator 使用元数据列必须显式设置remove_unused_columnsFalse否则训练会悄悄丢掉这些列。7.2 CSV 加载后浮点被存成字符串load_dataset(csv, ...)默认把所有列保持为字符串。用map强制转换dataset dataset.map(lambda x: {label: float(x[label])})7.3 挖掘难负例时include_positivesTrue的副作用开启后挖掘结果会把正例也作为负例放进输出列表。这只在构建评估器或想测量正例的排名时才有用训练时务必保持False否则正例被当作负例训练会直接毁掉信号。CLI 中对应--include-positives开关默认关闭。7.4 与数据形状相关的其他排错提示MNRL 家族必须配合BatchSamplers.NO_DUPLICATES否则同批出现重复 anchor 会制造假负例见 losses_sentence_transformer.md 与 train_sentence_transformer_example.py 生产模板的用法Cached*系列 loss 与gradient_checkpointingTrue互斥对比损失需要足够的数据量MultipleNegativesRankingLoss家族需要 10k 对才有意义生产级 SPLADE 需要 500k 三元组含挖掘的难负例CrossEncoder 继续训练也需要 10k–100k 标注对详见 troubleshooting.md 与 base_model_selection.md。八、完整工作流从原始对到可训练数据集综合以上所有要点一次标准的数据准备流程如下核对列名与列序确认标签列名为label/labels/score/scores之一输入列按 loss 期望的顺序排列两条铁律重塑数据按需select_columns重排、rename_column重命名、remove_columns删除元数据列、map转换 dtype挖掘难负例用 mine_hard_negatives.py 从独立语料挖掘 N 个难负例必要时加 cross-encoder 过滤假负例Hub 侧验证hf datasets sql/hf datasets info快速复核列名再进行max_steps1的冒烟测试生产模板已内置SMOKE_TEST环境变量模式见 train_sentence_transformer_example.py正式训练复制对应类型SentenceTransformer / CrossEncoder / SparseEncoder的生产模板替换MODEL_NAME、DATASET_NAME、RUN_NAME与 loss。如果训练中仍然出现「指标不提升」「列数不匹配」「NaN 损失」等故障请回到本仓库的 troubleshooting.md 按症状索引排查——其中「Metrics dont improve」与「ValueError: The dataset has ... columns」两条都与本文的数据格式规则直接相关。【免费下载链接】skillsGive your agents the power of the Hugging Face ecosystem项目地址: https://gitcode.com/GitHub_Trending/skills7/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
train-sentence-transformers 数据集格式全解列匹配规则、数据重塑与难负例挖掘实战指南【免费下载链接】skillsGive your agents the power of the Hugging Face ecosystem项目地址: https://gitcode.com/GitHub_Trending/skills7/skills导读本指南基于 train-sentence-transformers 技能仓库中的核心参考文档 dataset_formats.md系统讲解 sentence-transformers 训练中最容易踩坑、也最影响模型质量的一环数据集的形状与格式。读完本文你将掌握「列名与列序如何决定 loss 能否正常工作」「数据形状不匹配时如何重塑」「如何用mine_hard_negatives挖掘难负例并过滤假负例」以及如何在训练前用 Hub 侧命令快速验证数据集从而避免数小时训练因列序错误而报废。适用前提本文针对sentence-transformers5.0的SentenceTransformerbi-encoder、CrossEncoderreranker与SparseEncoderSPLADE训练流程配套的完整参考文档与生产模板均在本仓库 train-sentence-transformers 目录下。一、两条铁律label 靠列名识别输入靠列序定位sentence-transformers 的数据集格式规则可以浓缩成两句话这也是整个训练框架判断「哪个列是标签、哪些列是输入」的唯一依据如果 loss 需要标签数据集必须有一个名为label、labels、score或scores的列。凡是叫这几个名字之一的列一律被视为标签列。其余所有列都是输入。loss 会明确声明自己需要多少个输入列输入列的列名无关紧要但顺序至关重要。以CoSENTLoss为例它期望 2 个输入列加上 1 个浮点标签列。因此一个[premise, hypothesis, score]的数据集可以直接使用而[score, premise, hypothesis]虽然数据内容完全相同却会因为score排在第一位被误判为输入、打乱输入顺序而无法使用——必须先把列重排。这条规则在 losses_sentence_transformer.md 的决策表中体现得淋漓尽致「挑选与数据形状匹配的 loss而不是反过来」。训练失败时最常见的排查动作就是对照本仓库 troubleshooting.md 中ValueError: The dataset has ... columns but the loss expects N一节列数不匹配时优先检查是否有多余列用remove_columns删掉或顺序错误用select_columns重排列名从来不是判断依据列数与列序才是。二、各 loss 期望的数据形状速查每种 loss 的数据形状映射以 losses_sentence_transformer.md、losses_cross_encoder.md 与 losses_sparse_encoder.md 为准。除此之外还有几个跨 loss 的配方细节值得单独列出数据形状推荐 loss关键约束(anchor, positive)对MultipleNegativesRankingLoss或 Cached 变体需BatchSamplers.NO_DUPLICATES批次越大越好(anchor, positive, negative)三元组MultipleNegativesRankingLoss原生支持额外列即显式负例(text1, text2, score)score ∈ [-1,1]或[0,1]CoSENTLoss强烈推荐仅关注排序关系忽略绝对量纲(text1, text2, label)label ∈ {0,1}OnlineContrastiveLoss比ContrastiveLoss更抗标签噪声(text, class_id)单列 整数标签BatchAllTripletLoss等 batch-triplet 家族需BatchSamplers.GROUP_BY_LABEL保证同标签同批(query, positive, negative, score_diff)MarginMSELoss蒸馏标签需预先由教师模型算好(text, teacher_embedding)MSELoss蒸馏标签是完整的嵌入向量而非标量分数(query, passages[], labels[])LambdaLoss/ListNetLoss/ListMLELoss列表型数据可来自output_formatlabeled-list需要特别注意的细节CosineSimilarityLoss要求score归一化到[0, 1]。例如在stsb原始分数 0–5上只有当使用余弦相似度类 loss 时才需要除以 5CoSENTLoss/AnglELoss这类成对排序 loss 忽略绝对量纲直接使用原始分数即可。BatchAllTripletLoss/BatchHardTripletLoss/BatchSemiHardTripletLoss在批内挖掘三元组必须在训练参数中设置batch_samplerBatchSamplers.GROUP_BY_LABEL否则每个批次里同一标签没有多个样本批内挖掘无从谈起。MSELoss蒸馏的标签是教师模型的完整嵌入向量一个浮点列表不是标量分数MarginMSELoss蒸馏的标签是teacher_score(q, pos) - teacher_score(q, neg)必须逐行预先计算好loss 本身不会在内部调用教师模型。这一点在 losses_cross_encoder.md 的 Gotchas 中同样被强调。N-tuple 形状(anchor, positive, negative_1, negative_2, ..., negative_N)1 起始编号由mine_hard_negatives(..., output_formatn-tuple)生成而output_formatlabeled-list生成的是 CrossEncoder listwise 系列 loss如LambdaLoss所需的(query, documents[], scores[])列表形状。三、数据形状不匹配四种重塑操作当数据集列序、列名、多余列或 dtype 与 loss 期望不符时按照下面的操作逐项修正。以下示例均使用datasets库的DatasetAPI。3.1 重排列顺序列内容都对只是顺序不对# 现有列序是 [hypothesis, premise, score]但 CoSENTLoss 期望 premise 在前。 dataset dataset.select_columns([premise, hypothesis, score])3.2 重命名标签列你的标签列叫relevance但框架只认label/labels/score/scores# 标签列名为 relevance需要改成 label。 dataset dataset.rename_column(relevance, label)3.3 删除多余列记住第二铁律除标签列外的每一列都会被当作输入。带上元数据列如source_id、created_at、language会让输入列数量超限直接报「列数不匹配」# 框架会把所有非标签列视为输入元数据列必须删掉。 dataset dataset.remove_columns([source_id, created_at, language])3.4 转换 dtype从 CSV 加载的数据集默认把所有列存成字符串详见第五节 Gotchas而CoSENTLoss需要浮点标签# 标签是 str 类型需要转成 float 供 CoSENTLoss 使用。 dataset dataset.map(lambda x: {label: float(x[label])})这四种操作也是 troubleshooting.md 中「Metrics dont improve / are at baseline」一节给出的第一排查手段先用 dataset inspector--loss your-loss检查最常见的原因就是列序错误、标签列未被识别或形状不匹配。四、难负例挖掘检索模型质量的最大杠杆mine_hard_negatives位于sentence_transformers.util利用一个检索器retriever为(anchor, positive)对挖掘难负例产出一个可直接用于对比损失如MultipleNegativesRankingLoss的训练集。在 dataset_formats.md 中这是提升检索模型质量单一最高杠杆的操作losses_cross_encoder.md 也强调「对任何对比式 reranker 而言难负例挖掘都是必需的——随机负例什么都教不会模型」。4.1 基础用法from sentence_transformers import SentenceTransformer from sentence_transformers.util import mine_hard_negatives retriever SentenceTransformer(sentence-transformers/all-MiniLM-L6-v2) mined mine_hard_negatives( datasettrain_pairs, # 数据集需含 (anchor, positive) 或 (q, a) 列 modelretriever, num_negatives5, range_min0, range_max100, # 从检索排名的哪个区间内采样难负例 sampling_strategytop, # top 取排名第 1 的最难负例random 区间内随机 output_formatn-tuple, # triplet | n-tuple | labeled-pair | labeled-list use_faissTrue, )各参数含义与 mine_hard_negatives.py CLI 的--help一一对应dataset(anchor, positive)对数据集是挖掘的起点model负责对候选文档打分排序的检索器/双编码器可以是你当前的基座模型也可以换更强的模型num_negatives每个 anchor 挖掘的难负例数量库默认 3CLI 默认也是 3range_min/range_max从检索排序结果的哪个排名窗口内采样sampling_strategytop永远取窗口内排名第 1最难的random在窗口内随机选output_format控制输出数据集的形状见 4.2use_faiss是否用 FAISS 加速近似最近邻检索。4.2 四种输出格式output_format决定产出数据集的形状必须与后续训练选择的 loss 匹配triplet—(anchor, positive, negative)三元组。每个(query, negative)对一行。n-tuple—(anchor, positive, negative_1, negative_2, ..., negative_N)1 起始编号每个 query 一行所有负例在同一行。labeled-pair—(anchor, text, label)正例label1、负例label0。适合BinaryCrossEntropyLoss。labeled-list—(anchor, texts, labels)每个 query 一行携带候选文档列表与对应标签列表。适合 listwise 系列 lossLambdaLoss、ListNetLoss、ListMLELoss。4.3 用 cross-encoder 过滤假负例如果检索器返回的「负例」其实与 query 相关就形成了假负例会污染训练信号。可以传入一个 cross-encoder 作为「oracle」对候选重新打分再按分数阈值与边际条件剔除mined mine_hard_negatives( datasettrain_pairs, modelretriever, cross_encoderCrossEncoder(cross-encoder/ms-marco-MiniLM-L-6-v2), # 对候选重新打分 num_negatives5, max_score0.9, # 丢弃打分超过 0.9 的候选疑似假负例 relative_margin0.05, # 要求 neg_score pos_score * (1 - 0.05) absolute_margin0.2, # 要求 neg_score pos_score - 0.2 output_formatn-tuple, use_faissTrue, )使用原则relative_margin与absolute_margin通常二选一不要同时使用max_score作为硬性上限可以独立使用。这与 CLI 中--max-score、--min-score、--absolute-margin、--relative-margin的可选参数设计完全一致。4.4 CLI 一键挖掘scripts/mine_hard_negatives.py 是mine_hard_negatives的 CLI 包装器开箱即用。它支持从输入数据集的正例池挖掘也支持从独立的文档语料库挖掘生产环境推荐做法——典型检索语料如 Wikipedia、MS MARCO 远大于训练对池能挖出更难的负例# 基本用法从 (anchor, positive) 对挖掘 python mine_hard_negatives.py \ --dataset sentence-transformers/gooaq \ --model sentence-transformers/all-MiniLM-L6-v2 \ --num-negatives 5 \ --output-path data/gooaq-hard-negatives # 从独立语料库挖掘生产环境推荐 python mine_hard_negatives.py \ --dataset sentence-transformers/gooaq \ --model sentence-transformers/all-MiniLM-L6-v2 \ --corpus-dataset sentence-transformers/wikipedia-en-passages \ --corpus-column text \ --num-negatives 5 \ --output-path data/gooaq-hn-wiki # 配合 cross-encoder 过滤假负例 python mine_hard_negatives.py \ --dataset sentence-transformers/gooaq \ --model sentence-transformers/all-MiniLM-L6-v2 \ --cross-encoder cross-encoder/ms-marco-MiniLM-L-6-v2 \ --num-negatives 5 \ --max-score 0.9 \ --relative-margin 0.05 \ --output-path data/gooaq-hn-filtered # 挖掘完成后直接推送到 Hub python mine_hard_negatives.py \ --dataset sentence-transformers/gooaq --model ... --num-negatives 5 \ --push-to-hub your-username/gooaq-hard-negatives从源码可以看到该 CLI 的完整参数面--anchor-column/--positive-column指定输入列名、--output-format限定四种形状、--batch-size控制检索批大小、--use-faiss开启 FAISS、--output-scores把负例得分写入输出、--private控制推送仓库的可见性。脚本内部对--corpus-column做了存在性校验若指定列不在语料中会直接报错退出见 mine_hard_negatives.py。本地结果通过save_to_disk保存推送到 Hub 时使用push_to_hub(..., privateargs.private)。五、如何选择range_min/range_max与采样策略range_maxNone是库的默认值传入整数即可限制从检索排序列表中向下采样的范围。配置含义适用场景range_min0, range_max100从前 100 名检索结果中采样良好的默认配置range_min10, range_max100跳过前 10 名常含真正例没有 cross-encoder 过滤时的更安全选择range_min0, range_max1000更宽的采样网负例更多样但更慢sampling_strategytop永远选排名第 1 的最难负例追求每行最大训练信号sampling_strategyrandom在窗口内随机选取检索器本身噪声较大时更稳健从源码结构看range_min跳过的正是排序靠前的候选——这些位置最可能出现与 query 真正相关的文档在缺少 cross-encoder 把关时容易引入假负例因此文档建议至少从range_min10起步。六、训练前的 Hub 侧数据集快速检查在启动完整训练前用 Hugging Face Hub 的 CLI 快速核对列名与 loss 是否匹配是最省时的做法。本仓库的 huggingface-datasets 技能与 hf-cli 提供了配套工具# 流式读取数据集前 5 行走 DuckDB无需 load_dataset # 这是确认列名与 loss 匹配的最快方式。 hf datasets sql SELECT * FROM hf://datasets/id/split LIMIT 5 # 查看 config / splits / 大小 hf datasets info id # 渲染数据集 README hf datasets card id --text注意hf datasets sql依赖 DuckDBpip install duckdb。如果没有安装可以退回 Python 一行命令python -c from datasets import load_dataset; ds load_dataset(id, ...); print(ds.column_names, ds[0])另外本仓库 base_model_selection.md 提醒datasets 4会拒绝基于脚本的数据集加载器RuntimeError: Dataset scripts are no longer supported优先选择 parquet 支撑的镜像数据集。七、Gotchas训练脚本里的隐藏陷阱7.1remove_unused_columnsTrue默认开启Trainer 会丢弃未传给模型 forward 的列。大多数情况下这是合理行为但如果你依赖自定义 collator 使用元数据列必须显式设置remove_unused_columnsFalse否则训练会悄悄丢掉这些列。7.2 CSV 加载后浮点被存成字符串load_dataset(csv, ...)默认把所有列保持为字符串。用map强制转换dataset dataset.map(lambda x: {label: float(x[label])})7.3 挖掘难负例时include_positivesTrue的副作用开启后挖掘结果会把正例也作为负例放进输出列表。这只在构建评估器或想测量正例的排名时才有用训练时务必保持False否则正例被当作负例训练会直接毁掉信号。CLI 中对应--include-positives开关默认关闭。7.4 与数据形状相关的其他排错提示MNRL 家族必须配合BatchSamplers.NO_DUPLICATES否则同批出现重复 anchor 会制造假负例见 losses_sentence_transformer.md 与 train_sentence_transformer_example.py 生产模板的用法Cached*系列 loss 与gradient_checkpointingTrue互斥对比损失需要足够的数据量MultipleNegativesRankingLoss家族需要 10k 对才有意义生产级 SPLADE 需要 500k 三元组含挖掘的难负例CrossEncoder 继续训练也需要 10k–100k 标注对详见 troubleshooting.md 与 base_model_selection.md。八、完整工作流从原始对到可训练数据集综合以上所有要点一次标准的数据准备流程如下核对列名与列序确认标签列名为label/labels/score/scores之一输入列按 loss 期望的顺序排列两条铁律重塑数据按需select_columns重排、rename_column重命名、remove_columns删除元数据列、map转换 dtype挖掘难负例用 mine_hard_negatives.py 从独立语料挖掘 N 个难负例必要时加 cross-encoder 过滤假负例Hub 侧验证hf datasets sql/hf datasets info快速复核列名再进行max_steps1的冒烟测试生产模板已内置SMOKE_TEST环境变量模式见 train_sentence_transformer_example.py正式训练复制对应类型SentenceTransformer / CrossEncoder / SparseEncoder的生产模板替换MODEL_NAME、DATASET_NAME、RUN_NAME与 loss。如果训练中仍然出现「指标不提升」「列数不匹配」「NaN 损失」等故障请回到本仓库的 troubleshooting.md 按症状索引排查——其中「Metrics dont improve」与「ValueError: The dataset has ... columns」两条都与本文的数据格式规则直接相关。【免费下载链接】skillsGive your agents the power of the Hugging Face ecosystem项目地址: https://gitcode.com/GitHub_Trending/skills7/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
