如何微调任何Embedding模型？适配器微调让通用模型秒变领域专家

本文介绍如何使用LlamaIndex的Adapter适配器技术微调嵌入模型，无需大量GPU资源即可提升特定领域的检索效果。Adapter方法通过在预训练模型上添加轻量级适配器层，仅训练少量参数，显著降低计算需求。文章详细演示了从数据准备（自动生成问答对）、模型微调到效果评估的完整流程，对比了Adapter与全量微调的效果差异。该方法适用于BGE、OpenAI等各类嵌入模型，特别适合垂直领域RAG系

沐雪大神

1049人浏览 · 2025-11-20 12:01:06

沐雪大神 · 2025-11-20 12:01:06 发布

还在为微调嵌入模型需要大量GPU资源而发愁？今天教你用LlamaIndex的Adapter适配器技术，无论是BGE、OpenAI还是其他任何Embedding模型，都能轻松微调，用普通电脑就能让通用模型适配你的专业领域！

引言：为什么需要微调嵌入模型？

在RAG（检索增强生成）系统中，嵌入模型的质量直接决定了检索的准确性。虽然像BGE、OpenAI这样的通用嵌入模型已经很强大，但在特定领域（如医疗、法律、金融）中，它们往往表现不佳。

传统的全量微调需要：

大量GPU显存（通常需要16GB+）
长时间训练（可能需要数天）
存储完整模型副本

而Adapter适配器微调只需要：

普通GPU或CPU即可（显存需求降低90%）
训练时间大幅缩短
只保存几MB的适配器参数

什么是Adapter适配器微调？

Adapter适配器微调是一种参数高效的微调方法。它的核心思想是：在预训练模型上添加一个轻量级的适配器层，只训练这个适配器，而冻结原始模型参数。

原始嵌入 → [冻结的基础模型] → [可训练的Adapter层] → 微调后的嵌入

这样做的好处：

参数少：Adapter层通常只有几MB，而全量微调需要保存整个模型（几百MB到几GB）
训练快：只更新少量参数，训练速度提升10倍以上
效果好：在特定任务上，Adapter微调的效果往往接近全量微调

实战：用LlamaIndex实现Adapter微调

环境准备

首先，我们需要安装必要的依赖：

# pyproject.toml
[project]
dependencies = [
    "datasets>=4.4.1",
    "llama-index-core>=0.14.8",
    "llama-index-embeddings-adapter>=0.4.1",
    "llama-index-embeddings-huggingface>=0.6.1",
    "llama-index-embeddings-openai>=0.5.1",
    "llama-index-embeddings-openai-like>=0.2.2",
    "llama-index-finetuning>=0.4.1",
    "llama-index-llms-openai-like>=0.5.3",
    "llama-index-readers-file>=0.5.4",
    "python-dotenv>=1.2.1",
    "transformers[torch]>=4.57.1",
]

第一步：准备训练数据集

从PDF/Markdown等文档中提取文本，使用大语言模型自动生成问答对作为训练数据。需准备两份语料，一份为训练的语料，一份为验证的语料。为了测试方便，这里我们使用一份语料分别作训练和验证用。下载地址：

https://www.modelscope.cn/datasets/muxueai/ai_ai_yu_llm_study_lib/resolve/master/%E4%B8%AD%E5%8D%8E%E4%BA%BA%E6%B0%91%E5%85%B1%E5%92%8C%E5%9B%BD%E8%AF%81%E5%88%B8%E6%B3%95(2019%E4%BF%AE%E8%AE%A2).pdf

下载好放data目录。

项目的.env配置内容：

OPENAI_API_KEY=sk-xxx
OPENAI_API_BASE=https://api.siliconflow.cn/v1
LLM_MODEL=deepseek-ai/DeepSeek-V3
EMBEDDING_MODEL=Qwen/Qwen3-Embedding-8B

使用LlamaIndex的generate_qa_embedding_pairs函数，它会自动调用大语言模型生成高质量的问答对。

