# Semantic Cache：为LLM推理打造的分布式语义缓存层

> 一个OpenAI兼容的代理服务，通过向量相似性匹配实现语义级缓存，让相似问题复用已有答案，显著降低API调用成本和响应延迟。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-06-14T16:13:57.000Z
- 最近活动: 2026-06-14T16:20:32.406Z
- 热度: 161.9
- 关键词: LLM, 缓存, 向量搜索, OpenAI, Qdrant, 语义相似性, 性能优化, FastAPI, 多租户
- 页面链接: https://www.zingnex.cn/forum/thread/semantic-cache-llm
- Canonical: https://www.zingnex.cn/forum/thread/semantic-cache-llm
- Markdown 来源: ingested_event

---

## 原作者与来源

- **原作者/维护者**：Dhivakar A V（SRM IST-Trichy，CSE AI/ML 专业，2027届）
- **来源平台**：GitHub
- **原始标题**：semantic-cache
- **原始链接**：<https://github.com/dhivakarav/semantic-cache>
- **发布时间**：2026年6月14日

---

## 背景：为什么需要语义缓存？

在大语言模型（LLM）应用蓬勃发展的今天，API调用成本已成为许多产品的核心支出。传统的缓存策略基于精确匹配——只有当用户输入与历史查询完全一致时才能命中缓存。然而，现实场景中用户往往用不同的措辞表达相同的需求。

"北京天气怎么样？"和"今天北京会下雨吗？"本质上是同一个问题，但传统缓存会将它们视为完全不同的查询。这种语义层面的冗余请求造成了大量不必要的API调用，既浪费成本，又增加响应延迟。

---

## 项目概述

Semantic Cache 是一个分布式语义缓存层，专为LLM推理场景设计。它作为OpenAI兼容的代理服务运行，拦截所有API调用，通过向量嵌入和近似最近邻（ANN）搜索判断语义相似性，在匹配度超过阈值时直接返回缓存结果。

核心特性包括：

- **语义级匹配**：基于OpenAI text-embedding-3-small模型生成1536维向量表示
- **Qdrant向量存储**：高效的ANN搜索，支持TTL过期和多租户隔离
- **流式响应支持**：完整支持SSE（Server-Sent Events）流式传输的缓存与回放
- **智能阈值校准**：针对不同查询类型（事实性、代码、创意）配置不同的相似度阈值
- **冷启动预热**：通过k-means聚类历史查询日志，预生成代表性答案

---

## 技术架构解析

整个系统由几个关键组件协同工作：

### 1. FastAPI代理层

代理服务监听8000端口，提供与OpenAI完全兼容的API接口。当收到请求时，它执行以下步骤：

1. 使用SHA-256对系统提示词进行指纹计算
2. 调用OpenAI嵌入服务将用户输入转换为向量
3. 在Qdrant中执行ANN搜索查找相似历史查询
4. 如果找到相似度超过阈值的缓存项，直接返回缓存结果
5. 否则转发到上游LLM，并将结果存入缓存

### 2. 多租户隔离机制

每个租户的缓存通过`{tenant_id}:{system_prompt_fingerprint}`进行命名空间隔离。这意味着：

- 不同组织的数据完全隔离，不存在跨租户泄露风险
- 同一租户内不同系统提示词也会分别缓存，避免上下文混淆
- 租户ID通过HTTP头`X-Tenant-ID`传递，实现无感知切换

### 3. 查询类型感知的阈值策略

项目摒弃了固定的余弦相似度阈值，采用更精细的分类策略：

| 查询类型 | 默认阈值 | 设计考量 |
|---------|---------|---------|
| 事实性查询 | 0.96 | 需要极高准确性，避免错误答案被缓存复用 |
| 代码查询 | 0.94 | 代码语义敏感，细微差异可能导致完全不同的结果 |
| 创意查询 | 0.90 | 允许更大的语义漂移，相似问题可共享创意灵感 |

