# 本地语义检索教程：用 Sentence Transformers 找中英同义句，与关键词搜索对照

公开MiniLM固定revision真实本地encode，完整4×8相似度保留，同缓存离线再推理一致；未运行热榜中的其他模型。

## 环境

- Python 3.12+；在 reference 中 pip install -r requirements.txt。
- 首次下载固定公开模型revision需网络，随后可local_files_only重跑。模型权重不在包内，使用HF_HOME可指定自己的模型缓存目录。

## 启动

~~~sh
cd reference
python3 verify.py
# 运行后查看原生结果阅读器（读取records.json）
python3 -m http.server 8787
# 打开 http://127.0.0.1:8787/report.html
~~~

## 七步操作

1. 准备双语语料

输入为八条原创中英文说明和四个固定查询，包含密码同义说法、发票、导入联系人及无关烹饪条目。先固定语料，不只保留能成功的那几个例子。

2. 下载公开小模型

实际模型为公开免门控的paraphrase-multilingual-MiniLM-L12-v2，许可Apache-2.0，下载固定revision。它与HF热榜中观察到的EmbeddingGemma是不同模型。

3. 执行真实编码

使用SentenceTransformer真正加载权重，分别encode文档和查询，归一化后计算相似度矩阵。本文不是手写分数，也不是仅测试检索界面。

4. 比较同批查询

对同一批查询并排保留关键词基线与向量排序。关键词基线仅按小写空格词做子串匹配，中文未分词，不代表强BM25基线。英文忘记密码的查询能匹配密码说明；这说明当前输入的语义关联，不等于所有任务都更好。

5. 保留所有分数

保存完整4×8分数与所有候选，包括无关文档和干扰项。不隐藏低分或不理想结果，也不把单次小样本当作模型评测排行榜。

6. 缓存离线重跑

从本地缓存以local_files_only再次加载同一revision，重复编码并比较数值一致性。首次下载需要网络，权重仅保存在作者外盘缓存，不随练习包分发。

7. 说明模型身份

下载代码、原创语料、完整分数与revision文本，自行运行可再次取权重。教程只声称MiniLM本地推理，不声称运行了热门门控模型、GPU服务或付费API。

## 目录身份

- starter：待完成的任务接口与原创输入，TODO不是已完成实现。
- reference：作者原生完成参考和实际产物。records.json/browser-result.json为本地实测记录，不是AI助手回复。
- TASK.md：可交给相应AI助手的原始任务合同。该助手账号生成会话未运行。

## 依赖与许可

原创教学代码以MIT许可提供。第三方项目、模型及浏览器遵循其自身许可。第三方依赖由本地安装获取，不包含node_modules、模型权重、WASM运行时、数据库、缓存或凭据。

## 官方依据

- https://huggingface.co/sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2