217 lines
4.9 KiB
Markdown
217 lines
4.9 KiB
Markdown
# 后端改造清单
|
||
|
||
> 目标：在**不修改 Redis 全局配置**、不影响其他服务的前提下，优先优化当前语音 + 知识库后端链路的延迟、稳定性和可维护性。
|
||
|
||
## 一、改造原则
|
||
|
||
- **不动全局配置**：不修改 Redis `maxmemory` / `maxmemory-policy` 等服务端级配置。
|
||
- **先收敛链路，再做扩展**：优先减少重复上下文读取、重复检索、重复缓存逻辑。
|
||
- **优先 P0**：先解决影响延迟和准确率的核心路径。
|
||
- **可回退**：每一项改造都保留降级路径，避免影响线上。
|
||
|
||
## 二、当前重点文件
|
||
|
||
- `server/routes/chat.js`
|
||
- `server/services/realtimeDialogRouting.js`
|
||
- `server/services/toolExecutor.js`
|
||
- `server/services/kbRetriever.js`
|
||
- `server/services/redisClient.js`
|
||
- `server/services/nativeVoiceGateway.js`
|
||
- `server/services/contextKeywordTracker.js`
|
||
- `server/services/fastAsrCorrector.js`
|
||
- `server/services/contentSafeGuard.js`
|
||
|
||
## 三、P0：必须先改
|
||
|
||
### 1. 统一上下文装配入口
|
||
|
||
- [ ] 抽出统一的上下文装配服务
|
||
- [ ] 统一 Redis → MySQL 的读取顺序
|
||
- [ ] 同一轮对话避免多次读历史消息
|
||
- [ ] 统一文字链路与语音链路的上下文拼装规则
|
||
|
||
**目标文件**
|
||
|
||
- `server/routes/chat.js`
|
||
- `server/services/realtimeDialogRouting.js`
|
||
- `server/services/kbRetriever.js`
|
||
|
||
**验收标准**
|
||
|
||
- 同一 session 在一次请求链路里只装配一次上下文
|
||
- 文字和语音的上下文结果一致
|
||
|
||
---
|
||
|
||
### 2. KB 检索从“全库扫描”改为“候选集检索”
|
||
|
||
- [ ] 先根据关键词/意图分类出候选 collection
|
||
- [ ] 再做 VikingDB 检索
|
||
- [ ] 最后重排 topN 片段
|
||
- [ ] 保留全库扫描兜底开关
|
||
|
||
**目标文件**
|
||
|
||
- `server/services/toolExecutor.js`
|
||
- `server/services/kbRetriever.js`
|
||
- `server/services/realtimeDialogRouting.js`
|
||
|
||
**验收标准**
|
||
|
||
- 检索 collection 数量可控
|
||
- 平均延迟下降
|
||
- 检索结果不明显变差
|
||
|
||
---
|
||
|
||
### 3. Redis 写入改为 pipeline / multi
|
||
|
||
- [ ] `LPUSH + LTRIM + EXPIRE` 合并为一次往返
|
||
- [ ] 保留写失败降级逻辑
|
||
- [ ] 保留 TTL 机制
|
||
|
||
**目标文件**
|
||
|
||
- `server/services/redisClient.js`
|
||
|
||
**验收标准**
|
||
|
||
- 单次消息写入 Redis 往返次数减少
|
||
- 现有 TTL 行为不变
|
||
|
||
---
|
||
|
||
### 4. 缓存层次明确化
|
||
|
||
- [ ] 明确本地内存缓存只做短时减压
|
||
- [ ] Redis 作为共享缓存
|
||
- [ ] no-hit 结果只做短 TTL 去重，不长期存储
|
||
- [ ] 缓存 key 规范化
|
||
|
||
**目标文件**
|
||
|
||
- `server/services/toolExecutor.js`
|
||
- `server/services/redisClient.js`
|
||
|
||
**验收标准**
|
||
|
||
- 多实例时缓存行为可解释
|
||
- key 命名与 TTL 规则统一
|
||
|
||
---
|
||
|
||
## 四、P1：建议尽快改
|
||
|
||
### 5. 会话生命周期治理
|
||
|
||
- [ ] 给 `chatSessions` 增加更明确的上限
|
||
- [ ] 定时清理策略配置化
|
||
- [ ] 超过阈值时自动淘汰最旧 session
|
||
- [ ] 评估 session 状态是否需要下沉 Redis
|
||
|
||
**目标文件**
|
||
|
||
- `server/routes/chat.js`
|
||
- `server/services/nativeVoiceGateway.js`
|
||
|
||
**验收标准**
|
||
|
||
- 长时间运行不明显涨内存
|
||
- session 清理策略可观测
|
||
|
||
---
|
||
|
||
### 6. 预查询参数配置化
|
||
|
||
- [ ] 把 early block / debounce / 最小长度提成配置项
|
||
- [ ] 支持不同场景调参
|
||
- [ ] 记录 prequery 命中率
|
||
|
||
**目标文件**
|
||
|
||
- `server/services/nativeVoiceGateway.js`
|
||
|
||
**验收标准**
|
||
|
||
- 不改代码可调整阈值
|
||
- 误触发率下降
|
||
|
||
---
|
||
|
||
### 7. 结构化指标埋点
|
||
|
||
- [ ] 路由命中率
|
||
- [ ] Redis 命中率
|
||
- [ ] DB fallback 次数
|
||
- [ ] KB 检索耗时
|
||
- [ ] 重排耗时
|
||
- [ ] prequery 命中率
|
||
|
||
**目标文件**
|
||
|
||
- `server/services/realtimeDialogRouting.js`
|
||
- `server/services/toolExecutor.js`
|
||
- `server/services/kbRetriever.js`
|
||
|
||
**验收标准**
|
||
|
||
- 能按 session / route / tool 维度排查性能问题
|
||
|
||
---
|
||
|
||
## 五、P2：后续增强
|
||
|
||
### 8. 安全与兜底一致性
|
||
|
||
- [ ] 统一知识库 no-hit 的诚实兜底文案
|
||
- [ ] 统一品牌保护文案
|
||
- [ ] 避免不同入口返回不一致
|
||
|
||
**目标文件**
|
||
|
||
- `server/services/realtimeDialogRouting.js`
|
||
- `server/services/contentSafeGuard.js`
|
||
- `server/routes/chat.js`
|
||
|
||
---
|
||
|
||
### 9. 测试补强
|
||
|
||
- [ ] Redis 读写单测
|
||
- [ ] KB 检索与重排单测
|
||
- [ ] 语音/文字链路回归测试
|
||
- [ ] no-hit / 保护窗口 / 追问场景测试
|
||
|
||
**目标文件**
|
||
|
||
- `server/tests/test_redis_client.js`
|
||
- `server/tests/test_kb_retriever.js`
|
||
- `server/tests/test_kb_scenarios.js`
|
||
- `server/tests/test_kb_prompt_compare.js`
|
||
|
||
---
|
||
|
||
## 六、建议实施顺序
|
||
|
||
1. 上下文装配统一
|
||
2. KB 候选集检索
|
||
3. Redis pipeline
|
||
4. 会话生命周期治理
|
||
5. 预查询参数配置化
|
||
6. 指标埋点
|
||
7. 测试补强
|
||
|
||
## 七、建议验收口径
|
||
|
||
- **延迟**：核心查询链路 P50 明显下降
|
||
- **稳定性**：Redis 断开时可自动降级
|
||
- **一致性**：文字/语音链路输出策略一致
|
||
- **安全性**：no-hit 与品牌保护回复统一
|
||
- **可维护性**：关键阈值可配置，不依赖频繁改代码
|
||
|
||
## 八、备注
|
||
|
||
- 本清单只针对**应用层改造**。
|
||
- 不包含 Redis 全局配置修改。
|
||
- 若后续要做服务器级改动，需单独确认。
|