从PDF解析到Qdrant：构建高质量向量检索的完整实战链路

做RAG项目或者知识库检索的朋友应该都有体会：PDF几乎是所有企业文档的最终形态，但也是检索链路里最让人头疼的起点。一个PDF进来，里面可能混着扫描图片、复杂表格、页眉页脚、多栏排版，甚至还有公式和代码块。把这些内容解析成干净的纯文本本身就不容易，再切成合适的chunk做embedding向量化，然后灌进Qdrant这类向量数据库，最后还要保证检索召回结果够准——每一步都有坑，每一步都在影响最终效果。

我最近正好完整走了一遍“PDF转高质量文本→制作Qdrant数据集→增强embedding检索”的链路，踩了不少坑，也总结了一套相对稳定的流程。这篇博文就把整条链路拆开来讲，从解析选型、清洗切分、embedding模型选择，到Qdrant数据集构建和检索优化，全部覆盖。这套方法论适合正在做RAG知识库、企业文档问答、私有数据检索的朋友参考，哪怕你只是刚接触向量数据库，按着步骤走也能搭出一套能用的方案。

1. 整条链路拆解：从PDF到可用的检索数据集

1.1 数据处理的完整生命周期

很多人以为“PDF转文本”就是调一个库搞定，实际上完整链路比想象中长得多。我的做法是把整条流水线拆成五个阶段：

第一阶段是解析，把PDF文件变成原始的文本、表格、图片素材，这一步的核心是“尽量无损地把内容捞出来”；第二阶段是清洗，去掉页眉页脚、页码、乱码字符、多余空行，把解析产生的噪声清掉；第三阶段是切分，把长文档切成语义相对完整的chunk（文本块），这是决定后续检索粒度是否合理的关键；第四阶段是向量化，用embedding模型把每个chunk变成向量，同时保留原始文本、来源、页码等元信息；第五阶段是入库，把向量和元数据一起写入Qdrant，建好索引，供检索调用。

这五个阶段是串行依赖的，前一阶段的质量直接决定后一阶段的上限。尤其是解析和切分，如果这一步做不好，后面换再好的embedding模型也救不回来。我把这个链路跑通之后，一个很深的感触是：数据洗得越干净，检索效果提升越明显，这个提升幅度往往比换模型还大。

1.2 为什么“高质量文本”是检索效果的上限

要理解“高质量文本”为什么重要，得先明白embedding检索的基本逻辑。Embedding模型做的事情，是把一段文字映射成一个固定维度的向量（常见的有768维、1024维、1536维等），语义相近的文本在向量空间里的距离更近。这个映射的质量取决于两件事：一是模型本身的能力，二是输入文本的质量。

如果输入到模型里的文本是乱七八糟的——比如混入了页眉的公司名称、页脚的页码、PDF解析产生的断行乱序、甚至OCR识别出来的错别字——模型在向量化时就会被这些噪声干扰。本来一段讲“设备故障诊断方法”的内容，因为页眉反复出现“某某集团内部资料”，向量里就可能混入与“某某集团”相关的语义特征，检索时容易被无关信息带偏。更常见的情况是：文本被硬切在了一个不合适的边界，导致一个完整的技术概念被劈成两半，embedding出来的向量既不完整也不稳定，检索时自然召回不准。

所以在我的流程里，一直强调“宁可少收，不可收脏”。保证进入embedding模型的是干净、完整、语义自洽的文本，比多灌几万字但质量参差不齐的样本有效得多。

1.3 技术选型总览：用到的工具与方案

我最终定型的方案组合是这样的：

• PDF解析：PyMuPDF（fitz）作为主力解析库，pdfplumber作为表格提取补充，对于扫描件走PaddleOCR的OCR路线。
• 文本清洗与切分：基于Python实现，清洗规则自己写，切分用固定窗口+重叠+结构化感知的组合。
• Embedding模型：本地部署BAAI/bge-large-zh-v1.5作为主力模型，文本向量维度1024，中文效果稳定；在一些对英文和代码场景比较多的文档上，会交替使用bge-m3。
• 向量数据库：Qdrant，用Docker部署，使用余弦距离，配置HNSW索引。
• 检索增强：在Qdrant召回的基础上增加重排序（Rerank）和元数据过滤；部分场景配合BM25关键词做混合检索。

