ClawHub

Smart Cache

Data & APIs

本地智能缓存系统，为AI助手提供语义级别的请求缓存。当用户需要(1)减少重复API调用成本、(2)加速相似问题的响应、(3)创建本地缓存层来优化AI助手性能时使用此技能。支持精确匹配(L1)和语义相似匹配(L2)两种缓存模式。

Install

openclaw skills install 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
}

配置说明：

参数默认值说明
l1_max_size10000L1 缓存最大条目数
l2_max_size5000L2 缓存最大条目数
ttl_hours168缓存过期时间（小时），约 7 天
similarity_threshold0.85L2 语义匹配阈值（0-1）
embedding_provideropenaiembedding 提供者：openai、dashscope、local
embedding_modeltext-embedding-3-smallembedding 模型名称
api_key-API Key（支持 OPENAI_API_KEY / DASHSCOPE_API_KEY 环境变量）
enable_cost_trackingtrue是否启用成本追踪

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 天

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

  3. 调整相似度阈值：

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

  4. 定期清理：

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

  5. 监控缓存效果：

    • 命中率 > 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 - 配置文件模板
More in Data & APIs