183 lines
4.4 KiB
Markdown
183 lines
4.4 KiB
Markdown
# Agent 缓存系统
|
||
|
||
本文档描述了使用 DiskCache 实现的 Agent 缓存系统。
|
||
|
||
## 概述
|
||
|
||
Agent 缓存系统使用 DiskCache 来持久化缓存 Agent 实例，提供以下功能：
|
||
|
||
- ✅ **文件持久化**：缓存存储在磁盘上，重启后仍然保留
|
||
- ✅ **自动过期**：支持设置过期时间，自动清理过期项
|
||
- ✅ **缓存大小限制**：可设置最大缓存大小，自动淘汰旧数据
|
||
- ✅ **访问时自动续期**：每次访问时自动延长过期时间
|
||
- ✅ **线程安全**：支持多线程并发访问
|
||
|
||
## 配置
|
||
|
||
### 环境变量
|
||
|
||
可以通过以下环境变量配置缓存行为：
|
||
|
||
- `AGENT_CACHE_DIR`：缓存目录路径（默认：`./projects/agent_cache`）
|
||
- `AGENT_CACHE_SIZE_LIMIT`：缓存大小限制，字节（默认：`1073741824` = 1GB）
|
||
- `AGENT_CACHE_EXPIRE`：默认过期时间，秒（默认：`180` = 3分钟）
|
||
|
||
示例：
|
||
```bash
|
||
export AGENT_CACHE_DIR="/var/cache/agent"
|
||
export AGENT_CACHE_SIZE_LIMIT="5368709120" # 5GB
|
||
export AGENT_CACHE_EXPIRE="600" # 10分钟
|
||
```
|
||
|
||
### 代码配置
|
||
|
||
```python
|
||
from agent.agent_cache_manager import AgentCacheManager
|
||
|
||
# 创建缓存管理器
|
||
cache = AgentCacheManager(
|
||
cache_dir="./cache/agent_cache",
|
||
size_limit=1024*1024*1024, # 1GB
|
||
default_expire=180, # 3分钟
|
||
eviction_policy="least-recently-used" # LRU淘汰策略
|
||
)
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
### 1. 缓存 Agent
|
||
|
||
缓存系统已集成到 `init_agent` 函数中，会自动根据配置生成缓存键并缓存 Agent。
|
||
|
||
```python
|
||
from agent.deep_assistant import init_agent
|
||
from agent.agent_config import AgentConfig
|
||
|
||
# 创建配置
|
||
config = AgentConfig(
|
||
bot_id="your-bot-id",
|
||
session_id="user-session-123",
|
||
# ... 其他配置
|
||
)
|
||
|
||
# 初始化 Agent（会自动使用缓存）
|
||
agent = await init_agent(config)
|
||
```
|
||
|
||
### 2. 手动使用缓存
|
||
|
||
如果需要在其他地方使用缓存：
|
||
|
||
```python
|
||
from agent.agent_cache_manager import get_cache_manager
|
||
|
||
# 获取全局缓存管理器
|
||
cache = get_cache_manager()
|
||
|
||
# 设置缓存
|
||
cache.set("my-key", {"data": "value"}, expire=300) # 5分钟过期
|
||
|
||
# 获取缓存
|
||
value = cache.get("my-key")
|
||
if value is not None:
|
||
print("缓存命中！")
|
||
else:
|
||
print("缓存未命中")
|
||
|
||
# 删除缓存
|
||
cache.delete("my-key")
|
||
|
||
# 获取统计信息
|
||
stats = cache.get_stats()
|
||
print(f"缓存大小: {stats['size_mb']} MB")
|
||
print(f"缓存项数: {stats['total_items']}")
|
||
```
|
||
|
||
## 缓存管理工具
|
||
|
||
项目提供了缓存管理脚本：
|
||
|
||
```bash
|
||
# 查看缓存统计
|
||
poetry run python scripts/cache_manager.py stats
|
||
|
||
# 清理过期项
|
||
poetry run python scripts/cache_manager.py expired
|
||
|
||
# 清理超过1小时的项
|
||
poetry run python scripts/cache_manager.py cleanup --max-age 3600
|
||
|
||
# 清空所有缓存
|
||
poetry run python scripts/cache_manager.py clear
|
||
|
||
# 列出缓存键
|
||
poetry run python scripts/cache_manager.py list
|
||
|
||
# 删除特定缓存键
|
||
poetry run python scripts/cache_manager.py delete my-cache-key
|
||
```
|
||
|
||
## 缓存键生成
|
||
|
||
缓存键基于以下配置生成唯一哈希值：
|
||
|
||
- `bot_id`
|
||
- `system_prompt`
|
||
- `mcp_settings`
|
||
- `model_name`
|
||
- `language`
|
||
- `generate_cfg`
|
||
- `enable_thinking`
|
||
- `user_identifier`
|
||
- `session_id`
|
||
|
||
如果 `session_id` 为 None，则不使用缓存。
|
||
|
||
## 注意事项
|
||
|
||
1. **性能考虑**：
|
||
- 缓存存储在磁盘上，首次访问会有 I/O 开销
|
||
- 建议使用 SSD 存储缓存以提高性能
|
||
- 过期时间不宜设置过短，避免频繁重新创建 Agent
|
||
|
||
2. **内存管理**：
|
||
- Agent 对象可能占用较大内存
|
||
- 设置合理的缓存大小限制
|
||
- 定期清理不用的缓存项
|
||
|
||
3. **并发安全**：
|
||
- DiskCache 支持多进程并发访问
|
||
- 但在高并发场景下可能成为瓶颈
|
||
|
||
4. **调试**：
|
||
- 查看日志中的缓存相关信息
|
||
- 使用 `stats` 命令监控缓存使用情况
|
||
- 必要时清空缓存重置状态
|
||
|
||
## 故障排查
|
||
|
||
### 缓存不生效
|
||
|
||
1. 检查 `session_id` 是否设置（必须有 session_id 才会使用缓存）
|
||
2. 检查缓存目录是否存在且有写权限
|
||
3. 查看日志中是否有缓存相关错误
|
||
|
||
### 缓存过多
|
||
|
||
1. 检查缓存大小限制设置
|
||
2. 使用 `cleanup` 命令清理旧缓存
|
||
3. 调整默认过期时间
|
||
|
||
### 性能问题
|
||
|
||
1. 监控缓存命中率
|
||
2. 考虑增加缓存大小
|
||
3. 优化 Agent 创建速度
|
||
|
||
## 示例输出
|
||
|
||
```
|
||
INFO: Using cached agent for session: user-123, cache_key: agent_cache_a1b2c3d4
|
||
INFO: Cache stats - Total items: 5, Size: 256.78 MB
|
||
INFO: Cached agent for session: user-456, cache_key: agent_cache_e5f6g7h8
|
||
``` |