这套组合选型有几个考虑：一是尽量本地化部署，避免文档内容外发到第三方接口带来的数据安全问题；二是Qdrant本身轻量、性能稳，Python客户端API友好，适合快速搭建；三是BGE系列模型在中文语义任务里表现出色，而且支持长文本（bge-m3支持8192长度），灵活性高。下面我会按处理顺序，把每个环节的具体做法和参数细节讲透。

2. PDF解析：不同来源的PDF要用不同的解法

2.1 文本型PDF：常规解析库的选择

拿到一个PDF，第一个问题是：它的内容是“真实文字”还是“图片”？所谓的文本型PDF，就是文字可以直接选中复制的那种，这类PDF本质上是页面里嵌入了文本对象和字体信息，解析库能直接抽取。对这类PDF，我推荐优先用PyMuPDF（也就是fitz）。

选PyMuPDF的核心原因有几点。第一是速度快，PyMuPDF是C库封装，解析几百页的PDF几乎感觉不到延迟，对比纯Python实现的PyPDF2要快一个数量级；第二是版面信息保留好，它能拿到文本块的坐标位置，这对后续判断标题、正文、页眉页脚很有用；第三是稳定性好，遇到损坏的PDF文件不容易直接崩。

基础用法非常简单：

import fitz def pdf_to_text_with_pymupdf(pdf_path): doc = fitz.open(pdf_path) all_text = [] for page_num in range(len(doc)): page = doc.load_page(page_num) text = page.get_text("text") all_text.append({ "page": page_num + 1, "text": text }) return all_text

这里有个细节值得注意：get_text("text")拿的是纯文本，适合直接入库；但如果你想在切分阶段感知标题层级，可以考虑用get_text("dict")或get_text("blocks")，它们能拿到每个文本块的坐标和字体信息。我在实际项目里会用“blocks模式”解析一遍，拿到每个文本块的bbox坐标，这样后面在做标题识别、段落合并时就有数据支撑。

2.2 表格与复杂版面的处理

纯文本PDF里最麻烦的是表格。表格在文本抽取模式下会变成一行行散落的文本，行列关系完全丢失。比如一个两列三行的表格，直接抽取出来可能是“姓名张三年龄28”这样的一坨，根本没法看。

对表格的处理，我分两种情况。情况一：表格内容是有规律的简单表格，用pdfplumber的extract_table()方法就能拿到结构化行列数据，然后转成Markdown格式保留。情况二：复杂表格，比如合并单元格、跨页表格、嵌套表格，这种情况下pdfplumber也容易出错，我的经验是：如果表格信息重要，把表格区域截图保留，检索时返回原始图片；如果表格不重要，就按文本流方式抽取，不要强行结构化。

pdfplumber提取表格的做法：

import pdfplumber def extract_table_from_pdf(pdf_path, page_num): with pdfplumber.open(pdf_path) as pdf: page = pdf.pages[page_num] tables = page.extract_tables() # 转为markdown格式 md_lines = [] for table in tables: for row in table: cells = [str(cell).replace("\n", " ") if cell else "" for cell in row] md_lines.append("| " + " | ".join(cells) + " |") return "\n".join(md_lines)

在解析结果里，表格转成Markdown格式有个额外的好处：embedding模型对Markdown表格的语义理解通常比纯文本好，因为竖线和表头提供了结构信息，检索时也更容易通过“表头+内容”的组合匹配到用户问题的意图。

2.3 扫描件与图片型PDF：OCR路线

如果PDF翻开来全是图片，文字没法选中，那就是扫描件或者图片型PDF。这种PDF常规解析库毫无办法，必须走OCR（光学字符识别）。

