评估

sentence_transformers.evaluation 定义了不同的类，可用于在训练期间评估模型。

BinaryClassificationEvaluator

class sentence_transformers.evaluation.BinaryClassificationEvaluator(sentences1: list[str], sentences2: list[str], labels: list[int], name: str = '', batch_size: int = 32, show_progress_bar: bool = False, write_csv: bool = True, truncate_dim: int | None = None, similarity_fn_names: list[Literal['cosine', 'dot', 'euclidean', 'manhattan']] | None = None)[source]

通过计算识别相似和不相似句子的准确率来评估嵌入相似度。度量包括余弦相似度、点积得分、欧氏距离和曼哈顿距离。返回的分数是指定度量的准确率。

结果将写入 CSV 文件。如果 CSV 文件已存在，则会追加数据。

标签 0 表示不相似对，1 表示相似对。

参数:

sentences1 (List[str]) – 句子的第一列。
sentences2 (List[str]) – 句子的第二列。
labels (List[int]) – labels[i] 是 (sentences1[i], sentences2[i]) 对的标签。必须是 0 或 1。
name (str, optional) – 输出的名称。默认为 “”。
batch_size (int, optional) – 用于计算嵌入的批量大小。默认为 32。
show_progress_bar (bool, optional) – 如果为 True，则显示进度条。默认为 False。
write_csv (bool, optional) – 将结果写入 CSV 文件。默认为 True。
truncate_dim (Optional[int], optional) – 用于截断句子嵌入的维度。如果为 None，则使用模型当前的截断维度。默认为 None。
similarity_fn_names (Optional[List[Literal["cosine", "dot", "euclidean", "manhattan"]]], optional) – 要使用的相似度函数。如果未指定，则默认使用模型的 similarity_fn_name 属性。默认为 None。

示例

from sentence_transformers import SentenceTransformer
from sentence_transformers.evaluation import BinaryClassificationEvaluator
from datasets import load_dataset

# Load a model
model = SentenceTransformer('all-mpnet-base-v2')

# Load a dataset with two text columns and a class label column (https://hugging-face.cn/datasets/sentence-transformers/quora-duplicates)
eval_dataset = load_dataset("sentence-transformers/quora-duplicates", "pair-class", split="train[-1000:]")

# Initialize the evaluator
binary_acc_evaluator = BinaryClassificationEvaluator(
    sentences1=eval_dataset["sentence1"],
    sentences2=eval_dataset["sentence2"],
    labels=eval_dataset["label"],
    name="quora_duplicates_dev",
)
results = binary_acc_evaluator(model)
'''
Binary Accuracy Evaluation of the model on the quora_duplicates_dev dataset:
Accuracy with Cosine-Similarity:             81.60  (Threshold: 0.8352)
F1 with Cosine-Similarity:                   75.27  (Threshold: 0.7715)
Precision with Cosine-Similarity:            65.81
Recall with Cosine-Similarity:               87.89
Average Precision with Cosine-Similarity:    76.03
Matthews Correlation with Cosine-Similarity: 62.48
'''
print(binary_acc_evaluator.primary_metric)
# => "quora_duplicates_dev_cosine_ap"
print(results[binary_acc_evaluator.primary_metric])
# => 0.760277070888393

EmbeddingSimilarityEvaluator

class sentence_transformers.evaluation.EmbeddingSimilarityEvaluator(sentences1: list[str], sentences2: list[str], scores: list[float], batch_size: int = 16, main_similarity: str | SimilarityFunction | None = None, similarity_fn_names: list[Literal['cosine', 'dot', 'euclidean', 'manhattan']] | None = None, name: str = '', show_progress_bar: bool = False, write_csv: bool = True, precision: Literal['float32', 'int8', 'uint8', 'binary', 'ubinary'] | None = None, truncate_dim: int | None = None)[source]

根据嵌入的相似度来评估模型，通过计算 Spearman 和 Pearson 的等级相关性与黄金标准标签进行比较。度量包括余弦相似度、欧氏距离和曼哈顿距离。返回的分数是指定度量的 Spearman 相关性。

参数:

sentences1 (List[str]) – 句子对中的第一个句子列表。
sentences2 (List[str]) – 句子对中的第二个句子列表。
scores (List[float]) – sentences1[i] 和 sentences2[i] 之间的相似度得分。
batch_size (int, optional) – 处理句子的批量大小。默认为 16。
main_similarity (Optional[Union[str, SimilarityFunction]], optional) – 主要使用的相似度函数。可以是字符串（例如，“cosine”、“dot”）或 SimilarityFunction 对象。默认为 None。
similarity_fn_names (List[str], optional) – 要使用的相似度函数名称列表。如果为 None，则使用模型的 similarity_fn_name 属性。默认为 None。
name (str, optional) – 评估器的名称。默认为 “”.
show_progress_bar (bool, optional) – 在评估期间是否显示进度条。默认为 False。
write_csv (bool, optional) – 是否将评估结果写入 CSV 文件。默认为 True。
precision (Optional[Literal["float32", "int8", "uint8", "binary", "ubinary"]], optional) – 用于嵌入的精度。可以是“float32”、“int8”、“uint8”、“binary”或“ubinary”。默认为 None。
truncate_dim (Optional[int], optional) – 用于截断句子嵌入的维度。如果为 None，则使用模型当前的截断维度。默认为 None。

