def search(
        self,
        corpus: dict[str, dict[str, str]],
        queries: dict[str, str],
        top_k: int,
        score_function: str,
        return_sorted: bool = False,
        **kwargs,
    ) -> dict[str, dict[str, float]]:
        # Create embeddings for all queries using model.encode_queries()
        # Runs semantic search against the corpus embeddings
        # Returns a ranked list with the corpus ids
        if score_function not in self.score_functions:
            raise ValueError(
                "score function: {} must be either (cos_sim) for cosine similarity or (dot) for dot product".format(
                    score_function
                )
            )

        logger.info("Encoding Queries...")
        # 提取查询的 ID 列表
        query_ids = list(queries.keys())
        # 初始化结果字典 self.results，为每个查询预留存储空
        self.results = {qid: {} for qid in query_ids}
        # 按照查询 ID 提取查询文本，生成查询列表
        queries = [queries[qid] for qid in queries]

        # 调用模型的 encode_queries 方法将其编码为嵌入表示
        query_embeddings = self.model.encode_queries(
            queries,
            batch_size=self.batch_size,
            show_progress_bar=self.show_progress_bar,
            convert_to_tensor=self.convert_to_tensor,
            **kwargs,
        )

        logger.info("Sorting Corpus by document length (Longest first)...")
        # 按文档长度（标题 + 内容的字符数）对文档排序，优先处理长文档
        corpus_ids = sorted(
            corpus,
            key=lambda k: len(corpus[k].get("title", "") + corpus[k].get("text", "")),
            reverse=True,
        )
        # 按排序结果重新组织文档集合，提取文档的内容
        corpus = [corpus[cid] for cid in corpus_ids]

        logger.info("Encoding Corpus in batches... Warning: This might take a while!")
        logger.info(
            "Scoring Function: {} ({})".format(
                self.score_function_desc[score_function], score_function
            )
        )

        # 将文档分成块（每块大小为 self.corpus_chunk_size），逐块处理以节省内存
        itr = range(0, len(corpus), self.corpus_chunk_size)

        # 初始化一个 小顶堆（heapq）用于每个查询，存储前 k 个相关文档
        result_heaps = {
            qid: [] for qid in query_ids
        }  # Keep only the top-k docs for each query


        for batch_num, corpus_start_idx in enumerate(itr): #遍历每个文档块的起始索引

            logger.info("Encoding Batch {}/{}...".format(batch_num + 1, len(itr)))
            # 确保处理的文档块不会超过文档集合的范围
            corpus_end_idx = min(corpus_start_idx + self.corpus_chunk_size, len(corpus))

            # 如果启用了 save_corpus_embeddings 并缓存了文档块嵌入，则直接加载缓存
            # Encode chunk of corpus
            if (
                self.save_corpus_embeddings
                and "qid" in kwargs
                and len(self.corpus_embeddings[kwargs["qid"]])
            ):
                sub_corpus_embeddings = torch.tensor(
                    self.corpus_embeddings[kwargs["qid"]][batch_num]
                )
            else: # 否则，调用模型的 encode_corpus 方法对当前文档块进行编码
                # Encode chunk of corpus
                sub_corpus_embeddings = self.model.encode_corpus(
                    corpus[corpus_start_idx:corpus_end_idx],
                    batch_size=self.batch_size,
                    show_progress_bar=self.show_progress_bar,
                    convert_to_tensor=self.convert_to_tensor,
                )
                if self.save_corpus_embeddings and "qid" in kwargs:
                    self.corpus_embeddings[kwargs["qid"]].append(sub_corpus_embeddings)

            # Compute similarites using either cosine-similarity or dot product
            # 使用指定的评分函数（"cos_sim" 或 "dot"）计算查询嵌入和文档块嵌入的相似度
            cos_scores = self.score_functions[score_function](
                query_embeddings, sub_corpus_embeddings
            )
            cos_scores[torch.isnan(cos_scores)] = -1

            # Get top-k values
            # 按查询嵌入计算的相似度，找到每个查询的前 top_k 文档
            # 返回分数（cos_scores_top_k_values）
            # 和对应文档的索引（cos_scores_top_k_idx）
            cos_scores_top_k_values, cos_scores_top_k_idx = torch.topk(
                cos_scores,
                min(
                    top_k + 1,
                    len(cos_scores[1]) if len(cos_scores) > 1 else len(cos_scores[-1]),
                ),
                dim=1,
                largest=True,
                sorted=return_sorted,
            )
            cos_scores_top_k_values = cos_scores_top_k_values.cpu().tolist()
            cos_scores_top_k_idx = cos_scores_top_k_idx.cpu().tolist()


            # 更新小顶堆
            for query_itr in range(len(query_embeddings)):
                query_id = query_ids[query_itr]
                for sub_corpus_id, score in zip(
                    cos_scores_top_k_idx[query_itr], cos_scores_top_k_values[query_itr]
                ):
                    corpus_id = corpus_ids[corpus_start_idx + sub_corpus_id]
                    if corpus_id != query_id:
                        if len(result_heaps[query_id]) < top_k:
                            # 如果堆未满，直接插入
                            # Push item on the heap
                            heapq.heappush(result_heaps[query_id], (score, corpus_id))
                        else:
                            # 如果堆已满，插入新的元素并移除最小的元素（保持堆大小为 top_k）。
                            # If item is larger than the smallest in the heap, push it on the heap then pop the smallest element
                            heapq.heappushpop(
                                result_heaps[query_id], (score, corpus_id)
                            )
        # 将每个查询对应堆中的文档和分数整理到 self.results 中
        for qid in result_heaps:
            for score, corpus_id in result_heaps[qid]:
                self.results[qid][corpus_id] = score

        return self.results