OCR方案我首推PaddleOCR，它在中文识别上的准确率确实能打。完整流程是：先用PyMuPDF把每一页渲染成高分辨率图片，再用PaddleOCR做文字识别，最后按识别结果的行框坐标来组织文本顺序。

import fitz from paddleocr import PaddleOCR ocr = PaddleOCR(use_angle_cls=True, lang="ch", show_log=False) def ocr_pdf_page(pdf_path, page_num, dpi=200): doc = fitz.open(pdf_path) page = doc.load_page(page_num) # 渲染为高清图片 pix = page.get_pixmap(dpi=dpi) img_bytes = pix.tobytes("png") # OCR识别 result = ocr.ocr(img_bytes, cls=True) # 按行框坐标排序，组织文本 lines = [] for line_group in result: for line in line_group: box = line[0] # 坐标 text = line[1][0] # 文本 lines.append((box[0][1], box[0][0], text)) # y坐标, x坐标, 文本 lines.sort() # 按y坐标排序 return "\n".join(line[2] for line in lines)

OCR这一步的坑我后面会专门讲，这里先提一个关键点：渲染DPI不能太低。DPI低于150的时候，小字号文字容易出现识别错误；至少用200的DPI，像图表里的说明文字或者角标，建议直接到300。代价是渲染和识别时间变长，但准确率值得这个成本。

2.4 解析结果的质量验收标准

不管用哪种方式解析，我都会在正式批量处理前做一轮“抽检”。具体做法是：随机抽5-10个不同类型的PDF，把解析出来的文本和原PDF对比，检查下面几个方面：

• 文本顺序是否正确：多栏排版的文档是否出现了跨栏乱序。
• 段落边界是否合理：是否出现大面积断行，或者段落首尾残缺。
• 表格结构是否保留：表格内容是不是被拆得没法看。
• 乱码和特殊字符：是否出现□、�、乱码公式等无意义字符。
• 页眉页脚是否混入：首页页眉或版权声明是否混进了正文。

抽检通过后再进入批量处理。我在初版方案里就是因为没做足够的抽检，结果一批技术文档里混入了大量页脚“第 X 页 共 Y 页”，导致后面检索时频繁出现高度相似但不相关的向量，花了很长时间才排查出来。这个验收环节一定不能省。

3. 文本清洗与切分：决定embedding效果的隐藏变量

3.1 清洗：先把噪声清干净再入库

解析出来的文本只是“半成品”，必须经过清洗才能进入embedding环节。我把清洗规则分为几类：

页眉页脚与页码清理。这类文本的特征是：在每一页的固定区域反复出现，内容高度相似。可以用“跨页重复文本检测”的思路：统计所有页面顶部和底部的文本块，如果多页出现相同或高度相似的字符串，就判定为页眉页脚，直接过滤。别用简单的“删前N行后M行”，因为不同PDF的页边距和页眉高度差别很大，很容易误删正文。

断行合并。PDF解析出来的文本经常在每一行末尾加一个换行符，尤其在对齐排版时。比如：

本技术方案解决了传统方法中 存在的检测精度低、耗时长 的问题。

这显然应该合并成一个段落。我的做法是：对连续的非空行做判断，如果行尾没有句号、问号、感叹号、冒号等结束符，就视为断行，拼接成一个逻辑行；如果遇到空行或标题，则视为段落边界。

特殊字符和乱码清理。PDF里的字体编码问题会产生各种乱码，最常见的是\ufffd（替换字符）、控制字符、以及TAB和连续空格。统一用正则清理掉，同时把全角空格转成半角，把多个空格压缩为一个。

import re def clean_text(text): # 清理控制字符和乱码 text = re.sub(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f\ufffd]", "", text) # 全角空格转半角 text = text.replace(" ", " ") # 连续空格压缩 text = re.sub(r" {2,}", " ", text) # 去除每行首尾空白 lines = [line.strip() for line in text.splitlines()] text = "\n".join(lines) return text

