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

还在为微调嵌入模型需要大量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等文档中提取文本，使用大语言模型自动生成问答对作为训练数据。需准备两份语料，一份为训练的语料，一份为验证的语料。为了测试方便，这里我们使用一份语料分别作训练和验证用。下载地址如下，下载好放data目录。

  
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

项目的.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="adapter_model_output",  
    # 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.258 | 0.197 | | 原始bge模型 | 0.089 | 0.04 | | Adapter微调 | 0.123 | 0.063 | | 全量微调 | 0.235 | 0.128 |

可以看到，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()  
  

步骤概述：

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

6、EmbeddingAdapterFinetuneEngine和SentenceTransformersFinetuneEngine对比

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

7、eval_utils.py 代码

from llama_index.core.schema import TextNode``from llama_index.core import Settings``from llama_index.core import VectorStoreIndex``import pandas as pd``from tqdm import tqdm``def evaluate(``dataset,``embed_model,``top_k=5,``verbose=False,``):``corpus = dataset.corpus``queries = dataset.queries``relevant_docs = dataset.relevant_docs``embed_model = embed_model or Settings.embed_model``nodes = [TextNode(id_=id_, text=text) for id_, text in corpus.items()]``index = VectorStoreIndex(``nodes, embed_model=embed_model, show_progress=True``)``retriever = index.as_retriever(similarity_top_k=top_k)``eval_results = []``for query_id, query in tqdm(queries.items()):``retrieved_nodes = retriever.retrieve(query)``retrieved_ids = [node.node.node_id for node in retrieved_nodes]``expected_id = relevant_docs[query_id][0]``rank = None``for idx, id in enumerate(retrieved_ids):``if id == expected_id:``rank = idx + 1``break``is_hit = rank is not None # assume 1 relevant doc``mrr = 0 if rank is None else 1 / rank``eval_result = {``"is_hit": is_hit,``"mrr": mrr,``"retrieved": retrieved_ids,``"expected": expected_id,``"query": query_id,``}``eval_results.append(eval_result)``return eval_results``def display_results(names, results_arr):``"""Display results from evaluate."""``hit_rates = []``mrrs = []``for name, results in zip(names, results_arr):``results_df = pd.DataFrame(results)``hit_rate = results_df["is_hit"].mean()``mrr = results_df["mrr"].mean()``hit_rates.append(hit_rate)``mrrs.append(mrr)``final_df = pd.DataFrame(``{"retrievers": names, "hit_rate": hit_rates, "mrr": mrrs}``)``print(final_df)

总结

Adapter微调是一种参数高效、成本低廉、效果显著 的嵌入模型微调方法。通过本文的实战教程，你可以：

✅ 用普通电脑微调嵌入模型
✅ 在特定领域提升检索效果20%+
✅ 只保存几MB的适配器参数
✅ 快速迭代和实验不同的适配器架构

适用场景：

• • 垂直领域的RAG系统
• • 多语言检索优化
• • 特定文档类型的检索
• • 资源受限的环境

不适合的场景：

• • 需要大幅改变模型架构
• • 训练数据与预训练数据分布差异极大
• • 需要同时微调多个任务

希望这篇文章能帮助你在RAG系统中获得更好的检索效果！如果你在实际应用中遇到问题，欢迎在评论区交流讨论。

---

参考资源：

• • [LlamaIndex官方文档]
• https://developers.llamaindex.ai/python/examples/finetuning/embeddings/finetune\_embedding\_adapter
• • [Adapter微调论文]
• https://arxiv.org/abs/1902.00751
• • [BGE模型仓库]
• https://huggingface.co/BAAI/bge-small-en-v1.5
• 

• LlamaIndex入门指南和RAG原理

• 面向 AI 的编程时代：如何选好你的 IDE

• LlamaIndex 开发智能体 Agents 要点解析

• LlamaIndex 开发多智能体 Agents 入门基础

• LlamaIndex智能体Agents开发-记忆管理

• 让 Agent 说“机器能懂的话”——LlamaIndex 构建 Agent 的结构化输出策略

• 从零开始：手把手教你微调Embedding模型，让检索效果提升10倍！