示例

from datasets import load_dataset
from sentence_transformers import SentenceTransformer
from sentence_transformers.evaluation import EmbeddingSimilarityEvaluator, SimilarityFunction

# Load a model
model = SentenceTransformer('all-mpnet-base-v2')

# Load the STSB dataset (https://hugging-face.cn/datasets/sentence-transformers/stsb)
eval_dataset = load_dataset("sentence-transformers/stsb", split="validation")

# Initialize the evaluator
dev_evaluator = EmbeddingSimilarityEvaluator(
    sentences1=eval_dataset["sentence1"],
    sentences2=eval_dataset["sentence2"],
    scores=eval_dataset["score"],
    name="sts_dev",
)
results = dev_evaluator(model)
'''
EmbeddingSimilarityEvaluator: Evaluating the model on the sts-dev dataset:
Cosine-Similarity:  Pearson: 0.8806 Spearman: 0.8810
'''
print(dev_evaluator.primary_metric)
# => "sts_dev_pearson_cosine"
print(results[dev_evaluator.primary_metric])
# => 0.881019449484294

InformationRetrievalEvaluator

class sentence_transformers.evaluation.InformationRetrievalEvaluator(queries: dict[str, str], corpus: dict[str, str], relevant_docs: dict[str, set[str]], corpus_chunk_size: int = 50000, mrr_at_k: list[int] = [10], ndcg_at_k: list[int] = [10], accuracy_at_k: list[int] = [1, 3, 5, 10], precision_recall_at_k: list[int] = [1, 3, 5, 10], map_at_k: list[int] = [100], show_progress_bar: bool = False, batch_size: int = 32, name: str = '', write_csv: bool = True, truncate_dim: int | None = None, score_functions: dict[str, Callable[[Tensor, Tensor], Tensor]] | None = None, main_score_function: str | SimilarityFunction | None = None, query_prompt: str | None = None, query_prompt_name: str | None = None, corpus_prompt: str | None = None, corpus_prompt_name: str | None = None, write_predictions: bool = False)[source]

此类评估用于信息检索（IR）场景。

给定一组查询和一个大型语料库。它将为每个查询检索最相似的 k 个文档。它衡量平均倒数排名（MRR）、召回率@k 和归一化折扣累计增益（NDCG）。

参数:

queries (Dict[str, str]) – 一个映射查询 ID 到查询的字典。
corpus (Dict[str, str]) – 一个映射文档 ID 到文档的字典。
relevant_docs (Dict[str, Set[str]]) – 一个映射查询 ID 到相关文档 ID 集合的字典。
corpus_chunk_size (int) – 语料库的每个块的大小。默认为 50000。
mrr_at_k (List[int]) – 一个整数列表，表示 MRR 计算的 k 值。默认为 [10]。
ndcg_at_k (List[int]) – 一个整数列表，表示 NDCG 计算的 k 值。默认为 [10]。
accuracy_at_k (List[int]) – 一个整数列表，表示准确率计算的 k 值。默认为 [1, 3, 5, 10]。
precision_recall_at_k (List[int]) – 一个整数列表，表示精确率和召回率计算的 k 值。默认为 [1, 3, 5, 10]。
map_at_k (List[int]) – 一个整数列表，表示 MAP 计算的 k 值。默认为 [100]。
show_progress_bar (bool) – 在评估期间是否显示进度条。默认为 False。
batch_size (int) – 评估的批量大小。默认为 32。
name (str) – 评估的名称。默认为 “”.
write_csv (bool) – 是否将评估结果写入 CSV 文件。默认为 True。
truncate_dim (int, optional) – 截断嵌入的维度。默认为 None。
score_functions (Dict[str, Callable[[Tensor, Tensor], Tensor]]) – 一个映射得分函数名称到得分函数的字典。默认使用 model 的 similarity 函数。
main_score_function (Union[str, SimilarityFunction], optional) – 用于评估的主要得分函数。默认为 None。
query_prompt (str, optional) – 编码语料库时使用的提示。默认为 None。
query_prompt_name (str, optional) – 编码语料库时使用的提示的名称。默认为 None。
corpus_prompt (str, optional) – 编码语料库时使用的提示。默认为 None。
corpus_prompt_name (str, optional) – 编码语料库时使用的提示的名称。默认为 None。
write_predictions (bool) – 是否将预测结果写入 JSONL 文件。默认为 False。这对于下游评估很有用，因为它可以作为 ReciprocalRankFusionEvaluator 的输入，该评估器接受预计算的预测。