公式与代码块的识别保护。如果文档里有很多公式或代码，清洗时不要粗暴地删掉换行和空格，否则公式语义会崩。我的做法是：在清洗前先用特征（如代码缩进、公式环境标记）把代码块和公式块识别出来，打上标记，清洗时跳过这些区域，等到切分时再作为独立块处理。

3.2 切分：chunk size与overlap的参数选择

清洗完之后就是切分。切分有两条路线，一条是纯固定长度切分，一条是结构化感知切分。我实际用的多是两条路线的组合：先按文档结构切成大段（按标题、章节），再把长段落按长度切小，并带上重叠。

切分的关键参数是两个：chunk size（每个块的目标长度）和overlap（相邻块之间的重叠长度）。

我常用的配置是：chunk_size = 500字左右，overlap = 50-100字。这个参数不是拍脑袋定的，它取决于embedding模型的能力。以bge-large-zh-v1.5为例，它单次能处理的token上限是512，中文场景下一个字约等于1到1.5个token，也就是说500个汉字已经接近模型的一次性输入上限了。如果切得太大，embedding时后面部分的内容会被截断，损失语义；如果切得太小，单个块的语义容纳量不足，检索时容易召回零散的信息碎片。

重叠（overlap）的作用是“保边界”。比如一段文本被切成“块A”和“块B”，如果某个关键信息恰好横跨在边界处，没有重叠的话这个信息会被撕裂；加一段重叠后，两个块都包含部分跨边界内容，语义完整性会好很多。

我一般会针对具体文档类型做小批量参数实验：取同一份文档，分别用300/500/800字的chunk size各跑一遍，然后拿几个典型问题做检索测试，观察召回结果，最终确定参数。这个实验看起来简单，但比凭经验硬调靠谱得多。

3.3 语义切分与结构化切分的组合实践

纯固定长度切的缺点是：它不知道哪里是标题，哪里是段落边界，容易把一个完整章节切碎，或者把不相关的两段话硬拼在一起。

所以我增加了“结构化感知”的环节。在清洗阶段拿到文本块坐标和字体信息的基础上，我会识别标题行：字号明显大于正文、或者字体加粗、或者以“第X章”“第X节”“X.X.X”“摘要”“结语”等模式开头的行，都标记为潜在标题。切分时优先在标题处断开——标题和它下面的正文放在同一个块里，这样每个块都有明确的主题。

对于特别长的段落，再按固定长度切成子块，保证每个子块长度在合理范围。我在实现里用了递归的思路：段落长度小于两倍chunk size时直接成为一个块，大于时按句子边界切成多个块，每块尽量包含完整的句子。

切分完之后，还有个容易被忽略的环节：给每个块补上“上下文标题”作为元信息。比如一个块的内容是“介质温度保持在60°C以下”，如果单独看，检索时很难判断它属于哪个主题。但如果在切分时记录了它所属的章节路径，比如“设备维护手册 > 冷却系统 > 运行参数”，就能把这条层级信息作为元数据存进Qdrant，检索时既能做过滤，也可以拼进embedding文本里提升语义完整度。

3.4 切分质量的验证方法

切分质量好不好，不能光靠肉眼扫。我常用两个量化指标来验证：

语义完整性检查：随机抽取切分后的块，人工判断每个块是否是一个“语义自洽”的单元。所谓语义自洽，就是读起来像一段完整的话，有明确主题，而不是莫名其妙从半句话开始，到半句话结束。

检索召回验证：准备20-30个针对文档内容的问题，用embedding+Qdrant做检索，检查Top5召回结果里是否包含材料对应的关键段落。召回率低于预期，优先排查切分是否过碎或过粗。

我记得有一次做一份设备维修手册，300多个chunk人工检查时发现有大面积的“句首残缺”，排查后定位到是清洗阶段的断行合并规则出了问题：句号后面直接接了换行又被合并，导致下一句的开头被吞掉。这类问题如果不验证，后面检索效果会很难看。