更进一步，项目还实现了基于逻辑回归的阈值校准器。通过训练`(query_A, query_B, should_cache: bool)`样本对，分类器比固定阈值的效果提升了约15%。

### 4. 流式响应的处理艺术

LLM的流式输出（SSE）给缓存带来了额外挑战。Semantic Cache的解决方案是：

- 首次请求时，代理缓冲所有流式token，完整写入缓存后再返回给客户端
- 缓存命中时，从存储中读取完整响应，重新模拟SSE流式传输
- 客户端完全感知不到数据来自缓存还是实时生成

这种设计确保了用户体验的一致性，同时享受了缓存带来的性能提升。

---

## 性能表现

根据项目提供的基准测试数据：

```
请求1 — 缓存未命中 → 转发到上游LLM    126 ms
请求2 — 缓存命中   → 从Qdrant返回      4 ms   ✓ 31倍加速
请求3 — 不同租户   → 缓存未命中（隔离） 126 ms
请求4 — 流式命中   → SSE缓存回放       32 ms   ✓
```

缓存命中时的响应时间从126毫秒降至4毫秒，实现了31倍的性能提升。这对于高并发场景下的用户体验改善具有显著意义。

---

## 部署与使用

项目提供了多种部署方式，从简单到复杂：

### Docker Hub一键启动（最简单）

```bash
docker run -e OPENAI_API_KEY=sk-... -p 8000:8000 dhivakarav/semantic-cache
```

### Docker Compose完整栈

```bash
OPENAI_API_KEY=sk-... docker-compose -f docker/docker-compose.yml up
```

### 本地开发环境

```bash
# 安装依赖
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt

# 配置环境变量
cp .env.example .env
# 编辑.env，添加OPENAI_API_KEY

# 启动Qdrant（另一个终端）
docker run -p 6333:6333 qdrant/qdrant

# 运行代理服务
uvicorn src.proxy.server:app --host 0.0.0.0 --port 8000
```

---

## 客户端集成示例

任何使用OpenAI SDK的客户端只需修改base_url即可接入：

```python
from openai import OpenAI

client = OpenAI(
    api_key="your-key",
    base_url="http://localhost:8000/v1",
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "法国的首都是哪里？"}],
)
```

多租户场景下，只需添加额外HTTP头：

```python
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[...],
    extra_headers={"X-Tenant-ID": "org-123"},
)
```

---

## 项目技术栈

- **FastAPI**：异步代理服务器框架
- **Qdrant**：高性能向量数据库，支持ANN搜索
- **OpenAI Embeddings**：text-embedding-3-small模型（1536维）
- **scikit-learn**：阈值校准分类器
- **httpx**：异步HTTP客户端

---

## 测试覆盖

项目包含17个测试用例，涵盖：

- 缓存未命中/命中/TTL过期
- 多租户命名空间隔离
- 系统提示词指纹隔离
- 按查询类型的阈值强制执行
- 流式SSE转发和缓存回写
- 流式缓存回放

测试使用内存中的Qdrant实例和合成嵌入向量，无需真实API密钥或Docker环境即可运行。

---

## 总结与思考

Semantic Cache 代表了一种务实的工程思维：在LLM应用成本日益攀升的背景下，通过智能缓存策略实现显著的性能和成本优化。

这个项目的亮点在于：

1. **完全兼容OpenAI接口**：零成本迁移现有应用
2. **生产级特性**：多租户、流式支持、TTL过期、冷启动预热
3. **智能阈值策略**：区分查询类型，避免一刀切
4. **可观测性**：清晰的命中/未命中日志，便于监控

对于正在构建LLM应用的开发者来说，这是一个值得评估的基础设施组件。特别是在高QPS、查询模式相对集中的场景（如客服机器人、知识库问答），语义缓存的收益将非常明显。

作为SRM IST-Trichy大学的毕业设计项目，Semantic Cache展现了扎实的工程能力和对LLM应用痛点的深刻理解。