zhuchaowe/qwen_agent

Fork 0

朱潮 47f1d1c7eb cache

2025-12-17 23:05:42 +08:00

4.4 KiB

Raw Blame History

Agent 缓存系统

本文档描述了使用 DiskCache 实现的 Agent 缓存系统。

概述

Agent 缓存系统使用 DiskCache 来持久化缓存 Agent 实例，提供以下功能：

✅ 文件持久化：缓存存储在磁盘上，重启后仍然保留
✅ 自动过期：支持设置过期时间，自动清理过期项
✅ 缓存大小限制：可设置最大缓存大小，自动淘汰旧数据
✅ 访问时自动续期：每次访问时自动延长过期时间
✅ 线程安全：支持多线程并发访问

配置

环境变量

可以通过以下环境变量配置缓存行为：

AGENT_CACHE_DIR：缓存目录路径（默认：./projects/agent_cache）
AGENT_CACHE_SIZE_LIMIT：缓存大小限制，字节（默认：1073741824 = 1GB）
AGENT_CACHE_EXPIRE：默认过期时间，秒（默认：180 = 3分钟）

示例：

export AGENT_CACHE_DIR="/var/cache/agent"
export AGENT_CACHE_SIZE_LIMIT="5368709120"  # 5GB
export AGENT_CACHE_EXPIRE="600"  # 10分钟

代码配置

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。

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. 手动使用缓存

如果需要在其他地方使用缓存：

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']}")

缓存管理工具

项目提供了缓存管理脚本：

# 查看缓存统计
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，则不使用缓存。

注意事项

性能考虑：
- 缓存存储在磁盘上，首次访问会有 I/O 开销
- 建议使用 SSD 存储缓存以提高性能
- 过期时间不宜设置过短，避免频繁重新创建 Agent
内存管理：
- Agent 对象可能占用较大内存
- 设置合理的缓存大小限制
- 定期清理不用的缓存项
并发安全：
- DiskCache 支持多进程并发访问
- 但在高并发场景下可能成为瓶颈
调试：
- 查看日志中的缓存相关信息
- 使用 stats 命令监控缓存使用情况
- 必要时清空缓存重置状态

故障排查

缓存不生效

检查 session_id 是否设置（必须有 session_id 才会使用缓存）
检查缓存目录是否存在且有写权限
查看日志中是否有缓存相关错误

缓存过多

检查缓存大小限制设置
使用 cleanup 命令清理旧缓存
调整默认过期时间

性能问题

监控缓存命中率
考虑增加缓存大小
优化 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

4.4 KiB Raw Blame History Unescape Escape