4. Embedding模型选型：增强检索效果的第一抓手

4.1 主流embedding模型横向对比

“增强embedding检索”这句话里，embedding模型是核心引擎。我真正用过、也值得推荐的中文场景模型有下面几个：

我最终主力用的是BGE系列。原因有几点：一是离线可用，不用把内部文档送到外部API，数据安全可控；二是bge-m3支持超长输入，在处理技术文档这种大量长段落场景时非常有用，有些段落不需要切得很碎也能保持语义完整；三是BGE在中文语义相似度任务上的表现经过大量验证，社区资料也丰富，出了问题容易排查。

4.2 离线模型的部署与调用细节

BGE模型的本地部署我用的是sentence-transformers，这是目前最顺手的工具库。基本流程是：通过SentenceTransformer加载模型，对文本列表批量编码。实际操作中我建议加一个GPU推理的配置，因为CPU编码5000个chunk可能要半小时以上，GPU几分钟就跑完了。

from sentence_transformers import SentenceTransformer model = SentenceTransformer("BAAI/bge-large-zh-v1.5", device="cuda") # 编码时增加 normalize_embeddings 归一化 embeddings = model.encode( chunks, batch_size=64, normalize_embeddings=True, show_progress_bar=True )

有几个参数我单独说明。normalize_embeddings=True会把向量归一化为单位向量，这样在计算余弦相似度时，结果只取决于向量方向，与向量长度无关，在实际检索时更方便。batch_size需要根据显存调整，我常用的GPU是单卡16G显存，batch_size=64跑1024维模型完全没问题，显存小就降到32或16。

4.3 Embedding推理时的关键参数

Embedding不是把文本丢给模型就完事了，里面有几个容易忽视的参数：

max_seq_length。sentence-transformers默认会读取模型配置里的最大长度，但有些模型的配置并不准确，实际编码时可能把超长文本硬截断而没有任何warning。建议显式设置：

model.max_seq_length = 512

查询侧与文档侧的指令前缀。BGE模型建议：对“查询”（query）文本，在前面拼接指令“为这个句子生成表示以用于检索相关文章：”；对“文档”（document）文本则不需要加前缀。这个细节在BGE官方文档里有明确说明。查询侧加前缀能显著提升检索效果，文档侧加前缀反而会干扰向量语义。

query = "为这个句子生成表示以用于检索相关文章：" + query

混合精度推理。编码大量文本时，用fp16能省一半显存并加速推理。sentence-transformers里设置model.half()即可，但要注意推理结果与fp32有极细微差异，在可接受范围内。

4.4 LoRA微调Embedding模型的实践方向

如果你做的是某个强垂直领域的数据集，通用embedding模型的效果可能不够。这时候有两个选择：换一个领域更匹配的模型，或者用LoRA微调一个embedding模型。

LoRA微调embedding模型的思路是：用领域内的（问题，答案）对作为训练数据，让模型学会“把某个问题类型的向量拉近到对应答案内容”。在实际操作中，需要把数据构造成对比学习的形式——一组（anchor，positive，negative），其中positive是语义匹配的文本，negative是语义不相关的文本，用对比损失函数训练。

我对LoRA微调的建议是：先别急着微调。微调前至少确认通用模型在200条测试数据上的检索效果基线，找出那些召回错误的具体案例，分析是哪类语义关系没学好。如果分析下来确实是领域术语或特殊表述理解不到位，再准备至少500-1000条高质量的标注数据做微调。数据量不够的情况下，LoRA只会让模型过拟合训练集，泛化更差。

LoRA微调在FlagEmbedding框架里有现成的支持，权重参数通常设置在r=8、alpha=16，训练2-3个epoch。微调完要回到同样一批测试集上做对比，看召回率是否有实质提升。没有提升就回退通用模型，不要为了微调而微调。

5. Qdrant数据集构建：从向量到可检索的库

5.1 Qdrant的启动方式与基础概念

Qdrant是一个用Rust写的向量数据库，性能出色，部署也简单。我最常用的启动方式是Docker：