# # 1-gen_train_dataset.py

import json
from llama_index.core import SimpleDirectoryReader
from llama_index.core.node_parser import SentenceSplitter
import os 
from llama_index.finetuning import generate_qa_embedding_pairs 
from llama_index.llms.openai_like import OpenAILike
from dotenv import load_dotenv
load_dotenv()


BASE_DIR = r"D:\Test\embedding_ft\data"
# 训练集和验证集文件路径
TRAIN_FILES = [os.path.join(BASE_DIR, "中华人民共和国证券法(2019修订).pdf")]
VAL_FILES = [os.path.join(BASE_DIR, "中华人民共和国证券法(2019修订).pdf")]
# 训练集和验证集语料库文件路径
TRAIN_CORPUS_FPATH = os.path.join(BASE_DIR, "train_corpus.json")
VAL_CORPUS_FPATH = os.path.join(BASE_DIR, "val_corpus.json")

def load_corpus(files, verbose=False):
    if verbose:
        print(f"Loading files {files}")
    reader = SimpleDirectoryReader(input_files=files)
    docs = reader.load_data()
    if verbose:
        print(f"Loaded {len(docs)} docs")
    parser = SentenceSplitter()
    nodes = parser.get_nodes_from_documents(docs, show_progress=verbose)
    if verbose:
        print(f"Parsed {len(nodes)} nodes")
    return nodes

def mk_dataset():
    train_nodes = load_corpus(TRAIN_FILES, verbose=True)
    val_nodes = load_corpus(VAL_FILES, verbose=True)
    # openai-like兼容大模型
    llm = OpenAILike(
        model=os.getenv("LLM_MODEL"),
        api_base=os.getenv("OPENAI_API_BASE"), 
        api_key=os.getenv("OPENAI_API_KEY"),
        temperature=0.7,
    )
    train_dataset = generate_qa_embedding_pairs(llm=llm, nodes=train_nodes)
    val_dataset = generate_qa_embedding_pairs(llm=llm, nodes=val_nodes)
    train_dataset.save_json(TRAIN_CORPUS_FPATH)
    val_dataset.save_json(VAL_CORPUS_FPATH)

mk_dataset()

关键点：

SimpleDirectoryReader：自动读取PDF文档
SentenceSplitter：将文档切分为合适的文本块
generate_qa_embedding_pairs：使用LLM自动生成问答对，无需人工标注！
data目录下一共生成2个json,分别为微调所使用的训练集和验证集。
可以使用任意平台的大模型,为了生成高质量的数据集，尽量选择能力强的大模型；这里使用硅基平台的。

第二步：开始微调

使用LlamaIndex的EmbeddingAdapterFinetuneEngine，几行代码就能开始微调：

#  6-adapter-online-embedding.py

from llama_index.core.evaluation import EmbeddingQAFinetuneDataset
from llama_index.finetuning import EmbeddingAdapterFinetuneEngine
from llama_index.core.embeddings import resolve_embed_model

import os
from dotenv import load_dotenv

load_dotenv()

BASE_DIR = r"D:\Test\embedding_ft\data"
TRAIN_CORPUS_FPATH = os.path.join(BASE_DIR, "train_corpus.json")
VAL_CORPUS_FPATH = os.path.join(BASE_DIR, "val_corpus.json")

train_dataset = EmbeddingQAFinetuneDataset.from_json(TRAIN_CORPUS_FPATH)
val_dataset = EmbeddingQAFinetuneDataset.from_json(VAL_CORPUS_FPATH)

base_embed_model = resolve_embed_model(
    r"local:D:\Test\embedding_ft\model\BAAI\bge-small-en-v1___5"
)

finetune_engine = EmbeddingAdapterFinetuneEngine(
    train_dataset,
    base_embed_model,
    model_output_path="model_output_test",
    # bias=True,
    epochs=10,
    verbose=True,
    # optimizer_class=torch.optim.SGD,
    # optimizer_params={"lr": 0.01}
)