示例

import random
from sentence_transformers import SentenceTransformer
from sentence_transformers.evaluation import InformationRetrievalEvaluator
from datasets import load_dataset

# Load a model
model = SentenceTransformer('all-MiniLM-L6-v2')

# Load the Touche-2020 IR dataset (https://hugging-face.cn/datasets/BeIR/webis-touche2020, https://hugging-face.cn/datasets/BeIR/webis-touche2020-qrels)
corpus = load_dataset("BeIR/webis-touche2020", "corpus", split="corpus")
queries = load_dataset("BeIR/webis-touche2020", "queries", split="queries")
relevant_docs_data = load_dataset("BeIR/webis-touche2020-qrels", split="test")

# For this dataset, we want to concatenate the title and texts for the corpus
corpus = corpus.map(lambda x: {'text': x['title'] + " " + x['text']}, remove_columns=['title'])

# Shrink the corpus size heavily to only the relevant documents + 30,000 random documents
required_corpus_ids = set(map(str, relevant_docs_data["corpus-id"]))
required_corpus_ids |= set(random.sample(corpus["_id"], k=30_000))
corpus = corpus.filter(lambda x: x["_id"] in required_corpus_ids)

# Convert the datasets to dictionaries
corpus = dict(zip(corpus["_id"], corpus["text"]))  # Our corpus (cid => document)
queries = dict(zip(queries["_id"], queries["text"]))  # Our queries (qid => question)
relevant_docs = {}  # Query ID to relevant documents (qid => set([relevant_cids])
for qid, corpus_ids in zip(relevant_docs_data["query-id"], relevant_docs_data["corpus-id"]):
    qid = str(qid)
    corpus_ids = str(corpus_ids)
    if qid not in relevant_docs:
        relevant_docs[qid] = set()
    relevant_docs[qid].add(corpus_ids)

# Given queries, a corpus and a mapping with relevant documents, the InformationRetrievalEvaluator computes different IR metrics.
ir_evaluator = InformationRetrievalEvaluator(
    queries=queries,
    corpus=corpus,
    relevant_docs=relevant_docs,
    name="BeIR-touche2020-subset-test",
)
results = ir_evaluator(model)
'''
Information Retrieval Evaluation of the model on the BeIR-touche2020-test dataset:
Queries: 49
Corpus: 31923

Score-Function: cosine
Accuracy@1: 77.55%
Accuracy@3: 93.88%
Accuracy@5: 97.96%
Accuracy@10: 100.00%
Precision@1: 77.55%
Precision@3: 72.11%
Precision@5: 71.43%
Precision@10: 62.65%
Recall@1: 1.72%
Recall@3: 4.78%
Recall@5: 7.90%
Recall@10: 13.86%
MRR@10: 0.8580
NDCG@10: 0.6606
MAP@100: 0.2934
'''
print(ir_evaluator.primary_metric)
# => "BeIR-touche2020-test_cosine_map@100"
print(results[ir_evaluator.primary_metric])
# => 0.29335196224364596

NanoBEIREvaluator

class sentence_transformers.evaluation.NanoBEIREvaluator(dataset_names: list[~typing.Literal['climatefever', 'dbpedia', 'fever', 'fiqa2018', 'hotpotqa', 'msmarco', 'nfcorpus', 'nq', 'quoraretrieval', 'scidocs', 'arguana', 'scifact', 'touche2020'] | str] | None = None, dataset_id: str = 'sentence-transformers/NanoBEIR-en', mrr_at_k: list[int] = [10], ndcg_at_k: list[int] = [10], accuracy_at_k: list[int] = [1, 3, 5, 10], precision_recall_at_k: list[int] = [1, 3, 5, 10], map_at_k: list[int] = [100], show_progress_bar: bool = False, batch_size: int = 32, write_csv: bool = True, truncate_dim: int | None = None, score_functions: dict[str, ~collections.abc.Callable[[~torch.Tensor, ~torch.Tensor], ~torch.Tensor]] | None = None, main_score_function: str | ~sentence_transformers.similarity_functions.SimilarityFunction | None = None, aggregate_fn: ~collections.abc.Callable[[list[float]], float] = <function mean>, aggregate_key: str = 'mean', query_prompts: str | dict[str, str] | None = None, corpus_prompts: str | dict[str, str] | None = None, write_predictions: bool = False)[source]

此类评估 SentenceTransformer 模型在 NanoBEIR 信息检索数据集集合上的性能。

