dsh-data-domain-knowledge 0.1.0-alpha.11 → 0.1.0-alpha.13

package/README.md

@@ -3,17 +3,39 @@
 本地知识库插件：一个知识库是一个目录，里面四样东西。`knowledge.db` 保存 **SourceRaw**
 （原始可追溯文档）、按主题聚合可双向链接的 wiki 卡片，以及**两者的每一个版本**；
 `derived.db` 输出可检索的 **wikiNotes**、wiki
-知识图谱和向量索引，`<agentRoot>/memory/<库 id>` 保存版本快照、访问审计与反馈。默认使用本地 WeMM Python backend：从 WeMM
-原生 2048 维向量按 MRL 截取 1024 维，先做 binary/Hamming 粗筛，再用 int8 点积精算余弦
-（这是**向量路内部的粗排 → 精算**，与 stage 4 的 cross-encoder **重排**不是一回事）；
-模型不可用时明确降级到 FTS，不会伪造向量结果。Markdown 中的
-本地图片会与正文一起交给 WeMM，因此图片不是独立知识类型。
+知识图谱和向量索引，`<agentRoot>/memory/<库 id>` 保存操作日志、抽取轨迹、访问审计与反馈。
+默认使用本地 Python 推理：`BAAI/bge-small-zh-v1.5` 生成 512 维文本向量，
+`BAAI/bge-reranker-base` 对召回候选做交叉编码重排。部署入口必须完成环境自检，
+索引必须匹配当前模型；不满足时提示准备环境或重新编译。
+需要图片语义检索时，可配置 WeMM 多模态模型与匹配维度，Markdown 中的本地图片
+会与正文一起交给模型。图片不作为独立知识类型。
 
 Tita Agent 的固定数据根目录是 `$DSH_HOME/tita-agent`（默认 `~/.dsh/tita-agent`）。
 设置面板只展示这个目录并提供「打开目录」，不允许切换根路径；知识库、意图记录、记忆、
 模型和 Python 环境都从这里派生。
 
-## 承载范围（五个视图）
+## 首次运行环境准备
+
+向量模型和重排模型是部署必需项。打开 Tita 设置 → 环境准备 → 一键安装 / 修复。
+系统用 DSH 自带的 Python 3.12 创建专属依赖环境，不另行下载 Python；再下载固定 revision 的 `BAAI/bge-small-zh-v1.5`
+（512 维）和 `BAAI/bge-reranker-base`，然后运行真实推理自检。阶段、错误和下载日志
+可查看；下载失败可以重试。未就绪时阻止编译和知识召回，来源与历史内容仍可保存、读取。
+自检不单独检查 `sentencepiece`；依赖安装失败会显示安装错误，模型真实推理失败会显示对应模型的错误。
+
+命令行入口：
+
+```bash
+pnpm --filter dsh-data-domain-knowledge environment:prepare
+pnpm --filter dsh-data-domain-knowledge environment:check
+pnpm --filter dsh-data-domain-knowledge doctor
+```
+
+自检失败时命令返回非零退出码。依赖装在 Tita 专属虚拟环境中，不修改系统 Python，也不隐式运行 npm postinstall
+模型下载。已有知识在准备完成后需重新编译；宿主无需重启。自定义路径保留，使用默认
+资源时把高级设置中的路径恢复为空，并使用匹配的向量维度。
+细节见 [运行环境准备与自检](../../docs/current/16-知识运行环境准备与自检.md)。
+
+## 承载范围
 
 侧边栏 `TitaAgent` 面板的五个视图就是本插件的全部范围：
 
