Semantic Cache — 语义缓存

每次相似问题都重新推理 = 浪费 40-60% token。语义缓存让"这个之前查过了"自动复用。

一、原理

不是精确匹配（"TTS不工作" 和 "TTS出问题了" 是同一个意思），而是语义相似匹配。

查询 → 提取语义向量（本地embedding或关键词hash）
     ↓
  缓存命中？（相似度 > 0.85）
  ├─ 是 → 直接返回缓存结果（省 100% token）
  └─ 否 → 正常推理 → 结果存入缓存

二、三级缓存

三、适用场景（高命中率）

四、不适用（不要缓存）

• 涉及实时状态的查询（"现在几点""当前git状态"）
• 需要执行操作的查询（"帮我改这个文件"）
• 用户明确说"重新查"
• 安全/隐私相关查询

五、实现

# D:/Hermes/scripts/semantic_cache.py
import json, hashlib, time
from pathlib import Path

CACHE_DIR = Path("D:/Hermes/cache/semantic")
CACHE_DIR.mkdir(parents=True, exist_ok=True)

def get_cache_key(query, context=""):
    """生成语义缓存键：关键词提取 + hash"""
    # 提取有意义的词（去掉停用词）
    words = [w for w in query.lower().split() 
             if w not in STOP_WORDS and len(w) > 1]
    key = "|".join(sorted(words[:5]))  # 取前5个关键词
    return hashlib.md5(key.encode()).hexdigest()[:12]

def check(query, max_age_hours=6):
    """检查缓存"""
    key = get_cache_key(query)
    cache_file = CACHE_DIR / f"{key}.json"
    if cache_file.exists():
        data = json.loads(cache_file.read_text())
        age = time.time() - data["timestamp"]
        if age < max_age_hours * 3600:
            return data["result"]  # 命中！
    return None  # 未命中

def store(query, result):
    """存入缓存"""
    key = get_cache_key(query)
    cache_file = CACHE_DIR / f"{key}.json"
    cache_file.write_text(json.dumps({
        "query": query[:200],
        "result": result[:5000],
        "timestamp": time.time()
    }))

六、Agent 使用模式

每次回答用户前：
1. cache = check(user_query)
2. if cache:
     answer = cache + " [缓存命中]"
   else:
     answer = think_and_answer(user_query)
     store(user_query, answer)

七、与 context-engine 联动

• context-engine 的 prompt-cache 保留策略 = API 层面的缓存
• semantic-cache = 应用层面的缓存
• 两层叠加 → 总节省 60-80%

八、监控

# 缓存命中率
python D:/Hermes/scripts/semantic_cache.py --stats
# 输出: 命中率 47% | 已省 ~120K token | 节省 ~$0.35