交叉编码器微调中文笔记

# 前言

基于 LlamaIndex 文档（[https://docs.llamaindex.ai/en/stable/examples/finetuning/cross_encoder_finetuning/cross_encoder_finetuning/）的总结，用于学习和实践交叉编码器（Cross-Encoder）的微调。](https://docs.llamaindex.ai/en/stable/examples/finetuning/cross_encoder_finetuning/cross_encoder_finetuning/%EF%BC%89%E7%9A%84%E6%80%BB%E7%BB%93%EF%BC%8C%E7%94%A8%E4%BA%8E%E5%AD%A6%E4%B9%A0%E5%92%8C%E5%AE%9E%E8%B7%B5%E4%BA%A4%E5%8F%89%E7%BC%96%E7%A0%81%E5%99%A8%EF%BC%88Cross-Encoder%EF%BC%89%E7%9A%84%E5%BE%AE%E8%B0%83%E3%80%82)

## 1. 什么是交叉编码器？

- **交叉编码器**是一种用于信息检索的模型，通过同时处理查询（query）和文档（document）来预测它们的匹配度。
- 与嵌入模型（embeddings）不同，交叉编码器直接输出匹配分数，适合需要高精度的场景，如文档重新排序（reranking）。
- 微调交叉编码器可以提高特定领域或任务的检索性能。

## 2. 微调的目标

- 使用自定义数据集（问题-文档对）对交叉编码器进行微调。
- 提高模型在特定任务上的匹配预测能力。

## 3. 微调流程概述

1. **准备环境**：安装必要的 Python 库（如 LlamaIndex、SentenceTransformers、PyTorch 等）。
2. **准备数据集**：生成或加载问题-文档对数据集，分为正例（相关）和负例（不相关）。
3. **加载预训练模型**：使用 SentenceTransformers 加载预训练的交叉编码器模型（如 `cross-encoder/ms-marco-MiniLM-L-12-v2`）。
4. **微调模型**：使用训练数据对模型进行微调，调整参数以优化匹配预测。
5. **保存模型**：将微调后的模型保存到本地或 HuggingFace Hub。
6. **评估和使用**：测试微调模型的性能，并将其用于文档重新排序任务。

## 4. 数据集要求

- **格式**：数据集包含问题（query）、相关文档（正例）和不相关文档（负例）。
- **生成方式**：
    - 使用 LLM（如 LlamaIndex 的 `generate_qa_embedding_pairs`）生成合成数据集。
    - 或者手动准备真实数据集。
- **示例**：一个训练样本包括：
    - 查询：如“什么是机器学习？”
    - 正例文档：与查询高度相关的文档。
    - 负例文档：与查询不相关的文档。

## 5. 关键依赖

- **Python 库**：
    - `llama-index`：用于数据处理和生成。
    - `sentence-transformers`：用于加载和微调交叉编码器。
    - `torch`：PyTorch 框架，用于模型训练。
    - `transformers`：HuggingFace 的模型和数据集支持。
- **硬件**：推荐使用 GPU 加速训练。

## 6. 微调参数

- **模型**：如 `cross-encoder/ms-marco-MiniLM-L-12-v2`。
- **训练参数**：
    - 批量大小（batch size）：如 32。
    - 学习率（learning rate）：如 2e-5。
    - 训练轮数（epochs）：如 1 或更多。
- **损失函数**：交叉熵损失（CrossEntropyLoss），用于优化匹配分数。

## 7. 保存与使用

- **保存**：微调后的模型可保存到本地路径或上传到 HuggingFace Hub。
- **使用**：加载微调模型，通过 LlamaIndex 的 `SentenceTransformerRerank` 模块进行文档重新排序。

## 8. 注意事项

- **数据质量**：高质量的数据集对微调效果至关重要。
- **计算资源**：微调需要 GPU 支持，CPU 训练可能较慢。
- **评估**：微调后需通过测试集验证模型性能（如准确率、排序效果）。

---

# 交叉编码器微调操作步骤

以下是基于网页内容的详细操作步骤，假设你有 Python 编程基础和基本的机器学习知识。

## 步骤 1：设置环境

1. **安装 Python 和依赖**：
    - 确保 Python 版本为 3.8 或更高。
    - 安装必要的库：
        
        ```bash
        pip install llama-index sentence-transformers torch transformers datasets
        ```
        
2. **检查 GPU（可选）**：
    - 如果有 GPU，安装 PyTorch 的 GPU 版本：
        
        ```bash
        pip install torch --extra-index-url https://download.pytorch.org/whl/cu118
        ```
        
    - 验证 GPU 可用：
        
        ```python
        import torch
        print(torch.cuda.is_available())
        ```

## 步骤 2：准备数据集

1. **生成合成数据集**：
    - 使用 LlamaIndex 的 `generate_qa_embedding_pairs` 生成问题-文档对。
    - 示例代码：
        
        ```python
        from llama_index.finetuning import generate_qa_embedding_pairs
        from llama_index.core import SimpleDirectoryReader
        from llama_index.core.node_parser import SentenceSplitter
        
        # 加载文档
        documents = SimpleDirectoryReader("./data").load_data()
        node_parser = SentenceSplitter(chunk_size=512)
        nodes = node_parser.get_nodes_from_documents(documents)
        
        # 生成数据集
        qa_pairs = generate_qa_embedding_pairs(nodes)
        qa_pairs.save_json("qa_pairs.json")
        ```
        
    - 说明：将你的文档放在 `./data` 文件夹中，运行代码生成 `qa_pairs.json`。
2. **手动准备数据集（可选）**：
    - 准备 JSON 或 CSV 文件，格式如下：
        
        ```json
        [
            {
                "query": "什么是机器学习？",
                "positive": "机器学习是人工智能的一个分支...",
                "negative": "这是一篇无关的文档..."
            },
            ...
        ]
        ```

## 步骤 3：加载预训练模型

1. **加载交叉编码器模型**：
    - 使用 `sentence-transformers` 加载预训练模型。
    - 示例代码：
        
        ```python
        from sentence_transformers import SentenceTransformer
        
        model = SentenceTransformer("cross-encoder/ms-marco-MiniLM-L-12-v2")
        ```

## 步骤 4：准备训练数据

1. **转换数据集格式**：
    - 将 `qa_pairs.json` 转换为 `sentence-transformers` 所需的格式。
    - 示例代码：
        
        ```python
        from sentence_transformers import InputExample
        import json
        
        with open("qa_pairs.json", "r") as f:
            qa_pairs = json.load(f)
        
        train_examples = []
        for pair in qa_pairs:
            train_examples.append(InputExample(
                texts=[pair["query"], pair["positive"]],
                label=1.0
            ))
            train_examples.append(InputExample(
                texts=[pair["query"], pair["negative"]],
                label=0.0
            ))
        ```

## 步骤 5：微调模型

1. **设置训练参数**：
    - 定义批量大小、学习率等。
    - 示例代码：
        
        ```python
        from sentence_transformers import SentenceTransformer, losses
        from torch.utils.data import DataLoader
        
        # 数据加载器
        train_dataloader = DataLoader(train_examples, shuffle=True, batch_size=32)
        
        # 损失函数
        train_loss = losses.ContrastiveLoss(model)
        
        # 微调
        model.fit(
            train_objectives=[(train_dataloader, train_loss)],
            epochs=1,
            warmup_steps=100,
            output_path="./finetuned_model"
        )
        ```
        
    - 说明：微调后的模型将保存到 `./finetuned_model`。

## 步骤 6：保存模型

1. **保存到本地**：
    - 微调后的模型已自动保存到 `output_path`（如 `./finetuned_model`）。
2. **上传到 HuggingFace（可选）**：
    - 示例代码：
        
        ```python
        model.save_to_hub("your_username/finetuned_cross_encoder")
        ```

## 步骤 7：测试和使用

1. **加载微调模型**：
    - 示例代码：
        
        ```python
        from llama_index.core.postprocessor import SentenceTransformerRerank
        
        rerank = SentenceTransformerRerank(
            model="./finetuned_model",
            top_n=3
        )
        ```
        
2. **测试重新排序**：
    - 使用微调模型对文档进行重新排序。
    - 示例代码：
        
        ```python
        from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
        
        documents = SimpleDirectoryReader("./data").load_data()
        index = VectorStoreIndex.from_documents(documents)
        query_engine = index.as_query_engine(
            similarity_top_k=10,
            node_postprocessors=[rerank]
        )
        response = query_engine.query("什么是机器学习？")
        print(response)
        ```

## 步骤 8：评估模型

1. **准备测试集**：
    - 使用与训练集类似的格式，包含查询、正例和负例。
2. **计算指标**：
    - 使用 `sentence-transformers` 的评估工具计算准确率或排序指标（如 MRR）。
    - 示例代码：
        
        ```python
        from sentence_transformers.evaluation import BinaryClassificationEvaluator
        
        test_examples = [
            InputExample(texts=["query", "positive"], label=1.0),
            InputExample(texts=["query", "negative"], label=0.0)
        ]
        evaluator = BinaryClassificationEvaluator.from_input_examples(test_examples)
        model.evaluate(evaluator)
        ```

## 注意事项

- **数据质量**：确保数据集覆盖任务的多样性。
- **训练时间**：根据数据集大小和硬件，微调可能需要几分钟到几小时。
- **超参数调整**：根据需要调整 `batch_size`、`learning_rate` 和 `epochs`。
- **调试**：如果遇到错误，检查数据集格式、模型路径或依赖版本。