Guide · 使用教程
Model2Vec Python 教程:本地语义检索、中文样本与召回评估
固定版本与模型快照,用完整代码检查六文档、四查询的本地检索,保留中文首位失败及十项基础验证边界。
先验证检索结果,再接回答模型
本教程用 Model2Vec 建立一个不接向量数据库的小型语义检索实验:六条合成文档、四条人工指定参考答案的查询,输出前三名和命中记录。它演示模型加载、向量校验与失败解释,不是生产搜索系统,也没有多工具共同基准。
固定环境为 Python 3.11、model2vec 0.10.0,模型使用 minishlab/potion-base-8M。该模型面向英文;加入中文样本是为了暴露语言错配,不能把本教程理解为中文模型推荐。实测中“我想申请退款”的首位结果确实错误,后文保留原结果。
第一步:独立安装并准备模型
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install 'model2vec==0.10.0'
首次准备模型需要联网。保存下列代码为 download_model.py,在有模型访问权限与网络的环境运行。本次固定官方快照,方便复现;其他项目应记录自己使用的模型版本和许可。这里选择 allow_patterns 只下载推理所需的配置、分词器、权重与说明文件,不安装训练或蒸馏组件。
from huggingface_hub import snapshot_download
snapshot_download(
'minishlab/potion-base-8M',
revision='bf8b056651a2c21b8d2565580b8569da283cab23',
local_dir='./potion-base-8m',
allow_patterns=['*.json', '*.safetensors', 'README.md'],
)
python download_model.py
下载文件与后续输入文本是不同数据流。准备完成后从本地目录加载,避免每次推理都依赖远端。网络受限环境不要随意换不明镜像;先核对来源、完整性与目标平台兼容性。本文没有把模型下载速度作为推理延迟。
第二步:保存完整检索程序
把以下代码保存为 retrieve.py。文档 ID 与向量行一一对应;归一化后用矩阵乘法计算余弦相似度。代码拒绝空语料、重复 ID、空文本、非有限数值和零向量,防止坏数据悄悄进入排序。这里只读本地合成文本,不调用生成模型,也没有真实文件或账户操作。
argparse
hashlib
json
time
importlib.metadata version
pathlib Path
numpy np
model2vec StaticModel
DOCS=[
{:,:},
{:,:},
{:,:},
{:,:},
{:,:},
{:,:},
]
QUERIES=[(,),
(,),
(,),(,)]
():
docs: ValueError()
ids=[d[] d docs]
(ids)!=((ids)): ValueError()
( d[].strip() d docs): ValueError()
():
matrix=np.asarray(matrix,dtype=np.float32)
matrix.ndim!= np.isfinite(matrix).(): ValueError()
norms=np.linalg.norm(matrix,axis=,keepdims=)
np.(norms<=): ValueError()
matrix/norms
():
parser=argparse.ArgumentParser()
parser.add_argument(,=Path)
args=parser.parse_args()
args.model_directory.is_dir(): SystemExit()
validate_docs(DOCS)
started=time.perf_counter()
model=StaticModel.from_pretrained((args.model_directory))
loaded=time.perf_counter()
corpus=unit(model.encode([d[] d DOCS],use_multiprocessing=))
questions=unit(model.encode([q q,_ QUERIES],use_multiprocessing=))
corpus.shape[]==(DOCS) questions.shape[]==corpus.shape[]
[email protected]
rows=[]
i,(q,gold) (QUERIES):
order=np.argsort(-scores[i],kind=)[:]
top=[{:DOCS[j][],:((scores[i,j]),)} j order]
rows.append((query=q,expected=gold,top3=top,hit1=top[][]==gold,
hit3=gold [x[] x top]))
hashes={p.name:hashlib.sha256(p.read_bytes()).hexdigest() p args.model_directory.glob()}
(json.dumps((version=version(),dimensions=corpus.shape[],
corpus_count=(DOCS),model_sha256=hashes,
load_ms=((loaded-started)*,),
rows=rows,hit1=(r[] r rows),hit3=(r[] r rows),
note=),ensure_ascii=,indent=))
__name__==:main()
常见问题
- 软件免费等于运行免费吗?
- 不等于。许可、权重、计算、存储、下载、索引和维护分别核对。
- 本地一定完全离线吗?
- 首次准备模型可能联网;后续真实数据流按所选组件与配置检查。
- 四条查询能代表生产准确率吗?
- 不能。这是教学合成样本,不是统计估计或共同工具基准。
- 中文向量非空就合格吗?
- 不能。英文模型在退款查询上首位失败,需要按中文任务独立验收。
- 换模型需要重建索引吗?
- 应重新编码并验证,维度相同也不保证向量处于同一表示空间。
- 相似度能做权限控制吗?
- 不能。可访问文档范围应由可信身份和权限规则控制。