用户问:“订单上说钱退了,可卡里还没动静,怎么回事?”资料里写的却是:“订单页面显示已退款,表示平台已经发起操作,不表示银行账户一定实时到账。”两句话说的是同一件事,表达方式却不同。
上一篇《手撕 Naive RAG 文档问答 API》直接用原始问题检索。向量检索能够处理一部分表达差异,但也可能漏掉需要的资料。如果原文没有找到,后面的回答模型就缺少依据。本文从这个环节入手,用 LlamaIndex 实现单查询改写、HyDE 和 Multi-Query,观察送去检索的文字怎样变化,以及最终取回了哪些原文。
1. 查询改写发生在什么位置
先回顾一次基础 RAG 请求。Embedding 模型将问题转换成向量,检索程序找出相近的文档向量,取回对应原文;生成模型再阅读原文,回答用户问题。
Query Transformation,查询变换,是在检索前调整查询的表达或形式。 本文将这些做法统称为查询改写。它改变的是“拿什么去找资料”:可以把口语问题写清楚,可以扩展成一段文字,也可以生成几条不同的问法。LlamaIndex Query Transformations
1 | 基础流程:用户问题 → 编码问题 → 检索原文 → 根据原文回答 |
改写查询由原始问题生成,用来找资料;回答模型接收原始问题和检索到的原文,用来回答用户。 因此,原始问题同时走两条路径:一条经过改写后参与检索,另一条直接交给回答模型,保留用户最初的需求。
例如,将“订单上说钱退了,可卡里还没动静”改写成“订单显示已退款,但银行卡尚未到账”,是为了找到解释退款状态与到账区别的资料。找到资料后,回答模型结合原始问题和这些原文组织回答。改写查询是检索阶段的中间结果,不作为回答的事实依据。
把原始问题和改写查询分别保存,后面就能检查:改写有没有丢掉“还没到账”这个条件?回答有没有回应原始问题?
本篇依次增加下面几种处理方式,后文分别实现:
| 方式 | 送去检索的内容 | 想解决的问题 |
|---|---|---|
| 原始查询,作为基线 | 用户原话 | 先看当前检索已经能找到什么 |
| 单查询改写 | 一句更明确的问题 | 口语、冗余表达让检索重点不清楚 |
| HyDE | 一段模型生成的假设文档 | 短问题与解释型文档的表达差距较大 |
| Multi-Query | 原问题与几条不同问法 | 一种表达可能漏掉相关资料 |
这几种策略都不能补出知识库里不存在的政策。以退款为例,没有支付渠道的处理规则,改写也不能查出某笔款项的真实到账时间。
2. 准备同一套资料,先跑原始查询
获取示例与配置模型
下载完整示例包,解压并进入 query-transformation-example 目录。包内沿用前文的 9 个虚构退款文本块,保存了固定 ID、原文和来源;无需先运行前文的服务。
1 | chunks.jsonl 9 个已分块的退款资料 |
本文使用 Python 3.12,已核对并用于离线验证的依赖是 llama-index-core==0.14.25、llama-index-llms-openai==0.8.2 和 llama-index-embeddings-openai==0.7.0。先创建环境并按完整版本记录安装依赖:
1 | python3.12 -m venv .venv |
Windows PowerShell 用 py -3.12 -m venv .venv 创建环境,执行 .venv\Scripts\Activate.ps1 激活,再安装依赖;环境变量写成 $env:OPENAI_API_KEY="你的 API Key"。
示例默认使用 gpt-4.1-mini 生成改写、假设文档与可选的最终回答,使用 text-embedding-3-small 编码文档和查询。可通过 DEMO_LLM_MODEL、DEMO_EMBED_MODEL 环境变量改为账户支持的模型。这两个模型职责不同:前者生成文字,后者生成用于检索的向量。
为了集中观察查询变化,这里用 LlamaIndex 的内存向量索引。每次启动示例都会重新编码文档、创建索引,需要可用的模型服务与 API Key,也会产生模型调用费用。这里换用了 Embedding 模型,因此重新编码同一批原文,没有混用前文 BGE 模型生成的向量。
下文的改写文字和检索排序如标为“示意”,都不是实际模型输出。
看懂基线的几个对象
后文代码是 query_demo.py 的节选。想逐步操作,可以在示例目录启动 Python 交互环境,先执行这一段:
1 | from pathlib import Path |
build_components() 是示例自己的辅助函数,负责读取资料、配置模型、建立索引。它返回两个对象:llm 用于生成文字,retriever 是检索入口。传入 top_k=3 后,每次检索最多取 3 个文本块。
LlamaIndex 用 Node 表示可检索的文本块。本例将每行资料读成 TextNode,保留原有 ID;检索返回 list[NodeWithScore],也就是“节点和对应分数”的列表。上面的 item.node.text 是原文,item.node.metadata 是来源,item.score 是本次向量检索的相似度分数,不能当成答案正确的概率。
资料已经分好块,因此本例直接调用 VectorStoreIndex(nodes, embed_model=embed_model) 建库,不再次切分。来源字段仍保存在节点里,但不参与本例的向量编码。核心问题是:原始问题的前三条结果里,有没有解释“已退款”和“实际到账”区别的原文?先记录它,再比较改写之后的结果。
3. 先把一句问题改清楚
最简单的改写,是将口语转成更明确的查询。例如,前面的用户原话可以改成下面这样。这是手写示意:
订单显示已退款,但银行卡尚未到账,可能是什么原因,应该如何查询?
“钱退了”变成“订单显示已退款”,“卡里还没动静”变成“银行卡尚未到账”。这句话仍然在问原因与查询办法,没有断言银行处理失败,也没有补出用户未提供的订单号或日期。
在示例中,REWRITE_PROMPT 是交给模型的提示词模板,rewrite_query() 将原始问题填进去,返回一条查询字符串。这里先关注改写的约束:表达可以变化,用户给出的事实和条件要保留。
1 | from llama_index.core import PromptTemplate |
PromptTemplate 保存带占位符的文字,llm.predict() 填入 question 并调用模型,返回 str。strip() 去掉首尾空白;如果模型只返回空白,本例回退到原问题。这个回退只处理空输出,不能识别“语句通顺但意思改错了”的情况。
接着用返回的字符串检索。以下代码沿用第 2 节创建的 question、llm 和 retriever:
1 | from query_demo import rewrite_query |
这里要比较两件事:改写后的文字是否仍表达原来的需求,以及取回的原文是否更有用。比如“商品没有质量问题,退货运费谁承担?”若被改成“质量问题退货运费”,否定条件就丢了。提示词要求保留条件,但开发者仍需抽查输出,不能仅凭模型返回一条字符串就认为改写正确。
4. HyDE:先生成假设文档,再用它找原文
为什么把问题扩成一段文字
单查询改写的输出仍是问题。有时知识库里保存的是较长的解释段落,短问题提供的语义线索较少,这时可以尝试 HyDE(Hypothetical Document Embeddings,假设文档嵌入):先让生成模型写一段可能回答问题的文字,再把这段文字转换成向量,用它检索真实文档。HyDE 原论文
对于本文的退款问题,假设文档可能写成下面这样。这是手写示意,不是退款事实:
订单页面显示退款已处理,但支付账户尚未收到款项,可能涉及平台发起退款与支付渠道实际到账之间的时间差。查询时可以核对退款状态、退款账户以及支付渠道的处理记录。
这段文字出现了“平台发起退款”“支付渠道”“到账”“处理记录”等概念。它可能比原来的口语更接近政策文档的表达。但假设文档也可能猜错,例如编造处理时限,或者把“尚未到账”直接归因于银行故障。
因此,假设文档只参与检索,最终回答的依据来自知识库原文。 下面的流程保留了这个区别:
1 | 原始问题 → 生成模型 → 假设文档 → Embedding → 检索知识库 → 真实原文 |
用 LlamaIndex 明确区分两种文本
LlamaIndex 的 HyDEQueryTransform 实现了“生成假设文档”这一步。本例使用中文提示词,要求保留问题中的条件,避免凭空写出精确金额、日期或处理时限。以下节选仍使用前面的 llm 和 retriever:
1 | from llama_index.core.indices.query.query_transform import HyDEQueryTransform |
这里的 {context_str} 是 HyDE 组件要求的模板占位符,run(question) 会将原始问题填进去。虽然名称带有 context,这里填入的仍是用户问题,尚未检索任何资料。
hyde.run(question) 返回一个 QueryBundle。可以把它理解为装着本次查询信息的对象;这里重点看两个字段:
| 字段 | 本例保存什么 | 用在哪里 |
|---|---|---|
query_str |
原始用户问题 | 保留用户需求,供后续回答使用 |
embedding_strs |
仅包含假设文档的列表 | 供向量检索编码 |
例如,原始问题是“订单上说钱退了……”,打印 bundle.query_str 仍会得到这句话;bundle.embedding_strs[0] 则是模型刚写出的假设文档。retriever.retrieve(bundle) 读取后者来生成查询向量,然后返回知识库中的 NodeWithScore 列表。HyDE 的 QueryBundle 构造
这里设置 include_original=False,使检索输入更容易观察:只有一段假设文档。参考文档中的 include_original=True 则会把原问题也加入待编码的文本列表。在本例这种普通向量检索中,默认会分别编码这些文本,再对向量逐维取均值,用合成的向量检索一次。它不会分别取回两批文档。向量检索的聚合调用
所以,把 include_original 改为 True,是在试另一种查询向量构造方式,效果仍需比较。它也不能保证消除假设文档的偏差。官方 HyDE 示例就展示过:缺少上下文时,模型将一个编程语言名称解释成宗教词汇,进而把检索带向了错误方向。HyDE 失败示例
5. Multi-Query:用几种问法分别检索
同一个问题,多几个检索入口
HyDE 将问题扩成一段假设文档。Multi-Query,多查询检索,则为同一个问题生成几种表达,让每一种表达分别检索,再合并结果。 不同问法可能找到不同的相关文本块。LlamaIndex Simple Fusion Retriever
仍用同一个退款问题,可以得到下面这组查询。这些是手写示意:
1 | 原问题:订单上说钱退了,可卡里还没动静,怎么回事? |
第一种表达贴近订单状态,第二种强调处理流程,第三种强调核对记录。它们都围绕“已显示退款但未到账”,没有扩展到优惠券计算或退货地址等无关问题。
本例保留原始问题,再生成最多 3 条额外查询。每条最多取 3 个文本块,最多得到 4 份结果列表。某些块可能在几份列表中重复出现,合并时需要处理它们。
生成查询,并清理输出
MULTI_QUERY_PROMPT 要求模型每行写一条查询。generate_queries() 返回 list[str],并完成空行过滤、相同文本去重和数量限制。下面是示例中的实现:
1 | MULTI_QUERY_PROMPT = PromptTemplate( |
queries 一开始就保存原问题,因此额外查询为空时仍能执行原始检索。seen 是 Python 的集合,用于判断同一条文字是否已经出现;它只去掉完全相同的字符串,不判断两句不同表达是否语义重复。最多接受 num_extra 条额外查询,也不要求模型必须凑够这个数量。
这段代码假定模型遵守“一行一条、不要编号”的输出约定。如果模型写出解释段落或编号,简单的逐行解析仍可能把它当查询。小例子可以先打印检查;接入应用时,再按输出格式做更严格的解析。
获得查询后,逐条调用同一个 retriever。先只保存各次结果,尚不生成回答:
1 | from query_demo import generate_queries |
此时 result_lists 的类型是 list[list[NodeWithScore]]:外层列表对应不同问法,内层列表保存该问法取回的原文。几条查询可以独立检索,本例为了便于观察按顺序执行。
重复原文只保留一次,怎样决定排序
如果只把列表接在一起,同一条退款政策可能出现四次。但去掉重复块之后,还需要决定哪些块优先保留。
假设把各次检索结果按查询顺序拼接,去重时保留每个 ID 首次出现的位置,再直接取前三条。下面用 A、B、C、D 表示四个不同文本块的 ID,列表顺序表示各次检索的排名。这是手工示意:
1 | 第一种问法:A、B、C |
最终仍是第一种问法找到的 A、B、C。第二种问法新找到的 D 排在后面,被截掉了;C 在第二次检索中排第一,这个排名信息也没有被利用。按 ID 去重只能处理同一个块重复出现,不能综合各次检索的排名来决定哪些块优先保留。
本例用固定的 node_id 识别同一个文本块,再用 RRF(Reciprocal Rank Fusion,倒数排名融合) 汇总它在各份结果中的位置。可以先这样理解:一个块出现在某次检索的前列,就得到一份排名贡献;在多次检索中靠前出现,贡献便累加起来。这个方法不再直接比较不同查询的原始相似度分数。LlamaIndex RRF 示例
本例将每份列表的排名从 1 开始,贡献写成 1 / (60 + rank)。rank 表示当前块排第几位,60 是用于平缓排名差异的常数。为了看清计分,下面另用两份较短的手工结果演示:
| 文本块 | 查询一中的位置 | 查询二中的位置 | 累计贡献 |
|---|---|---|---|
| A:退款处理与到账区别 | 第 1 位 | 第 2 位 | 1/61 + 1/62 ≈ 0.03252 |
| B:退款说明概览 | 第 2 位 | 没出现 | 1/62 ≈ 0.01613 |
| C:支付渠道查询办法 | 没出现 | 第 1 位 | 1/61 ≈ 0.01639 |
按累计值降序排列,结果是 A、C、B。A 在两次检索中都靠前,所以排在前面;这份分数表达排名贡献,不是相似度,也不表示原文有多大概率正确。
前面的表格演示了怎样手工计算 RRF 分数。下面用 fuse_rrf() 实现同样的规则:按各次检索中的排名计分,按 ID 累加同一个块的贡献,再按累计分数排序。函数接收前面保存的 result_lists,可处理多份检索结果,默认返回排名靠前的最多 3 个节点:
1 | from llama_index.core.schema import NodeWithScore |
nodes_by_id 保存原始节点,scores 保存累计贡献。每份列表内的 seen_in_list 防止同一节点在同一次检索里被重复计分;跨列表再次出现则可以累加。sorted(..., key=scores.get, reverse=True) 按各 ID 对应的累计分数降序排列。最后重新创建 NodeWithScore,其中的 score 已经换成 RRF 分数。
完成后,把前面得到的 result_lists 传进去:
1 | from query_demo import fuse_rrf |
这样,多查询会扩大候选资料的范围,最终交给回答模型的仍最多是 3 个块。不过,相关政策如果被几份文档重复转载,它们可能使用不同 ID;按 ID 去重只能合并同一个块,不能自动识别内容相近的不同块。
了解后,再换成框架提供的入口
LlamaIndex 的 QueryFusionRetriever 可以把查询生成、分别检索和结果融合封装起来。下面是另一种实现,沿用前面配置的 llm、retriever,不需要再执行上面的手写循环:
1 | from llama_index.core.retrievers import QueryFusionRetriever |
[retriever] 是只包含一个检索入口的列表,足以完成多查询检索;num_queries=4 包含原始问题,最多另外生成 3 条。底层 retriever 控制每次取多少块,外层 similarity_top_k=3 控制融合后最终返回多少块。use_async=False 让这个普通脚本顺序执行。
两种实现的细节有区别:本文手写版本按稳定 node_id 去重,排名从 1 开始;已核对的框架版本按 node.hash 去重,排名从 0 开始。框架默认的查询解析也不做本文这种字符串去重。因此,示意分数和边界行为不应直接当成框架输出。QueryFusionRetriever 源码
参考资料中还有 Multi-Step,分步查询。它会根据前一步的检索或回答继续生成后续问题;本文的 Multi-Query 则一次生成同一问题的几种问法,各次检索不依赖前一次回答。实现本文目标时,无需加入分步推理流程。
6. 把结果接回回答,仍然回答原始问题
这三种策略完成检索后,都得到 NodeWithScore 列表。因此,回答步骤可以共用一个函数。
answer_question() 接收原始 question、最终的 nodes 和 llm。它把节点中的原文拼成参考资料,再与原始问题一起交给模型。下面是示例中的实现;ANSWER_PROMPT 用于限制回答依据:
1 | from llama_index.core.schema import MetadataMode |
MetadataMode.NONE 表示这里只取节点文本,不自动拼上元数据。来源仍保留在节点中,由程序另外打印。函数的输入里没有改写查询或假设文档,它们不会被拼进回答参考资料。
前面任一种策略完成检索后得到的 nodes,都可以交给同一个回答函数:
1 | from query_demo import answer_question |
回答如果说“通常需要三个工作日”,这个时限应能在检索到的原文中找到。如果只有假设文档写了这个数字,真实原文没有,回答就没有依据。提示词有助于限制回答,输出是否忠于资料仍需要核对。
7. 跑通流程之后,怎样判断改写有没有用
先观察中间结果
示例程序已将前面讲过的步骤连接起来。在示例目录运行以下命令,默认使用同一个退款问题。它们只展示查询和检索结果,便于先检查资料是否找对:
1 | python query_demo.py --strategy baseline |
输出先显示原始问题和策略。rewrite 额外显示改写后的查询,hyde 显示原问题与假设文档,multi 显示实际使用的查询列表。之后,每个最终结果都包含固定 node_id、来源、分数与原文;多查询的分数会明确标为 RRF 融合分数。
需要生成最终回答时,加上 --answer;想观察另一句话或减少额外查询,可传入相应参数:
1 | python query_demo.py --strategy hyde --answer |
第二条命令保留原问题,最多再生成一条查询。先检查“没有质量问题”是否保留下来,再看原文有没有讲个人原因退货的运费约定。
没有 API Key 时,也可以运行离线检查:
1 | python smoke_check.py |
本文已经在固定依赖下跑过这份检查:使用固定的模型返回与模拟 Embedding,调用真实的 LlamaIndex HyDE、向量索引和 Fusion 组件,检查了查询传递、去重限量、RRF 排序以及回答的输入。它验证的是程序连接与数据处理,不代表模拟向量具有语义检索能力,也不能证明哪种策略效果更好。真实模型端到端调用和业务效果未实测。
固定最终资料数量,再比较内容
不要只看改写后的问题是否更像正式语言,也不要把不同策略的分数直接横向比较。本例可以先固定 Embedding 模型、同一批资料、每次检索 3 个块,以及最终返回 3 个块,再核对内容。
对于默认问题,期望找到的证据包括“平台已发起退款不等于账户实时到账”“支付渠道处理时间”“未到账时的查询办法”。这些内容主要在 refund.md 的“退款到账”和 policy.pdf 第 2 页。对于“没有质量问题”的运费问题,则要找到个人原因退货的约定,不能只返回质量问题由商家承担运费的规则。
可以先用几种有代表性的问法,手工记录下面几项:
| 比较项 | 具体检查什么 |
|---|---|
| 改写是否保留需求 | 否定、时间、业务主体等条件有没有变化 |
| 最终原文是否有用 | 前 3 个块能否支持回答,是否遗漏必要规则 |
| 回答是否有依据 | 时限、金额与政策等结论能否对应取回的原文 |
| 额外调用是否值得 | 改写调用和多次检索增加的时间、费用是否换来了有用资料 |
固定最终最多 3 个块,可以避免仅凭“把更多资料塞给回答模型”就认定改写有效。但两种策略找出这 3 个块所做的工作不同。这里的候选块,指检索找到、供最终选择的文本块。以本文的默认配置为例:
| 策略 | 检索次数 | 检索得到的结果条数 | 最终保留 |
|---|---|---|---|
| 原始查询 | 1 次 | 最多 3 条 | 最多 3 个块 |
| Multi-Query | 最多 4 次 | 每次最多 3 条,共最多 12 条 | 融合后最多 3 个块 |
这 12 条结果可能包含重复块,不代表有 12 个不同的块。Multi-Query 从这些候选结果中选出最终的 3 个块,同时增加了生成查询的模型调用,以及各条查询的编码和检索工作。
因此,比较时还要记录检索结果的总条数、按 ID 去重后的候选块数量,以及生成查询、查询编码和检索的调用次数、耗时与费用。这样才能判断:找到的资料是否更有用,以及这些变化花了多少额外开销。
实际测量查询延迟时,将建库与查询分开;本例每次启动会重建内存索引,不能把整个脚本耗时当成单次检索耗时。
根据问题选择策略
单查询改写适合先处理口语、冗余与表述不清。HyDE 可以尝试用于短问题与解释文档差距较大的情况,但不熟悉的专有名词、歧义词可能让假设文档偏离主题。Multi-Query 可以扩大同一问题的检索覆盖,但重复的问法未必带来新资料,跑偏的问法反而会增加噪声;RRF 也可能把反复出现的无关块排到前面。
如果原始问题已经清楚,基线已经找全所需原文,额外生成步骤可能没有收益。如果用户问“它怎么还没到?”,而上下文没有说明“它”是商品还是退款,改写不能可靠恢复缺失的信息,需要先补齐上下文或向用户澄清。
接入原来的问答 API 前,可以先做一个小范围对照:
- 选几个测试问题,例如口语问题“钱退了,卡里怎么还没收到?”,以及带否定条件的问题“商品没有质量问题,退货运费谁承担?”
- 直接用原始问题检索,记录找到的资料和遗漏的必要规则,作为比较基线。
- 一次只试一种策略。例如先试 Multi-Query,与基线比较:有没有找到之前漏掉的到账说明?有没有漏掉原本能找到的个人原因退货规则?之后再单独试 HyDE,便于看清每种策略的作用。
- 固定同一批资料、模型和检索数量,对同一组问题重复比较,观察改善或退步是否多次出现。
这里的“能够复现的变化”,指在相同资料和配置下,多次比较都能观察到类似的改善或退步。模型生成的查询文字可以不同,重点是检索结果是否反复表现出这种变化,避免仅凭一次碰巧找对资料就认定策略有效。结合前面记录的时间和费用,再决定是否将这项策略接入问答 API。