NanoBEIR 集合由多个 BEIR 信息检索数据集的缩小版组成，适合在运行完整的 BEIR 评估之前快速对模型的检索性能进行基准测试。这些数据集在 Hugging Face 的 Sentence Transformers NanoBEIR 集合中可用，该集合将 Zeta Alpha 的原始集合重新格式化为默认的 NanoBEIR-en 数据集，并包含许多翻译版本。此评估器为每个数据集单独报告与 InformationRetrievalEvaluator 相同的指标（例如，MRR、nDCG、Recall@k），并且还报告了所有数据集的聚合指标。

参数:

dataset_names (List[str]) – 要评估的数据集的简短名称（例如，“climatefever”、“msmarco”）。如果未指定，则使用所有预定义的 NanoBEIR 数据集。可用数据集的完整列表是：“climatefever”、“dbpedia”、“fever”、“fiqa2018”、“hotpotqa”、“msmarco”、“nfcorpus”、“nq”、“quoraretrieval”、“scidocs”、“arguana”、“scifact”和“touche2020”。
dataset_id (str) – 加载数据集的 HuggingFace 数据集 ID。默认为“sentence-transformers/NanoBEIR-en”。数据集必须包含每个 NanoBEIR 数据集的“corpus”、“queries”和“qrels”子集，存储在名为 Nano{DatasetName} 的分割中（例如，NanoMSMARCO 或 NanoNFCorpus）。
mrr_at_k (List[int]) – 一个整数列表，表示 MRR 计算的 k 值。默认为 [10]。
ndcg_at_k (List[int]) – 一个整数列表，表示 NDCG 计算的 k 值。默认为 [10]。
accuracy_at_k (List[int]) – 一个整数列表，表示准确率计算的 k 值。默认为 [1, 3, 5, 10]。
precision_recall_at_k (List[int]) – 一个整数列表，表示精确率和召回率计算的 k 值。默认为 [1, 3, 5, 10]。
map_at_k (List[int]) – 一个整数列表，表示 MAP 计算的 k 值。默认为 [100]。
show_progress_bar (bool) – 在评估期间是否显示进度条。默认为 False。
batch_size (int) – 评估的批量大小。默认为 32。
write_csv (bool) – 是否将评估结果写入 CSV 文件。默认为 True。
truncate_dim (int, optional) – 截断嵌入的维度。默认为 None。
score_functions (Dict[str, Callable[[Tensor, Tensor], Tensor]]) – 一个映射得分函数名称到得分函数的字典。默认为 {SimilarityFunction.COSINE.value: cos_sim, SimilarityFunction.DOT_PRODUCT.value: dot_score}。
main_score_function (Union[str, SimilarityFunction], optional) – 用于评估的主要得分函数。默认为 None。
aggregate_fn (Callable[[list[float]], float]) – 用于聚合分数的函数。默认为 np.mean。
aggregate_key (str) – 用于聚合分数的键。默认为 "mean"。
query_prompts (str | dict[str, str], optional) – 添加到查询中的提示。如果是字符串，则将相同的提示添加到所有查询。如果是字典，则期望 dataset_names 中的所有数据集都是键。
corpus_prompts (str | dict[str, str], optional) – 添加到语料库中的提示。如果是字符串，则将相同的提示添加到所有语料库。如果是字典，则期望 dataset_names 中的所有数据集都是键。
write_predictions (bool) – 是否将预测结果写入 JSONL 文件。默认为 False。这对于下游评估很有用，因为它可以作为 ReciprocalRankFusionEvaluator 的输入，该评估器接受预计算的预测。

提示

请参阅 Hugging Face 上的 NanoBEIR 数据集集合，其中包含不同语言的有效 NanoBEIR dataset_id 选项。

示例

from sentence_transformers import SentenceTransformer
from sentence_transformers.evaluation import NanoBEIREvaluator

model = SentenceTransformer('intfloat/multilingual-e5-large-instruct')

datasets = ["QuoraRetrieval", "MSMARCO"]
query_prompts = {
    "QuoraRetrieval": "Instruct: Given a question, retrieve questions that are semantically equivalent to the given question\nQuery: ",
    "MSMARCO": "Instruct: Given a web search query, retrieve relevant passages that answer the query\nQuery: "
}

evaluator = NanoBEIREvaluator(
    dataset_names=datasets,
    query_prompts=query_prompts,
)