def _evaluate_split(
        self, retriever, corpus, queries, relevant_docs, lang=None, **kwargs
    ):
        start_time = time()
        # 调用 retriever 的 search() 方法：
        # 输入文档集合 corpus 和查询集合 queries。
        # 返回每个查询的检索结果，格式为 {query_id: {doc_id: score}}
        results = retriever(corpus, queries)
        end_time = time()
        logger.info(
            "Time taken to retrieve: {:.2f} seconds".format(end_time - start_time)
        )
        # 尝试改成true 查看这个预测结果是什么，
        # if kwargs.get("save_predictions", False):
        if kwargs.get("save_predictions", True):
            output_folder = kwargs.get("output_folder", "predictions_results")
            if not os.path.isdir(output_folder):
                os.makedirs(output_folder)
            top_k = kwargs.get("top_k", None)
            if top_k is not None:
                for qid in list(results.keys()):
                    doc_ids = set(
                        sorted(
                            results[qid], key=lambda x: results[qid][x], reverse=True
                        )[:top_k]
                    )
                    results[qid] = {
                        k: v for k, v in results[qid].items() if k in doc_ids
                    }
            if lang is None:
                qrels_save_path = (
                    f"{output_folder}/{self.metadata_dict['name']}_predictions.json"
                )
            else:
                qrels_save_path = f"{output_folder}/{self.metadata_dict['name']}_{lang}_predictions.json"

            with open(qrels_save_path, "w") as f:
                json.dump(results, f)

        调用 evaluate 方法:

        # 使用标注的相关性数据（relevant_docs）和检索结果（results）计算以下指标：
        # NDCG（归一化折损累计增益）: 衡量排序质量。
        # MAP（平均准确率）: 衡量多个查询的准确率均值。
        # Recall: 衡量相关文档的检索覆盖率。
        # Precision: 衡量检索结果的相关性。
        # 参数:# retriever.k_values: 指定评估时的 k 值列表（如 top-1、top-10 等）。
              # ignore_identical_ids: 是否忽略查询和文档 ID 相同的情况。
        ndcg, _map, recall, precision = retriever.evaluate(
            relevant_docs,
            results,
            retriever.k_values,
            ignore_identical_ids=kwargs.get("ignore_identical_ids", True),
        )
        # evaluate_custom 方法:
        # 使用 relevant_docs 和 results 计算自定义指标。
        # mrr（平均倒数排名）:
        # 衡量第一个相关文档出现在检索结果中的平均排名
        mrr = retriever.evaluate_custom(
            relevant_docs, results, retriever.k_values, "mrr"
        )
        scores = {
            **{f"ndcg_at_{k.split('@')[1]}": v for (k, v) in ndcg.items()},
            **{f"map_at_{k.split('@')[1]}": v for (k, v) in _map.items()},
            **{f"recall_at_{k.split('@')[1]}": v for (k, v) in recall.items()},
            **{f"precision_at_{k.split('@')[1]}": v for (k, v) in precision.items()},
            **{f"mrr_at_{k.split('@')[1]}": v for (k, v) in mrr.items()},
        }
        return scores