docker run -p 6333:6333 -p 6334:6334 \ -v $(pwd)/qdrant_storage:/qdrant/storage \ qdrant/qdrant:latest

启动后有两个端口：6333是HTTP/REST端口，用来调API；6334是gRPC端口，Python客户端默认走gRPC，性能更好。

Qdrant的基础概念里，最核心的是Collection（集合）。一个Collection相当于一个“表”，它规定了向量维度、距离计算方式、索引类型等。在实际项目中，我建议按“文档类别+应用场景”来规划Collection，比如product_manual、research_paper、legal_docs分开存放，避免不同类型的内容互相干扰检索结果。

5.2 Collection设计与关键参数配置

创建Collection时，有四个关键参数必须认真设置：

向量维度。这个必须和embedding模型的输出维度严格一致。bge-large-zh-v1.5是1024维，bge-m3也是1024维，text-embedding-3-small是1536维。对不上，写入数据时直接报错。

距离度量方式。Qdrant支持Cosine、Euclid、Dot三种。我之前提到用normalize_embeddings=True做了向量归一化，这时候用Dot和Cosine在数学上是等价的，但Dot在搜索引擎里计算效率更高。为了保险和直观，我通常还是选Cosine，这样返回的score天然就是0到1之间的相似度，调阈值的时候不用换算。

HNSW索引参数。HNSW是Qdrant默认的近似最近邻索引。关键参数是m和ef_construct。m控制每个节点的连接数，值越大召回越准但内存越高；ef_construct控制建索引时的搜索范围，越大索引质量越高。中规中矩的配置是m=16，ef_construct=100，数据量大或精度要求高时调到m=32、ef_construct=200。

量化配置。Qdrant支持Scalar Quantization，可以把向量从fp32压缩到int8，内存能省4倍，精度损失通常在1%-3%以内。对于百万级的向量数据量，这个优化非常明显。唯一要注意的是，量化后检索结果的分数会有偏移，阈值需要重新调。

from qdrant_client import QdrantClient from qdrant_client.models import VectorParams, Distance, HnswConfig client = QdrantClient(host="localhost", port=6333) client.recreate_collection( collection_name="knowledge_base", vectors_config=VectorParams( size=1024, distance=Distance.COSINE, hnsw_config=HnswConfig(m=16, ef_construct=100) ), )

5.3 数据写入：批量插入与Payload组织

Collection建好后就是写入数据。Qdrant支持单条upsert和批量upsert。强烈建议用批量写入，不要一条条insert，批量写入的吞吐量高一个数量级。每批128-256个点比较合适。Qdrant的写入上限由服务端配置的optimizers决定，写太快会触发节流，但批量写入能有效规避这个问题。

写入时每个点（Point）包含三个部分：id（向量点唯一标识）、vector（embedding向量）、payload（元数据）。Payload是Qdrant最灵活的部分，我常用的字段包括：

• doc_id：原始文档唯一标识
• chunk_id：文本块标识
• text：原始文本内容（检索结果展示时会用到）
• title：文档标题
• source：文件路径或来源URL
• page：页码
• section：章节路径，比如“第2章 > 3.1节”
• doc_type：文档类型，比如“手册”“论文”“合同”

from qdrant_client.models import PointStruct payloads = [] for i, chunk in enumerate(chunks): payloads.append({ "doc_id": doc_id, "chunk_id": f"{doc_id}_{i}", "text": chunk, "title": doc_title, "page": page_num, "section": section_path, "doc_type": doc_type }) points = [ PointStruct( id=start_id + i, vector=embeddings[i].tolist(), payload=payload ) for i, payload in enumerate(payloads) ] client.upsert( collection_name="knowledge_base", points=points, batch_size=128 )

5.4 构建“检索质量可观测”的数据集