finetune_engine.finetune()
embed_model = finetune_engine.get_finetuned_model()
print(embed_model)

关键参数说明：

使用bge-small-en-v1.5作为基础模型（你也可以选择其他模型），从魔塔社区或者Hugging face上下载模型文件保存到项目的model目录下。
model_output_path: 适配器模型保存路径（只有几MB）
epochs: 训练轮数，通常4-10轮就足够
bias: 是否在Adapter层使用偏置（可选）
optimizer_class 和 optimizer_params: 自定义优化器（可选）

第三步：评估模型效果

微调完成后，我们需要评估模型在验证集上的表现。通常使用两个指标：

Hit Rate（命中率）：检索到的Top-K结果中是否包含正确答案
MRR（平均倒数排名）：正确答案在检索结果中的平均排名倒数

# 5-eval-mrr.py

from llama_index.embeddings.openai_like import OpenAILikeEmbedding
from llama_index.core.evaluation import EmbeddingQAFinetuneDataset
from eval_utils import evaluate, display_results
from sentence_transformers import SentenceTransformer
from llama_index.core.embeddings import resolve_embed_model
from llama_index.embeddings.adapter import LinearAdapterEmbeddingModel
import os
from dotenv import load_dotenv
load_dotenv()

BASE_DIR = r"D:\Test\embedding_ft\data"
VAL_CORPUS_FPATH = os.path.join(BASE_DIR, "val_corpus.json")

val_dataset = EmbeddingQAFinetuneDataset.from_json(VAL_CORPUS_FPATH)

# 评估在线的Embedding模型
qwen3_embedding = OpenAILikeEmbedding(
    model_name=os.getenv("EMBEDDING_MODEL"),
    api_base=os.getenv("OPENAI_API_BASE"),
    api_key=os.getenv("OPENAI_API_KEY"),
    embed_batch_size=10,
)
qwen3_embedding_val_results = evaluate(val_dataset, qwen3_embedding)

print(display_results(["qwen3_embedding"], [qwen3_embedding_val_results]))

# 评估原始的Embedding模型
orgin_embedding_val_results = evaluate(val_dataset, r"local:D:\Test\embedding_ft\model\BAAI\bge-small-en-v1___5")
print(display_results(["orgin_embedding"], [orgin_embedding_val_results]))


# 评估本地微调过的Embedding模型,路径前要加上local:
ft_embedding_val_results = evaluate(val_dataset, r"local:D:\Test\embedding_ft\exp_finetune")
print(display_results(["ft_embedding"], [ft_embedding_val_results]))


# 评估Adapter微调过的Embedding模型 

base_embed_model = resolve_embed_model(r"local:D:\Test\embedding_ft\model\BAAI\bge-small-en-v1___5")

adapt_embed_model = LinearAdapterEmbeddingModel(base_embed_model, "model_output_test")
apapt_val_results = evaluate(val_dataset, adapt_embed_model)
display_results(["adapt_embedding"], [apapt_val_results])

评估结果示例：

模型类型	Hit Rate	MRR
qwen3模型	0.258427	0.197004
原始bge模型	0.089888	0.04588
Adapter微调	0.123596	0.053558
全量微调	0.235955	0.128839

可以看到，Adapter微调在只训练少量参数的情况下，效果已非常明显！

进阶：使用两层神经网络Adapter

如果单层线性Adapter效果不够好，可以尝试两层神经网络Adapter：

from llama_index.core.embeddings.adapter_utils import TwoLayerNN
from llama_index.finetuning import EmbeddingAdapterFinetuneEngine
from llama_index.embeddings.adapter import AdapterEmbeddingModel

# 创建两层神经网络适配器
adapter_model = TwoLayerNN(
    384,   # 输入维度（BGE-small的输出维度）
    1024,  # 隐藏层维度
    384,   # 输出维度
    bias=True,
    add_residual=True,  # 添加残差连接
)

