|
| 1 | +# v0.19.5 · 语义增强：本地 embedding（REQ-259/REQ-262 余项） |
| 2 | + |
| 3 | +> 状态：**已实施（2026-09-04，提交 244ea92/8cab673/c57ce0c/81e552b/6a10ba0/31f91e5/cd9bcee；真实模型下载与端到端命中实测登记真机验收待办）**。 |
| 4 | +> 排期注：原 v0.19.4（REQ-259 语义增强）经 2026-09-04 用户裁决被反馈批抢占序号——本批以 v0.19.5 交付；需求池 REQ-259 目标版本已同步。 |
| 5 | +
|
| 6 | +## 定位 |
| 7 | + |
| 8 | +本地 embedding 内嵌 ONNX（bge-small-zh-v1.5 int8）——检索与发现层的语义增强：FTS5 词法之上叠加语义召回，RRF 融合；**无模型/推理失败/维度不一致一律自动降级 FTS-only**（层层本地兜底，不阻塞任何读路径——设计铁律 1/2 与 §六 降级链）。 |
| 9 | + |
| 10 | +## 交付构成 |
| 11 | + |
| 12 | +| 提交 | 内容 | |
| 13 | +|------|------| |
| 14 | +| 244ea92 | 纯层地基：EmbeddingEngine trait（Noop/Onnx/Ollama 预留）+ f32le 编解码 + 零向量安全余弦 + cosine_top_k（5 测试）；ort rc.13 依赖（本地缓存离线可解析，与 oar-ocr 共用 onnxruntime.dll） | |
| 15 | +| 8cab673 | bge BERT WordPiece 分词器（vocab.txt 加载/特殊标记校验/512 窗截断/UNK 诚实降级；4 测试） | |
| 16 | +| c57ce0c | OnnxEmbedding 引擎（ort rc13 API 攻坚：&mut Session→内部 Mutex、Tensor::from_array、try_extract_tensor 切片直读；[CLS]+L2；批 ≤32；缺模型/形状不符如实报错）+ 引擎槽（AppState Arc<Mutex<EmbeddingSlot>>，Noop 默认）+ kb_embedding_status/load 命令 | |
| 17 | +| 81e552b | 混合检索 RRF 合流：kb_search_hybrid（引擎可选）+ 语义合流独立模块（dim 一致性校验、余弦 top-K ∪ FTS 候选 → rrf k=60 → limit）；三路接线：kb_search 命令 / 学习库问答 kb_run / 检索建议证据候选；FTS wrapper 留测试 | |
| 18 | +| 6a10ba0 | reindex 后置向量回填：kb_fill_embeddings（全量块→批嵌入→写列+meta model/dim/format；3 集成测试）；kb_reindex_all 重建成功后自动回填（失败如实记录不阻断）；stats.embedding_ready/engine 按 meta 实态（fts5+onnx） | |
| 19 | +| 31f91e5 | 模型下载命令 kb_embedding_download：hf-mirror 双源（Xenova ONNX 量化 + BAAI vocab.txt）、.part 原子落位、600s 超时 | |
| 20 | +| cd9bcee | 设置页「学习库」段治理 UI：引擎状态徽标（noop/就绪 dim）+ 下载/加载按钮 + 回填引导（重建按钮既有） | |
| 21 | + |
| 22 | +## 口径与决策记录 |
| 23 | + |
| 24 | +- **选型**：内嵌 ONNX bge-small-zh-v1.5（用户 2026-09-04 裁决"优先尝试内嵌 ONNX"）；Ollama 端点因"用户自装、零分发"列为同一 trait 的未来实现位（本批不做） |
| 25 | +- **降级链**：无模型（Noop）→ FTS-only；推理失败 → FTS-only + 状态可见；模型更换未重建（dim 与库内 meta 不符）→ FTS-only + 日志提示重建；未回填行 embedding=NULL 自然缺席语义候选 |
| 26 | +- **存储**：kb_chunks.embedding BLOB（v0.19.0 DDL 预留）f32le；kb_meta embedding_model/embedding_dim/embedding_format（检索合流 dim 校验数据源；回填完成标记=meta 写入） |
| 27 | +- **回填时机**：全量重建（kb_reindex_all）成功后置自动回填（引擎就绪时）；软重建钩子（保存/删除）不增量补向量——语义一致性以重建按钮为准（UI 已引导），未回填期间检索恒 FTS 精度 |
| 28 | +- **`/ask` 接线评估（收尾）**：不新增 `/ask` 命令——任务入口已有 `/refine`/`/enrich`，学习库问答走会话 retrieval 模式（📚 会话 + kb_qa 闸门），无第三命令缺口；该评估结论登记，不产生代码变更 |
| 29 | +- **向量索引不做**（YAGNI）：余弦全量线扫在本地量级（数千 chunk × 512 维）毫秒级，达量级再评估（设计 §六 记录延续） |
| 30 | + |
| 31 | +## 真机验收待办（登记） |
| 32 | + |
| 33 | +1. **模型链路端到端**：下载（hf-mirror 可达性）→ 加载 → 重建回填 → stats 显示 fts5+onnx → 语义命中实测（中文小评测集 ~30 查询，与纯 FTS 对比召回） |
| 34 | +2. vocab 来源确认：BAAI 仓库根 vocab.txt 与本分词器匹配性（若缺 → 改用 Xenova tokenizer.json 需补解析，登记为潜在偏差） |
| 35 | +3. ort 与既有 oar-ocr 运行时共存回归（同一 onnxruntime.dll 双引擎并发） |
| 36 | +4. 混合检索精度/排序观感与 RRF 参数（k=60 沿用设计稿定案）实机复核 |
| 37 | +5. 语义建议（发现路径）开启后的实机质量评估（建议制·默认关不受影响） |
| 38 | + |
| 39 | +## 验证记录 |
| 40 | + |
| 41 | +kb 系 88/88 + kb_embed 系（含引擎缺模型错误路径）全绿；clippy 零；vitest 551/551；tsc 零；Rust 全量（终批门禁）见提交轮记录（预存 note_filter 2 例除外）。 |
0 commit comments