@@ -22,7 +44,7 @@ Tita Agent 的固定数据根目录是 `$DSH_HOME/tita-agent`（默认 `~/.dsh/t
 | `overview` | Agent 概览 | 各设置的挂载节点 |
 | `intent` | 意图 | `intent_record` / `intent_store_view`、`/intent/*` 路由、`titaDataAgentIntent` 服务；会话审计留痕落 `<agentRoot>/intent/` |
 | `knowledge` | 知识库 | `recall_knowledge` 等工具名、`/knowledge/*` 与 `/convert` 路由、`tita-data-agent-knowledge` / `-convert` 设置 |
-| `memory` | 记忆 | 抽取轨迹、轴 / Knowledge 真源、处理日志、`feedback.ndjson`、`access-audit.ndjson`，根在 `<agentRoot>/memory/<库 id>`；磁盘目录布局 |
+| `memory` | 记忆 | 抽取轨迹、处理日志、`feedback.ndjson`、`access-audit.ndjson`，根在 `<agentRoot>/memory/<库 id>`；轴 / Knowledge 真源在主库 |
 | `eval` | 评测 | 问题集格式（开发期能力，不注册运行时入口） |
 
 意图的**会话审计留痕**落在 `<agentRoot>/intent/`：`intent.db` 保存当前记录与追加历史
@@ -53,7 +75,7 @@ Tita Agent 的固定数据根目录是 `$DSH_HOME/tita-agent`（默认 `~/.dsh/t
 | Knowledge | `knowledge` + `knowledge_sources` | 原子事实、坐标、来源、状态；不保存 Card 的排版 |
 | Wiki Card | `card` + `blob` + `revision` | 面向阅读和召回组装的正文；正文中的 Markdown 标题是 Section 真源 |
 | Knowledge 落位 | `card_knowledge` | 记录 Knowledge 在某张 Card 中的 Section 和顺序；这是关联索引，不是 Knowledge 属性 |
-| Wiki Note / FTS / Vector / Graph | 派生文件 | 可以从 Card 和 Knowledge 重新构建，不是真实知识来源 |
+| Wiki Note / FTS / Vector / Graph | `derived.db` | 可以从 Card 和 Knowledge 重新构建；编译结果在同一事务发布 |
 
 ### 状态语义
 
@@ -70,7 +92,29 @@ Knowledge ID 只在一个 `knowledge.db` 内有意义。相同文本在同一个
 
 这意味着当前实现适用于“一个知识库对应一个业务范围”的模型。未来如果一个库需要混合多个租户、环境或有效期，再把 Scope 纳入判重策略。
 
-### Knowledge 类型
+### 身份算法
+
+新 Knowledge ID 使用归一化文本的 SHA-256。归一化保留比较条件、小数、负号和标识符
+分隔符，判重同时比较正文。存量 ID 不重写；人工编辑正文保留 ID 并增加内容版本。
+
+### 来源更新与复核
+
+来源改版后保留旧 Knowledge 和原始证据版本，不自动判定失效。证据记录 `toVersion`，
+读取时返回 `currentVersion`、`evidenceStatus`、`quoteInCurrentVersion`。召回中缺少当前
+可定位证据的知识带 `requiresReview: true`；是否停用仍由人工裁决。
+
+引用定位不等于语义成立。组织校验能拒绝输入中没有出现的数值或比较条件，但不能证明
+任意自然语言陈述成立；召回如实返回 `claimVerification: 'unverified'`。
+
+### 编译发布与一致性
+
+Notes、FTS、向量、图和 manifest 在 `derived.db` 中通过一次事务发布。召回与图查询
+读取已发布快照；失败或取消时保留上一版结果。删除状态立即过滤旧片段。抽取失败不
+保存成功指纹，模型身份、位置或本地文件版本变化会阻止旧向量复用。
+
+目录边界、事务和验证范围见 [知识一致性与编译快照](../../docs/current/15-知识一致性与编译快照.md)。
+
+### Knowledge 类型字段
 
 当前不把 `Fact` / `Rule` / `Procedure` / `Constraint` 加成 Knowledge 的正式列。类型暂作为抽取或 Card metadata 的扩展信息，只有当不同类型需要不同的召回、验证或执行策略时，才升级为结构化字段。
 
@@ -185,20 +229,22 @@ SourceRaw → Knowledge → Wiki Card → Wiki Note → FTS / Vector / Rerank
 
 ## 本地启用 WeMM
 
-在 Apple Silicon 上执行一次（在插件包目录内）：
+推荐使用「环境准备」面板选择 WeMM 量化版或腾讯 BF16 版。面板会安装所选模型并自动
+设置匹配的维度。也可在 Apple Silicon 上执行旧版辅助脚本（在插件包目录内）：
 
 ```bash
 bash scripts/setup-embedding.sh
 ```
 
-脚本会把 Python 环境放到 `~/.dsh/tita-agent/resource/python`，把量化模型放到
+脚本会用 `DSH_PYTHON`（未设置时为系统 `python3`）建立隔离依赖环境，把模型放到
 `~/.dsh/tita-agent/resource/models/WeMM-Embedding-2B-Quantized`。新配置会自动发现这两个路径；
-设置位于 Tita Data Agent → Agent 概览 →「构建」节点：
+当前脚本安装的是 `ewin-reg` 社区维护的 INT4 / FP8 量化版，不是腾讯官方发行，模型卡将许可标为 `other`。
+它的输出维度为 2048。设置位于 Tita Data Agent → Agent 概览 →「构建」节点：
 
 - Provider：`WeMM Python（本地）`
 - Python：`~/.dsh/tita-agent/resource/python/bin/python`
 - Model：`~/.dsh/tita-agent/resource/models/WeMM-Embedding-2B-Quantized`
-- 维度：`1024`
+- 维度：`2048`
 - 设备：`自动（优先 MPS）`
 
 知识库默认保存在 `~/.dsh/tita-agent/domain_knowledge/<库 id>`。点击「编译」后，
@@ -285,6 +331,11 @@ HTTP `GET /knowledge/bases` 在返回前先刷新。
 | `derived.db` | wikiNotes、知识图谱、检索索引 | 可重新编译 |
 | `assets/` | 来源图片与附件 | 丢失对应素材 |
 
+知识库提供 `images.publish` 工具作为本地图床。它接收宿主本地 `file_path` 或 Base64 图片，按
+`assets/<SHA-256 前 12 位>/<文件名>` 写入当前知识库，并返回 `/knowledge/assets/<kb>/<路径>` 地址
+和 Markdown 图片引用。独立图床图片不要求来源或卡片引用，也不会被孤儿清理误删。工具会校验图片格式和 MIME，
+单张图片上限为 20 MiB；写入不需要用户审批。
+
 `resource/` 保存模型、Python 环境与 `knowledge-bases.json`。
 如果资源目录没有本地 Python 或模型，就使用 `python3` 或 Hugging Face 模型名。
 

package/eval/README.md

@@ -1,19 +1,26 @@
 # Tita Knowledge Retrieval Evaluation
 
 `evaluate-retrieval.mjs` 对同一份已经编译好的 Knowledge Store，逐条运行
-`fts`、`vector`、`hybrid`，输出 Recall、MRR、nDCG 和 p50/p95 latency。它不自动
+`fts`、`vector`、`hybrid`，输出 Recall、MRR、nDCG、弃答准确率和 p50/p95 latency。它不自动
 下载公开数据集，也不会改写知识库；公开数据集需要先转换为本插件的 qrels 格式。
 
 ## qrels 格式
 
 每行一个 JSON 对象，`relevant_unit_ids` 使用编译后的稳定 `unitId`，例如
 `metric:sales_amount`。可以附加 `include_problems` 和 `subset`，用于分组评测文本、
-图片 Markdown、表格截图等场景。
+图片 Markdown、表格截图等场景。`subset` 当前保留在输入中；按子集运行时先分别生成
+qrels 文件，runner 不自动输出子集汇总。
 
 ```json
 {"id":"q1","query":"销售额如何计算","relevant_unit_ids":["metric:sales_amount"],"subset":"text"}
+{"id":"q2","query":"库内没有依据的问题","relevant_unit_ids":[],"subset":"abstention"}
 ```
 
+空 `relevant_unit_ids` 明确表示“不应召回”。必须提供这个字段，避免把漏标注误当作
+弃答样本。正例的 Recall、MRR、nDCG 只使用有正例的查询计算；弃答样本单独输出
+`abstention.count`、`falseAnswers`（任何命中均计为误召回）和 `accuracy`。
+只有弃答样本时，正例指标为 `null`。接口失败会使评测失败，不会当作成功弃答。
+
 ## 本地运行
 
 先在 UI 点击一次「编译」，再运行：
@@ -21,7 +28,7 @@
 ```bash
 pnpm --filter dsh-data-domain-knowledge build
 node plugins/dsh-data-domain-knowledge/eval/evaluate-retrieval.mjs \
-  --root "$HOME/.tita-data-agent/knowledge" \
+  --root "$HOME/.dsh/tita-agent/domain_knowledge/default" \
   --qrels plugins/dsh-data-domain-knowledge/eval/queries.example.jsonl
 ```
 
@@ -29,10 +36,10 @@ node plugins/dsh-data-domain-knowledge/eval/evaluate-retrieval.mjs \
 
 ```bash
 TITA_EVAL_PROVIDER=wemm-python \
-TITA_EVAL_PYTHON="$HOME/.tita-data-agent/embedding-venv/bin/python" \
-TITA_EVAL_MODEL="$HOME/.tita-data-agent/models/WeMM-Embedding-2B-Quantized" \
+TITA_EVAL_PYTHON="$HOME/.dsh/tita-agent/resource/python/bin/python" \
+TITA_EVAL_MODEL="$HOME/.dsh/tita-agent/resource/models/WeMM-Embedding-2B-Quantized" \
 node plugins/dsh-data-domain-knowledge/eval/evaluate-retrieval.mjs \
-  --root "$HOME/.tita-data-agent/knowledge" \
+  --root "$HOME/.dsh/tita-agent/domain_knowledge/default" \
   --qrels ./queries.jsonl
 ```
 
@@ -61,12 +68,13 @@ checkpoint 编译后再跑同一份 qrels。每次比较固定知识卡片、qre
    评测，但它仍然是模型级评测，不是 Tita 端到端评测。
 3. Tita 专属 golden set：建议先人工标注 100–200 条查询，至少包含指标口径、表/字段
    语义、同义词、跨语言、图片中的 UI/图表信息、hard negative 和“不应召回”样本。
-   每条 query 标注 1–3 个正例 unitId；每轮发布前固定这份集合，新增样本走版本控制。
+   有答案的 query 标注 1–3 个正例 unitId；不应召回的 query 使用空集合。每轮发布前
+   固定这份集合，新增样本走版本控制。
 
 ## 指标与门槛
 
 主指标使用 `nDCG@10`、`Recall@10`、`MRR@10`，辅助看 `Recall@5/20`；同时记录
-向量编译吞吐（units/min）、查询 p50/p95、模型常驻内存、`03_compiled` 索引大小和
+弃答准确率和误召回数。另行测量向量编译吞吐（units/min）、模型常驻内存、`derived.db` 大小和
 向量复用率。多模态集合要单独报告 text→image、image→text、text+image 三类结果，
 不能只看总平均。
 
@@ -74,3 +82,6 @@ checkpoint 编译后再跑同一份 qrels。每次比较固定知识卡片、qre
 至少应在语义改写和图片子集上带来可观增益；具体阈值在首轮 100–200 条标注跑完后再
 根据置信区间确定，不预先假设量化版一定优于 BF16。最终结果同时保存 qrels、配置、
 模型 revision、硬件和原始 JSON，确保可复现。
+
+runner 关闭 cross-encoder 重排，比较原始召回路线。完整 Rerank 链路的质量要另行
+测量。自动化回归测试使用小型本地语料和模型替身，不构成真实模型质量门槛的验收结果。

package/eval/evaluate-retrieval.mjs

@@ -56,8 +56,8 @@ if (!limits.length || !modes.length) usage('invalid --k or --modes')
 const lines = (await readFile(args.qrels, 'utf8')).split(/\r?\n/).map(line => line.trim()).filter(Boolean).filter(line => !line.startsWith('#'))
 const qrels = lines.map((line, index) => {
   const item = JSON.parse(line)
-  const relevant = item.relevant_unit_ids ?? item.relevant ?? []
-  if (!item.query || !Array.isArray(relevant) || relevant.length === 0) throw new Error(`qrels line ${index + 1} needs query and non-empty relevant_unit_ids`)
+  const relevant = item.relevant_unit_ids ?? item.relevant
+  if (!item.query || !Array.isArray(relevant)) throw new Error(`qrels line ${index + 1} needs query and relevant_unit_ids (empty means abstain)`)
   return { ...item, relevant_unit_ids: [...new Set(relevant.map(String))] }
 })
 if (!qrels.length) throw new Error('qrels is empty')
@@ -93,26 +93,35 @@ try {
       // is disabled and the raw fused ranking is measured.
       const response = await runtime.recall(qrel.query, maxLimit, qrel.include_problems === true, mode, undefined, { rerank: false })
       latencies.push(performance.now() - started)
+      if (!response.ok) throw new Error(`${qrel.id ?? qrel.query}: ${response.error?.code ?? 'RECALL_FAILED'}`)
       if (response.data.backend === 'fts' && mode !== 'fts') fallbackCount += 1
-      rows.push({ hits: response.data.hits, relevant: new Set(qrel.relevant_unit_ids) })
+      rows.push({ hits: response.data.hits, relevant: new Set(qrel.relevant_unit_ids), subset: qrel.subset ?? 'default' })
     }
     const metrics = {}
     for (const limit of limits) {
       let recall = 0
       let mrr = 0
       let score = 0
-      for (const row of rows) {
+      const positiveRows = rows.filter(row => row.relevant.size > 0)
+      for (const row of positiveRows) {
         const hits = row.hits.slice(0, limit)
         recall += hits.filter(hit => row.relevant.has(hit.unitId)).length / row.relevant.size
         const rank = hits.findIndex(hit => row.relevant.has(hit.unitId))
         mrr += rank < 0 ? 0 : 1 / (rank + 1)
         score += ndcg(row.hits, row.relevant, limit)
       }
-      metrics[`recall@${limit}`] = Number((recall / rows.length).toFixed(4))
-      metrics[`mrr@${limit}`] = Number((mrr / rows.length).toFixed(4))
-      metrics[`ndcg@${limit}`] = Number((score / rows.length).toFixed(4))
+      const divisor = positiveRows.length || 1
+      metrics[`recall@${limit}`] = positiveRows.length ? Number((recall / divisor).toFixed(4)) : null
+      metrics[`mrr@${limit}`] = positiveRows.length ? Number((mrr / divisor).toFixed(4)) : null
+      metrics[`ndcg@${limit}`] = positiveRows.length ? Number((score / divisor).toFixed(4)) : null
+    }
+    const negativeRows = rows.filter(row => row.relevant.size === 0)
+    const falseAnswers = negativeRows.filter(row => row.hits.length > 0).length
+    output.modes[mode] = {
+      metrics, positiveCount: rows.length - negativeRows.length,
+      abstention: { count: negativeRows.length, falseAnswers, accuracy: negativeRows.length ? Number((1 - falseAnswers / negativeRows.length).toFixed(4)) : null },
+      latencyMs: { p50: percentile(latencies, 0.5), p95: percentile(latencies, 0.95) }, fallbackCount,
     }
-    output.modes[mode] = { metrics, latencyMs: { p50: percentile(latencies, 0.5), p95: percentile(latencies, 0.95) }, fallbackCount }
   }
 } finally {
   runtime.close()

package/eval/queries.example.jsonl

@@ -1,2 +1,3 @@
 {"id":"q-agent-architecture","query":"知识编译与召回的 Agent 架构","relevant_unit_ids":["concept:agent_architecture"],"subset":"text"}
 {"id":"q-ui-architecture","query":"Tita 数据 Agent 的界面和架构","relevant_unit_ids":["concept:agent_architecture","concept:ui_reference"],"subset":"text-image"}
+{"id":"q-no-evidence","query":"火星香蕉的年度产量是多少","relevant_unit_ids":[],"subset":"abstention"}