finetune_engine = EmbeddingAdapterFinetuneEngine(
    train_dataset,
    base_embed_model,
    model_output_path="model_2layer_output",
    model_checkpoint_path="model_2layer_ck",  # 保存检查点
    adapter_model=adapter_model,
    epochs=25,  # 两层网络需要更多轮次
    verbose=True,
)

finetune_engine.finetune()

# 加载微调后的模型
embed_model_2layer = finetune_engine.get_finetuned_model(
    adapter_cls=TwoLayerNN
)

使用微调后的模型

微调完成后，可以像使用普通嵌入模型一样使用它：

from llama_index.embeddings.adapter import LinearAdapterEmbeddingModel
from llama_index.core.embeddings import resolve_embed_model

# 加载基础模型
base_embed_model = resolve_embed_model(
    r"local:D:\Test\embedding_ft\model\BAAI\bge-small-en-v1___5"
)

# 加载适配器
embed_model = LinearAdapterEmbeddingModel(
    base_embed_model, 
    "model_output_test"
)

# 在RAG系统中使用
from llama_index.core import VectorStoreIndex, Document

documents = [Document(text="你的文档内容")]
index = VectorStoreIndex.from_documents(
    documents, 
    embed_model=embed_model
)
query_engine = index.as_query_engine()
response = query_engine.query("你的问题")

最佳实践与技巧

1. 数据准备

数据量：通常1000-10000个问答对就足够
数据质量：确保查询和文档的相关性标注准确
数据平衡：尽量覆盖领域内的各种查询类型

2. 训练参数调优

学习率：默认学习率通常效果不错，如需调整建议在0.0001-0.001之间
训练轮数：单层Adapter通常4-10轮，两层网络需要15-25轮
批次大小：根据显存调整，通常16-32效果较好

3. 模型选择

基础模型：选择与你的领域相近的预训练模型
Adapter类型：先尝试单层线性Adapter，效果不够再试两层网络

4. 效果评估

在验证集上评估，避免过拟合
对比多个模型（原始模型、Adapter微调、全量微调）
关注实际业务指标，而不仅仅是Hit Rate和MRR

5、对闭源模版的微调

该方法同样适用于网上闭源的Embedding模型的微调，比如对openai的text-embedding-ada-002微调，代码如下

from llama_index.finetuning import EmbeddingAdapterFinetuneEngine, generate_qa_embedding_pairs
from llama_index.embeddings.openai import OpenAIEmbedding

# 步骤1：准备数据集
train_dataset = generate_qa_embedding_pairs(train_nodes)
val_dataset = generate_qa_embedding_pairs(val_nodes)

# 步骤2：创建在线 embedding 实例
embed_model = OpenAIEmbedding(model_name="text-embedding-ada-002", api_key="sk-...")

# 步骤3：初始化微调引擎
finetune_engine = EmbeddingAdapterFinetuneEngine(
    train_dataset,
    embed_model,
    model_output_path="adapter_output",
    epochs=4,
    verbose=True,
)

# 步骤4：开始微调
finetune_engine.finetune()

步骤概述：

准备训练数据集（如 EmbeddingQAFinetuneDataset）。
用 resolve_embed_model 或 OpenAIEmbedding/HuggingFaceEmbedding 创建在线 embedding 实例。
初始化 EmbeddingAdapterFinetuneEngine，传入数据集和 embedding 实例，指定输出路径等参数。
调用 finetune() 开始训练，微调的适配器会自动保存。

6、EmbeddingAdapterFinetuneEngine和SentenceTransformersFinetuneEngine对比

EmbeddingAdapterFinetuneEngine 用于在任意黑盒嵌入模型（如 OpenAI、sentence-transformers、本地模型等）输出的向量上微调一个轻量级的适配器（如线性层），不改变原始大模型参数，适合模型不可训练或只想快速适配场景。
SentenceTransformersFinetuneEngine 则直接对 sentence-transformers 兼容的大模型参数进行全量微调，适合你有完整训练权限和资源时使用。两者都能提升检索效果，但微调对象和适用场景不同。