125 lines
9.9 KiB
Markdown
125 lines
9.9 KiB
Markdown
# 聊天知识中心
|
||
|
||
本模块将归档中的单聊文本整理为待审知识，审核发布后由现有模型网关检索引用。知识默认不启用、草稿不会进入检索，原始归档保留。
|
||
|
||
## 首次使用
|
||
|
||
1. 更新管理 API、模型网关与前端，启动知识 Worker。
|
||
2. 管理端进入「知识中心 → 知识加工与检索」，选择具体客户端账号。
|
||
3. 点击「从聊天整理知识」，选择该租户的客服来源账号。建议先设置消息上限 10000，采用规则整理。
|
||
4. 在「加工任务」查看进度，在「知识与审核」逐条核对来源、事实、身份、脱敏结果和适用条件。
|
||
5. 保存草稿、审核通过、发布。健康或个体医疗信息需要专业审核并通用化，不能将患者个人情况当作普遍结论。
|
||
6. 在「检索测试」检查真实问题的召回结果，再开启该账号的「客服使用知识」。未命中时，模型会收到追问、不得编造业务事实的要求。
|
||
7. 通过「引用记录」查看网关每次使用的知识 ID、版本和检索耗时。发布后的编辑会退回草稿；旧版本可恢复为新草稿，重新审核发布。
|
||
|
||
所有写操作必须选择具体账号。「全部账号」只提供授权范围内的汇总视图。知识不跨租户共享。
|
||
|
||
## 第二版：整理与审核流程
|
||
|
||
- 「全部账号」下可以点击「选择账号开始整理」，展开账号选择；选择具体账号后进入整理向导。
|
||
- 先预览所选来源与日期内的单聊消息量、会话数、身份明确的有效文本量，以及本次最多读取条数。预览不创建任务，不调用模型，不返回聊天正文。
|
||
- 预览的有效文本条数覆盖整个选定范围，不代表本次一定生成的知识数。新任务在创建时重新确定截止水位和消息总数；预览后新增的归档可能使数字变化。
|
||
- 新任务展示「已读 / 实际计划消息数」、来源、整理方式和完成原因。旧任务缺少总数时只展示已读条数，不使用配置上限冒充实际总数。
|
||
- 支持暂停、继续和取消。取消只停止后续处理，已经生成的草稿保留；已发起的模型请求可能仍计费。取消某个任务不会自动关闭该来源的持续整理开关。
|
||
- 相同范围、整理方式与处理上限的任务在排队、处理中或暂停时，不能重复创建。可以继续原任务或取消后重建。
|
||
- 在知识列表勾选当前页的条目，进入批量审核。每条需要展开查看脱敏来源，核对事实和适用条件后分别勾选；缺少条件、版本变化或状态不符会单独提示。
|
||
- 支持批量发布、驳回、停用。每条分别调用现有鉴权接口、检查当前版本与来源并写入审计；操作不是一个整批事务，成功项保留，失败项逐条显示且不自动重试。
|
||
- 批量操作期间可以停止后续请求；已经发起的操作会完成。离开页面也会停止后续请求。刷新后按实际状态处理未完成项。
|
||
- 已过期知识不能审核通过或发布；只有已发布知识可停用。账号至少有一条有效、来源未失效的已发布知识，才能开启客服使用知识。
|
||
- 修复了消息上限恰好等于完整范围末尾时丢弃最后一个问答的问题。若上限确实截断后续上下文，末尾未闭合问答仍会丢弃。
|
||
|
||
本次任务统计保存在已有 `options_json`，不新增数据库列。旧任务、已有知识和来源追溯保持兼容。
|
||
|
||
## 启动与部署
|
||
|
||
本地开发：
|
||
|
||
```powershell
|
||
cd C:\kefu\wechat_rpa
|
||
python run_backend.py --db backend.db
|
||
```
|
||
|
||
启动器现在同时拉起管理 API、模型网关、知识 Worker。单独运行 Worker：
|
||
|
||
```bash
|
||
python knowledge_worker.py --db /data/backend.db
|
||
# 只执行一个批次，可用于诊断
|
||
python knowledge_worker.py --db /data/backend.db --once
|
||
```
|
||
|
||
当前生产部署使用根目录 `deploy/im-admin/compose.yaml`，已增加 `knowledge-worker` 服务，并复用现有镜像和数据库卷。不要使用已经过时的 `wechat_rpa/backend_deploy` 配置替代当前部署。
|
||
|
||
更新前备份 SQLite（使用 SQLite backup API 或停止写入后备份数据库及其密钥），保留当前镜像作为回退。构建前端后，在生产部署目录执行：
|
||
|
||
```bash
|
||
docker compose up -d --build api gateway knowledge-worker
|
||
docker compose logs --tail=100 knowledge-worker
|
||
```
|
||
|
||
API 启动时新增知识表、FTS5 表、来源失效触发器和归档扫描索引；首次索引构建时间取决于数据库与磁盘。建议低峰部署。现有管理角色自动获得新权限，其他角色需配置 `knowledge:read/write/review/publish/export`；加工和审核同时要求 `im:content:read`。
|
||
|
||
关闭「客服使用知识」即可回退到原回复链路。回滚代码前停止 Worker，保留新增表与数据，避免恢复旧库覆盖部署后的新增归档。
|
||
|
||
## 整理与增量更新
|
||
|
||
- 规则整理不调用模型。按单聊、连续发言及 30 分钟间隔整理完整问答，跨读取批次保留上下文。
|
||
- 只接受明确的客服来源账号；发送者身份还必须与来源账号匹配。群聊、未知方向、非文本、撤回消息和不完整片段不会自动产生可用知识。
|
||
- 每批规则任务读取最多 200 条，模型任务最多 20 条，使用游标和租约。任务、游标、草稿在数据库中持久化；Worker 崩溃后租约最长 5 分钟到期，可继续处理。
|
||
- 暂停会使在途批次失去提交权限。已经开始的模型请求不能撤销，重试可能产生额外调用，因此调用预算按发起前预扣。页面展示调用次数和字符量，不将字符数冒充 token 数或费用。
|
||
- 模型整理使用管理端配置的主答模型，只发送规则预处理后的脱敏问答。输出始终为待审草稿，不能自动发布。
|
||
- 精确重复问答去重；同义问法和相互冲突的不同答案仍需审核。暂未实现自动语义合并。
|
||
- 任务固定截止时间并读取该时点的消息版本。上限截断时，最后一个未闭合问答会丢弃；增加范围重新加工可补齐，已生成草稿会去重。
|
||
- 创建任务时勾选「持续整理」后，该来源账号后续的消息插入或内容/状态变化会写入增量队列。会话静默 30 分钟后，Worker 只重新整理变化会话，使用规则方式生成草稿，不产生自动模型费用。可在加工任务页停用或恢复。
|
||
- 撤回、修改、删除消息时，关联知识立即标为来源失效，并删除关键词索引。向量库中的旧点即使尚未清理，也不能通过 SQL 租户、状态、版本和来源复核。重新加工、审核后才可再次使用。
|
||
|
||
## 检索配置
|
||
|
||
默认关键词检索使用 SQLite FTS5，对中文采用双字切分，英文采用词切分，不扫描整个归档。它无法完整覆盖同义表达；需要更好的语义召回时配置向量服务。
|
||
|
||
在 `deploy/im-admin/.env` 配置以下变量，重建 API、网关和 Worker 的容器环境：
|
||
|
||
```dotenv
|
||
KNOWLEDGE_QDRANT_URL=http://your-qdrant:6333
|
||
KNOWLEDGE_QDRANT_KEY=
|
||
# 完整 embeddings API 地址，不会自动补路径
|
||
KNOWLEDGE_EMBEDDING_URL=https://your-provider.example/v1/embeddings
|
||
KNOWLEDGE_EMBEDDING_MODEL=your-embedding-model
|
||
KNOWLEDGE_EMBEDDING_KEY=your-secret
|
||
```
|
||
|
||
向量接口需支持 `{model,input}` 请求及 `data[0].embedding` 响应。URL、模型、密钥只从服务端环境读取。发布知识时完成向量写入后才置为已发布；配置不完整或服务失败会阻止本次发布，不会假装索引已完成。未配置语义服务时，可正常发布为关键词知识。
|
||
|
||
不同 embedding 模型/地址使用不同集合，防止不同向量空间混用。更换模型或为已有关键词知识补建向量时：
|
||
|
||
```bash
|
||
python knowledge_worker.py --db /data/backend.db --reindex --tenant ACTUAL_TENANT_ID
|
||
```
|
||
|
||
重建期间现有关键词检索仍可用。查询使用关键词与向量结果融合，最多选 5 条且限制引用总长度；语义服务暂不可用时回退关键词，管理端显示回退状态。当前相关度阈值是初始值，需在真实业务评估集上校准。
|
||
|
||
只有网关的 `purpose=chat` 会检索，界面识别等内部用途不受影响。同一次网关请求的模型候选共享证据；不同工具轮会重新检索，不跨客户缓存检索结果。网关幂等缓存中的知识引用也会重新检查是否有效。
|
||
|
||
## 数据与追溯
|
||
|
||
- `knowledge_job`：任务、固定水位、处理游标、未闭合上下文、租约、用量。
|
||
- `knowledge_item` / `knowledge_revision`：当前知识与每次编辑、审核、发布的版本快照。
|
||
- `knowledge_source`：来源消息 ID、版本、角色及脱敏文本。
|
||
- `knowledge_fts`：关键词索引；Qdrant payload 只保存条目 ID、租户和版本，不保存正文。
|
||
- `knowledge_settings` / `knowledge_watch` / `knowledge_dirty`：启用状态及增量队列。
|
||
- `knowledge_retrieval_log`：网关引用的条目与版本、处理方式、耗时；日志不等于客服消息已成功发出。
|
||
|
||
「导出已发布知识」提供 UTF-8 JSONL，包含 `schema_version=knowledge-v1`、ID、版本、问题、答案、适用条件、分类及有效期。导出不包含原始聊天或患者信息字段；只导出当前租户的有效已发布知识。
|
||
|
||
自动脱敏覆盖已知发送者姓名、手机号、身份证号、长编号、邮箱、链接和带标签的地址；它不是完整的个人信息识别器，自由文本地址、第三方姓名等仍必须人工检查。
|
||
|
||
## 验证与上线评估
|
||
|
||
```bash
|
||
python -m unittest test_knowledge -v
|
||
python -m unittest test_model_gateway test_archive_api test_admin_api
|
||
```
|
||
|
||
前端：在 `admin-web` 执行 `pnpm --filter @vben/web-antd typecheck` 和 `pnpm --filter @vben/web-antd build`。
|
||
|
||
上线前先用独立问题集测试正确知识召回、回答准确性、无依据追问、权限隔离和延迟。相同客户、会话及近重复案例不应同时出现在知识构建样本与评估集。当前实现未处理语音、图片、附件，没有将生产 40 万条聊天自动送入模型，也没有执行模型微调。
|