我正在做的这个查询改写器项目，起因其实特别朴素：RAG知识库里明明有答案，但用户换了个口语化的问法，检索就召不回内容了。一开始我试过直接用Prompt调大模型做改写，效果时好时坏，延迟和成本也不可控，后来决定用LoRA微调一个专门的查询改写器，把这件事彻底做成推理时只增加几十毫秒的固定流程。整个过程做下来，踩了不少坑，也把LoRA微调从原理到落地完整过了一遍，这里把完整的思路、数据构造、训练配置和翻车经验一起整理出来。如果你正在做RAG、搜索相关的东西，或者想拿LoRA练手，这篇可以直接照着走。
1. 查询改写器解决什么问题，为什么这事值得自己微调
1.1 一个让我决定自己写改写器的检索翻车现场
事情是这样的，我手上有一套企业内部的文档问答系统，文档已经被切成小块做了向量化，底模检索用的是Embedding模型，粗排精排也调过一轮。用户在页面上问"上个月的报销政策还生效吗"，结果检索回来的Top-5片段里完全没有提到"报销政策"这几个字的相关文档，最后模型只能瞎编。我看了日志才发现，文档库里对应章节的标题叫"财务费用管理办法（修订版）"，正文里反复出现的关键词是"费用核销""票据规范"，而用户口中的"报销"在这份文档里一次都没出现——Embedding模型虽然能理解语义，但面对这种说法差异很大的口语化query，向量距离还是被拉得太远，召回直接崩了。
这就是典型的查询改写（Query Rewriting）要解决的问题：在检索之前，先把用户的原始输入变成一组更适合检索的query，让召回命中率上去，而不是指望检索模型自己去处理各种口语变体。传统做法里有人做同义词词典、做规则改写、做伪相关反馈，但泛化能力都很有限，尤其面对长尾问法基本无能为力。
于是我尝试直接用Prompt让大模型做改写。我在系统Prompt里写"请把用户问题改写成三个适合搜索引擎的查询"，效果确实可用，但问题也很明显：每一次改写都要走一次大模型推理，7B模型的单次响应延迟大概在1到2秒，QPS一上来根本扛不住；而且同一个问题在temperature稍微调高一点之后，改写结果的稳定性很差，有时候三个改写结果里有俩是重复的，有时候JSON格式突然就崩了，还得额外写解析纠错逻辑。
更麻烦的是，通用模型的改写偏向"日常对话理解"，它不理解我后面的检索链路需要什么样的query形式。我要的不是"把话说得更清楚"，而是"让我的Embedding模型更容易命中"，这两者之间差着一个检索系统自己才懂的方言。
1.2 查询改写器的工作边界与三条改写策略
在动手做之前，我先把查询改写器在系统里的边界画清楚了：它接收一条用户输入，输出多条改写后的检索query，然后这些query统一去走向量检索，把召回结果合并去重，再交给后续的RAG流程。它不负责生成答案，不负责排序，只负责把"人说的话"翻译成"检索系统更容易理解的话"。
具体来说，我让改写器只做三件事。第一是语义拆解：把包含多个意图的长query拆成多个语义单一的短query，比如"怎么申请年假和报销"拆成"申请年假流程"和"费用报销流程"两条；第二是同义扩展：把口语词、简称、模糊指代扩展成文档库里更常见的规范表达，比如"报销"扩展出"费用核销""财务报销""费用报销"，"公司电脑"扩展出"办公设备""IT资产"；第三是关键词化：把疑问句、陈述句压缩成关键词组合，方便适配关键词检索和稀疏向量召回，比如"我想知道服务器一直重启是什么原因"改写成"服务器 频繁重启 原因 排查"。
有了这三条明确的改写策略，我才发现这事非常适合训练一个专用模型：改写行为是高度套路化的，不需要通用模型那么强的指令跟随能力，也不需要多深的推理能力，但它需要极其稳定地遵守输出格式、极其了解我的检索词表习惯，这正好是LoRA微调的舒适区——把一个小模型往特定的输出风格和格式上"掰"。通用大模型强在全能，而查询改写器需要的是"钻牛角尖式"的稳定，两者需求完全不一样。
2. LoRA微调原理速通：极小参数量把模型拽向"新技能"
2.1 LoRA到底在改什么：低秩矩阵的直觉解释
微调一个模型，本质上是希望它把概率分布往"符合我要求的方向"移动。全参数微调是所有权重都更新，7B模型光bf16的权重就得占14个GB显存，再加上梯度、优化器状态，单卡根本放不下，就算放得下，训练一次的时间和成本也离谱。LoRA的做法就非常讨巧：它不更新原始权重W，而是在W旁边并联两串小矩阵A和B，让前向计算从原来的h = Wx变成h = Wx + BAx，训练时只更新A和B，原始权重全程冻结。
这里的核心假设是：模型从通用能力到特定任务之间的"偏移量"，其实只需要很小的参数承载。类比一下的话，通用预训练模型已经是一个博学多才的成年人，你不需要重新教他语言和逻辑，只需要在他耳边念一段时间"我们这个领域的习惯用语"；LoRA训练出来的增量参数，相当于一本随身携带的行业短语手册，用的时候翻开就行，成本远低于重新培养一个人。
那为什么用低秩矩阵而不是直接加个全连接层？因为要控制参数量。一个7B模型的权重矩阵动辄几千乘几千维，假设某个权重矩阵是4096×4096，用低秩分解成A(4096×r)和B(r×4096)，当r=16时，参数量从约1677万变成约13万，只有原来的0.8%左右。这个"秩"r就决定了表达能力的大小，r越大能承载的偏移量就越多，但也更容易过拟合。
2.2 rank、alpha、target modules怎么定
该模块里三件套事rank（秩）、alpha（缩放系数）、target modules（要适配的模块）怎么确定。我的经验是先拿rank=16起步，alpha=32，观察训练集loss和验证集loss的gap。如果验证集loss持续走高而训练集loss还在降，就是过拟合信号，把rank往下调；如果两个loss都降不下去，说明表达能力不够，再往上调rank。查询改写这个任务本身模式不复杂，我最终用的rank=8效果最好，rank=64那版反而严重过拟合，改写结果出现了大量复读原文的情况。
alpha的作用是对低秩矩阵的贡献做缩放。PyTorch实现里，实际加到前向计算上的增量是(alpha / r) * BAx，所以alpha通常设为r的2倍。这个比例如果太大，训练初期模型输出就会被扰动得很厉害，容易出现"灾难性遗忘"——模型连正常的言语连贯性都丢了；太小则新技能学不进去。还有一个常见误区是alpha必须比r大，其实不一定，更关键的是alpha/r的比值要稳定，我大部分实验都是用alpha=rank*2这个经验值。
target modules的选择决定了LoRA挂在哪些权重矩阵上。注意力层的q_proj、k_proj、v_proj、o_proj是大多数LoRA实验默认挂的位置，因为注意力矩阵对语义理解影响最大。但查询改写本质是一个"生成风格/输出格式改写"任务，前馈网络（gate_proj、up_proj、down_proj）对输出词表和表达习惯的影响更直接。我对比过只挂attention和全挂的两种配置，全挂时格式稳定性明显更好，JSON解析失败率从7%降到1.5%左右。所以我现在的默认配置是七个模块一起挂，代价是训练参数大约多了一倍，但7B模型整体仍然只训练了0.2%的参数，完全可控。
3. 训练前的三件套：基座模型、数据集与工具链
3.1 基座选型：为什么我选Qwen2.5-7B-Instruct
域内基座模型选择上，我重点看了几个候选：ChatGLM系列、Baichuan系列、Qwen系列、LLaMA系列。由于要做中文查询改写，LLaMA系的中文能力需要额外补，放弃；ChatGLM和Baichuan都能用，但综合对比下来，Qwen2.5系列中文指令跟随能力最稳，尤其是在需要严格按格式输出的时候，翻车概率比同类模型低不少。我这边的显存是单卡24GB，7B模型做LoRA训练刚好宽裕，推理时权重约占14GB显存，加上Activation和缓存还能留出足够的concurrent推理空间。
如果你显存只有16GB，可以考虑Qwen2.5-3B或者Qwen2.5-1.5B，查询改写这个任务本身难度不大，小模型配合好的数据集也能达到不错的水平，但复杂语义拆解能力会明显弱一些。我的建议是：如果你只需要同义扩展和关键词化，3B模型完全够用；如果要处理长query多意图拆解，老老实实上7B，省下来的调试时间比显卡差价值钱得多。
3.2 构造训练数据：从原始query到多路改写
数据集是这次项目里回报率最高的一环，也是最花时间的一环。我总共收集了大概12000条原始query，来自几个渠道：一是线上日志里真实用户的失败query样本，这部分最宝贵，因为全是真实长尾表达；二是从文档库里反向构造，拿每个文档的标题和小标题反推"用户可能会怎么问"，再人工写出对应的检索友好query；三是用通用大模型批量生成改写候选，再做人工抽检和修正。
每条样本的格式是一个输入对应多个输出，输出之间没有顺序强依赖。举个例子：
输入： "合同快到期了要续签，应该找哪个部门？"
输出：
- "合同续签流程"
- "合同到期续签 申请部门"
- "合同续签 需要什么材料"
这里就同时用到了语义拆解（原query里隐含"找谁办"和"怎么办"两层意思）和关键词化（把口语压缩成检索词组合）。
数据质量上踩过的坑是数量焦虑：一开始我总想搞到十万条"看起来很多"的数据，结果发现大部分都是重复或质量很差的，反而让模型学了一堆噪声。后来我把训练轮数减少、把数据清洗提到最高优先级，12000条干净数据的效果远比40000条口水数据好。清洗时主要做三件事：过滤掉和业务域无关的闲聊query；去重时必须按语义去重而不是字符串去重；人工修正一批"改写得没那么好"的样本，因为模型是学分布的，错误样本多了它会把错误当默认行为。
3.3 用LLaMA-Factory组织数据与标记格式
训练框架我选了LLaMA-Factory，主要是看中它对Qwen系和LoRA训练的支持最省心，一条命令就能从数据准备走到模型输出，中间各种SFT阶段的坑大部分都被框架提前处理了。LLaMA-Factory支持的数据格式有alpaca和sharegpt两种，查询改写属于单轮任务，我用alpaca格式就够了。
具体地，在数据文件query_rewrite.json里，每条样本的结构是：
[ { "instruction": "根据用户的原始查询，生成多条适合检索系统使用的改写查询。每条改写查询另起一行，不要编号，不要重复。", "input": "合同快到期了要续签，应该找哪个部门？", "output": "合同续签流程\n合同到期续签 申请部门\n合同续签 需要什么材料" } ]这里有个非常关键的设计：输出格式我故意没有用JSON数组，而是用"每行一条"的纯文本格式。原因后面会详细讲，简单来说就是生成模型在生成JSON时非常容易因为引号、括号、转义符出错，而"换行分隔"这个格式几乎不会错。框架里不需要额外做预处理，只要在dataset_info.json里注册一下数据集名字，就能直接在训练配置里引用了。
4. 跑通一次LoRA微调：配置、命令与训练过程复盘
4.1 LLaMA-Factory环境准备
环境准备阶段，我从零开始部署过一次，也踩了不少坑。首先是依赖版本要配对：LLaMA-Factory当前版本对transformers和torch的版本有要求，直接照着官方README的requirements装大概率没问题，但千万别为了其他项目把transformers升到最新版然后又跑回来，我试过一次因为transformers版本不兼容导致模型加载阶段直接崩掉，排查了半天。
安装命令：
git clone https://github.com/hiyouga/LLaMA-Factory.git cd LLaMA-Factory pip install -e .[torch].[torch]这个extra会把torch、transformers、peft、datasets等核心依赖一起装上。训练前我先用一个很小的数据集（几百条样本）跑一遍，确认整个链路能通，再切到全量数据，这样能快速区分"环境问题"和"模型问题"。
4.2 训练配置详解（进阶版yaml）
我用的是LLaMA-Factory的yaml配置文件方式，比在命令行里传一堆参数要清晰得多。整个配置长这样：
model_name_or_path: Qwen/Qwen2.5-7B-Instruct template: qwen stage: sft finetuning_type: lora dataset: query_rewrite cutoff_len: 2048 preprocessing_num_workers: 16 lora_rank: 8 lora_alpha: 16 lora_dropout: 0.05 lora_target: all output_dir: outputs/qwen25-7b-query-rewrite-lora logging_steps: 10 save_steps: 500 plot_loss: true overwrite_cache: true per_device_train_batch_size: 4 gradient_accumulation_steps: 8 learning_rate: 2.0e-4 num_train_epochs: 3.0 lr_scheduler_type: cosine warmup_ratio: 0.1 bf16: true这里的参数大多数是按经验设置的。lora_rank: 8和lora_alpha: 16对应前面说的2倍关系；lora_target: all是LLaMA-Factory里的快捷写法，表示所有可适配的Linear层都挂LoRA，省得一个一个列模块名；per_device_train_batch_size: 4配合gradient_accumulation_steps: 8，等效batch size是32，这个数值在SFT阶段比较稳，既不会太大导致收敛慢，也不会太小导致梯度噪声爆炸。
有个细节：cutoff_len: 2048对查询改写任务已经完全够用，因为我们样本的输入输出都很短，设太长反而浪费计算。如果样本平均长度只有一两百个token，可以干脆设成512，训练速度能再快一截。learning_rate: 2.0e-4是LoRA微调比较常见的起点，我试过5e-4，模型loss降得很快但验证集效果明显变差，典型的学习率过大。
4.3 训练过程中的观察点
启动训练：
llamafactory-cli train configs/qwen7b_query_rewrite_lora.yaml训练开始后我一般盯三个地方。第一个是loss曲线：SFT的loss通常不会像预训练那么低，因为任务是生成式的，loss数值降到0.8到1.0附近基本就说明模型学到模式了，不用追求loss无限低，那基本意味着开始背训练集了。第二个是trainable params这一行日志：一个7B模型LoRA训练只应该显示一两千万可训练参数，如果这个数字异常大，去检查是不是误开了全参数微调。第三个是定期保存的中间checkpoint。
训练耗时方面，单卡24GB跑7B模型，12000条数据3个epoch，总共大概需要2到3小时。如果这个时间严重超出预期，优先检查batch size和gradient_accumulation_steps是不是配得太大了。
训练完成后，模型不会自动合并到原始权重里，而是保存了一个包含LoRA增量矩阵的adapter目录。我在推理阶段最常用的做法是直接用peft加载adapter做验证，等效果确认没问题了，再合并一次权重，导出成最终推理模型：
llamafactory-cli export \ --model_name_or_path Qwen/Qwen2.5-7B-Instruct \ --adapter_name_or_path outputs/qwen25-7b-query-rewrite-lora \ --template qwen \ --finetuning_type lora \ --export_dir outputs/qwen25-7b-query-rewrite-lora-merged \ --export_size 4 \ --export_legacy_format false合并这一步的实际意义在于：如果不合并，推理时每条请求都要先加载底座模型再动态把LoRA的增量矩阵叠加进去，框架算下来大概会增加20%-30%的推理耗时；合并之后的模型就是普通权重，部署和量化都方便得多。
5. 微调效果评测与六个容易踩的坑
5.1 评测指标与实测效果
训练效果好不好的判断标准，不能只看训练loss降没降，对于查询改写器来说，最终标准是"改写后的query在真实检索链路里能不能带回更多的相关文档"。
我搭了一套评测集，大概1000条query，每个query都人工标注了相关文档ID。离线指标主要看两个：一个是Recall@K，原始query直接检索的Recall@10基线大概是0.61，用微调后的改写器改写再检索，合并去重后Recall@10能到0.75，提升幅度约14个百分点；另一个指标是"有效改写率"，我统计了改写结果里出现"完全没有意义/输出无效/格式崩坏"的比例，训练前用通用Prompt大模型改写时这个比例大概在5%左右，微调后降到0.5%以下。
更有意思的是，我还顺手做了个对比：把同一个query分别丢给"直接用Prompt调用Qwen2.5-7B-Instruct"和"LoRA微调后的Qwen2.5-7B-Instruct"去改写，结果微调模型的输出明显更"懂检索"——它会更主动地输出文档库里出现过的规范术语，而通用模型虽然语义通顺，但经常给出一堆"怎么查报销"这种口语化表达，对检索帮助有限。这说明LoRA微调确实把模型拽向了一个具体的输出域，而不只是换了一层指令模板。
5.2 实战中踩过的坑
最后把这次项目里踩过、也替你们踩过的坑集中列一下，每一个都是花过时间换来的：
第一个坑是输出格式用JSON导致训练崩溃。第一版数据集我让模型输出JSON数组，结果训练时loss死活降不到合理范围，推理时也经常输出不合法JSON。后来把格式改成"每行一条"之后，问题几乎立刻消失。原因在于，模型的语言建模损失是逐token累积的，JSON里那些引号、花括号、逗号占了大量token，却对检索语义毫无贡献，等于让模型在一堆格式噪声里学语义，自然学不好。这个经验对任何做信息抽取、结构化输出微调的人都适用：输出格式越简单越好。
第二个坑是rank开太大导致过拟合。有一版我把rank设成64，训练集loss降到0.3，看起来非常好，但评测下来Recall@K反而比rank=8的版本低了三个多点。检查改写结果发现，模型把训练数据里的文档专有名词背下来了，遇到新query时喜欢把那些词往外吐，属于典型的"应试记忆"。rank=8反而因为表达容量有限，逼着模型去学更抽象的改写规律。
第三个坑是学习率过大导致灾难性遗忘。有一版learning_rate设了5e-4，训练到后面发现模型连"根据用户的原始查询，生成多条改写"这句话里的正常中文输出都开始错乱了，说明原始权重已经被破坏得太严重。LoRA虽然只更新增量矩阵，但过大的学习率会让增量矩阵对整个输出的影响过大，相当于在原模型上盖了一层厚厚的滤镜。
第四个坑是评测指标用错了对象。一开始我用BERTScore和ROUGE之类的文本相似度指标来评改写好坏，结果指标和检索效果相关性很差——有些改写结果文本上跟标准答案很像，但召回的文档反而是错的。后来我才想明白，查询改写器的目标不是"生成得像标注答案"，而是"帮我从文档库里捞回正确的东西"，所以必须用下游检索链路的Recall@K来做核心指标，文本相似度只能做辅助参考。
第五个坑是推理时temperature没调。有段时间我发现线上改写结果忽好忽坏，查了半天发现是推理服务的temperature设成了0.9，生成结果随机性太大。查询改写不是创意写作，temperature设成0.1到0.3就够了，甚至可以直接设为0做贪心解码。我最后统一改成0.2，线上稳定性立刻上来了。
第六个坑是adapter合并后忘掉验证模板。合并模型之后，直接拿普通chat模板去调用，结果发现输出格式完全不对。原因是训练数据里我在instruction里写了"输出不要编号不要重复"，这个约束只在训练分布里存在，如果不把这个约束放到推理的system prompt里，模型在自由生成时容易放飞自我。换句话说，微调模型的输入模板必须和训练时一致，差一点都会导致输出漂移。
整个项目从发现问题到最终上线，大概用了三周时间，其中一半时间在搞数据，四分之一在调参，真正改代码的时间反而不多。做下来最大的感受是：LoRA微调的入门门槛其实比大多数人想象的低，难的从来不是训练本身，而是清楚地定义"你希望模型学会什么行为"以及"用什么指标判断它学会了"——这两件事想清楚了，训练反而是一项水到渠成的工作。