scores = evaluator.evaluate(results) 

return mrr(qrels, results, k_values)

# From https://github.com/beir-cellar/beir/blob/f062f038c4bfd19a8ca942a9910b1e0d218759d4/beir/retrieval/custom_metrics.py#L4
def mrr(
    qrels: dict[str, dict[str, int]],
    results: dict[str, dict[str, float]],
    k_values: List[int],
) -> Tuple[Dict[str, float]]:
    """
    计算查询的平均倒数排名（Mean Reciprocal Rank）。
    测量第一个相关文档出现在检索结果中的排名的倒数。
    """
    MRR = {}

    # 为每个 k 值（k_values 中的前 k 个文档）初始化 MRR@k 为 0.0。
    for k in k_values:
        MRR[f"MRR@{k}"] = 0.0

    # 计算 k_values 中的最大值 k_max，后续只需计算 top_k 文档。
    # 初始化 top_hits 用于存储每个查询的 top_k 文档。
    k_max, top_hits = max(k_values), {}
    logging.info("\n")

    # 对每个查询 query_id 的文档得分进行排序，按分数从高到低取前 k_max 个文档。
    for query_id, doc_scores in results.items():
        top_hits[query_id] = sorted(
            doc_scores.items(), key=lambda item: item[1], reverse=True
        )[0:k_max]


    for query_id in top_hits:
        # 提取查询的相关文档 query_relevant_docs
        query_relevant_docs = set(
            [doc_id for doc_id in qrels[query_id] if qrels[query_id][doc_id] > 0]
        )
        # 遍历 k 值，对于每个查询：
        # 如果第一个相关文档出现在第 rank + 1 位，则累加其倒数排名到 MRR@k。
        for k in k_values:
            for rank, hit in enumerate(top_hits[query_id][0:k]):
                if hit[0] in query_relevant_docs:
                    MRR[f"MRR@{k}"] += 1.0 / (rank + 1)
                    break

    # 对每个 k 值，取查询的平均倒数排名
    for k in k_values:
        MRR[f"MRR@{k}"] = round(MRR[f"MRR@{k}"] / len(qrels), 5)
        logging.info("MRR@{}: {:.4f}".format(k, MRR[f"MRR@{k}"]))

    return MRR