results = evaluator(model)
'''
NanoBEIR Evaluation of the model on ['QuoraRetrieval', 'MSMARCO'] dataset:
Evaluating NanoQuoraRetrieval
Information Retrieval Evaluation of the model on the NanoQuoraRetrieval dataset:
Queries: 50
Corpus: 5046

Score-Function: cosine
Accuracy@1: 92.00%
Accuracy@3: 98.00%
Accuracy@5: 100.00%
Accuracy@10: 100.00%
Precision@1: 92.00%
Precision@3: 40.67%
Precision@5: 26.00%
Precision@10: 14.00%
Recall@1: 81.73%
Recall@3: 94.20%
Recall@5: 97.93%
Recall@10: 100.00%
MRR@10: 0.9540
NDCG@10: 0.9597
MAP@100: 0.9395

Evaluating NanoMSMARCO
Information Retrieval Evaluation of the model on the NanoMSMARCO dataset:
Queries: 50
Corpus: 5043

Score-Function: cosine
Accuracy@1: 40.00%
Accuracy@3: 74.00%
Accuracy@5: 78.00%
Accuracy@10: 88.00%
Precision@1: 40.00%
Precision@3: 24.67%
Precision@5: 15.60%
Precision@10: 8.80%
Recall@1: 40.00%
Recall@3: 74.00%
Recall@5: 78.00%
Recall@10: 88.00%
MRR@10: 0.5849
NDCG@10: 0.6572
MAP@100: 0.5892
Average Queries: 50.0
Average Corpus: 5044.5

Aggregated for Score Function: cosine
Accuracy@1: 66.00%
Accuracy@3: 86.00%
Accuracy@5: 89.00%
Accuracy@10: 94.00%
Precision@1: 66.00%
Recall@1: 60.87%
Precision@3: 32.67%
Recall@3: 84.10%
Precision@5: 20.80%
Recall@5: 87.97%
Precision@10: 11.40%
Recall@10: 94.00%
MRR@10: 0.7694
NDCG@10: 0.8085
'''
print(evaluator.primary_metric)
# => "NanoBEIR_mean_cosine_ndcg@10"
print(results[evaluator.primary_metric])
# => 0.8084508771660436

评估自定义/翻译数据集

import logging
from pprint import pprint

from sentence_transformers import SentenceTransformer
from sentence_transformers.evaluation import NanoBEIREvaluator

logging.basicConfig(format="%(asctime)s - %(message)s", datefmt="%Y-%m-%d %H:%M:%S", level=logging.INFO)

model = SentenceTransformer("google/embeddinggemma-300m")
evaluator = NanoBEIREvaluator(
    ["msmarco", "nq"],
    dataset_id="lightonai/NanoBEIR-de",
    batch_size=32,
)
results = evaluator(model)
print(results[evaluator.primary_metric])
pprint({key: value for key, value in results.items() if "ndcg@10" in key})

MSEEvaluator

class sentence_transformers.evaluation.MSEEvaluator(source_sentences: list[str], target_sentences: list[str], teacher_model=None, show_progress_bar: bool = False, batch_size: int = 32, name: str = '', write_csv: bool = True, truncate_dim: int | None = None)[source]

计算计算出的句子嵌入与目标句子嵌入之间的均方误差（乘以 100）。

MSE 计算方式为 ||teacher.encode(source_sentences) - student.encode(target_sentences)||。

对于多语言知识蒸馏（https://hugging-face.cn/papers/2004.09813），source_sentences 是英语，target_sentences 是其他语言，如德语、中文、西班牙语……

参数:

source_sentences (List[str]) – 使用教师模型嵌入的源句子。
target_sentences (List[str]) – 使用学生模型嵌入的目标句子。
teacher_model (SentenceTransformer, optional) – 用于计算源句子嵌入的教师模型。
show_progress_bar (bool, optional) – 计算嵌入时显示进度条。默认为 False。
batch_size (int, optional) – 计算句子嵌入的批量大小。默认为 32。
name (str, optional) – 评估器的名称。默认为 “”.
write_csv (bool, optional) – 将结果写入 CSV 文件。默认为 True。
truncate_dim (int, optional) – 用于截断句子嵌入的维度。如果为 None，则使用模型当前的截断维度。默认为 None。

示例

from sentence_transformers import SentenceTransformer
from sentence_transformers.evaluation import MSEEvaluator
from datasets import load_dataset

# Load a model
student_model = SentenceTransformer('paraphrase-multilingual-mpnet-base-v2')
teacher_model = SentenceTransformer('all-mpnet-base-v2')

# Load any dataset with some texts
dataset = load_dataset("sentence-transformers/stsb", split="validation")
sentences = dataset["sentence1"] + dataset["sentence2"]

# Given queries, a corpus and a mapping with relevant documents, the MSEEvaluator computes different MSE metrics.
mse_evaluator = MSEEvaluator(
    source_sentences=sentences,
    target_sentences=sentences,
    teacher_model=teacher_model,
    name="stsb-dev",
)
results = mse_evaluator(student_model)
'''
MSE evaluation (lower = better) on the stsb-dev dataset:
MSE (*100):  0.805045
'''
print(mse_evaluator.primary_metric)
# => "stsb-dev_negative_mse"
print(results[mse_evaluator.primary_metric])
# => -0.8050452917814255

ParaphraseMiningEvaluator