数据写完只是第一步，真正要做的是一套“可观测”的数据集。我的做法是：为每个Collection维护一个评估问题集，至少包含30-50个针对该文档集的高质量问题，每个问题都标注了期望召回的文档或段落。每次调整切分参数、换embedding模型、改检索策略，都在这个评估集上跑一遍，对比MRR（Mean Reciprocal Rank）或Recall@5，用数字验证改动是否有效，而不是凭感觉判断。

这个评估集看起来麻烦，但实际价值极大。没有它，你根本不知道一个改动究竟是变好了还是变差了。特别是当你尝试换embedding模型或者调chunk size的时候，有了评估集，一次对照实验就能给出明确结论。

6. 检索效果增强：Embedding之外的加分手段

6.1 相似度计算的细节

检索时最基础的操作是：把用户的query向量化，然后在Qdrant里搜最近的N个向量。Qdrant的search接口支持设置limit、score_threshold、filter等参数。

这里有个重要的调参经验：不要只依赖score_threshold来过滤结果。Cosine相似度在没有阈值约束时，返回的结果可能有一半是语义相近但实际无关的。但阈值设高了，又容易漏掉正确答案。我通常的做法是：

1. 先设一个相对低的阈值（比如0.5），保证召回率。
2. 取回Top50结果，进入下一阶段的重排序。
3. 重排序之后用更精确的阈值或直接取TopK作为最终结果。

6.2 元数据过滤：缩小检索范围

元数据过滤是我强烈推荐的一项能力。在Qdrant的search请求里加filter参数，可以按payload字段精确过滤。比如：指定只看某个文档类型、只看某个章节、或限定在某一时间段内。

from qdrant_client.models import Filter, FieldCondition, MatchValue client.search( collection_name="knowledge_base", query_vector=query_vec, limit=50, query_filter=Filter( must=[ FieldCondition(key="doc_type", match=MatchValue(value="manual")), FieldCondition(key="section", match=MatchValue(value="冷却系统")) ] ) )

这个功能在实际场景里非常实用。比如用户问“冷却系统的故障怎么排查”，如果你提前知道了问题所属的领域或产品型号，直接filter到对应手册的对应章节，检索精度会大幅提升。即使不知道，也可以用“过滤类型=manual”这种粗粒度的filter来排除论文和合同里的废话干扰。

6.3 重排序（Rerank）的价值

Qdrant召回Top50之后，下一步是重排序。为什么需要重排序？因为embedding检索是“语义相近”就行，但语义相近不等于“回答了用户问题”。Rerank模型（也叫cross-encoder）做的事情是：把用户query和召回文本拼接在一起，整体输入一个模型，输出一个更精细的相关性分数。

我常用的重排序方案是BAAI/bge-reranker-v2-m3。使用方法：

from sentence_transformers import CrossEncoder reranker = CrossEncoder("BAAI/bge-reranker-v2-m3", device="cuda") pairs = [[query, doc] for doc in retrieved_texts] scores = reranker.predict(pairs)

重排序的价值在于：它把“召回”和“精排”分成了两个阶段。召回阶段用轻量的双塔embedding模型快速筛出候选集，精排阶段用更重的cross-encoder模型对候选集做精细打分。这套“粗排+精排”的思路在搜索引擎里已经验证了很多年，在RAG链路里同样适用。

6.4 混合检索：向量+关键词的组合

最后一个提升效果的手段是混合检索。向量检索擅长理解语义，但关键词匹配在某些场景更可靠——比如检索型号、编号、人名、专有名词时，用户输入的“ABC-12345”这种精确编号，向量检索往往找不准，而关键词检索能一键命中。

最简单有效的混合检索方式是这样：对同一个问题，同时跑向量检索和BM25关键词检索，把两路结果合并，用RRF（Reciprocal Rank Fusion）算法融合排序。RRF的思路很简单：每个文档在结果列表里的排名取倒数，排名越靠前，融合分数越高，两路都命中的文档得分会明显高于单路命中的文档。

我在实际项目中，混合检索的引入让精确编号类问题的命中率提升明显，整体检索效果也更稳定。Qdrant本身不内置BM25，我一般用Elasticsearch或直接在内存里用rank_bm25库，对召回文本数量不大的场景完全够用。

