gardel/Mofox-Core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

删除无用文档和测试文件

Browse Source
This commit is contained in:
Windpicker-owo
2025-12-13 20:50:19 +08:00
parent 9a0163d06b
commit d7ab785ced
20 changed files with 0 additions and 7186 deletions
Download Patch File Download Diff File Expand all files Collapse all files

267
docs/guides/OBJECT_LEVEL_MEMORY_ANALYSIS.md
View File

@@ -1,267 +0,0 @@
# 对象级内存分析指南
## 🎯 概述
对象级内存分析可以帮助你：
- 查看哪些 Python 对象类型占用最多内存
- 追踪对象数量和大小的变化
- 识别内存泄漏的具体对象
- 监控垃圾回收效率
## 🚀 快速开始
### 1. 安装依赖
```powershell
pip install pympler
```
### 2. 启用对象级分析
```powershell
# 基本用法 - 启用对象分析
python scripts/run_bot_with_tracking.py --objects
# 自定义监控间隔（10 秒）
python scripts/run_bot_with_tracking.py --objects --interval 10
# 显示更多对象类型（前 20 个）
python scripts/run_bot_with_tracking.py --objects --object-limit 20
# 完整示例（简写参数）
python scripts/run_bot_with_tracking.py -o -i 10 -l 20
```
## 📊 输出示例
### 进程级信息
```
================================================================================
检查点 #1 - 12:34:56
Bot 进程 (PID: 12345)
RSS: 45.23 MB
VMS: 125.45 MB
占比: 0.35%
子进程: 1 个
子进程内存: 32.10 MB
总内存: 77.33 MB
变化:
RSS: +2.15 MB
```
### 对象级分析信息
```
📦 对象级内存分析 (检查点 #1)
--------------------------------------------------------------------------------
类型 数量 总大小
--------------------------------------------------------------------------------
dict 12,345 15.23 MB
str 45,678 8.92 MB
list 8,901 5.67 MB
tuple 23,456 4.32 MB
type 1,234 3.21 MB
code 2,345 2.10 MB
set 1,567 1.85 MB
function 3,456 1.23 MB
method 4,567 890.45 KB
weakref 2,345 678.12 KB
🗑️ 垃圾回收统计:
- 代 0 回收: 125 次
- 代 1 回收: 12 次
- 代 2 回收: 2 次
- 未回收对象: 0
- 追踪对象数: 89,456
📊 总对象数: 123,456
--------------------------------------------------------------------------------
```
## 🔍 如何解读输出
### 1. 对象类型统计
每一行显示：
- **类型名称**: Python 对象类型（dict、str、list 等）
- **数量**: 该类型的对象实例数量
- **总大小**: 该类型所有对象占用的总内存
**关键指标**：
- `dict` 多是正常的（Python 大量使用字典）
- `str` 多也是正常的（字符串无处不在）
- 如果看到某个自定义类型数量异常增长 → 可能存在泄漏
- 如果某个类型占用内存异常大 → 需要优化
### 2. 垃圾回收统计
**代 0/1/2 回收次数**：
- 代 0：最频繁，新创建的对象
- 代 1：中等频率，存活一段时间的对象
- 代 2：最少，长期存活的对象
**未回收对象**：
- 应该是 0 或很小的数字
- 如果持续增长 → 可能存在循环引用导致的内存泄漏
**追踪对象数**：
- Python 垃圾回收器追踪的对象总数
- 持续增长可能表示内存泄漏
### 3. 总对象数
当前进程中所有 Python 对象的数量。
## 🎯 常见使用场景
### 场景 1: 查找内存泄漏
```powershell
# 长时间运行，频繁检查
python scripts/run_bot_with_tracking.py -o -i 5
```
**观察**：
- 哪些对象类型数量持续增长？
- RSS 内存增长和对象数量增长是否一致？
- 垃圾回收是否正常工作？
### 场景 2: 优化内存占用
```powershell
# 较长间隔，查看稳定状态
python scripts/run_bot_with_tracking.py -o -i 30 -l 25
```
**分析**：
- 前 25 个对象类型中，哪些是你的代码创建的？
- 是否有不必要的大对象缓存？
- 能否使用更轻量的数据结构？
### 场景 3: 调试特定功能
```powershell
# 短间隔，快速反馈
python scripts/run_bot_with_tracking.py -o -i 3
```
**用途**：
- 触发某个功能后立即观察内存变化
- 检查对象是否正确释放
- 验证优化效果
## 📝 保存的历史文件
监控结束后，历史数据会自动保存到：
```
data/memory_diagnostics/bot_memory_monitor_YYYYMMDD_HHMMSS_pidXXXXX.txt
```
文件内容包括：
- 每个检查点的进程内存信息
- 每个检查点的对象统计（前 10 个类型）
- 总体统计信息（起始/结束/峰值/平均）
## 🔧 高级技巧
### 1. 结合代码修改
在你的代码中添加检查点：
```python
import gc
from pympler import muppy, summary
def debug_memory():
"""在关键位置调用此函数"""
gc.collect()
all_objects = muppy.get_objects()
sum_data = summary.summarize(all_objects)
summary.print_(sum_data, limit=10)
```
### 2. 比较不同时间点
```powershell
# 运行 1 分钟
python scripts/run_bot_with_tracking.py -o -i 10
# Ctrl+C 停止，查看文件
# 等待 5 分钟后再运行
python scripts/run_bot_with_tracking.py -o -i 10
# 比较两次的对象统计
```
### 3. 专注特定对象类型
修改 `run_bot_with_tracking.py` 中的 `get_object_stats()` 函数，添加过滤：
```python
def get_object_stats(limit: int = 10) -> Dict:
# ...现有代码...
# 只显示特定类型
filtered_summary = [
row for row in sum_data
if 'YourClassName' in row[0]
]
return {
"summary": filtered_summary[:limit],
# ...
}
```
## ⚠️ 注意事项
### 性能影响
对象级分析会影响性能：
- **pympler 分析**: ~10-20% 性能影响
- **gc.collect()**: 每次检查点触发垃圾回收，可能导致短暂卡顿
**建议**：
- 开发/调试时使用对象分析
- 生产环境使用普通监控（不加 `--objects`）
### 内存开销
对象分析本身也会占用内存：
- `muppy.get_objects()` 会创建对象列表
- 统计数据会保存在历史中
**建议**：
- 不要设置过小的 `--interval`（建议 >= 5 秒）
- 长时间运行时考虑关闭对象分析
### 准确性
- 对象统计是**快照**，不是实时的
- `gc.collect()` 后才统计，确保垃圾已回收
- 子进程的对象无法统计（只统计主进程）
## 📚 相关工具
| 工具 | 用途 | 对象级分析 |
|------|------|----------|
| `run_bot_with_tracking.py` | 一键启动+监控 | ✅ 支持 |
| `memory_monitor.py` | 手动监控 | ✅ 支持 |
| `windows_memory_profiler.py` | 详细分析 | ✅ 支持 |
| `run_bot_with_pympler.py` | 专门的对象追踪 | ✅ 专注此功能 |
## 🎓 学习资源
- [Pympler 文档](https://pympler.readthedocs.io/)
- [Python GC 模块](https://docs.python.org/3/library/gc.html)
- [内存泄漏调试技巧](https://docs.python.org/3/library/tracemalloc.html)
---
**快速开始**:
```powershell
pip install pympler
python scripts/run_bot_with_tracking.py --objects
```
🎉

391
docs/guides/memory_deduplication_guide.md
View File

@@ -1,391 +0,0 @@
# 记忆去重工具使用指南
## 📋 功能说明
`deduplicate_memories.py` 是一个用于清理重复记忆的工具。它会：
1. 扫描所有标记为"相似"关系的记忆对
2. 根据重要性、激活度和创建时间决定保留哪个
3. 删除重复的记忆，保留最有价值的那个
4. 提供详细的去重报告
## 🚀 快速开始
### 步骤1: 预览模式（推荐）
**首次使用前，建议先运行预览模式，查看会删除哪些记忆：**
```bash
python scripts/deduplicate_memories.py --dry-run
```
输出示例：
```
============================================================
记忆去重工具
============================================================
数据目录: data/memory_graph
相似度阈值: 0.85
模式: 预览模式（不实际删除）
============================================================
✅ 记忆管理器初始化成功，共 156 条记忆
找到 23 对相似记忆（阈值>=0.85）
[预览] 去重相似记忆对 (相似度=0.904):
保留: mem_20251106_202832_887727
- 主题: 今天天气很好
- 重要性: 0.60
- 激活度: 0.55
- 创建时间: 2024-11-06 20:28:32
删除: mem_20251106_202828_883440
- 主题: 今天天气晴朗
- 重要性: 0.50
- 激活度: 0.50
- 创建时间: 2024-11-06 20:28:28
[预览模式] 不执行实际删除
============================================================
去重报告
============================================================
总记忆数: 156
相似记忆对: 23
发现重复: 23
预览通过: 23
错误数: 0
耗时: 2.35秒
⚠️ 这是预览模式，未实际删除任何记忆
💡 要执行实际删除，请运行: python scripts/deduplicate_memories.py
============================================================
```
### 步骤2: 执行去重
**确认预览结果无误后，执行实际去重：**
```bash
python scripts/deduplicate_memories.py
```
输出示例：
```
============================================================
记忆去重工具
============================================================
数据目录: data/memory_graph
相似度阈值: 0.85
模式: 执行模式（会实际删除）
============================================================
✅ 记忆管理器初始化成功，共 156 条记忆
找到 23 对相似记忆（阈值>=0.85）
[执行] 去重相似记忆对 (相似度=0.904):
保留: mem_20251106_202832_887727
...
删除: mem_20251106_202828_883440
...
✅ 删除成功
正在保存数据...
✅ 数据已保存
============================================================
去重报告
============================================================
总记忆数: 156
相似记忆对: 23
成功删除: 23
错误数: 0
耗时: 5.67秒
✅ 去重完成！
📊 最终记忆数: 133 (减少 23 条)
============================================================
```
## 🎛️ 命令行参数
### `--dry-run`（推荐先使用）
预览模式，不实际删除任何记忆。
```bash
python scripts/deduplicate_memories.py --dry-run
```
### `--threshold <相似度>`
指定相似度阈值，只处理相似度大于等于此值的记忆对。
```bash
# 只处理高度相似（>=0.95）的记忆
python scripts/deduplicate_memories.py --threshold 0.95
# 处理中等相似（>=0.8）的记忆
python scripts/deduplicate_memories.py --threshold 0.8
```
**阈值建议**：
- `0.95-1.0`: 极高相似度，几乎完全相同（最安全）
- `0.9-0.95`: 高度相似，内容基本一致（推荐）
- `0.85-0.9`: 中等相似，可能有细微差别（谨慎使用）
- `<0.85`: 低相似度，可能误删（不推荐）
### `--data-dir <目录>`
指定记忆数据目录。
```bash
# 对测试数据去重
python scripts/deduplicate_memories.py --data-dir data/test_memory
# 对备份数据去重
python scripts/deduplicate_memories.py --data-dir data/memory_backup
```
## 📖 使用场景
### 场景1: 定期维护
**建议频率**: 每周或每月运行一次
```bash
# 1. 先预览
python scripts/deduplicate_memories.py --dry-run --threshold 0.92
# 2. 确认后执行
python scripts/deduplicate_memories.py --threshold 0.92
```
### 场景2: 清理大量重复
**适用于**: 导入外部数据后，或发现大量重复记忆
```bash
# 使用较低阈值，清理更多重复
python scripts/deduplicate_memories.py --threshold 0.85
```
### 场景3: 保守清理
**适用于**: 担心误删，只想删除极度相似的记忆
```bash
# 使用高阈值，只删除几乎完全相同的记忆
python scripts/deduplicate_memories.py --threshold 0.98
```
### 场景4: 测试环境
**适用于**: 在测试数据上验证效果
```bash
# 对测试数据执行去重
python scripts/deduplicate_memories.py --data-dir data/test_memory --dry-run
```
## 🔍 去重策略
### 保留原则（按优先级）
脚本会按以下优先级决定保留哪个记忆：
1. **重要性更高** (`importance` 值更大)
2. **激活度更高** (`activation` 值更大)
3. **创建时间更早** (更早创建的记忆)
### 增强保留记忆
保留的记忆会获得以下增强：
- **重要性** +0.05（最高1.0）
- **激活度** +0.05（最高1.0）
- **访问次数** 累加被删除记忆的访问次数
### 示例
```
记忆A: 重要性0.8, 激活度0.6, 创建于 2024-11-01
记忆B: 重要性0.7, 激活度0.9, 创建于 2024-11-05
结果: 保留记忆A（重要性更高）
增强: 重要性 0.8 → 0.85, 激活度 0.6 → 0.65
```
## ⚠️ 注意事项
### 1. 备份数据
**在执行实际去重前，建议备份数据：**
```bash
# Windows
xcopy data\memory_graph data\memory_graph_backup /E /I /Y
# Linux/Mac
cp -r data/memory_graph data/memory_graph_backup
```
### 2. 先预览再执行
**务必先运行 `--dry-run` 预览：**
```bash
# 错误示范 ❌
python scripts/deduplicate_memories.py # 直接执行
# 正确示范 ✅
python scripts/deduplicate_memories.py --dry-run # 先预览
python scripts/deduplicate_memories.py # 再执行
```
### 3. 阈值选择
**过低的阈值可能导致误删：**
```bash
# 风险较高 ⚠️
python scripts/deduplicate_memories.py --threshold 0.7
# 推荐范围 ✅
python scripts/deduplicate_memories.py --threshold 0.92
```
### 4. 不可恢复
**删除的记忆无法恢复！** 如果不确定，请：
1. 先备份数据
2. 使用 `--dry-run` 预览
3. 使用较高的阈值（如 0.95）
### 5. 中断恢复
如果执行过程中中断（Ctrl+C），已删除的记忆无法恢复。建议：
- 在低负载时段运行
- 确保足够的执行时间
- 使用 `--threshold` 限制处理数量
## 🐛 故障排查
### 问题1: 找不到相似记忆对
```
找到 0 对相似记忆（阈值>=0.85）
```
**原因**：
- 没有标记为"相似"的边
- 阈值设置过高
**解决**：
1. 降低阈值：`--threshold 0.7`
2. 检查记忆系统是否正确创建了相似关系
3. 先运行自动关联任务
### 问题2: 初始化失败
```
❌ 记忆管理器初始化失败
```
**原因**：
- 数据目录不存在
- 配置文件错误
- 数据文件损坏
**解决**：
1. 检查数据目录是否存在
2. 验证配置文件：`config/bot_config.toml`
3. 查看详细日志定位问题
### 问题3: 删除失败
```
❌ 删除失败: ...
```
**原因**：
- 权限不足
- 数据库锁定
- 文件损坏
**解决**：
1. 检查文件权限
2. 确保没有其他进程占用数据
3. 恢复备份后重试
## 📊 性能参考
| 记忆数量 | 相似对数 | 执行时间（预览） | 执行时间（实际） |
|---------|---------|----------------|----------------|
| 100 | 10 | ~1秒 | ~2秒 |
| 500 | 50 | ~3秒 | ~6秒 |
| 1000 | 100 | ~5秒 | ~12秒 |
| 5000 | 500 | ~15秒 | ~45秒 |
**注**: 实际时间取决于服务器性能和数据复杂度
## 🔗 相关工具
- **记忆整理**: `src/memory_graph/manager.py::consolidate_memories()`
- **自动关联**: `src/memory_graph/manager.py::auto_link_memories()`
- **配置验证**: `scripts/verify_config_update.py`
## 💡 最佳实践
### 1. 定期维护流程
```bash
# 每周执行
cd /path/to/bot
# 1. 备份
cp -r data/memory_graph data/memory_graph_backup_$(date +%Y%m%d)
# 2. 预览
python scripts/deduplicate_memories.py --dry-run --threshold 0.92
# 3. 执行
python scripts/deduplicate_memories.py --threshold 0.92
# 4. 验证
python scripts/verify_config_update.py
```
### 2. 保守去重策略
```bash
# 只删除极度相似的记忆
python scripts/deduplicate_memories.py --dry-run --threshold 0.98
python scripts/deduplicate_memories.py --threshold 0.98
```
### 3. 批量清理策略
```bash
# 先清理高相似度的
python scripts/deduplicate_memories.py --threshold 0.95
# 再清理中相似度的（可选）
python scripts/deduplicate_memories.py --dry-run --threshold 0.9
python scripts/deduplicate_memories.py --threshold 0.9
```
## 📝 总结
- ✅ **务必先备份数据**
- ✅ **务必先运行 `--dry-run`**
- ✅ **建议使用阈值 >= 0.92**
- ✅ **定期运行，保持记忆库清洁**
- ❌ **避免过低阈值（< 0.85）**
- ❌ **避免跳过预览直接执行**
---
**创建日期**: 2024-11-06
**版本**: v1.0
**维护者**: MoFox-Bot Team