Khazad：基于 Redis Vector Sets 的 LLM 语义缓存层

开发者 GuglielmoCerri 在 Hacker News 发布了开源项目 Khazad，一个面向 LLM API 调用的「传输层语义缓存」。它通过 Redis Vector Sets 存储请求的向量表示，在 HTTP 客户端层面拦截调用，对语义近似请求直接返回缓存结果，应用代码无需任何改动。

官方给出的参考数据为：在 0.50 命中率场景下，缓存命中约 280 ms，远端调用约 7900 ms，整体可减少约 50% 的 API 调用、降低约 50% 的费用。需要注意的是，项目方明确这些数字为「示意值」，实际效果取决于流量分布。

核心机制

Khazad 的设计围绕几个关键属性展开：

• 模型感知：按 (provider, model) 对分别建立向量集，不会把 gpt-4o 的回答误命中给 gpt-4o-mini；可通过 cache_scope="host" 改为按提供方主机隔离。
• 对话感知：对完整消息列表（system、user、assistant）整体嵌入，避免「对话不同但最后一句相同」造成的误命中。
• 双向流式支持：命中时以真实 SSE 流回放；未命中时逐 chunk 捕获流式响应，并在内部重组为规范 JSON，使流式与非流式请求可互相服务。中断的流不会被缓存。

使用场景与限制

项目建议在以下场景启用：FAQ 机器人、客服助手、RAG 前端等高重复流量；CI 与开发环境避免重复计费；需要确定性响应的演示与压测；以及存在成本上限的内部工具。

同时明确了几项运维注意事项：

• 提示与响应以明文存储在 Redis，涉及 PII 或密钥时需配置 TTL、启用 Redis AUTH/TLS。
• Patch 作用于整个 Python 进程，init() 之后创建的所有 httpx 客户端都会被包装；非 LLM 流量不受影响，但需在退出前调用 stop()。可通过 hosts=[...] 白名单限定拦截范围。
• 仅覆盖基于 httpx 的 SDK（OpenAI、Anthropic、Gemini 的 google-genai、Mistral 等），基于 requests、aiohttp 或 boto3（Bedrock）的 SDK 不被拦截。
• 缓存是单进程的，多 worker 共享 Redis 但各自需要调用 init()。
• 建议从 threshold=0.90 起步，通过 get_stats() 观察 avg_hit_similarity，若接近阈值说明流量多样性过高，不宜缓存。

安装与上手

环境要求 Python ≥ 3.10 与 Redis 8（需支持 Vector Sets），可通过 docker run -d --name redis8 -p 6379:6379 redis:8 启动。项目已发布到 PyPI，使用 uv add khazad 即可安装；如需 OpenAI 嵌入后端，可选 khazad[openai-embeddings]。本地开发则可从 GitHub GuglielmoCerri/khazad 克隆后 uv sync --group dev。

典型用法是直接实例化 Khazad 类并传入 redis_url、threshold、ttl 等参数，随后正常使用任何基于 httpx 的 LLM SDK 即可。仓库中提供了 OpenAI、Azure OpenAI 等多个示例，覆盖同步与流式调用场景。API 入口包括 init()、stop()、get_stats()、flush()、is_active()。