class sentence_transformers.evaluation.ParaphraseMiningEvaluator(sentences_map: dict[str, str], duplicates_list: list[tuple[str, str]] | None = None, duplicates_dict: dict[str, dict[str, bool]] | None = None, add_transitive_closure: bool = False, query_chunk_size: int = 5000, corpus_chunk_size: int = 100000, max_pairs: int = 500000, top_k: int = 100, show_progress_bar: bool = False, batch_size: int = 16, name: str = '', write_csv: bool = True, truncate_dim: int | None = None)[source]

给定大量句子，此评估器执行释义（重复）挖掘并识别相似度最高的对。它将提取的释义对与一组黄金标签进行比较，并计算 F1 分数。

参数:

sentences_map (Dict[str, str]) – 一个将句子 ID 映射到句子的字典。例如，sentences_map[id] => sentence。
duplicates_list (List[Tuple[str, str]], optional) – 一个包含 ID 对 [(id1, id2), (id1, id5)] 的列表，用于识别 sentences_map 中的重复项/释义。默认为 None。
duplicates_dict (Dict[str, Dict[str, bool]], optional) – 一个默认字典，映射 [id1][id2] 为 True，如果 id1 和 id2 是重复的。必须是对称的，即如果 [id1][id2] => True，则 [id2][id1] => True。默认为 None。
add_transitive_closure (bool, optional) – 如果为 True，则添加传递闭包，即如果 dup[a][b] 和 dup[b][c]，则 dup[a][c]。默认为 False。
query_chunk_size (int, optional) – 为了识别释义，将计算所有句子对之间的余弦相似度。由于这可能需要大量内存，因此我们执行批量计算。query_chunk_size 个句子将与最多 corpus_chunk_size 个句子进行比较。在默认设置下，5000 个句子将被分组并最多与 100k 个其他句子进行比较。默认为 5000。
corpus_chunk_size (int, optional) – 语料库将被分批处理，以减少内存需求。默认为 100000。
max_pairs (int, optional) – 我们最多提取 max_pairs 个潜在的释义候选。默认为 500000。
top_k (int, optional) – 对于每个查询，我们提取 top_k 个最相似的对并将其添加到排序列表中。也就是说，对于一个句子，最多不能找到 top_k 个释义。默认为 100。
show_progress_bar (bool, optional) – 输出进度条。默认为 False。
batch_size (int, optional) – 计算句子嵌入的批量大小。默认为 16。
name (str, optional) – 实验名称。默认为 “”.
write_csv (bool, optional) – 将结果写入 CSV 文件。默认为 True。
truncate_dim (Optional[int], optional) – 用于截断句子嵌入的维度。如果为 None，则使用模型当前的截断维度。默认为 None。

示例

from datasets import load_dataset
from sentence_transformers.SentenceTransformer import SentenceTransformer
from sentence_transformers.evaluation import ParaphraseMiningEvaluator

# Load a model
model = SentenceTransformer('all-mpnet-base-v2')

# Load the Quora Duplicates Mining dataset
questions_dataset = load_dataset("sentence-transformers/quora-duplicates-mining", "questions", split="dev")
duplicates_dataset = load_dataset("sentence-transformers/quora-duplicates-mining", "duplicates", split="dev")

# Create a mapping from qid to question & a list of duplicates (qid1, qid2)
qid_to_questions = dict(zip(questions_dataset["qid"], questions_dataset["question"]))
duplicates = list(zip(duplicates_dataset["qid1"], duplicates_dataset["qid2"]))

# Initialize the paraphrase mining evaluator
paraphrase_mining_evaluator = ParaphraseMiningEvaluator(
    sentences_map=qid_to_questions,
    duplicates_list=duplicates,
    name="quora-duplicates-dev",
)
results = paraphrase_mining_evaluator(model)
'''
Paraphrase Mining Evaluation of the model on the quora-duplicates-dev dataset:
Number of candidate pairs: 250564
Average Precision: 56.51
Optimal threshold: 0.8325
Precision: 52.76
Recall: 59.19
F1: 55.79
'''
print(paraphrase_mining_evaluator.primary_metric)
# => "quora-duplicates-dev_average_precision"
print(results[paraphrase_mining_evaluator.primary_metric])
# => 0.5650940787776353

RerankingEvaluator

class sentence_transformers.evaluation.RerankingEvaluator(samples: list[dict[str, str | list[str]]], at_k: int = 10, name: str = '', write_csv: bool = True, similarity_fct: ~collections.abc.Callable[[~torch.Tensor, ~torch.Tensor], ~torch.Tensor] = <function cos_sim>, batch_size: int = 64, show_progress_bar: bool = False, use_batched_encoding: bool = True, truncate_dim: int | None = None, mrr_at_k: int | None = None)[source]

此类评估 SentenceTransformer 模型在重排任务中的性能。

