diff --git a/DESIGN-v2-llm-optimizer.md b/DESIGN-v2-llm-optimizer.md new file mode 100644 index 0000000..53a4c72 --- /dev/null +++ b/DESIGN-v2-llm-optimizer.md @@ -0,0 +1,376 @@ +# 织忆 v2 — LLM 驱动的自优化系统 + +> 版本：v2.0.0-draft +> 状态：待评审 +> 基于：v1.0.0-stable + +--- + +## 1. 背景与目标 + +### 1.1 现状问题 + +v1 版本中，织忆各个模块（distill、consolidate、recall）各自为政，没有全局感知和自主优化能力： + +``` +commit → distill（被动，一次一条） + ↓ +consolidate（定时，固定流程，不感知状态） + ↓ +质量回溯（采样20条，不闭环） + ↓ +recall（独立系统） +``` + +**核心矛盾**：LLM 没有被用来管理织忆，参数全靠手设，异常靠牧尘发现。 + +### 1.2 升级目标 + +1. **LLM 全局巡检** — 主动发现全流程堵点和异常 +2. **参数自动调优** — 基于指标自动调整，无需手设 +3. **Hermes 监督汇报** — 我执行操作，牧尘知情，重大决策上报 +4. **可回滚** — 任何时候可切回 v1.0.0-stable + +### 1.3 设计原则 + +| 原则 | 说明 | +|---|---| +| 成本优先 | 无异常不调用 LLM，用指标驱动触发 | +| 我执行 | LLM 发现/建议，我执行操作，不让它直连数据 | +| 可观测 | 每次决策记录 JSONL + git commit | +| 轻量触发 | 规则引擎处理常见情况，LLM 只处理复杂因果 | + +--- + +## 2. 系统架构 + +### 2.1 角色分工 + +``` +┌─────────────────────────────────────────────────────┐ +│ 织忆 v2 独立部署包（可部署在其他机器） │ +│ │ +│ ┌─────────────────────────────────────────────┐ │ +│ │ LLM Agent（独立运行，不依赖 Hermes） │ │ +│ │ ├─ 自己的 cronjob（每 60 分钟自检） │ │ +│ │ ├─ 规则引擎：自动调参 │ │ +│ │ ├─ LLM 巡检：复杂因果自主决策 │ │ +│ │ └─ 自主调用织忆 API 执行操作 │ │ +│ └─────────────────────────────────────────────┘ │ +│ │ +│ 决策日志 → git commit → 飞书通知牧尘 │ +└─────────────────────────────────────────────────────┘ + ↓（飞书通知，仅重大决策） +┌─────────────────────────────────────────────────────┐ +│ Hermes（可选，不参与运行） │ +│ ├─ 旁听重大决策（飞书收到通知） │ +│ └─ 牧尘可通过 Hermes 转发指令给 LLM Agent │ +└─────────────────────────────────────────────────────┘ +``` + +### 2.2 独立性设计 + +LLM Agent 脱离 Hermes 独立运行的关键点： +- 自己的定时器（systemd timer 或 cronjob） +- 自己持有织忆 API 地址和认证 +- 自己管理 LLM API（可独立配置模型和端点） +- 飞书机器人直接通知牧尘，不经过 Hermes 中转 +- 部署时只需修改配置文件，无需改动 Hermes + +### 2.3 与 v1 的关系 + +- v1 的各个 API 和逻辑保持不变，作为执行层 +- v2 在 v1 之上加了一层"调度 + 巡检"逻辑 +- v2 的调度器用 cronjob 实现，调用 v1 的已有 API + +--- + +## 3. 触发机制 + +### 3.1 指标驱动（非定时） + +每 60 分钟读取一次状态（现有 cronjob `织忆状态看板`），判断是否触发巡检： + +| 触发条件 | 说明 | +|---|---| +| recall 命中率连续 2 次下降 | 需要巡检 recall 质量 | +| gap_detected 堆积 > 5 条未处理 | 需要巡检 recall gap | +| distill 队列积压 > 20 条 | 需要巡检 distill 瓶颈 | +| consolidate 质量分 < 0.6 | 需要巡检聚类/质量回溯 | +| 冲突堆积 > 3 条 | 需要巡检冲突处理 | +| 规则引擎连续 3 次调参无效 | 需要 LLM 分析复杂因果 | + +**无异常时完全不调用 LLM**，不花额外费用。 + +### 3.2 手动触发 + +牧尘可以随时说"巡检织忆"，我会立即执行一次完整巡检。 + +--- + +## 4. 参数自动调优 + +### 4.1 参数列表 + +| 参数 | 位置 | 默认值 | 正常范围 | 调整粒度 | +|---|---|---|---|---| +| `dbscan_epsilon` | consolidate | 0.5 | 0.3–1.5 | ±0.1 | +| `dbscan_min_points` | consolidate | 3 | 2–10 | ±1 | +| `decay_rate` | tuning.go | 0.015 | 0.005–0.05 | 乘/除 1.2 | +| `gap_threshold` | tuning.go | 3 | 1–10 | ±1 | +| `consolidate_after` | tuning.go | 50 | 20–200 | ±10 | +| `prune_threshold` | consolidation_pipe.go | 0.15 | 0.05–0.5 | ±0.05 | + +### 4.2 规则引擎调参（无需 LLM） + +规则引擎根据指标直接调整参数： + +``` +IF recall 命中率下降 AND noise_points > 总数 30%: + → epsilon += 0.1 + +IF gap 堆积 > 5 AND gap_threshold 连续 2 次调低无效: + → 触发 LLM 巡检 + +IF distill 质量分下降 AND decay_rate 最近 7 天内未调: + → decay_rate /= 1.2 + +IF 修剪节点数 / 总节点数 > 20%: + → prune_threshold += 0.05 +``` + +### 4.3 LLM 辅助调参 + +规则引擎遇到复杂因果时，调用 LLM： + +``` +触发条件：规则引擎连续 3 次调参后指标未改善 +输入：系统手册 + 当前指标快照 + 调参历史 + 异常事件 +LLM 输出： + { + "analysis": "根因分析", + "action": "调参 / 重蒸 / 合并 / 其他", + "parameters": { "epsilon": 0.6 }, + "reason": "..." + } +``` + +### 4.4 调参执行流程 + +``` +规则引擎判断需要调参 + ↓ +读取当前参数值 + ↓ +应用调整（写入 tuning.go 或调用 API） + ↓ +记录到 llm-tuning-log.jsonl + ↓ +git commit "llm-tune: epsilon 0.5→0.6" + ↓ +下次指标采样时判断是否生效 +``` + +--- + +## 5. LLM 系统手册 + +### 5.1 手册内容 + +触发 LLM 巡检时，注入以下上下文： + +``` +你是织忆记忆系统的巡检员，负责发现全流程的堵点和异常。 + +【系统架构】 +- distill：记忆蒸馏，commit 时被动触发，将长对话压缩为记忆 +- consolidate：记忆整合，定时（DBSCAN 聚类 + 剪枝 + 衰减校准 + 质量回溯） +- recall：记忆召回，查询时向量检索 +- graph：图谱管理，实体/关系/冲突 + +【参数说明】 +- dbscan_epsilon：聚类半径，影响聚类数量和 noise 比例 +- dbscan_min_points：最小点数，影响核心点判定 +- decay_rate：遗忘衰减率，值越大记忆衰减越快 +- gap_threshold：recall gap 感测阈值，连续 N 次 miss 才记录 +- prune_threshold：图谱剪枝权重阈值 + +【正常范围】 +- recall 命中率 > 70% +- noise_points / 总数 < 20% +- distill 质量分 > 0.6 +- gap 堆积 < 5 条 +- 冲突 < 3 条堆积 + +【约束】 +- 不要轻易触发全量重蒸，成本高 +- 优先用规则调参，复杂情况才用 LLM +- 每次操作记录到 /home/muc/projects/memoryweave/ops/llm-tuning-log.jsonl + +【当前状态】 +{timestamp} +{metrics_snapshot} +{recent_events} +调参历史：{tuning_history} +``` + +### 5.2 手册存放位置 + +``` +/home/muc/projects/memoryweave/ops/ops-manual.md +``` + +--- + +## 6. 决策日志 + +### 6.1 日志格式（JSONL，每行一条） + +```json +{"ts":"2026-06-09T03:00:00Z","type":"parameter_tune","param":"dbscan_epsilon","old":"0.5","new":"0.6","reason":"recall命中率下降，noise>30%","trigger":"rule_engine","result":"pending","model":"minimaxai/minimax-m2.7"} +{"ts":"2026-06-09T04:00:00Z","type":"llm_inspection","trigger":"gap堆积>5","analysis":"根因是gap_threshold设置过低","actions":["gap_threshold+=1"],"model":"minimaxai/minimax-m2.7"} +``` + +### 6.2 文件位置 + +``` +/home/muc/projects/memoryweave/ops/llm-tuning-log.jsonl +``` + +### 6.3 Git 版本化 + +每次有决策写入后，提交一次： + +```bash +git add ops/llm-tuning-log.jsonl +git commit -m "llm-tune: epsilon 0.5→0.6 (recall下降触发)" +``` + +--- + +## 7. LLM Agent 的运行方式 + +### 7.1 自主 Loop（独立于 Hermes） + +LLM Agent 独立运行，通过 systemd timer 每 60 分钟自检： + +``` +systemd timer（每 60 分钟）: + ├─ 读取指标（/api/v1/stats） + ├─ 规则引擎判断 + │ └─ 可处理 → 自动调参 → 记录日志 + │ └─ 复杂因果 → 调用 LLM 巡检 + └─ LLM 巡检结果 → 执行操作 → 记录日志 + └─ 重大决策 → 飞书机器人直接通知牧尘 +``` + +### 7.2 飞书直接通知牧尘 + +LLM Agent 拥有自己的飞书机器人，重大决策不经过 Hermes 直接通知牧尘： + +| 决策类型 | 是否通知 | +|---|---| +| 小调参（epsilon ±0.1） | ❌ 静默 | +| 正常调参（decay_rate ±20%） | ❌ 静默 | +| 大幅调参（decay_rate ±50%以上） | ✅ 飞书通知 | +| 触发全量重蒸 | ✅ 飞书通知 | +| 连续 3 次调参无效 | ✅ 飞书通知 | +| 发现系统性问题（distill 质量持续下降） | ✅ 飞书通知 | + +### 7.3 汇报格式（飞书） + +``` +🤖 织忆 LLM 巡检报告 + +时间：2026-06-09 08:00 +发现问题：recall 命中率下降至 62%，连续 2 次调参无效 +分析：根因是 DBSCAN epsilon 过小，导致记忆碎片化 +操作：epsilon 0.5→0.7，触发 consolidate full +建议：观察 3 天，如未改善考虑扩大 rerank 范围 +``` + +### 7.4 Hermes 的位置 + +Hermes 不参与 LLM Agent 的运行，只在以下场景介入： +- 牧尘通过飞书问 Hermes "织忆最近怎么了"→ Hermes 查询日志回答 +- 牧尘让 Hermes "帮看看织忆的状态"→ Hermes 调用 LLM Agent 的状态 API +- LLM Agent 通知牧尘后，牧尘追问 Hermes → Hermes 解读 + +--- + +## 8. 回滚机制 + +### 8.1 回滚到 v1 + +```bash +cd /home/muc/projects/memoryweave +git checkout v1.0.0-stable +git reset --hard +systemctl --user restart zhiyid +``` + +### 8.2 v1.0.0-stable 内容 + +``` +commit: fix: add clusters_found/noise_points/quality_score to consolidate API +tag: v1.0.0-stable +``` + +### 8.3 v2 开发分支 + +``` +主开发分支：main（当前） +v1 稳定版：v1.0.0-stable（tag） +v2 发布后打 tag：v2.0.0-stable +``` + +--- + +## 9. 实施计划 + +### Phase 1：日志基础设施（v2 前置） +- 创建 `ops/llm-tuning-log.jsonl` +- 创建 `ops/ops-manual.md` +- 实现 git commit 封装 + +### Phase 2：LLM Agent Loop +- 实现 cronjob 驱动的自主巡检 +- 实现规则引擎自动调参 +- 实现 JSONL 写入 + git commit + +### Phase 3：Hermes 旁听汇报 +- 实现飞书重大决策上报 +- 实现牧尘手动巡检入口（飞书 → Hermes → LLM Agent） + +--- + +## 10. 待确认问题 + +1. **调参上限** — LLM 一次调整不超过一个参数，幅度不超过 ±50% ✅ +2. **手动巡检入口** — 牧尘说"巡检织忆"→ LLM Agent 自己的飞书机器人直接响应 ✅ +3. **LLM Agent 用的模型** — 和织忆共用同一个 LLM API（`LLM_ENDPOINT` / `LLM_MODEL` 环境变量）✅ + +--- + +## 11. 实施计划 + +### Phase 1：日志基础设施（v2 前置） +- 创建 `ops/llm-tuning-log.jsonl` +- 创建 `ops/ops-manual.md` +- 创建 `ops/llm-agent/` 目录（LLM Agent 代码） +- 实现 git commit 封装 + +### Phase 2：LLM Agent 独立服务 +- 实现 systemd timer + service +- 实现指标读取 + 规则引擎调参 +- 实现 LLM 巡检调用 +- 配置独立飞书机器人 + +### Phase 3：部署独立运行 +- 配置文件（织忆 API 地址、LLM 端点、飞书机器人） +- 部署在其他机器上验证 +- 验证脱离 Hermes 自主运行 + +--- + +*文档状态：草稿 v0.3，待牧尘确认后固化到 Obsidian* \ No newline at end of file