7. 踩坑实录：我在这条链路上遇到的问题

7.1 PDF解析层的坑

坑一：pdfplumber提取空白表格。有的PDF表格是用背景色块+文字组合实现的，pdfplumber的线条检测可能识别不出，导致extract_table()返回空数组。后续处理时就漏掉了一部分内容。排查方法就是：如果一个PDF全是这种格子，解析结果里表格区域大面积为空，就要更换方案改用视觉模型或直接截图处理。

坑二：OCR顺序混乱。PaddleOCR对扫描件的识别顺序偶尔会乱，尤其遇到多栏排版时，左边栏还没读完就跳到右边栏。后来我用“按识别框的y坐标分组、再按x坐标排序”的方式，先按行分簇，簇内再按列排序，才把顺序问题基本解决。

坑三：PyMuPDF的“text”模式丢特殊字符。有些PDF里包含特殊符号或公式，用get_text("text")抽出来直接变成空白或乱码。后来改用get_text("rawdict")把每个字符的Unicode和坐标都拿出来，再做字符级别的清理和组装，情况好很多。

7.2 向量化层的坑

坑四：模型最大长度设置不对导致静默截断。有一版切分参数是chunk_size=800字，完全超过了bge-large-zh-v1.5的512 token上限。结果发现检索效果极差，排查后发现模型编码时把超长文本尾部悄悄截断了。这个坑非常隐蔽，因为sentence-transformers不会报warning。后来不仅在代码里显式设置了model.max_seq_length，还加了一个切分后长度检查的断言，超长直接报警。

坑五：查询侧指令前缀漏加。BGE模型要求query加指令前缀，我在初版代码里忘了这个细节，结果检索效果总感觉差一口气。加上前缀之后，召回质量有明显提升。这个在BGE官方文档里有明确说明，但不踩一次真的容易忽略。

7.3 Qdrant与检索层的坑

坑六：Collection维度写错，数据写不进去。一开始用bge-m3跑了一批数据，向量维度1024；后来切到text-embedding-3时忘了重建集合，维度1536对不上，upsert直接报错。这个问题的教训是：换embedding模型时，一定要重建Collection，或者使用多命名向量。Qdrant支持同时存多个命名向量，如果你有多个模型的需求，可以在一个Collection里给不同模型建独立的向量字段，切换模型时不用动数据。

坑七：batch_size过大触发服务端节流。刚开始写数据图快，batch_size设成1024，结果Qdrant开始报429错误。后来调整到256，并且加了简单的重试逻辑，稳定写入。Qdrant的批量写入不是越大越好，要兼顾服务端优化器的处理能力。

坑八：检索结果大量重复。这是切分阶段埋的雷——overlap过大（比如设了200字）导致相邻chunk内容高度重叠，检索返回的前几名全是同一段文字的不同版本。后来overlap控制在50-100字，配合去重逻辑（按文章ID+起始偏移去重），问题解决。

坑九：score_threshold设太高，检索结果太少。有段时间为了“精确”，把score_threshold设成0.85，结果很多合理问题都返回空结果。后来我彻底理解了score阈值和模型、数据分布高度相关——不同模型产出的分数区间差异很大，bge-large-zh-v1.5的检索分数普遍在0.6-0.85之间，阈值设0.7左右比较合理。更好的做法是先不设阈值，取Top50，靠重排序来收敛。

最后再分享一个实际工作中的体会：这套流程建立起来之后，真正耗时间的不是某个单点技术，而是持续的数据质量迭代。我会在每次检索效果不理想时，回看具体是哪里出了问题——是解析丢了内容，切分切碎了语义，还是模型对领域术语理解不够。这种“从结果倒推链路”的习惯，比盲目调参有效得多。如果你也正在走这条路，建议从最上游的PDF解析开始严格把关，数据质量这块做到位，后面的每一步都会轻松很多。