130 lines
8.3 KiB
Markdown
130 lines
8.3 KiB
Markdown
# 阶段 F：Embedding 与知识库问题与解决方案
|
||
|
||
> 记录日期：2026-09-04。涉及分支：`feat/multimodal-pipeline`，前序功能提交：`6eb97bf`。
|
||
> 本文按既有复盘格式记录原因、后果、解决思路、实际方案和验证结果。修复随当前分支提交；合并状态以 Git 与 PR 记录为准。
|
||
|
||
## 1. 背景
|
||
|
||
阶段 F 将占位向量替换为真实本地 Embedding，并加入 API 路由、CPU/CUDA 模型子进程、转写笔记和聊天知识库上下文。联调问题跨越运行环境、索引、持久化与本地处理约束，不能仅根据“模型已下载”判断整条链路正常。
|
||
|
||
```text
|
||
前端 / 后续 Tauri WebView → 后端 API → 模型路由
|
||
→ 带模型空间标识的向量索引 → 知识检索 / 聊天来源
|
||
```
|
||
|
||
## 2. 问题总览
|
||
|
||
| 编号 | 问题 | 后果 | 实际方案 |
|
||
| --- | --- | --- | --- |
|
||
| F-01 | 配置、推理与索引错误共用提示 | 已有模型却被提示未配置 | 区分推理错误与索引错误 |
|
||
| F-02 | Windows 热重载事件循环不支持异步子进程 | 命令行成功，HTTP 失败 | 线程管道子进程兼容路径 |
|
||
| F-03 | 重建忽略向量失败，异常游标未关闭 | 虚报成功或阻塞重建 | 严格校验、回滚和显式关闭 |
|
||
| F-04 | 搜索记录仅保存在内存或浏览器 | 刷新丢失，桌面无法统一管理 | SQLite 历史与 API |
|
||
| F-05 | 聊天忽略 `use_rag` | 没有知识库内容 | 真实 Block 上下文与来源事件 |
|
||
| F-06 | 本地转写导出未传递限制 | 正文可能发送给远程 Embedding | 持久化本地索引标记 |
|
||
| F-07 | 推理结束才读取当前模型标识 | 向量与空间错配 | 冻结模型、revision 和设备配置 |
|
||
|
||
## 3. F-01 / F-03：模型可用不等于索引可用
|
||
|
||
### 原因与后果
|
||
|
||
`embed_remote` 捕获异常后返回 `None`，上层将调用失败与索引缺失统一显示为“请配置 Embedding”。默认库曾有 29 个 Block 和模型元信息，但没有向量侧表。普通保存允许降级保留正文，这一策略又被用于严格重建，导致没有向量也可能报告完成。异常回溯保留查询游标时，还会影响后续写事务。
|
||
|
||
### 解决思路与实际方案
|
||
|
||
纯向量查询使用严格错误处理：模型失败保留安全错误码；模型可用但索引缺失时返回 `SEMANTIC_INDEX_UNAVAILABLE`，明确提示重建。混合检索仍可退到全文检索。重建先准备向量，再进入事务，检查空间一致和完整覆盖，失败保留旧索引。查询游标在 `finally` 中关闭。
|
||
|
||
前序真实本地验证：重建后 29 个 Block 对应 29 条向量，查询返回 20 条结果。这是当时样本库的历史记录，不代表全部环境与规模。
|
||
|
||
## 4. F-02：Windows 热重载下本地模型无法启动
|
||
|
||
### 原因与后果
|
||
|
||
Windows 下 `uvicorn --reload` 使用的事件循环可能不支持 `asyncio.create_subprocess_exec`，抛出 `NotImplementedError`。模型与依赖均已安装，普通 `asyncio.run` 冒烟成功，但实际 HTTP 请求失败。第一轮只修提示和索引，未覆盖此启动方式。
|
||
|
||
### 实际方案与验证
|
||
|
||
优先保留异步子进程，仅在不支持时使用 `ThreadedProcess`。同步创建进程以避免取消时失去进程归属；管道读写与等待在线程中执行，保留输出上限、隐藏窗口、超时、取消和回收逻辑。
|
||
|
||
修复后通过前端实际连接的 `/api/search` 验证成功；测试覆盖真实小子进程的结果读取与取消回收。重新安装权重不能解决此类事件循环兼容问题。
|
||
|
||
## 5. F-04 / F-05：搜索记录与聊天知识库
|
||
|
||
### 原因与后果
|
||
|
||
历史最初包含硬编码示例并只在内存更新；第一轮改成 `localStorage` 虽解决刷新丢失，却不符合后续 Tauri 统一管理应用数据的要求。聊天只有 `use_rag` 字段，没有执行检索。
|
||
|
||
### 实际方案
|
||
|
||
SQLite v5 增加 `search_history`，保留最近 10 条去重查询，重复项置顶。记录属于配置的 `APP_DB_PATH`，Tauri 可复用后端；这不等于已实现 Rust 原生存储。此前浏览器记录没有自动迁入 SQLite。
|
||
|
||
| 方法 | 路径 | 行为 |
|
||
| --- | --- | --- |
|
||
| POST | `/api/search` | 记录提交的非空查询，再执行检索 |
|
||
| GET | `/api/search/history` | 返回 `{"queries": [...]}`，最近项在前 |
|
||
| DELETE | `/api/search/history` | 清空历史，返回空数组 |
|
||
|
||
前端通过 API 加载与清空，失败显示错误。聊天开启知识库时最多取 6 个来源，每段正文最多 3000 字符、合计最多 12000 字符；资料明确标为非指令，SSE 返回 `Citation` 供定位。关闭时不附加笔记，无命中时不生成来源。请求与事件测试不等于外部模型回答质量验收。
|
||
|
||
## 6. F-06：仅本地转写的笔记索引
|
||
|
||
### 原因与后果
|
||
|
||
`create_transcript_note` 调用通用 `create_note`，后者默认执行 API Embedding。转写本身遵守 `local_only`，导出索引却可能上传正文。只增加临时调用标记也无法覆盖后续重建。
|
||
|
||
### 实际方案
|
||
|
||
仅本地任务新生成的 Markdown 写入 frontmatter：
|
||
|
||
```yaml
|
||
---
|
||
embedding_local_only: true
|
||
---
|
||
```
|
||
|
||
解析器读取标记，索引向路由传入 `local_only=True`，跳过远程绑定与凭据解析。普通笔记保持 API 优先和本地回退。本地向量失败时，普通保存仍可保留正文与全文索引；严格重建报错并保留旧索引。
|
||
|
||
标记随 Vault 持久化，编辑保留标记和重建时继续生效。此标记约束 Embedding，不是笔记的通用联网权限；显式开启远程聊天知识库仍可能提供相关片段。旧导出笔记不会自动补标记，必要时应人工补入；删除标记恢复普通索引路由。
|
||
|
||
## 7. F-07：异步推理中的模型空间一致性
|
||
|
||
### 原因与后果
|
||
|
||
请求开始使用 Bekko，推理期间切到 Granite，结束时重新读取 `model_id` 就可能把旧向量标为新模型。两者都是 384 维，维度校验无法发现错误。
|
||
|
||
### 实际方案
|
||
|
||
进入本地路径时调用 `LocalEmbedding.snapshot()` 复制模型和设备配置。通过请求级 `ContextVar` 将相同配置传给 Runtime，结束或异常时恢复上下文；返回模型标识取自同一快照，下一请求使用新设置。
|
||
|
||
快照仅在实际进入本地路径时创建，避免正常 API 请求额外依赖本地配置。API 的 URL、模型、维度和请求扩展冻结规则保持不变。
|
||
|
||
## 8. 回退行为与验证
|
||
|
||
| 场景 | 预期 |
|
||
| --- | --- |
|
||
| 普通请求，API 有效 | 使用 API，不执行本地推理 |
|
||
| 普通请求，无 API | 使用本地模型 |
|
||
| 普通请求，API 失败或响应无效 | 回退本地，保留 `fallback_reason` |
|
||
| 本地限定索引，存在 API | 不请求 API、不解析远程凭据 |
|
||
| 本地限定后再发普通请求 | API 仍可调用，不泄漏临时限制 |
|
||
| 推理期间修改设置 | 当前向量与身份一致，下一请求采用新设置 |
|
||
| 空间混用或索引覆盖不完整 | 严格重建拒绝提交，不混合不同向量空间 |
|
||
|
||
本地限定笔记与远程索引并存时，现有完整覆盖检查可能使纯向量查询提示不完整、重建拒绝混合空间；混合检索仍可退到全文检索。不能为获得完整远程索引而绕过本地标记。
|
||
|
||
提交审阅时已用隔离数据库复现：一篇普通 API 笔记与一篇本地限定笔记共存，配置未变化，全量重建仍返回 `EMBEDDING_SPACE_CHANGED`。此项列为合并阻碍，尚未修复；后续需区分预期的处理策略差异和实际配置漂移，并明确各向量空间的索引覆盖范围。
|
||
|
||
本轮在 `backend/` 执行：
|
||
|
||
```powershell
|
||
.venv/Scripts/python.exe -m pytest tests/test_model_routing.py tests/test_media_jobs.py tests/test_routed_retrieval.py tests/test_local_models.py -q -p no:cacheprovider
|
||
```
|
||
|
||
结果：132 项通过，覆盖 API 回退、本地限定导出和重建、模型切换及 Windows 子进程路径，不调用真实外部 API；有既有 Starlette/httpx 弃用提示。
|
||
|
||
前序持久化修复记录：后端搜索历史、聊天与媒体相关 9 项，前端搜索与聊天 5 项及类型检查通过。各轮结果是针对性验证，不相加当作全仓测试数。
|
||
|
||
## 9. 工程经验
|
||
|
||
区分配置、权重安装、推理运行、索引覆盖四种状态；按用户实际启动方式验证；跨异步边界冻结身份；持久化处理限制；增加限制时也验证普通 API 回退没有被破坏。
|