真实语义检索:编码、融合与重排跑在同一条链路
在CPU运行公开多语言模型,比较关键词、向量、RRF与CrossEncoder,并观察租户、版本和无答案问题。
前六节已经把团队知识库接到真实HTTP和SQLite。关键词查询能找到“差旅报销”,却可能漏掉“出差回来多久交单”。这次保留同一个知识库业务,用预训练模型编码文档,再以CrossEncoder重排,逐项比较各阶段结果。最后返回原文证据及来源,便于继续检查答案依据。
同一查询经过四种排序
关键词分支按中文双字窗口和英文词项计算重叠,便于看到字面匹配为何失败。这是简化词法基线,不是前六节的SQLite BM25。向量分支先把每个块编码、归一化并落盘,查询时计算同一模型的查询向量,再做精确点积检索。小语料全量扫描便于隔离表示质量,暂不引入ANN误差。
RRF融合的是名次:每路第r名贡献1/(60+r)。两路的原始分数不在同一尺度,所以不直接相加。融合后最多四个候选交给CrossEncoder;它把查询和每段原文放在一起推理,重新排序。重排可以调换已有候选,无法找回被前面丢掉的证据。
建立独立环境
在自己的非系统盘工作目录新建 agentdepth-semantic,进入该目录。下面的三个Python文件都保存在这里;使用Python 3.13创建独立环境。首次安装需要网络和数GB可用磁盘;两个公开权重总量约一GB,下载完成后推理完全在CPU本地进行,不需要付费API或GPU。
先保存 requirements.txt:
sentence-transformers==6.2.0
transformers==5.22.1
torch==2.15.0
numpy==2.5.4
python-docx==1.2.0
pymupdf==2.1
beautifulsoup4==4.15.0Windows PowerShell依次执行:
py -3.13 -m venv .venv
$env:PYTHONPATH = ""
$env:PIP_CACHE_DIR = Join-Path (Get-Location) ".runtime/pip"
.venv/Scripts/python -m pip install -r requirements.txtmacOS/Linux执行:
python3.13 -m venv .venv
PYTHONPATH= PIP_CACHE_DIR="$PWD/.runtime/pip" .venv/bin/python -m pip install -r requirements.txt这些设置只作用于当前进程/终端,避免已有全局Python路径混入环境。默认权重、索引和结果放在本目录 .runtime。需要放到另一块盘时,在运行前设置 RETRIEVAL_STATE 为自己的绝对路径。不要把这个运行目录提交到网站的public目录或发布包。
两个模型的模型卡均标记Apache-2.0许可:多语言Embedding、多语言重排器。用于其他产品时保留对应许可与归属信息。
下载固定版本的模型
保存 download_models.py。它只下载固定commit的配置、分词器与safetensors权重,检查模型仓库提供的权重SHA-256,最后写入来源清单。网络失败会保留.part并报错;重新运行会重新下载未完成文件,下载完成后才进入本地加载。
"""用标准库下载固定公开版本;网络失败时停止并保留未完成文件。"""
import hashlib
import json
import os
from pathlib import Path
import urllib.request
ROOT = Path(os.getenv('RETRIEVAL_STATE', Path(__file__).parent / '.runtime'))
MODELS = [
('encoder', 'sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2', 'e8f8c211226b894fcb81acc59f3b34ba3efd5f42'),
('reranker', 'cross-encoder/mmarco-mMiniLMv2-L12-H384-v1', '1427fd652930e4ba29e8149678df786c240d8825'),
]
def main():
for name, repo, revision in MODELS:
folder = ROOT / 'models' / name
folder.mkdir(parents=True, exist_ok=True)
url = f'https://huggingface.co/api/models/{repo}/revision/{revision}?blobs=true'
with urllib.request.urlopen(url, timeout=60) as response:
metadata = json.load(response)
for entry in metadata['siblings']:
filename = entry['rfilename']
# 只取 PyTorch safetensors 和 tokenizer / pooling 配置,跳过 ONNX 等重复权重。
if filename.startswith(('onnx/', 'openvino/')):
continue
if not (filename.endswith(('.json', '.txt', '.model')) or filename == 'model.safetensors'):
continue
target = folder / filename
target.parent.mkdir(parents=True, exist_ok=True)
expected = entry.get('lfs', {}).get('sha256')
if target.exists() and (not expected or hashlib.sha256(target.read_bytes()).hexdigest() == expected):
continue
partial = target.with_suffix(target.suffix + '.part')
source = f'https://huggingface.co/{repo}/resolve/{revision}/{filename}'
with urllib.request.urlopen(source, timeout=120) as response, partial.open('wb') as output:
while block := response.read(1024 * 1024):
output.write(block)
if expected and hashlib.sha256(partial.read_bytes()).hexdigest() != expected:
raise ValueError(f'权重校验失败:{filename}')
partial.replace(target)
print(name, filename, target.stat().st_size, flush=True)
(folder / 'source.json').write_text(json.dumps(dict(repo=repo, revision=revision)), encoding='utf-8')
if __name__ == '__main__':
main()编码、发布与查询
保存 kb.py。先看三个边界:chunks保留Markdown行号与字符偏移;publish先构建完整快照再切换活动指针;search先根据可信租户过滤,随后所有排序只处理允许的块。这个程序由本地调用者传入租户,接回第04节HTTP服务时必须使用tenant_of的认证结果,不能直接采用用户请求里的tenant字段。
编码器最多接收128个token;Markdown按80字符拆段后,还会使用实际分词器检查标题与正文的总长度,超限直接要求细分,避免静默截掉例外条件。CrossEncoder的输入上限设为256。
每个文档版本进入块ID。更新时移除该租户旧版本,重新构建快照;另一个租户的同名文档不受影响。这里采用单写者、小数据全量重建,进程内查询持有完整快照。它没有实现多写者竞争、分布式指针同步、后台垃圾回收或权限撤回通知。版本切换完成后,其他长驻读取进程也要显式重新load。
"""真实 CPU 编码、混合检索和 CrossEncoder 重排;不调用生成或收费接口。"""
import hashlib
import json
import os
from pathlib import Path
import re
import time
# 在导入模型库之前指定项目内缓存,避免权重进入用户系统盘目录。
ROOT = Path(__file__).resolve().parent
STATE = Path(os.getenv('RETRIEVAL_STATE', ROOT / '.runtime')).resolve()
os.environ['HF_HOME'] = str(STATE / 'models')
os.environ['HUGGINGFACE_HUB_CACHE'] = str(STATE / 'models' / 'hub')
os.environ['TRANSFORMERS_CACHE'] = str(STATE / 'models' / 'transformers')
os.environ.setdefault('HF_HUB_DISABLE_XET', '1')
os.environ.setdefault('HF_HUB_DISABLE_SYMLINKS_WARNING', '1')
import numpy as np
import torch
from sentence_transformers import SentenceTransformer, CrossEncoder
ENCODER = 'sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2'
ENCODER_REV = 'e8f8c211226b894fcb81acc59f3b34ba3efd5f42'
RERANKER = 'cross-encoder/mmarco-mMiniLMv2-L12-H384-v1'
RERANKER_REV = '1427fd652930e4ba29e8149678df786c240d8825'
def chunks(tenant, name, text, revision=1):
"""按 Markdown 标题和非空行分块,保存原文行号;不把标题当事实正文。"""
result, heading = [], ''
for line, raw in enumerate(text.splitlines(), 1):
if raw.startswith('#'):
heading = raw.lstrip('#').strip()
elif raw.strip():
# 长段按字符切分只是这个小工程的策略,来源仍能定位到原行和偏移。
for start in range(0, len(raw), 80):
result.append(dict(tenant=tenant, document=name, revision=revision,
id=f'{name}@{revision}:{line}:{start}', title=heading,
text=raw[start:start + 80], source=f'{name}.md:L{line}:char{start}'))
return result
def terms(text):
"""中文双字窗口与英文词项;这是词法基线,不冒称语义表示或 BM25。"""
out = set()
for word in re.findall(r'[\u4e00-\u9fff]+|[a-z0-9_]+', text.lower()):
if re.fullmatch(r'[\u4e00-\u9fff]+', word):
out.update(word[i:i + 2] for i in range(max(1, len(word) - 1)))
else:
out.add(word)
return out
class Knowledge:
def __init__(self):
torch.set_num_threads(4)
for name, repo, revision in [('encoder', ENCODER, ENCODER_REV), ('reranker', RERANKER, RERANKER_REV)]:
source = json.loads((STATE / 'models' / name / 'source.json').read_text())
if source != dict(repo=repo, revision=revision):
raise ValueError('本地模型版本不匹配,请重新下载到独立目录')
self.encoder = SentenceTransformer(str(STATE / 'models' / 'encoder'), device='cpu', local_files_only=True)
self.reranker = CrossEncoder(str(STATE / 'models' / 'reranker'), device='cpu', max_length=256, local_files_only=True)
def publish(self, rows):
"""整批构建不可变快照,最后原子切换指针;不做有风险的半批增量更新。"""
if not rows or len({(r['tenant'], r['id']) for r in rows}) != len(rows):
raise ValueError('快照必须非空,且租户内块 ID 唯一')
content = json.dumps(rows, ensure_ascii=False, sort_keys=True)
digest = hashlib.sha256(content.encode()).hexdigest()
texts = [r['title'] + '\n' + r['text'] for r in rows]
if any(len(self.encoder.tokenizer(text)['input_ids']) > self.encoder.max_seq_length for text in texts):
raise ValueError('块超过编码器 token 上限,请细分并保留来源偏移')
vectors = self.encoder.encode(texts,
normalize_embeddings=True, show_progress_bar=False)
folder = STATE / 'indexes' / digest
folder.mkdir(parents=True, exist_ok=True)
np.save(folder / 'vectors.npy', vectors, allow_pickle=False)
(folder / 'rows.json').write_text(content, encoding='utf-8')
manifest = dict(encoder=ENCODER, revision=ENCODER_REV, digest=digest,
dimensions=int(vectors.shape[1]), normalized=True)
(folder / 'manifest.json').write_text(json.dumps(manifest), encoding='utf-8')
pointer = STATE / 'active.tmp'
pointer.write_text(digest, encoding='utf-8')
pointer.replace(STATE / 'active.txt')
self.load()
def load(self):
folder = STATE / 'indexes' / (STATE / 'active.txt').read_text().strip()
manifest = json.loads((folder / 'manifest.json').read_text())
content = (folder / 'rows.json').read_text(encoding='utf-8')
if (manifest['encoder'], manifest['revision']) != (ENCODER, ENCODER_REV):
raise ValueError('编码模型不兼容,必须重建索引')
if hashlib.sha256(content.encode()).hexdigest() != manifest['digest']:
raise ValueError('文档快照损坏')
self.rows = json.loads(content)
self.vectors = np.load(folder / 'vectors.npy', allow_pickle=False)
if self.vectors.shape != (len(self.rows), manifest['dimensions']):
raise ValueError('向量与文档数量或维度不一致')
def search(self, query, tenant, candidate_k=4):
"""先按可信身份过滤,再产生任何候选;租户参数须由上游认证结果提供。"""
if candidate_k < 1 or not query.strip():
raise ValueError('查询不能为空,候选数必须为正')
allowed = [i for i, row in enumerate(self.rows) if row['tenant'] == tenant]
if not allowed:
return {name: [] for name in ('keyword', 'dense', 'hybrid', 'reranked')}, {}
timings, start = {}, time.perf_counter()
query_terms = terms(query)
lexical = {i: len(query_terms & terms(self.rows[i]['title'] + self.rows[i]['text']))
for i in allowed}
keyword = sorted((i for i in allowed if lexical[i]), key=lambda i: (-lexical[i], i))[:candidate_k]
timings['keyword_ms'] = (time.perf_counter() - start) * 1000
start = time.perf_counter()
if len(self.encoder.tokenizer(query)['input_ids']) > self.encoder.max_seq_length:
raise ValueError('查询超过编码器 token 上限')
q = self.encoder.encode([query], normalize_embeddings=True, show_progress_bar=False)[0]
scores = self.vectors[allowed] @ q
dense = [allowed[p] for p in np.argsort(-scores, kind='stable')[:candidate_k]]
timings['dense_ms'] = (time.perf_counter() - start) * 1000
start = time.perf_counter()
fused = {}
for ranking in (keyword, dense):
for rank, i in enumerate(ranking, 1):
fused[i] = fused.get(i, 0) + 1 / (60 + rank)
hybrid = sorted(fused, key=lambda i: (-fused[i], i))[:candidate_k]
timings['fusion_ms'] = (time.perf_counter() - start) * 1000
start = time.perf_counter()
pairs = [[query, self.rows[i]['title'] + '\n' + self.rows[i]['text']] for i in hybrid]
rerank_scores = self.reranker.predict(pairs, show_progress_bar=False)
reranked = [hybrid[p] for p in np.argsort(-rerank_scores, kind='stable')]
timings['rerank_ms'] = (time.perf_counter() - start) * 1000
return {name: [self.rows[i] for i in order] for name, order in
dict(keyword=keyword, dense=dense, hybrid=hybrid, reranked=reranked).items()}, timings
DOCUMENTS = {
'travel': '# 差旅报销\n出差结束后,应在十个工作日内提交发票和报销单。国际差旅须附汇率凭证。',
'leave': '# 年假申请\n休年假应提前三个工作日提交申请,并由直属主管审批。病假需提供诊断证明。',
'access': '# 生产权限\n生产数据库只读权限需由系统负责人批准,有效期为七天。禁止共享账号。',
'incident': '# 生产事故\n线上服务不可用时,立即联系值班人员,保存时间线,并在恢复后补充事故复盘。',
'refund': '# 退款政策\n普通商品收到后七天内可以申请退款,定制商品不支持无理由退货。',
'invoice': '# 发票规则\n开具增值税发票需要企业名称和税号。发票抬头错误时,应先红冲原发票再重开。',
'password': '# 密码重置\n忘记登录密码时,通过已绑定的手机验证码重置。不要将验证码发给他人。',
'meal': '# 加班餐补\n工作日晚间加班超过两小时可以申请餐补,每人每天最高三十元。',
}
def seed():
rows = [r for name, text in DOCUMENTS.items() for r in chunks('alpha', name, text)]
rows += chunks('beta', 'travel', '# 差旅报销\n差旅结束后三十天内提交报销单。')
return rows用保留问题比较,而不是只展示成功问法
保存 evaluate.py。开发集的报销/发票问法用来解释机制,保留集使用其他意图,避免把同一问题的简单改写拆到两边。数据只有12条,是自制教学样本,不是业务上线评测。最后一个问题在知识库里没有答案,单独检查候选,不把Recall的空分母计作满分。
Recall@3检查需要的文档有多少进入前三;MRR@3只看第一个相关结果的名次。多证据题即使MRR等于1,也可能漏掉另一份材料。每个阶段都保存文档ID,耗时单独记录;预热不算进逐题测量,权重加载时间另存。
"""固定开发/保留集上的真实检索评测;结果只代表这些自制教学样本。"""
import json
import time
import numpy as np
from kb import Knowledge, STATE, seed, chunks, ENCODER, ENCODER_REV, RERANKER, RERANKER_REV
# 同一个意图的改写留在同一集合,避免把同源改写分到开发与保留两边。
CASES = [
('dev', '差旅报销', ['travel']),
('dev', '出差回来多久交单', ['travel']),
('dev', '开票抬头写错了怎么办', ['invoice']),
('dev', '发票需要什么信息', ['invoice']),
('holdout', '休息几天要找谁同意', ['leave']),
('holdout', '生产数据库访问许可多久失效', ['access']),
('holdout', '网站突然打不开了要先找谁', ['incident']),
('holdout', '订做的商品不喜欢可以退吗', ['refund']),
('holdout', '忘了账户口令怎么重新登录', ['password']),
('holdout', '晚上多干两小时饭钱能报多少', ['meal']),
('holdout', '数据库授权到期和线上故障分别找谁', ['access', 'incident']),
('holdout', '火星移民签证在哪里办理', []),
]
def main():
start = time.perf_counter()
kb = Knowledge()
load_seconds = time.perf_counter() - start
kb.publish(seed())
kb.search('差旅报销', 'alpha') # 预热单独进行,不混入逐题耗时。
results = []
for split, query, gold in CASES:
stages, timings = kb.search(query, 'alpha')
rankings = {stage: [r['document'] for r in rows] for stage, rows in stages.items()}
assert all(r['tenant'] == 'alpha' for rows in stages.values() for r in rows)
results.append(dict(split=split, query=query, gold=gold, rankings=rankings, timings=timings))
print(query, '=>', ' | '.join(f'{stage}:{ids[:3]}' for stage, ids in rankings.items()))
summaries = {}
for split in ('dev', 'holdout'):
subset = [r for r in results if r['split'] == split and r['gold']]
for stage in ('keyword', 'dense', 'hybrid', 'reranked'):
recalls, reciprocals = [], []
for row in subset:
ranked, gold = row['rankings'][stage][:3], set(row['gold'])
recalls.append(len(set(ranked) & gold) / len(gold))
reciprocals.append(next((1 / rank for rank, item in enumerate(ranked, 1) if item in gold), 0))
summary = dict(n=len(subset), recall3=round(float(np.mean(recalls)), 4),
mrr3=round(float(np.mean(reciprocals)), 4))
summaries[f'{split}/{stage}'] = summary
print(split, stage, summary)
timing_summary = {key: {'p50_ms': round(float(np.percentile([r['timings'][key] for r in results], 50)), 2),
'p95_ms': round(float(np.percentile([r['timings'][key] for r in results], 95)), 2)}
for key in results[0]['timings']}
print('阶段耗时(预热后,12题,CPU)', timing_summary)
# 向量检索总会给出最近邻;不把无答案题的候选误称为有效证据。
print('无答案题各阶段候选数', {k: len(v) for k, v in results[-1]['rankings'].items()})
old = seed()
updated = [r for r in old if not (r['tenant'] == 'alpha' and r['document'] == 'travel')]
updated += chunks('alpha', 'travel', '# 差旅报销\n出差结束后,应在十四个工作日内提交发票和报销单。', revision=2)
kb.publish(updated)
kb.load() # 从磁盘重新读取当前快照。
hits, _ = kb.search('差旅报销', 'alpha')
assert not any(r['document'] == 'travel' and r['revision'] == 1 for r in hits['reranked'])
beta, _ = kb.search('差旅报销', 'beta')
assert beta['reranked'][0]['revision'] == 1
missing, _ = kb.search('差旅报销', 'unknown')
assert all(not values for values in missing.values())
print('磁盘重载、alpha新版本、beta旧版本、未知租户隔离:PASS')
report = dict(models=dict(encoder=ENCODER, encoder_revision=ENCODER_REV,
reranker=RERANKER, reranker_revision=RERANKER_REV),
load_seconds=load_seconds, cases=results, summary=summaries, timings=timing_summary)
STATE.mkdir(parents=True, exist_ok=True)
(STATE / 'result.json').write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding='utf-8')
if __name__ == '__main__':
main()按顺序运行,macOS/Linux把解释器路径替换成.venv/bin/python:
.venv/Scripts/python -X utf8 download_models.py
.venv/Scripts/python -X utf8 evaluate.py实际结果怎样读
本次运行得到以下结果;12题中开发集4题、保留集8题,其中保留集1题无答案,排名指标按其余7题计算。
| 集合 / 路径 | Recall@3 | MRR@3 |
|---|---|---|
| dev/keyword | 1.0000 | 1.0000 |
| dev/dense | 1.0000 | 0.8750 |
| dev/hybrid | 1.0000 | 1.0000 |
| dev/reranked | 1.0000 | 1.0000 |
| holdout/keyword | 0.7143 | 0.7143 |
| holdout/dense | 1.0000 | 1.0000 |
| holdout/hybrid | 1.0000 | 1.0000 |
| holdout/reranked | 1.0000 | 1.0000 |
“休息几天要找谁同意”和“网站突然打不开了要先找谁”在关键词路径中没有候选,向量路径分别把leave与incident排到第一。但“出差回来多久交单”的向量第一名是leave,正确的travel排第二;关键词与融合则把travel放在第一。向量并非对每个问题都更好。
保留集上重排没有进一步提高这两个指标,却增加了计算时间。先观察这个结果,再决定是否保留该组件;不要为了展示“升级成功”而修改标签。
| 阶段 | p50 / ms | p95 / ms |
|---|---|---|
| keyword_ms | 0.12 | 0.22 |
| dense_ms | 13.96 | 15.19 |
| fusion_ms | 0.01 | 0.01 |
| rerank_ms | 43.24 | 57.47 |
运行末尾:
无答案题各阶段候选数 {'keyword': 0, 'dense': 4, 'hybrid': 4, 'reranked': 4}
磁盘重载、alpha新版本、beta旧版本、未知租户隔离:PASS逐题查询、gold、四组候选与耗时保存在.runtime/result.json,可以按同一query比较修改前后。
无答案问题也会得到向量近邻。相似度表示“当前集合中比较接近”,不是“这份材料可以回答问题”。本例没有校准拒答阈值,不能把top1直接写成肯定答案。接入回答端时,应另设可回答/不可回答标签与支持度检查,并保留“仅返回检索列表”的状态。
阶段耗时只代表本机CPU、四个计算线程、这12个短查询。p95是这12次的样本分位数,不是生产SLO。增加候选数会增加重排计算,扩大k也可能引入噪声;修改候选预算后应重跑同一保留集,而非只保留变好的题。
连接后续工程与排错
真实文件解析见第10节。解析结果使用相同块契约,可直接送进publish。要接回原HTTP服务,可以在启动时加载Knowledge,在/search内调用search(question.query, tenant);返回来源块后再沿第04节的引用校验进入回答。原FTS5工程可继续作为HTTP接口和词法检索基线。
| 现象 | 先检查 | 下一步 |
|---|---|---|
| 首次下载慢或超时 | 是否能访问固定权重URL,磁盘是否足够 | 检查自己的网络,重跑下载;不要删版本约束 |
| 提示找不到source.json | 是否先完成模型下载,RETRIEVAL_STATE是否一致 | 用相同运行目录下载和查询 |
| 向量排序意外 | 块文本、模型revision、归一化和截断 | 先看各阶段ID,再换模型;维度相同不代表空间兼容 |
| 更新后仍返回旧规则 | 活动指针、租户、当前进程是否load | 核对来源revision,重载同一快照 |
| 无答案问题有候选 | 检索器没有拒答机制 | 单独校准答案支持度,不能拿相似度当正确概率 |
课后练习展开习题收起习题
练习:找到检索的取舍
- 把候选预算从4改为2,重跑保留集。哪道题丢了必要文档?若没有变化,也如实说明这个样本不足以区分预算。
- 从快照删除alpha的退款文档,保留beta资料。查询退款后检查来源列表;相关内容不存在时,重排是否仍返回其他文档?
- 把新版本差旅期限改为十五个工作日,观察alpha与beta的来源版本。若只改源文本却未publish,解释为什么结果不变。
参考检查思路
比较同一题的keyword、dense、hybrid和reranked列表,找到正确ID最早在哪一步消失。删除后alpha不能看到beta资料;剩余最近邻仍可能不支持答案。源文本与已发布索引是不同对象,发布并load后才使用新快照。
接口依据:Sentence Transformers编码与重排、多语言CrossEncoder模型卡。模型卡说明训练背景;选择业务模型时,再用自己的保留问题比较。