给定一个查询和一组文档，它计算所有可能文档的得分 [query, doc_i]，并按降序排序。然后，计算 MRR@10、NDCG@10 和 MAP 来衡量排名的质量。

参数:

samples (list) –
一个字典列表，其中每个字典代表一个样本，并具有以下键：
- ’query’：搜索查询。
- ’positive’：相关文档列表。
- ’negative’：不相关文档列表。
at_k (int, 可选) – 对于每个查询，仅考虑前 k 个最相似的文档进行评估。默认为 10。
name (str, optional) – 评估器的名称。默认为 “”.
write_csv (bool, optional) – 将结果写入 CSV 文件。默认为 True。
similarity_fct (Callable[[torch.Tensor, torch.Tensor], torch.Tensor], optional) – 句子嵌入之间的相似度函数。默认是余弦相似度。默认为 cos_sim。
batch_size (int, optional) – 计算句子嵌入的批量大小。默认为 64。
show_progress_bar (bool, optional) – 计算嵌入时显示进度条。默认为 False。
use_batched_encoding (bool, optional) – 是否以批量方式编码查询和文档以提高速度，或者逐个编码以节省内存。默认为 True。
truncate_dim (Optional[int], optional) – 用于截断句子嵌入的维度。如果为 None，则使用模型当前的截断维度。默认为 None。
mrr_at_k (Optional[int], 可选) – 已弃用的参数。请改用 at_k。默认为 None。

示例

from sentence_transformers import SentenceTransformer
from sentence_transformers.evaluation import RerankingEvaluator
from datasets import load_dataset

# Load a model
model = SentenceTransformer("all-MiniLM-L6-v2")

# Load a dataset with queries, positives, and negatives
eval_dataset = load_dataset("microsoft/ms_marco", "v1.1", split="validation")

samples = [
    {
        "query": sample["query"],
        "positive": [text for is_selected, text in zip(sample["passages"]["is_selected"], sample["passages"]["passage_text"]) if is_selected],
        "negative": [text for is_selected, text in zip(sample["passages"]["is_selected"], sample["passages"]["passage_text"]) if not is_selected],
    }
    for sample in eval_dataset
]

# Initialize the evaluator
reranking_evaluator = RerankingEvaluator(
    samples=samples,
    name="ms-marco-dev",
)
results = reranking_evaluator(model)
'''
RerankingEvaluator: Evaluating the model on the ms-marco-dev dataset:
Queries: 9706      Positives: Min 1.0, Mean 1.1, Max 5.0   Negatives: Min 1.0, Mean 7.1, Max 9.0
MAP: 56.07
MRR@10: 56.70
NDCG@10: 67.08
'''
print(reranking_evaluator.primary_metric)
# => ms-marco-dev_ndcg@10
print(results[reranking_evaluator.primary_metric])
# => 0.6708042171399308

SentenceEvaluator

class sentence_transformers.evaluation.SentenceEvaluator[source]

所有评估器的基类。特别是，此类引入了 greater_is_better 和 primary_metric 属性。前者是一个布尔值，指示是否较高的评估分数更好，这在训练参数中将 load_best_model_at_end 设置为 True 时用于选择最佳检查点。

后者是一个字符串，指示评估器的主要指标。当评估器返回指标字典时，必须定义它，并且主指标是指向主指标的键，即用于模型选择和/或日志记录的指标。

扩展此类并实现 __call__ 以用于自定义评估器。

SequentialEvaluator

class sentence_transformers.evaluation.SequentialEvaluator(evaluators: ~collections.abc.Iterable[~sentence_transformers.evaluation.SentenceEvaluator.SentenceEvaluator], main_score_function=<function SequentialEvaluator.<lambda>>)[source]

此评估器允许传递多个子评估器。当模型被评估时，数据会按顺序传递给所有子评估器。

所有分数都传递给“main_score_function”，该函数派生出一个最终分数值。

参数:

evaluators (Iterable[SentenceEvaluator]) – SentenceEvaluator 对象集合。
main_score_function (function, optional) – 一个接受分数列表并返回主要分数的函数。默认为选择列表中的最后一个分数。

示例

evaluator1 = BinaryClassificationEvaluator(...)
evaluator2 = InformationRetrievalEvaluator(...)
evaluator3 = MSEEvaluator(...)
seq_evaluator = SequentialEvaluator([evaluator1, evaluator2, evaluator3])

TranslationEvaluator

class sentence_transformers.evaluation.TranslationEvaluator(source_sentences: list[str], target_sentences: list[str], show_progress_bar: bool = False, batch_size: int = 16, name: str = '', print_wrong_matches: bool = False, write_csv: bool = True, truncate_dim: int | None = None)[source]

