Merge origin/main into feat/export-service
同步 main（054f704），解决 contracts.py / main.py / README.md / 技术栈说明 的合并冲突。 - contracts.py：保留 pydantic 多行导入并新增 RequestOverride - main.py：合并 lifespan（导出孤儿清理 + 转写/本地模型生命周期） - README.md / 技术栈说明：文档取 main 最新版本 Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
Claude Code
@@ -0,0 +1,28 @@
|
||||
# Frontend phase2：PR #23 关闭意见修复
|
||||
|
||||
对应评论：https://gitea.kronecker.cc/Kronecker/NotesAgentic/pulls/23#issuecomment-97
|
||||
|
||||
本次在独立克隆目录整合 `feat/frontend-phase2-themes-trace-mermaid`（`f273fef`）与 `main`（`352557d`），处理关闭评论中的两项 P2 问题及合并冲突。
|
||||
|
||||
## 修复内容
|
||||
|
||||
- 主题安装和列表加载仅处理存储，不挂载 CSS。切换主题时先校验目标 CSS，再移除旧主题样式并仅挂载当前自定义主题；切回内置主题时清除自定义样式。
|
||||
- 插件设置保存记录提交时的编辑版本。请求期间的新编辑保留未保存状态，可再次提交；失败保留输入并允许重试。切换插件后，旧加载和保存响应不再覆盖当前插件状态。
|
||||
- 解决 9 个冲突文件，保留 main 的聊天记录持久化、会话并发修复、中英文支持及完整 Shiki 语言与图标能力，同时保留 phase2 的 Trace、引用导航、主题包、Mermaid 和共享插件命令表单。
|
||||
- 内置主题列表继续随界面语言响应式更新，自定义主题列表由安装记录派生，避免维护多份可变列表。
|
||||
|
||||
## 验证
|
||||
|
||||
- 39 个前端测试文件、224 项测试通过，包含 main 与 phase2 原有用例及新增回归测试。
|
||||
- 类型检查和生产构建通过；仍有大体积 chunk 提示。
|
||||
- 临时恢复旧主题服务和旧插件设置面板后，5 项新增回归测试按预期失败；随后恢复修复代码。
|
||||
- 独立浏览器验证页使用真实组件、主题存储及 Mermaid/Shiki 渲染；插件设置请求由页内测试接口延迟返回，不访问实际插件后端。
|
||||
- 浏览器确认安装未启用主题无样式影响、多主题切换无残留、回到内置主题清除样式；保存期间继续输入后可再次保存最新值；浅色和深色下 Mermaid 与 Shiki 均生成正常内容。
|
||||
|
||||
未执行生产插件后端的端到端验收；本次不包含后端实现修改。
|
||||
|
||||
## 再次审阅后的修复
|
||||
|
||||
- 密钥保存使用提交快照，只清空未变化的输入；保存失败保留草稿。密钥保存、删除与普通设置保存互斥，切换插件或卸载组件后忽略旧响应。
|
||||
- 未安装社区主题的预览改为独立、禁用脚本的 iframe，使用该社区主题的实际 CSS。打开和关闭预览不安装主题、不修改当前主题及持久化设置，也不保留延时回滚任务。
|
||||
- 最新验证：40 个测试文件、233 项测试通过，类型检查和构建通过；浏览器确认深色社区主题在预览窗口中生效，外层仍为浅色主题，关闭后预览被移除。
|
||||
@@ -0,0 +1,146 @@
|
||||
# 多模态管线与模型运行
|
||||
|
||||
更新日期：2026-09-04。阶段 F 实现位于 `feat/multimodal-pipeline`，接口以 `/openapi.json` 为准。
|
||||
|
||||
## 安装
|
||||
|
||||
API 保留 `backend/.venv`，模型依赖安装到独立的 `backend/.venv-models`。在项目根目录执行：
|
||||
|
||||
```powershell
|
||||
# 默认 CPU
|
||||
./backend/scripts/install-model-runtime.ps1
|
||||
# CUDA 显式选装，不安装或修改 NVIDIA 驱动
|
||||
./backend/scripts/install-model-runtime.ps1 -Device cuda
|
||||
```
|
||||
|
||||
脚本固定 torch/torchaudio 2.9.1，分别选择 CPU / cu128 wheel；其他已验证依赖由 `model-requirements.lock` 锁定。不要求 vLLM、FlashAttention。`APP_MODEL_PYTHON` 可指定模型解释器。
|
||||
|
||||
设置 → 模型提供商 → 本地模型提供下载、续传、删除、设备与预算配置。推理不自动下载；“已下载并校验”不代表设备已通过推理验证，最近实际设备与诊断单独显示。
|
||||
|
||||
默认 CPU、2 线程、8 GiB 内存预算。独立子进程按需加载，每任务结束释放，取消/超时终止并回收进程。单模型串行执行，排队中的交互向量请求优先于转写，不抢占运行中任务。请求 CUDA 但不可用时回退 CPU，记录原因。任务冻结运行配置。当前要求单 API worker，不支持跨进程调度。
|
||||
|
||||
## 模型与许可
|
||||
|
||||
| 能力 | 模型 | 固定 revision | 权重许可 |
|
||||
| --- | --- | --- | --- |
|
||||
| 默认 Embedding | hotchpotch/bekko-embedding-v1-a8m | c721113d59a1d91b447450324f51c4b3332c924a | MIT |
|
||||
| 可选 Embedding | ibm-granite/granite-embedding-97m-multilingual-r2 | 835ad14087e140460703cf0fae09f97d469d65c2 | Apache-2.0 |
|
||||
| 转写、语言识别 | Qwen/Qwen3-ASR-0.6B | 5eb144179a02acc5e5ba31e748d22b0cf3e303b0 | Apache-2.0 |
|
||||
| 声纹相似度 | iic/speech_eres2netv2_sv_zh-cn_16k-common | 3317286545c587ae682dbc166831d9448780eebb | Apache-2.0 |
|
||||
|
||||
来源：[Bekko](https://huggingface.co/hotchpotch/bekko-embedding-v1-a8m)、[Granite](https://huggingface.co/ibm-granite/granite-embedding-97m-multilingual-r2)、[Qwen3-ASR](https://huggingface.co/Qwen/Qwen3-ASR-0.6B)、[ERes2NetV2](https://modelscope.cn/models/iic/speech_eres2netv2_sv_zh-cn_16k-common)。下载固定 revision；HF LFS / ModelScope 校验 SHA-256，HF 普通文件校验 Git blob hash。中断保留 .partial，使用 Range 续传；校验失败、磁盘不足和中断分别记录。
|
||||
|
||||
## 媒体接口
|
||||
|
||||
| 方法与路径 | 行为 |
|
||||
| --- | --- |
|
||||
| POST /api/media/attachments?filename=... | 二进制上传，宿主分配 ID，25 MiB 上限 |
|
||||
| GET /api/media/attachments/{id} | 受控读取，支持播放器 Range |
|
||||
| POST /api/media/transcriptions | 202/queued；local_only、diarization、terminology、idempotency_key |
|
||||
| GET /api/media/transcriptions | 按状态分页查询 |
|
||||
| GET /api/media/transcriptions/{id} | 状态、分段、原文、修订、进度 |
|
||||
| GET /api/media/transcriptions/{id}/events | SSE；after / Last-Event-ID 回放 |
|
||||
| POST /api/media/transcriptions/{id}/cancel | 取消排队或运行任务 |
|
||||
| POST /api/media/transcriptions/{id}/retry | 新 attempt，保留 previous_job_id |
|
||||
| PATCH /api/media/transcriptions/{id} | revision 乐观锁校对、重命名 |
|
||||
| GET /api/media/transcriptions/{id}/revisions | 历史修订 |
|
||||
| POST /api/media/transcriptions/{id}/notes | Knowledge 写入；任务/修订/选项幂等 |
|
||||
| POST /api/media/speaker-matches | 两附件声纹比对，支持 local_only |
|
||||
| GET /api/media/attachments/{id}/cleanup-impact | 清理影响与保留笔记 |
|
||||
| DELETE /api/media/attachments/{id} | 清理附件、转写正文、修订及术语 |
|
||||
|
||||
任务、模型快照、事件和修订写入 SQLite。重启把未完成任务标为 TRANSCRIPTION_INTERRUPTED，不自动重新上传。幂等摘要包含内容、选项、模型和提供商配置；同键不同输入返回 409。
|
||||
|
||||
API 优先，无配置或无效结果时本地回退。local_only 禁止远程模型。纯文本附件和既有 sidecar 可导入，但已有真实音频时不使用旁边文本冒充识别。
|
||||
|
||||
PyAV 提取音轨至 16 kHz 单声道，最长 1 小时，禁止解码器网络协议。能量分段后交给 Qwen3-ASR，返回片段边界，不宣称逐字对齐。ERes2NetV2 提取片段声纹并按相似度聚类；短片段、同段多人、重叠发言需要人工校对。缺失能力返回 DIARIZATION_UNAVAILABLE；未启用逐字对齐返回 WORD_TIMESTAMPS_UNAVAILABLE。
|
||||
|
||||
术语是识别后的替换规则，保留原始文本和来源。重命名只修改显示名，稳定 ID 不变。笔记包含音频与时间跳转链接；重复导出不覆盖用户编辑。清理保留已导出笔记，音频链接失效，已清理任务不可重试。重建索引保留转写与笔记关联。
|
||||
|
||||
## 向量空间
|
||||
|
||||
生产使用真实模型；HashEmbeddingProvider 仅供测试注入。本地/API 向量都写入按模型空间隔离的 routed_block_vectors；不同模型、revision、接口或维度不混用。旧 128 维测试索引不用于真实查询。
|
||||
|
||||
模型不可用时仍可保存 Markdown/FTS；语义查询返回索引未就绪，混合查询可使用全文检索。切换模型后重建全部索引。Benchmark 验证当前空间完整覆盖。
|
||||
|
||||
## Token 用量
|
||||
|
||||
GET /api/usage 使用带时区的 start/end（左闭右开），支持 provider_id、model、source。页面提供今日、7 天、30 天、自定义时段。
|
||||
|
||||
按实际 attempt 保存 request_id、Agent run_id、模型、来源、时间、原始数值与归一化计数。覆盖 Chat、流式、Agent、Embedding、媒体及本地推理。累计快照取最大值并 upsert；回放不新增请求，真实重试有新 attempt。流中断保留已收到计数。
|
||||
|
||||
输入缓存按供应商口径归一化，推理不重复加入输出；缓存命中率按完整输入口径加权。缺失为 null，显示每项覆盖数。本地 Embedding 使用真实 tokenizer，其他本地能力不编造 Token。写入失败不影响回复；原始 usage 仅保留数值白名单。本应用观测值不是厂商账单。
|
||||
|
||||
## 自定义请求 JSON
|
||||
|
||||
request_overrides 每项含 capability、model（空表示全部）、stream（null 表示全部模式）、body。通用规则先于模型规则，同层显式流式规则优先。对象递归合并、数组替换、标量覆盖、null 保持实际值；删除键恢复继承。
|
||||
|
||||
```json
|
||||
{
|
||||
"capability": "chat",
|
||||
"model": "special-model",
|
||||
"stream": true,
|
||||
"body": {
|
||||
"stream_options": { "include_usage": true },
|
||||
"enable_thinking": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
model、消息、系统提示、工具、媒体文件、stream 由宿主管理，冲突拒绝。禁止 body 注入凭据、Header、URL，无模板求值。媒体独立匹配规则，嵌套扩展作为 JSON 文本 multipart 字段，不接收聊天规则。是否支持某扩展由供应商决定。
|
||||
|
||||
POST /api/providers/request-preview 不联网，隐藏正文/文件且不包含凭据。表单有格式化、校验、删除规则、预览；Provider version 检测保存冲突，适配器冻结配置。原有连接测试只验证模型列表连通性，不等于厂商推理接受扩展字段。
|
||||
|
||||
## 验证记录
|
||||
|
||||
### 阶段 F 收尾行为（2026-09-05）
|
||||
|
||||
CUDA 页面安装入口：**设置 → 模型提供商 → 本地模型 → CUDA 运行组件（可选）**。未安装时显示“下载并安装 CUDA 组件”；安装中展示真实阶段和不定进度条，失败可重试。后端仅运行项目内固定安装脚本，写入独立 `.venv-models-cuda`，检查依赖及 CUDA wheel 后才标记就绪。已有环境会先检查；成功后选择 CUDA 并保存运行设置即可使用，CPU 环境保留。显式 `APP_MODEL_PYTHON` 继续优先，页面提示覆盖关系。当前页面安装支持 Windows，需后端能找到 uv；不会自动安装显卡驱动。
|
||||
|
||||
- 模型卡片读取权重目录的实际文件大小，包含未完成下载的文件；下载进度与磁盘占用分别显示。
|
||||
- 本地任务串行执行；等待队列中交互检索优先级为 0，媒体任务为 10，后台笔记索引为 20。同级 FIFO，不抢占已运行任务。
|
||||
- 默认 CPU。选择 CUDA 后，设备不可用直接使用 CPU；CUDA 初始化失败或显存不足时先释放原子进程，再用冻结的同一任务配置重试 CPU 一次。其他错误不触发设备重试；用户取消不会启动后续尝试。重试会清除上一尝试的部分转写片段。
|
||||
- 安装脚本固定 CPU/CUDA wheel 为 `2.9.1+cpu` / `2.9.1+cu128`，避免已有 CPU wheel 被误认为满足 CUDA 安装。可用 `-RuntimeDirectory` 指定独立环境，后端通过 `APP_MODEL_PYTHON` 选择；不自动更换显卡驱动。
|
||||
- 运行诊断写入应用 SQLite，保留最近 200 条，覆盖本地成功、失败、取消及能力 API 调用/回退事件。仅保留模型、设备、数值耗时、资源、状态码及请求标识，不保存输入、文件路径、密钥或异常全文。排队取消不记作实际模型用量；设备重试有独立 attempt，共享逻辑 request_id。
|
||||
- 前端同一次提交在响应丢失后复用上传和任务幂等键；收到附件 ID 后只重试创建任务。“重新处理为新任务”明确创建新标识。客户端待提交状态仅在当前页面内存中，已接收任务和结果由后端持久化。
|
||||
- 转写修订可选择“更新已导出笔记”。后端在 Vault 写锁内校验上次导出内容摘要，保留 note_id 和本地索引限制。用户编辑过正文时返回冲突，不覆盖；旧记录没有摘要时需先创建新笔记。重建索引保留导出基线与关联。
|
||||
- 用量卡片单列音频实际调用次数、已报告时长和覆盖次数；时长不换算为 Token。重试分别计数，历史未知数据保持“未提供”。
|
||||
- 请求 JSON 可导入、导出和恢复默认。文件格式为 `{ "version": 1, "request_overrides": [...] }`，只包含扩展规则；服务端复用受保护字段与凭据校验，导入成功仍需保存提供商才生效。
|
||||
- 请求预览不联网。聊天“发送测试推理请求”使用当前草稿、已保存的凭据引用和固定短消息，支持流式/非流式，不读取知识库、工具或附件，并计入真实用量。更改模型、连接、规则或 JSON 有效性后，旧结果和迟到响应失效；媒体规则继续通过真实媒体操作验收。
|
||||
|
||||
独立 CUDA 环境示例（不改变默认 CPU 环境）：
|
||||
|
||||
```powershell
|
||||
./backend/scripts/install-model-runtime.ps1 -Device cuda -RuntimeDirectory ./backend/.venv-models-cuda
|
||||
$env:APP_MODEL_PYTHON = (Resolve-Path ./backend/.venv-models-cuda/Scripts/python.exe).Path
|
||||
```
|
||||
|
||||
设置环境变量后需从同一终端重启后端；CPU 默认仍可用。模型权重与运行环境不提交仓库。
|
||||
|
||||
### 2026-09-04 联调修复补充
|
||||
|
||||
Windows 热重载不支持异步子进程时使用线程管道兼容路径。本地 Embedding 进入推理前冻结模型与设备配置，向量空间标识来自同一快照；普通 API 成功及失败回退策略保持不变。
|
||||
|
||||
仅本地转写新生成的笔记增加 `embedding_local_only: true` frontmatter，索引与后续重建跳过远程 Embedding。它只约束索引，不是通用的笔记联网权限；旧导出笔记需人工补标记。SQLite v6 将策略保存到 Block，重建按普通/仅本地策略分别校验空间和覆盖，统一事务提交。查询在各空间内排序后用 RRF 合并排名，缺少分区时保留全文检索降级。升级已有库后重建一次以同步策略。
|
||||
|
||||
搜索记录保存在应用 SQLite，使用 `/api/search/history` GET/DELETE 读取和清空。聊天已接入真实知识库上下文与 Citation。详细原因和验证见[阶段 F 问题与解决方案](../retrospectives/阶段F-Embedding与知识库问题与解决方案.md)。
|
||||
|
||||
2026-09-04，Windows / Python 3.12 / torch 2.9.1+cpu：后端 472 项、前端 93 项测试通过，类型检查和生产构建通过，仍有既有大 bundle 警告。Edge 真实 API 页面、播放器时长/定位、模型与用量卡片无页面异常。
|
||||
|
||||
真实模型完成音频 → 转写 → 片段声纹 → 笔记 → 语义检索闭环。示例来自固定 ModelScope revision；权重和音频不提交仓库。
|
||||
|
||||
| 实测 | 结果 |
|
||||
| --- | --- |
|
||||
| Bekko 中文小样本 | 384 维；相关相似度 0.495、无关 0.083 |
|
||||
| Qwen3-ASR 短中文音频 | 加载约 11.1 秒、推理约 6.3 秒、峰值约 5.4 GiB |
|
||||
| ERes2NetV2 | 同音频 1.000，不同示例说话人 0.090，片段聚类完成 |
|
||||
| 笔记闭环 | 重复导出同 note_id，语义检索找回同笔记 |
|
||||
|
||||
这是功能冒烟，不是代表性课程语料完整质量评估。CUDA 实机、Granite 对照、逐字强制对齐及重叠语音质量未验证。每任务释放模型有加载成本；长音频准确率、阈值与吞吐需要目标机器专项验收。
|
||||
|
||||
```powershell
|
||||
cd backend
|
||||
.venv/Scripts/python scripts/local-model-smoke.py bekko --download
|
||||
.venv/Scripts/python scripts/local-model-smoke.py qwen3-asr --download --audio C:/path/to/speech.wav
|
||||
.venv/Scripts/python scripts/local-model-smoke.py eres2netv2 --download --audio C:/path/to/speech.wav --reference C:/path/to/reference.wav
|
||||
```
|
||||
@@ -0,0 +1,55 @@
|
||||
# 阶段 F 收尾验收记录
|
||||
|
||||
日期：2026-09-05。对应 `feat/multimodal-finalization`，基于 `6bdba2c`（阶段 F 主分支合并）。
|
||||
|
||||
## 完成范围
|
||||
|
||||
本轮补齐运行诊断持久化、真实磁盘占用、后台索引优先级、CUDA 设备失败时 CPU 单次重试、上传与任务重试幂等、跨修订安全更新笔记、音频用量分项，以及请求 JSON 导入/导出/重置和实际聊天推理验证。原有 API 优先、无配置/无效响应使用本地模型、local_only 禁止远程调用的流程继续保留。
|
||||
|
||||
具体行为见[开发说明](多模态管线与模型运行开发说明.md)，接口见[开发版契约](../contracts/第二阶段接口契约-开发版.md)，故障与修复见[问题记录 F-13～F-15](../retrospectives/阶段F-Embedding与知识库问题与解决方案.md)。
|
||||
|
||||
## 自动化与页面验证
|
||||
|
||||
| 项目 | 结果 |
|
||||
| --- | --- |
|
||||
| 后端全量 `python -m pytest -q -p no:cacheprovider` | 559 通过；1 条已有 Starlette/httpx 弃用提示 |
|
||||
| 前端全量 `npm test -- --run` | 29 个文件、103 项通过 |
|
||||
| 类型与生产构建 `npm run build` | vue-tsc 与 Vite 构建通过，仍有既有大 bundle 提示 |
|
||||
| `git diff --check` | 通过 |
|
||||
| 真实页面 | 模型卡片读取实际大小；音频统计显示真实缺失；提供商表单展示请求编辑、恢复默认、导入/导出及推理验证入口 |
|
||||
| 请求 Adapter 验证 | 隔离 HTTP Transport 检查最终流式/非流式请求和扩展字段，不访问外部供应商 |
|
||||
| 失败恢复 | 初始化/OOM 故障注入、CPU 再失败、进程回收、队列顺序、重复提交、修订冲突和旧结果失效均覆盖 |
|
||||
|
||||
## CPU / CUDA 真实模型闭环
|
||||
|
||||
Windows、Python 3.12。保留原 `.venv-models` CPU 环境，独立安装 `.venv-models-cuda`；安装后检查 `torch=2.9.1+cu128`、`cuda_available=True`。显卡为 NVIDIA GeForce RTX 4060 Laptop GPU。
|
||||
|
||||
CPU 与 CUDA 分别创建隔离 Vault、附件目录和 SQLite，只读取固定 revision 权重；运行短中文音频 → Qwen3-ASR → ERes2NetV2 片段聚类 → Markdown 笔记 → Bekko 语义检索 → 修订更新。两次均返回已完成，检索命中同一笔记，更新保留 note_id 和 `embedding_local_only: true`，结束后本地运行队列无活跃任务。CPU 实际设备为 `cpu`，CUDA 各次实际设备为 `cuda:0`。
|
||||
|
||||
| CUDA 环节 | 权重 revision | 加载 / 推理耗时 |
|
||||
| --- | --- | --- |
|
||||
| Qwen3-ASR-0.6B | `5eb144179a02acc5e5ba31e748d22b0cf3e303b0` | 30.375 / 3.234 秒 |
|
||||
| ERes2NetV2 片段聚类 | `3317286545c587ae682dbc166831d9448780eebb` | 5.735 / 0.578 秒 |
|
||||
| Bekko 首次笔记索引 | `c721113d59a1d91b447450324f51c4b3332c924a` | 19.860 / 0.656 秒 |
|
||||
|
||||
这些是单次功能冒烟观察值；运行期间有其他验证任务，不用于宣称吞吐或 CPU/GPU 性能倍率。短样本只产生 1 个片段和 1 个 speaker，不能验证多人重叠语音质量。CUDA OOM 恢复使用故障注入，并非实机显存耗尽测试。
|
||||
|
||||
## 中文 Embedding 小样本对照
|
||||
|
||||
固定 8 篇人工构造的短文，主题为线性代数、死锁、Python 函数、语义检索、光合作用、备份及两个无关干扰项（晚餐、篮球）。6 条改写查询，各有一个预期相关文档；对全部文档做余弦排序。
|
||||
|
||||
| 模型 | revision | Hit@1 / Recall@5 / MRR |
|
||||
| --- | --- | --- |
|
||||
| Bekko A8M | `c721113d59a1d91b447450324f51c4b3332c924a` | 1.0 / 1.0 / 1.0 |
|
||||
| Granite 97M Multilingual r2 | `835ad14087e140460703cf0fae09f97d469d65c2` | 1.0 / 1.0 / 1.0 |
|
||||
|
||||
两者在这 6 条查询上的目标排名均为 1。该结果仅证明中文检索冒烟可运行，样本量不足以区分模型优劣；继续保留 Bekko 默认、Granite 可选。
|
||||
|
||||
## 未关闭的专项验收
|
||||
|
||||
- 带参考转写和说话人标注的真实课程长录音尚未提供，不能报告 CER/WER、DER、阈值或长音频吞吐达标。
|
||||
- 现阶段时间戳为片段级；逐字强制对齐、同段多人/重叠语音仍未实现，不将片段聚类视为完整说话人分离。
|
||||
- 外部供应商特殊 JSON 的兼容性，需要在目标账号和模型上点击实际推理验证；离线协议通过不替代厂商验收。
|
||||
- Tauri/Rust Host 和生产 MCP 沙箱按后续阶段安排；本轮数据持久化在后端 SQLite/Vault，为桌面集成保留稳定接口。
|
||||
|
||||
结论：阶段 F 本轮工程收尾已实现并完成 CPU/CUDA 功能验收；上述质量及外部服务专项保持待验收状态，不标记为全部通过。分支仍需独立审阅后决定合并。
|
||||
Reference in New Issue
Block a user