sunlixue-smart-cache（孙立雪智能缓存）

Smart Cache - 本地智能缓存系统

概述

Smart Cache 是一个为 OpenClaw/QClaw 设计的本地智能缓存系统，通过缓存 AI 响应来减少 API 调用成本和响应时间。

核心功能：

• L1 精确缓存：完全相同的请求直接返回缓存结果
• L2 语义缓存：语义相似的请求返回相似结果（基于向量嵌入）
• 缓存管理：自动过期、容量限制、手动清理
• 成本追踪：记录节省的 token 和费用
• MCP 协议接口：支持与其他 AI 工具集成

快速开始

检查缓存状态

python scripts/cache_manager.py status

查询缓存

# 精确查询
python scripts/cache_manager.py query "你好，今天天气怎么样？"

# 语义查询（返回相似度 > 0.85 的结果）
python scripts/cache_manager.py query-semantic "今天天气如何？" --threshold 0.85

添加缓存

python scripts/cache_manager.py add "你好" "你好！有什么可以帮助你的吗？"

清理缓存

# 清理过期缓存
python scripts/cache_manager.py clean --expired

# 清理全部
python scripts/cache_manager.py clean --all

# 清理特定时间范围
python scripts/cache_manager.py clean --before "2024-01-01"

缓存模式

L1 精确缓存 (Exact Cache)

适用于完全相同的请求。使用 SHA256 哈希作为 key，O(1) 查找时间。

特点：

• 100% 准确率，零误判
• 适用于重复性问题

示例：

用户: "什么是Python？"
→ 缓存命中 → 直接返回缓存的回答

L2 语义缓存 (Semantic Cache)

适用于语义相似但不完全相同的请求。需要配置 embedding API 才能启用。

工作原理：

1. 将查询文本转换为向量嵌入（需要 API Key）
2. 在缓存中查找与查询向量相似度最高的条目
3. 返回相似度超过阈值的缓存结果

特点：

• 支持 OpenAI、DashScope（阿里云）、本地模型三种 embedding 来源
• 基于余弦相似度匹配
• 可配置阈值（默认 0.85）

示例：

缓存: "今天天气怎么样？" → "今天晴天，气温25度..."
查询: "今天天气如何？"
→ 相似度 0.92 → 返回缓存的回答

注意： L2 语义匹配需要 embedding API 支持（详见配置说明）。

配置

配置文件位于 ~/.qclaw/smart-cache/config.json：

{
  "cache_dir": "~/.qclaw/smart-cache/data",
  "l1_max_size": 10000,
  "l2_max_size": 5000,
  "ttl_hours": 168,
  "similarity_threshold": 0.85,
  "embedding_provider": "openai",
  "embedding_model": "text-embedding-3-small",
  "api_key": "your-api-key",
  "enable_cost_tracking": true
}

配置说明：

Embedding Provider 配置

OpenAI（推荐）：

{
  "embedding_provider": "openai",
  "embedding_model": "text-embedding-3-small",
  "api_key": "sk-..."
}

阿里云 DashScope：

{
  "embedding_provider": "dashscope",
  "embedding_model": "text-embedding-v1",
  "api_key": "your-dashscope-key"
}

本地模型（无需 API Key）：

{
  "embedding_provider": "local",
  "embedding_model": "all-MiniLM-L6-v2"
}

本地模型需要安装：pip install sentence-transformers

成本追踪

查看节省的成本：

python scripts/cache_manager.py stats

输出示例：

📊 缓存统计
━━━━━━━━━━━━━━━━━━━━━━━━━━━
总请求数: 1,234
L1命中: 456 (37%)
L2命中: 189 (15%)
缓存未命中: 589 (48%)

💰 成本节省
━━━━━━━━━━━━━━━━━━━━━━━━━━━
节省Token: 89,234
估算节省: $0.27

集成到 OpenClaw

方法1：作为 MCP Server 运行

MCP Server 支持 stdio 和 HTTP 两种模式。

stdio 模式（推荐，用于 OpenClaw）：

python scripts/mcp_server.py --mode stdio

HTTP 模式（用于其他工具）：

python scripts/mcp_server.py --mode http --port 8080

方法2：直接 API 调用

from scripts.cache_api import SmartCache

cache = SmartCache()

# 查询缓存
result = cache.query("用户的问题")
if result:
    print(f"缓存命中！相似度: {result.similarity}")
    print(f"回答: {result.response}")
else:
    # 调用实际API
    response = call_llm_api("用户的问题")
    # 存入缓存
    cache.store("用户的问题", response)

脚本说明

scripts/cache_manager.py

主缓存管理工具，提供命令行接口：

• status - 查看缓存状态
• query - 精确查询
• query-semantic - 语义查询（L2，需要 embedding 配置）
• add - 添加缓存条目
• clean - 清理缓存
• stats - 查看统计信息

scripts/cache_api.py

Python API 模块，提供编程接口：

• SmartCache - 主缓存类
• CacheEntry - 缓存条目类
• CacheStats - 统计信息类

scripts/embeddings.py

向量嵌入工具，支持多种 embedding 来源：

• OpenAIEmbeddings - OpenAI Embedding API
• DashScopeEmbeddings - 阿里云 DashScope API
• LocalEmbeddings - 本地 sentence-transformers 模型

用法示例：

from scripts.embeddings import get_text_embedding, compute_similarity

# 获取单条文本的嵌入向量
emb = get_text_embedding("你好")

# 计算两条文本的相似度
sim = compute_similarity("今天天气怎么样", "今天天气好吗")

scripts/mcp_server.py

MCP 协议服务器，支持与其他 AI 工具集成：

• stdio 模式：用于 OpenClaw MCP 集成
• http 模式：用于其他支持 HTTP 的工具

最佳实践

1. 合理设置 TTL：根据内容更新频率设置过期时间

- 事实性内容：7 天 - 时效性内容：1-24 小时 - 永久性内容：30 天

1. L2 语义缓存需要 API Key：如果未配置 embedding，L2 查询会使用字符级 Jaccard 作为后备方案

1. 调整相似度阈值：

- 严格匹配：0.95 - 常规使用：0.85 - 宽松匹配：0.75

1. 定期清理：

   # 每周清理一次过期缓存
   0 0 * * 0 python ~/.qclaw/smart-cache/scripts/cache_manager.py clean --expired

1. 监控缓存效果：

- 命中率 > 30% 表示缓存有效 - 命中率 < 10% 考虑调整阈值或 TTL

故障排除

缓存未命中率高

1. 检查相似度阈值是否过高
2. 确认缓存容量是否足够
3. 检查 TTL 设置是否过短

语义匹配不准确

1. 确认已配置 embedding API（检查 config.json 中的 api_key）
2. 尝试不同的 embedding 模型
3. 调整相似度阈值

API Key 相关错误

1. 确认在 ~/.qclaw/smart-cache/config.json 中配置了 api_key
2. 或设置环境变量 OPENAI_API_KEY / DASHSCOPE_API_KEY
3. 检查 API Key 是否有效、未过期

磁盘空间问题

1. 减小缓存容量（l1_max_size、l2_max_size）
2. 缩短 TTL（ttl_hours）
3. 定期运行清理：cache_manager.py clean --expired

资源

scripts/

• cache_manager.py - 命令行管理工具
• cache_api.py - Python API 模块
• mcp_server.py - MCP 协议服务器
• embeddings.py - 向量嵌入工具

references/

• api_reference.md - API 详细文档

assets/

• config_template.json - 配置文件模板