def recall_cap(
    qrels: dict[str, dict[str, int]],
    results: dict[str, dict[str, float]],
    k_values: List[int],
) -> Tuple[Dict[str, float]]:
    """
    测量检索系统是否能够检索到所有相关文档，考虑文档数量的限制。
    """
    # 初始化 R_cap@k 为 0.0
    capped_recall = {}

    for k in k_values:
        capped_recall[f"R_cap@{k}"] = 0.0

    # 找到 k_values 中的最大值 k_max
    k_max = max(k_values)
    logging.info("\n")

   
    for query_id, doc_scores in results.items():
        #  # 对每个查询，取前 k_max 个文档
        top_hits = sorted(doc_scores.items(), key=lambda item: item[1], reverse=True)[
            0:k_max
        ]
        # 提取查询的所有相关文档
        query_relevant_docs = [
            doc_id for doc_id in qrels[query_id] if qrels[query_id][doc_id] > 0
        ]
        # 计算前 k 个文档中检索到的相关文档数，并归一化为 1
        for k in k_values:
            retrieved_docs = [
                row[0] for row in top_hits[0:k] if qrels[query_id].get(row[0], 0) > 0
            ]
            denominator = min(len(query_relevant_docs), k)
            capped_recall[f"R_cap@{k}"] += len(retrieved_docs) / denominator

    for k in k_values:
        capped_recall[f"R_cap@{k}"] = round(capped_recall[f"R_cap@{k}"] / len(qrels), 5)
        logging.info("R_cap@{}: {:.4f}".format(k, capped_recall[f"R_cap@{k}"]))

    # 对所有查询取平均，得到最终的 R_cap@k
    return capped_recall


def hole(
    qrels: dict[str, dict[str, int]],
    results: dict[str, dict[str, float]],
    k_values: List[int],
) -> Tuple[Dict[str, float]]:
    """
    测量检索结果中未被标注的文档数量占比
    """
    Hole = {}

    for k in k_values:
        Hole[f"Hole@{k}"] = 0.0

    annotated_corpus = set()
    for _, docs in qrels.items():
        for doc_id, score in docs.items():
            annotated_corpus.add(doc_id)

    k_max = max(k_values)
    logging.info("\n")

    for _, scores in results.items():
        top_hits = sorted(scores.items(), key=lambda item: item[1], reverse=True)[
            0:k_max
        ]
        for k in k_values:
            hole_docs = [
                row[0] for row in top_hits[0:k] if row[0] not in annotated_corpus
            ]
            Hole[f"Hole@{k}"] += len(hole_docs) / k

    for k in k_values:
        Hole[f"Hole@{k}"] = round(Hole[f"Hole@{k}"] / len(qrels), 5)
        logging.info("Hole@{}: {:.4f}".format(k, Hole[f"Hole@{k}"]))

    return Hole


def top_k_accuracy(
    qrels: dict[str, dict[str, int]],
    results: dict[str, dict[str, float]],
    k_values: List[int],
) -> Tuple[Dict[str, float]]:
    """
    测量前 k 个文档中是否包含相关文档
    """
    # 始化 Accuracy@k 为 0.0
    top_k_acc = {}

    # 找到 k_max，初始化 top_hits
    for k in k_values:
        top_k_acc[f"Accuracy@{k}"] = 0.0

    k_max, top_hits = max(k_values), {}
    logging.info("\n")

    #  对每个查询，按得分排序，提取前 k_max 个文档
    for query_id, doc_scores in results.items():
        top_hits[query_id] = [
            item[0]
            for item in sorted(
                doc_scores.items(), key=lambda item: item[1], reverse=True
            )[0:k_max]
        ]

    for query_id in top_hits:
        # 提取查询的相关文档
        query_relevant_docs = set(
            [doc_id for doc_id in qrels[query_id] if qrels[query_id][doc_id] > 0]
        )
        # 检查前 k 个文档是否包含相关文档
        for k in k_values:
            for relevant_doc_id in query_relevant_docs:
                if relevant_doc_id in top_hits[query_id][0:k]:
                    top_k_acc[f"Accuracy@{k}"] += 1.0
                    break
    # 对所有查询取平均，得到 Accuracy@k
    for k in k_values:
        top_k_acc[f"Accuracy@{k}"] = round(top_k_acc[f"Accuracy@{k}"] / len(qrels), 5)
        logging.info("Accuracy@{}: {:.4f}".format(k, top_k_acc[f"Accuracy@{k}"]))

    return top_k_acc