2024 年我们公司做一个法律文档智能检索 把 10 万份合同 案例 法规切成 chunk 灌进向量库 让律师用自然语言查询。原型阶段用 OpenAI 的 text-embedding-3-small 加 Pinecone 一切顺利 律师反馈也不错。但真正上线半年我们陆续踩了一堆坑。第一种最让我傻眼 我们一开始切 chunk 用 1000 字符固定长度切 结果一份合同的某个关键条款被切成两半 检索时永远找不到完整条款 律师投诉"系统说没有这条 但我明明记得合同里有"。第二种最难缠 同样的查询在不同月份 召回结果不同 排查发现是 Embedding 模型版本变了 OpenAI 静默升级了 text-embedding-3-small 的 weights 我们之前存的向量是旧版的 新查询是新版的 余弦相似度直接漂移。第三种最离谱 月度账单一个月 8000 美元 Pinecone 占 5000 OpenAI embedding 占 3000 业务侧才赚 1.5 万 净利润被吃掉一半。第四种最致命 律师查"上海地区限购政策" 召回了一堆"北京限购""深圳限购"的内容 全凭语义相似度 没考虑实体 keyword 全文检索 召回质量差。第五种最莫名其妙 中文长 query 比如"租赁合同中关于押金退还的特殊约定条款" 召回质量明显差于短 query 排查发现 embedding 模型对长文本的语义编码能力本身就有限 query 越长信息越分散。我盯着这一连串问题想了很久才彻底想明白第一版错在一个根本的认知上我以为向量检索就是 把文档切片 灌进向量库 查询用 cosine 找最近邻 OK 可这个认知是错的真正能扛业务的向量检索是一个 chunk 策略 加 模型选型与版本锁定 加 混合检索向量+keyword 加 reranking 加 metadata 过滤 加 索引参数调优 加 评测体系 的整套工程方法论 任何一环没做都可能让检索质量差到律师弃用本文从头梳理 Embedding 与向量检索的工程化要点 chunk 怎么切 模型怎么选 混合检索怎么做 rerank 怎么用 索引参数怎么调 评测怎么搭 以及一些把向量检索做扎实要避开的工程坑
问题背景:为什么向量检索不是 embed + cosine 就完事
很多人对向量检索的认知是 找个 embedding 模型 把文档变成向量 存进 Pinecone Milvus 查询时算 cosine 取 top-k 就完事 但生产里你会发现 召回不准 排序错乱 长 query 效果差 成本失控 这些问题用纯向量检索几乎无解。问题的根源在于:
- chunk 是质量上限:切坏一份文档 后面再好的模型再好的索引也救不回来 chunk 策略是向量检索的根。
- 纯向量检索盲点多:精确的人名 公司名 法条号 这些 keyword 用向量召回不准 必须配 BM25 全文检索做混合。
- 语义相似不等于业务相关:"上海限购"与"北京限购"语义高度相似但业务上完全不同 必须用 metadata 过滤或 reranker 修正。
- 模型升级会漂移:embedding 模型升级后向量空间变了 老向量与新查询不在同一空间 召回会突然变差。
- top-k 越大不一定越好:k=100 召回多但噪声多 LLM context 也撑爆 必须 rerank 把真正相关的提到前面。
- 评测必须量化:没有 NDCG MRR 这些指标 优化全靠拍脑袋 一个改动是变好还是变坏说不清。
一 Chunk 策略:语义边界与重叠
chunk 是把长文档切成小块 每块 embed 成一个向量。固定长度切是最差的 因为会切断语义边界 一个句子或者一个条款被切成两半 召回时永远拿不到完整信息。生产推荐 按语义边界切 加 chunk overlap 加 metadata 保留。
from langchain.text_splitter import RecursiveCharacterTextSplitter
import tiktoken
# 按字符的递归分割 优先按段落 句子 换行切 避免切断语义
splitter = RecursiveCharacterTextSplitter(
chunk_size=800, # 每块约 800 字符 中文约 400 字
chunk_overlap=150, # 相邻 chunk 重叠 150 字符 防边界信息丢
separators=[
'\n\n', # 优先按段落切
'\n', # 其次按行切
'。', '!', '?', # 中文句号
'.', '!', '?', # 英文句号
';', ';', # 分号
' ', # 空格
'',
],
length_function=len,
)
def chunk_document(doc: dict) -> list:
"""doc = {'id', 'title', 'content', 'metadata'}"""
chunks = splitter.split_text(doc['content'])
result = []
for i, text in enumerate(chunks):
result.append({
'id': f"{doc['id']}__chunk_{i}",
'doc_id': doc['id'],
'chunk_index': i,
'text': text,
'metadata': {
**doc['metadata'],
'title': doc['title'],
'chunk_count': len(chunks),
# 关键 把 chunk 前后文也存进 metadata 用于检索后扩展上下文
'prev_chunk': chunks[i-1][-200:] if i > 0 else None,
'next_chunk': chunks[i+1][:200] if i < len(chunks)-1 else None,
},
})
return result
切完 chunk 还有一步必须做 用 tiktoken 精确算 token 防止个别 chunk 因为长句无法被分隔符切断而超过 embedding 模型的 max input length OpenAI text-embedding-3 的上限是 8191 token 超过就被截断 语义损失。下面是 token 校验工具 在 chunk 入库前必须跑一遍。
# tiktoken 精确算 token 防止超 embedding 模型上下文限制
encoder = tiktoken.get_encoding('cl100k_base')
def validate_chunk_tokens(chunks: list, max_tokens: int = 8000):
for c in chunks:
tokens = len(encoder.encode(c['text']))
if tokens > max_tokens:
raise ValueError(f"chunk {c['id']} exceeds {max_tokens} tokens")
chunk 大小的工程经验 中文 400 字 英文 800 字是甜区 太小信息密度不够 模型抓不到语义 太大会稀释关键信息 召回相似度被无关内容拉低。chunk_overlap 是必须的 一般设 chunk_size 的 15-20% 让句子边界不至于硬切断。metadata 里存 prev_chunk next_chunk 的尾部前部 让检索命中后能动态扩展上下文给 LLM 这是个工程小技巧但效果显著。
二 模型选型与版本锁定
embedding 模型选型决定召回质量上限。OpenAI 的 text-embedding-3-large 质量最好但贵 small 便宜质量也够用 中文场景 BGE-large-zh 或者 m3e-large 是开源里第一梯队 自部署免费但要 GPU 资源。模型一旦上线必须锁版本 不要用 latest 这种 alias。
from openai import OpenAI
from typing import Literal
import hashlib
client = OpenAI()
class EmbeddingService:
"""统一 embedding 接口 记录模型版本 避免后续漂移"""
def __init__(self, model: str = 'text-embedding-3-small'):
# 模型必须精确 不用 alias
self.model = model
self.dim = {
'text-embedding-3-small': 1536,
'text-embedding-3-large': 3072,
'text-embedding-ada-002': 1536,
}[model]
# 模型版本 hash 用于向量库 metadata
self.version = hashlib.md5(model.encode()).hexdigest()[:8]
def embed_batch(self, texts: list, batch_size: int = 100) -> list:
all_vectors = []
for i in range(0, len(texts), batch_size):
batch = texts[i:i+batch_size]
resp = client.embeddings.create(
model=self.model,
input=batch,
encoding_format='float',
)
all_vectors.extend([d.embedding for d in resp.data])
return all_vectors
def embed_query(self, query: str) -> list:
# 查询单独走一次 避免与 batch 接口的微小差异
resp = client.embeddings.create(model=self.model, input=query)
return resp.data[0].embedding
模型升级时必须做 全量重建向量 然后切流量 不能新老向量混用。下面是切流量的工程实现 用 metadata 标记每条向量的模型版本 查询时按版本过滤 灰度切流。
import pinecone
pinecone.init(api_key='...', environment='us-east-1-aws')
index = pinecone.Index('legal-docs')
def search_with_version_filter(query: str, version: str, top_k: int = 20):
"""按 embedding 版本过滤 避免新老向量混查"""
svc = EmbeddingService()
vec = svc.embed_query(query)
return index.query(
vector=vec,
top_k=top_k,
filter={'embedding_version': {'$eq': version}},
include_metadata=True,
)
# 升级时 先并行存两个版本 灰度切流 完全切完删旧版本
def reindex_to_new_model(old_model: str, new_model: str, percent: int):
"""灰度切流 percent 是新模型的流量占比"""
# 1 后台 job 用新模型 embed 所有 chunk 存到 index 标 version=new
# 2 查询时 按 user_id hash 决定走 old 还是 new
# 3 监控 NDCG MRR 与老版本对齐 才提高 percent
pass
模型选型的工程经验 中英混合场景用 OpenAI 3-large 质量稳定 纯中文用 BGE 自部署性价比高 长文本用 jina-embeddings-v3 支持 8k 上下文 短查询用 small 模型省钱 不要一个 small 模型走天下。我们公司法律文档检索 长文档用 large 短 query 用 small 双模型混合 成本降 40% 质量没下降。
三 混合检索:向量 + BM25
纯向量检索的盲点是精确 keyword 法条号 案号 人名 公司名 这些必须靠全文检索。生产推荐 向量 + BM25 双路召回 然后融合 这是 RAG 系统的标配。
from rank_bm25 import BM25Okapi
import jieba
class HybridRetriever:
def __init__(self, chunks: list, vector_index):
self.chunks = chunks
self.vector_index = vector_index
# BM25 需要分词
tokenized = [list(jieba.cut(c['text'])) for c in chunks]
self.bm25 = BM25Okapi(tokenized)
self.embedding_svc = EmbeddingService()
HybridRetriever 的初始化把 BM25 索引与 embedding 服务都准备好 接下来核心的 search 方法做两路召回 然后用 RRF 倒数排名融合 比简单的加权求和更鲁棒 因为不同召回的 score 分布差异巨大 直接加权融合会被一边主导 RRF 用排名而非分数 对极端值不敏感 是工业界的标配。
def search(self, query: str, top_k: int = 20,
vector_weight: float = 0.6, bm25_weight: float = 0.4) -> list:
# 1 向量召回
vec = self.embedding_svc.embed_query(query)
vec_results = self.vector_index.query(
vector=vec, top_k=top_k * 3, include_metadata=True,
)
vec_scores = {r['id']: r['score'] for r in vec_results['matches']}
# 2 BM25 召回
tokens = list(jieba.cut(query))
bm25_raw = self.bm25.get_scores(tokens)
# 归一化到 0-1
max_bm25 = max(bm25_raw) if max(bm25_raw) > 0 else 1
bm25_scores = {
self.chunks[i]['id']: bm25_raw[i] / max_bm25
for i in range(len(self.chunks))
}
# 3 RRF 倒数排名融合 比加权求和更鲁棒
all_ids = set(vec_scores) | set(bm25_scores)
vec_rank = {id_: rank for rank, id_ in enumerate(
sorted(vec_scores, key=vec_scores.get, reverse=True), 1)}
bm25_rank = {id_: rank for rank, id_ in enumerate(
sorted(bm25_scores, key=bm25_scores.get, reverse=True), 1)}
fused = {}
k = 60 # RRF 常数
for id_ in all_ids:
score = 0
if id_ in vec_rank:
score += vector_weight / (k + vec_rank[id_])
if id_ in bm25_rank:
score += bm25_weight / (k + bm25_rank[id_])
fused[id_] = score
# 返回融合后 top_k
sorted_ids = sorted(fused, key=fused.get, reverse=True)[:top_k]
return [{'id': id_, 'score': fused[id_]} for id_ in sorted_ids]
RRF Reciprocal Rank Fusion 比加权求和更鲁棒 因为不同召回的 score 分布差异巨大 直接加权融合会被一边主导 RRF 用排名而非分数 对极端值不敏感 是工业界的标配。混合权重 0.6:0.4 是个起点 实际要看业务 法律检索 keyword 占比可以再高 通用知识库向量占比可以再高 通过 A/B 测试调。
四 Reranker:精排提升 Top-K 质量
第一阶段 hybrid retrieval 召回 50-100 个候选 第二阶段用专门的 cross-encoder reranker 重新排序 取 top 10-20 给 LLM。reranker 比 embedding 准确率高很多 因为它同时看 query 和 doc 而 embedding 是分开 encode。
from sentence_transformers import CrossEncoder
# BGE 的 reranker 中文场景效果好
reranker = CrossEncoder('BAAI/bge-reranker-large', max_length=512)
def rerank(query: str, candidates: list, top_k: int = 10) -> list:
"""candidates = [{'id', 'text', 'score'}] 来自 hybrid retrieval"""
pairs = [(query, c['text']) for c in candidates]
scores = reranker.predict(pairs, batch_size=32)
for c, s in zip(candidates, scores):
c['rerank_score'] = float(s)
candidates.sort(key=lambda x: x['rerank_score'], reverse=True)
return candidates[:top_k]
# 也可以用 Cohere rerank API 不用自部署
import cohere
co = cohere.Client('...')
def rerank_with_cohere(query: str, candidates: list, top_k: int = 10):
docs = [c['text'] for c in candidates]
resp = co.rerank(
model='rerank-multilingual-v3.0',
query=query,
documents=docs,
top_n=top_k,
)
return [
{**candidates[r.index], 'rerank_score': r.relevance_score}
for r in resp.results
]
rerank 是召回质量的关键放大器 我们公司加 rerank 后 律师查询的 top-3 准确率从 62% 提到 87% 单次查询成本只增加约 0.001 美元 性价比极高。reranker 自部署用 BGE 单 GPU 跑 batch 32 latency 50ms 完全够实时 API 形式用 Cohere 不要管基础设施。
[mermaid]flowchart TD
A[用户 query] --> B[预处理 分词 同义词]
B --> C[向量 embed]
B --> D[BM25 关键词检索]
C --> E[向量库 top 60]
D --> F[全文索引 top 60]
E --> G[RRF 融合]
F --> G
G --> H[Top 50 候选]
H --> I[Cross-Encoder Rerank]
I --> J[Top 10 精排]
J --> K[Metadata 过滤]
K --> L[扩展前后 chunk]
L --> M[喂给 LLM 生成]
五 索引参数调优:HNSW 与 IVF
向量库的索引参数对召回质量与延迟有巨大影响。主流向量库 Pinecone Milvus Qdrant 都支持 HNSW IVF 索引 不同参数权衡不同 必须按业务调。
from pymilvus import Collection, CollectionSchema, FieldSchema, DataType
# Milvus HNSW 索引配置 推荐生产默认
def create_hnsw_index(collection_name: str):
fields = [
FieldSchema(name='id', dtype=DataType.VARCHAR, max_length=128, is_primary=True),
FieldSchema(name='doc_id', dtype=DataType.VARCHAR, max_length=64),
FieldSchema(name='text', dtype=DataType.VARCHAR, max_length=8192),
FieldSchema(name='vector', dtype=DataType.FLOAT_VECTOR, dim=1536),
FieldSchema(name='category', dtype=DataType.VARCHAR, max_length=32),
FieldSchema(name='created_at', dtype=DataType.INT64),
]
schema = CollectionSchema(fields)
col = Collection(collection_name, schema)
# HNSW 召回准 延迟低 内存大
col.create_index('vector', {
'index_type': 'HNSW',
'metric_type': 'COSINE',
'params': {
'M': 16, # 每层最大邻居数 越大召回越准 内存越大
'efConstruction': 200, # 构建时搜索深度 越大索引质量越好 构建越慢
},
})
# metadata 字段加索引 加速过滤
col.create_index('category', {'index_type': 'TRIE'})
col.create_index('created_at', {'index_type': 'STL_SORT'})
return col
# 查询时调 ef 参数 越大召回越准 延迟越高
def search_hnsw(col, vector: list, top_k: int = 20, ef: int = 64,
category_filter: str = None):
expr = f'category == "{category_filter}"' if category_filter else None
return col.search(
data=[vector],
anns_field='vector',
param={'metric_type': 'COSINE', 'params': {'ef': ef}},
limit=top_k,
expr=expr,
output_fields=['doc_id', 'text', 'category'],
)
HNSW M=16 ef=64 是通用甜区 我们公司 100 万向量规模 P99 延迟 30ms 召回 95%+ 这套参数能扛大部分业务 极致追求召回率的把 ef 提到 128 延迟翻倍但召回率 99%。IVF 索引适合超大规模 1 亿向量以上 用 IVF_PQ 配 nlist=4096 nprobe=64 平衡延迟与召回率 但调参更复杂 没必要的话先用 HNSW。metadata 字段必须建索引 否则 filter 时要全表扫描 严重拖慢查询。
六 向量检索的工程坑:那些文档里学不到的
讲完原理来说几个真实生产里踩过的坑。第一个坑是 embedding 模型对中英混合不友好 一段中文夹几个英文术语 embedding 后语义偏向英文 因为模型训练数据英文为主 解决方案是预处理时把英文术语做语义保留的中文翻译 或者用多语言 reranker 修正。第二个坑是 chunk 边界的去重 同一份文档切出来的 chunk 因为有 overlap 会有部分重复 召回 top-k 时可能拿到 3 个高度重叠的 chunk 浪费 LLM context 必须在返回前做去重。第三个坑是 metadata cardinality 高的字段不要做向量库 filter 因为 filter 是后过滤 会让向量库召回更多候选再过滤 性能差 改用预过滤或者分 collection 分库。第四个坑是 query 改写 用户原始 query 往往不适合向量检索 必须用一个小模型先做 query 改写 加同义词 加上下文 这一步对召回质量影响很大。第五个坑是 embedding 模型的 max input length 超长文档直接 embed 会截断 一份 50 页合同 embed 后只剩前 1 页的语义 必须先切 chunk 再 embed 不要图省事。
关键概念速查
| 概念 | 含义 | 工程价值 |
|---|---|---|
| Chunk | 文档切片 | 检索质量上限 |
| Chunk Overlap | 相邻 chunk 重叠 | 防边界信息丢 |
| Embedding | 文本转向量 | 语义检索基础 |
| HNSW | 近似最近邻索引 | 百万级低延迟 |
| BM25 | 关键词检索 | 向量盲点补足 |
| RRF | 倒数排名融合 | 多路召回鲁棒融合 |
| Reranker | cross-encoder 精排 | top-k 质量放大 |
| Metadata Filter | 结构化过滤 | 纯语义不够时兜底 |
| NDCG MRR | 排序质量指标 | 优化必须量化 |
| Query 改写 | 查询扩展 | 提升召回上限 |
避坑清单
- chunk 必须按语义边界切 不要固定长度 优先按段落 句子 分隔符切 边界对齐才能保住语义。
- chunk_overlap 必须有 15-20% chunk_size 防止句子边界硬切断 关键信息丢失。
- embedding 模型必须锁版本 不用 latest alias OpenAI 静默升级会让向量空间漂移召回质量突变。
- 纯向量召回必须配 BM25 混合检索 keyword 法条号 公司名这类精确匹配靠纯向量召回不准。
- 多路召回融合用 RRF 不用加权求和 RRF 对不同分布的 score 鲁棒。
- top-k 召回 50-100 个候选必须 rerank 直接给 LLM 召回噪声会污染回答质量。
- HNSW M=16 ef=64 是通用甜区 100 万向量规模 P99 30ms 召回 95%+ 不够再调 ef。
- metadata 必须建索引 否则 filter 全表扫描 严重拖慢查询。
- 模型升级必须全量重建向量灰度切流 不要新老向量混用 否则相似度不可比。
- 必须搭评测体系 NDCG MRR 一组标注集 每次改动跑回归 否则优化全靠拍脑袋。
总结
向量检索这事 很多人的直觉是 找个 embedding 模型 文档变成向量 算 cosine 取 top-k 就完事 可这其实是把 我会调 embeddings API 和 我能在生产做出律师 客服 知识库能用的检索系统 混为一谈。前者是会用 API 后者是懂检索工程。中间隔着的是 chunk 策略 模型选型 混合检索 reranker 索引参数 评测体系 整整一套工程方法论。
从原型到生产 你需要做的事远不止 embed + cosine。你要懂 chunk 怎么切 要选合适的 embedding 模型并锁版本 要做向量+BM25 混合检索 要加 cross-encoder rerank 要调 HNSW 参数 要建 metadata 索引 要搭评测集做回归 要做 query 改写。每一项单独看都不复杂 但它们组合在一起 才是一个能在生产扛得住的检索系统。少任何一项 都可能让你的系统召回不准 用户弃用。
我经常用一个比喻来理解向量检索 它有点像一个图书馆。文档是书 chunk 是把书拆成章节 embedding 是给每个章节贴个语义标签 向量库是按标签排序的书架 BM25 是图书馆的关键词索引卡 reranker 是图书管理员 你说"我要找一本关于上海限购的书" 管理员先按标签拿一堆候选 再翻看内容确认 最后给你最合适的几本。你不能因为有了贴标签的书架就觉得能服务好读者 还要管标签质量 关键词索引 管理员审核 评测反馈 这才是一整套图书馆服务。
这套架构最难的地方在于 它的复杂度在小数据小流量 demo 时几乎完全暴露不了。你 demo 用 1000 个 chunk 一切都很顺 觉得向量检索真好用。但真正上规模 10 万 100 万 chunk 真实用户的各种 query 各种长尾 case 你才发现 99% 的复杂度都在 那 1% 的边角 case 里 chunk 切坏 模型漂移 keyword 召不回 长 query 失效 metadata 过滤性能差。建议任何想用向量检索做严肃业务的团队 上线前一定要做 真实数据评测 找业务方标 500 条 query 算 NDCG MRR 看每一项优化是真的提升还是错觉 千万别等用户来教你 那时候已经在用脚投票弃用了。
—— 别看了 · 2026