feat(docs): add Graphiti optimization方案文档
This commit is contained in:
yunying
181
architecture/Graphiti-优化方案.md
Normal file
181
architecture/Graphiti-优化方案.md
Normal file
@@ -0,0 +1,181 @@
|
||||
# Graphiti 知识图谱云端调用优化方案
|
||||
|
||||
## 背景
|
||||
|
||||
当前 OpenClaw 的 Graphiti 插件在每条消息处理时都会触发完整的知识图谱构建流程（`add_episode`），导致频繁调用云端大模型：
|
||||
|
||||
- **每次 `add_episode` 调用**：3 次云端 LLM 调用（节点提取、关系提取、节点去重）
|
||||
- **16 个活跃 Agent**：日均约 285 条有效消息
|
||||
- **月云端调用量**：~8,550 次
|
||||
- **老大 coding plan 配额**：90,000 次/月
|
||||
- **Graphiti 占比**：9.5%（未计算 Agent 对话本身的调用）
|
||||
|
||||
为大幅降低云端调用成本，同时保持知识图谱功能完整，特制定本优化方案。
|
||||
|
||||
## 优化目标
|
||||
|
||||
- **主要目标**：将 Graphiti 月云端调用从 ~8,550 次降至 **<1,000 次**
|
||||
- **次要目标**：保持实时向量搜索能力，知识图谱构建质量不降
|
||||
- **约束条件**：最小化工程改动，确保可回滚
|
||||
|
||||
## 方案设计：两层架构 + 动态调度
|
||||
|
||||
### 架构概览
|
||||
|
||||
```
|
||||
┌─────────────────┐ ┌──────────────────┐
|
||||
│ 实时层 │ │ 批量层 │
|
||||
│ (全本地，零云端) │ │ (云端，定时批量) │
|
||||
└────────┬────────┘ └────────┬─────────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────────┐ ┌──────────────────┐
|
||||
│ 原始消息存储 │ │ 知识图谱构建 │
|
||||
│ + 向量索引 │ │ (实体+关系提取) │
|
||||
└────────┬────────┘ └────────┬─────────┘
|
||||
│ │
|
||||
└──────────┬───────────┘
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ 统一搜索接口 │
|
||||
│ (graphiti_search)│
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
### 实时层（零云端调用）
|
||||
|
||||
- **触发时机**：每条用户/助手消息到达时
|
||||
- **处理内容**：
|
||||
- 将原始消息存入 Neo4j 作为 `EpisodicNode`
|
||||
- 使用本地 Ollama (`nomic-embed-text`) 生成向量嵌入
|
||||
- 存储向量用于实时相似度搜索
|
||||
- **技术栈**：完全本地（IPEX-LLM + Intel iGPU）
|
||||
- **效果**：消息发出后立即可被向量搜索命中
|
||||
|
||||
### 批量层（云端调用）
|
||||
|
||||
- **触发时机**：cron 定时任务（每日 11 次）
|
||||
- **处理内容**：
|
||||
- 收集自上次处理以来的所有新消息
|
||||
- 为每条消息添加 **Agent 命名空间前缀**（如 `[yunying] 运营官：...`）
|
||||
- 合并所有消息为 **单个 episode**
|
||||
- 调用 Graphiti REST `/messages` 接口进行完整知识图谱构建
|
||||
- **技术栈**：云端大模型（qwen3.5-plus）用于高质量实体/关系提取
|
||||
- **效果**：保持知识图谱构建质量，但有 ≤2 小时延迟
|
||||
|
||||
### 动态调度策略
|
||||
|
||||
基于 3 天实测活跃度数据（4/4-4/6），制定以下 cron 调度：
|
||||
|
||||
| 时间段 | 调度频率 | 理由 |
|
||||
|--------|----------|------|
|
||||
| **00:00-03:00** | 跳过 | 几乎无活跃（日均 <0.5 条/小时） |
|
||||
| **04:00** | 1 次 | 🌙 凌晨兜底，汇总夜间消息 |
|
||||
| **09:00-14:00** | 每 1-2 小时 | 上午/午间中等活跃 |
|
||||
| **16:00-20:00** | 每 1 小时 | 🔴 下午/晚间高峰（日均 8-15 条/小时） |
|
||||
| **22:00** | 1 次 | 全天收尾 |
|
||||
|
||||
**具体 cron 配置：**
|
||||
```cron
|
||||
# Graphiti 批量 ingest 调度 v1.0
|
||||
0 4 * * * /path/to/batch_ingest.sh
|
||||
0 9 * * * /path/to/batch_ingest.sh
|
||||
0 10 * * * /path/to/batch_ingest.sh
|
||||
0 12 * * * /path/to/batch_ingest.sh
|
||||
0 14 * * * /path/to/batch_ingest.sh
|
||||
0 16 * * * /path/to/batch_ingest.sh
|
||||
0 17 * * * /path/to/batch_ingest.sh
|
||||
0 18 * * * /path/to/batch_ingest.sh
|
||||
0 19 * * * /path/to/batch_ingest.sh
|
||||
0 20 * * * /path/to/batch_ingest.sh
|
||||
0 22 * * * /path/to/batch_ingest.sh
|
||||
```
|
||||
|
||||
## 预期效果
|
||||
|
||||
| 指标 | 优化前 | 优化后 | 改善幅度 |
|
||||
|------|--------|--------|----------|
|
||||
| 日批次次数 | - | 11 | - |
|
||||
| 每批次云端调用 | - | 3 | - |
|
||||
| **日云端调用** | ~285 | **33** | ↓ 88% |
|
||||
| **月云端调用** | ~8,550 | **~990** | ↓ 88% |
|
||||
| **配额占比** | 9.5% | **1.1%** | ↓ 88% |
|
||||
| 实时搜索 | ✅ | ✅ | 无变化 |
|
||||
| 知识图谱质量 | ✅ | ✅ | 无变化 |
|
||||
| 知识图谱延迟 | 0 秒 | ≤2 小时 | 可接受 |
|
||||
|
||||
## 实施步骤
|
||||
|
||||
### 1. 配置变更
|
||||
|
||||
- 修改 `~/.openclaw/openclaw.json`：
|
||||
```json
|
||||
{
|
||||
"plugins": {
|
||||
"entries": {
|
||||
"graphiti": {
|
||||
"config": {
|
||||
"autoCapture": false // 关闭实时 ingest
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 部署批量脚本
|
||||
|
||||
- 脚本位置：`~/.openclaw/services/graphiti-batch/batch_ingest.sh`
|
||||
- 功能：
|
||||
- 扫描所有 Agent 的 session transcript 文件
|
||||
- 提取 user/assistant 消息，过滤系统消息
|
||||
- 添加 `[agent_name]` 命名空间前缀
|
||||
- 合并为单个 episode 并调用 Graphiti REST API
|
||||
- 记录处理统计用于后续调度优化
|
||||
|
||||
### 3. 配置 cron
|
||||
|
||||
- 安装上述 11 条 cron 任务
|
||||
- 日志输出到 `~/.openclaw/services/graphiti-batch/cron.log`
|
||||
|
||||
### 4. 重启服务
|
||||
|
||||
- 重启 OpenClaw Gateway 使 `autoCapture: false` 生效
|
||||
|
||||
## 风险与缓解
|
||||
|
||||
| 风险 | 缓解措施 |
|
||||
|------|----------|
|
||||
| **消息丢失** | 脚本记录最后处理时间戳，失败自动重试 |
|
||||
| **实体混淆** | Agent 命名空间前缀确保上下文隔离 |
|
||||
| **紧急场景延迟** | 关键任务可通过 `/recall` 直接查询历史 |
|
||||
| **调度不准** | 脚本埋点记录每批消息量，2 周后优化调度 |
|
||||
| **回滚困难** | 保留原配置，改回 `autoCapture: true` 即可 |
|
||||
|
||||
## 回滚方案
|
||||
|
||||
如遇问题，执行以下步骤即可回退：
|
||||
|
||||
1. 修改 `~/.openclaw/openclaw.json` → `"autoCapture": true`
|
||||
2. 删除 cron 任务：`crontab -l | grep -v batch_ingest | crontab -`
|
||||
3. 重启 Gateway：`openclaw gateway restart`
|
||||
|
||||
## 实施状态
|
||||
|
||||
- ✅ **已实施**：2026-04-06 17:00
|
||||
- ✅ **配置更新**：`autoCapture: false`
|
||||
- ✅ **脚本部署**：`batch_ingest.sh` 测试通过
|
||||
- ✅ **Cron 安装**：11 条任务已生效
|
||||
- ✅ **首次运行**：17:00 成功处理 2 条新消息
|
||||
|
||||
## 后续优化
|
||||
|
||||
- **数据驱动调度**：收集 2 周 `batch_stats.csv` 数据，优化 cron 频率
|
||||
- **优先级标记**：支持关键消息即时处理（需额外开发）
|
||||
- **监控告警**：建立调用次数和处理延迟监控
|
||||
|
||||
---
|
||||
**文档作者**：运营官 (yunying)
|
||||
**评审人员**：参谋 (canmou)、小X总指挥 (director)
|
||||
**实施日期**：2026-04-06
|
||||
**版本**：1.0
|
||||
Reference in New Issue
Block a user