给定两种不同语言的句子集，例如（en_1，en_2，en_3...）和（fr_1，fr_2，fr_3...），并假设 fr_i 是 en_i 的翻译。检查 vec(en_i) 是否与 vec(fr_i) 的相似度最高。计算两个方向的准确率。

标签需要指示句子之间的相似度。

参数:

source_sentences (List[str]) – 源语言的句子列表。
target_sentences (List[str]) – 目标语言的句子列表。
show_progress_bar (bool) – 计算嵌入时是否显示进度条。默认为 False。
batch_size (int) – 计算句子嵌入的批量大小。默认为 16。
name (str) – 评估器的名称。默认为空字符串。
print_wrong_matches (bool) – 是否打印错误的匹配项。默认为 False。
write_csv (bool) – 是否将评估结果写入 CSV 文件。默认为 True。
truncate_dim (int, optional) – 截断句子嵌入的维度。如果为 None，则使用模型的当前截断维度。默认为 None。

示例

from sentence_transformers import SentenceTransformer
from sentence_transformers.evaluation import TranslationEvaluator
from datasets import load_dataset

# Load a model
model = SentenceTransformer('paraphrase-multilingual-mpnet-base-v2')

# Load a parallel sentences dataset
dataset = load_dataset("sentence-transformers/parallel-sentences-news-commentary", "en-nl", split="train[:1000]")

# Initialize the TranslationEvaluator using the same texts from two languages
translation_evaluator = TranslationEvaluator(
    source_sentences=dataset["english"],
    target_sentences=dataset["non_english"],
    name="news-commentary-en-nl",
)
results = translation_evaluator(model)
'''
Evaluating translation matching Accuracy of the model on the news-commentary-en-nl dataset:
Accuracy src2trg: 90.80
Accuracy trg2src: 90.40
'''
print(translation_evaluator.primary_metric)
# => "news-commentary-en-nl_mean_accuracy"
print(results[translation_evaluator.primary_metric])
# => 0.906

TripletEvaluator

class sentence_transformers.evaluation.TripletEvaluator(anchors: list[str], positives: list[str], negatives: list[str], main_similarity_function: str | SimilarityFunction | None = None, margin: float | dict[str, float] | None = None, name: str = '', batch_size: int = 16, show_progress_bar: bool = False, write_csv: bool = True, truncate_dim: int | None = None, similarity_fn_names: list[Literal['cosine', 'dot', 'euclidean', 'manhattan']] | None = None, main_distance_function: str | SimilarityFunction | None = 'deprecated')[source]

根据三元组（句子，正例，反例）评估模型。检查 similarity(sentence, positive_example) > similarity(sentence, negative_example) + margin。

参数:

anchors (List[str]) – 用于检查相似度的句子。（例如，查询）
positives (List[str]) – 正例句子列表
negatives (List[str]) – 反例句子列表
main_similarity_function (Union[str, SimilarityFunction], optional) – 要使用的相似度函数。如果未指定，则使用余弦相似度、点积、欧氏距离和曼哈顿距离。默认为 None。
margin (Union[float, Dict[str, float]], optional) – 各种相似度指标的边距。如果提供浮点数，它将用作所有相似度指标的边距。如果提供字典，键应为“cosine”、“dot”、“manhattan”和“euclidean”。值指定负样本比正样本更远离锚点的最小边距。默认为 None。
name (str) – 输出的名称。默认为 “”.
batch_size (int) – 用于计算嵌入的批量大小。默认为 16。
show_progress_bar (bool) – 如果为 True，则显示进度条。默认为 False。
write_csv (bool) – 将结果写入 CSV 文件。默认为 True。
truncate_dim (int, optional) – 用于截断句子嵌入的维度。如果为 None，则使用模型当前的截断维度。默认为 None。
similarity_fn_names (List[str], optional) – 要评估的相似度函数名称列表。如果未指定，则使用 model.similarity_fn_name 进行评估。默认为 None。

示例

from sentence_transformers import SentenceTransformer
from sentence_transformers.evaluation import TripletEvaluator
from datasets import load_dataset

# Load a model
model = SentenceTransformer('all-mpnet-base-v2')

# Load a dataset with (anchor, positive, negative) triplets
dataset = load_dataset("sentence-transformers/all-nli", "triplet", split="dev")

# Initialize the TripletEvaluator using anchors, positives, and negatives
triplet_evaluator = TripletEvaluator(
    anchors=dataset[:1000]["anchor"],
    positives=dataset[:1000]["positive"],
    negatives=dataset[:1000]["negative"],
    name="all_nli_dev",
)
results = triplet_evaluator(model)
'''
TripletEvaluator: Evaluating the model on the all-nli-dev dataset:
Accuracy Cosine Similarity:        95.60%
'''
print(triplet_evaluator.primary_metric)
# => "all_nli_dev_cosine_accuracy"
print(results[triplet_evaluator.primary_metric])
# => 0.956