Redis LangCache 语义缓存

该能力将 Redis LangCache（一款全托管式语义缓存服务）集成至 OpenClaw 工作流中。LangCache 存储 LLM 的 prompt 和响应，对语义相似的查询返回已缓存结果，从而降低调用成本与延迟。

前提条件

使用 LangCache 前，请确保已配置以下环境变量：

LANGCACHE_HOST=
LANGCACHE_CACHE_ID=
LANGCACHE_API_KEY=

请将这些变量保存在 ~/.openclaw/secrets.env 中，或在 OpenClaw 设置中进行配置。

核心操作

搜索缓存响应

调用 LLM 前，先检查是否存在语义相似的已缓存响应：

./scripts/langcache.sh search "什么是语义缓存？"

指定相似度阈值（0.0–1.0，数值越高匹配越严格）：

./scripts/langcache.sh search "什么是语义缓存？" --threshold 0.95

结合属性过滤进行搜索：

./scripts/langcache.sh search "什么是语义缓存？" --attr "model=gpt-5"

存储新响应

收到 LLM 响应后，将其缓存以供后续复用：

./scripts/langcache.sh store "什么是语义缓存？" "语义缓存基于语义相似性存储响应……"

添加属性以支持过滤与组织：

./scripts/langcache.sh store "prompt" "response" --attr "model=gpt-5" --attr "user_id=123"

删除缓存条目

按条目 ID 删除：

./scripts/langcache.sh delete --id ""

按属性删除：

./scripts/langcache.sh delete --attr "user_id=123"

清空缓存

清除所有条目（请谨慎使用）：

./scripts/langcache.sh flush

集成模式

LangCache 在 agent 工作流中的推荐集成模式如下：

1. 接收用户 prompt
2. 在 LangCache 中搜索语义相似的已缓存响应
3. 若命中缓存（相似度 >= 阈值）：
   - 立即返回缓存响应
   - 记录缓存命中日志，用于可观测性分析
4. 若未命中缓存：
   - 调用 LLM API
   - 将 prompt + 响应存入 LangCache
   - 返回 LLM 响应

默认缓存策略

该策略由系统自动强制执行。所有缓存操作 必须遵守 下列规则。

CACHEABLE（白名单）

NEVER CACHE（硬性拦截）

以下类型的内容在 代码层被明确拦截 —— 缓存操作将拒绝存储此类数据。

检测正则模式

以下正则表达式模式将触发硬性拦截：

# 时效性
b(today|tomorrow|tonight|yesterday)b
b(this|next|last)s+(week|month|year|monday|tuesday|...)b
b(ins+d+s+(minutes?|hours?|days?))b
b(deadline|eta|appointment|schedule[d]?)b

# 凭证类
b(api[_-]?key|token|password|secret|otp|2fa)b
b(bearer|auth[orization]*)s+S+

# 标识符
bd{10,}b                          # 电话号码、长 ID
b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+   # 邮箱
b(order|account|message|chat)[_-]?idb

# 个人上下文
b(mys+(wife|husband|partner|friend|boss|mom|dad|brother|sister))b
b(saids+tos+me|tolds+me|betweens+us)b

属性策略

使用属性对缓存进行分区管理：

• model：所使用的 LLM 模型（模型切换时尤为有用）
• category：factual、template、style、command
• skill：生成该响应的技能模块
• version：API 或 prompt 版本

搜索策略

LangCache 支持两种搜索策略：

• semantic（默认）：基于向量的语义相似度匹配
• exact：不区分大小写的精确匹配

可组合使用两者实现混合搜索：

./scripts/langcache.sh search "prompt" --strategy "exact,semantic"

可观测性

监控缓存性能指标：

• 追踪缓存命中率（hit/miss ratio）
• 记录命中的相似度得分
• 对高未命中率发出告警（可能表明阈值设置过高）
• 定期审查已存储条目，确保其相关性与有效性

参考文档

• API Reference — 完整的 REST API 文档
• Best Practices — 性能优化实践指南

示例

• examples/basic-caching.sh — 基础缓存工作流示例
• examples/agent-integration.py — Python 集成模式示例