一个开源的语义缓存代理服务，通过向量相似度匹配实现智能缓存，帮助LLM产品大幅降低推理成本，解决传统哈希缓存无法处理自然语言变体的问题。

CacheIQ：基于语义相似度的LLM推理成本优化方案\n\n## LLM产品化的成本困境\n\n随着大型语言模型（LLM）的商业化应用日益普及，一个严峻的现实摆在开发者面前：推理成本与使用量呈线性增长。对于提供LLM服务的SaaS产品来说，这意味着随着用户规模扩大，API调用费用会迅速吞噬利润空间。\n\n传统的解决方案是引入缓存机制——当用户提出相同问题时直接返回缓存结果。然而，简单的哈希缓存存在一个根本性缺陷：自然语言具有无限的表达方式，用户可以用成千上万种不同的措辞提出本质上相同的问题。传统的精确匹配缓存对这些语义等价但表述不同的查询束手无策，导致企业不得不为回答"同一个问题"支付数千次费用。\n\n## CacheIQ 的解决方案\n\nCacheIQ 是一个基于语义相似度的智能缓存代理服务，它通过理解查询的语义而非仅仅匹配字符串，来解决传统缓存的局限性。该项目由 Mar10 Labs 开发，采用 Kotlin 和 Spring Boot 构建，集成了 pgvector 向量数据库来实现高效的语义检索。\n\n## 核心特性与架构\n\n### 语义缓存机制\n\nCacheIQ 的核心创新在于使用文本嵌入（embeddings）来表示查询的语义。当用户发送请求时，系统会：\n\n1. 将查询文本转换为高维向量表示\n2. 在向量数据库中搜索语义相似的过往查询\n3. 如果相似度超过设定阈值，直接返回缓存结果\n4. 否则，将请求转发给LLM并将结果存入缓存\n\n这种方法能够识别诸如"你好"和"您好"、"什么是机器学习"和"请解释机器学习的概念"等语义等价的查询，显著提高缓存命中率。\n\n### 技术栈选择\n\nCacheIQ 采用了企业级的技术栈：\n\n- Kotlin 21：现代化的JVM语言，提供空安全、协程等特性\n- Spring Boot 3.2：成熟的Java生态Web框架\n- PostgreSQL + pgvector：关系型数据库配合向量扩展，支持高效的余弦相似度搜索\n- Redis：用于会话管理\n- Micrometer + Prometheus：全面的指标监控\n- Grafana：可视化监控仪表盘\n\n### 分层架构设计\n\n项目遵循整洁架构原则，分为四个层次：\n\nAPI层（ProxyController）：接收HTTP请求，处理输入验证和响应格式化\n\n应用层（SemanticCacheUseCase）：实现业务逻辑，协调缓存查找和LLM调用\n\n领域层（Domain）：定义核心实体和输入/输出端口接口\n\n基础设施层（Infrastructure）：包含各种适配器实现，包括Groq API适配器、PostgreSQL缓存适配器、指标监控适配器等\n\n## 快速部署与使用\n\nCacheIQ 提供了完整的 Docker Compose 配置，使得部署变得非常简单：\n\nbash\n# 1. 克隆仓库\ngit clone https://github.com/Mar10-Labs/cache-iq && cd cache-iq\n\n# 2. 启动服务\ndocker compose up -d\n\n# 3. 验证服务状态\ncurl http://localhost:8081/actuator/health\n\n\n服务启动后，用户可以通过标准的HTTP API与LLM交互：\n\nbash\n# 首次调用 - 缓存未命中（MISS）\ncurl -X POST http://localhost:8081/proxy/chat \\\n -H \"Content-Type: application/json\" \\\n -H \"X-Tenant-Id: demo\" \\\n -d '{\"messages\":[{\"role\":\"user\",\"content\":\"Hello\"}], \"model\":\"llama-3.3-70b-versatile\"}'\n\n# 重复调用 - 缓存命中（HIT）\ncurl -X POST http://localhost:8081/proxy/chat \\\n -H \"Content-Type: application/json\" \\\n -H \"X-Tenant-Id: demo\" \\\n -d '{\"messages\":[{\"role\":\"user\",\"content\":\"Hello\"}], \"model\":\"llama-3.3-70b-versatile\"}'\n\n\n## 监控与可观测性\n\nCacheIQ 内置了完善的监控能力。通过响应头，客户端可以了解缓存状态：\n\n- X-Cache：显示 HIT 或 MISS\n- X-Cache-Llm-Model：使用的LLM模型\n- X-Cache-Llm-Provider：服务提供商（groq、claude等）\n- X-Cache-Embedding-Model：嵌入模型信息\n\n此外，系统还暴露了 Prometheus 指标端点和 Grafana 仪表盘，运维团队可以实时监控缓存命中率、响应延迟、错误率等关键指标。\n\n## 成本优化的实际效果\n\n对于典型的LLM应用场景，语义缓存可以带来显著的成本节约：\n\n客服问答系统：用户经常询问相似的问题，语义缓存可以将缓存命中率提升至60-80%，意味着相应的API成本降低。\n\n内容生成工具：当多个用户请求类似的内容（如"写一封求职信"）时，缓存可以避免重复生成。\n\n教育辅导应用：学生对同一知识点的提问往往表述不同但意图相同，语义缓存能有效识别这些等价查询。\n\n## 项目路线图与展望\n\nCacheIQ 目前处于积极开发阶段，已实现的功能包括语义缓存代理、嵌入模拟、Groq API模拟、完整的监控体系。正在开发的功能包括：\n\n- 真实的ONNX嵌入模型（all-MiniLM-L6-v2）支持\n- 真实的Groq API集成\n- PII（个人身份信息）检测功能\n- 更全面的测试覆盖\n\n## 开源价值与意义\n\n作为一个开源项目，CacheIQ 为LLM应用开发者提供了一个可立即投入生产的缓存解决方案。它不仅降低了LLM产品的运营成本，还展示了向量数据库在实际应用中的强大能力。\n\n对于正在构建LLM产品的团队来说，CacheIQ 提供了一个经过深思熟虑的架构参考，展示了如何将语义搜索、缓存策略和监控体系有机地整合在一起。该项目的MIT许可证也允许企业自由使用和定制。

CacheIQ：基于语义相似度的LLM推理成本优化方案\n\nLLM产品化的成本困境\n\n随着大型语言模型（LLM）的商业化应用日益普及，一个严峻的现实摆在开发者面前：推理成本与使用量呈线性增长。对于提供LLM服务的SaaS产品来说，这意味着随着用户规模扩大，API调用费用会迅速吞噬利润空间。\n\n传统的解决方案是引入缓存机制——当用户提出相同问题时直接返回缓存结果。然而，简单的哈希缓存存在一个根本性缺陷：自然语言具有无限的表达方式，用户可以用成千上万种不同的措辞提出本质上相同的问题。传统的精确匹配缓存对这些语义等价但表述不同的查询束手无策，导致企业不得不为回答"同一个问题"支付数千次费用。\n\nCacheIQ 的解决方案\n\nCacheIQ 是一个基于语义相似度的智能缓存代理服务，它通过理解查询的语义而非仅仅匹配字符串，来解决传统缓存的局限性。该项目由 Mar10 Labs 开发，采用 Kotlin 和 Spring Boot 构建，集成了 pgvector 向量数据库来实现高效的语义检索。\n\n核心特性与架构\n\n语义缓存机制\n\nCacheIQ 的核心创新在于使用文本嵌入（embeddings）来表示查询的语义。当用户发送请求时，系统会：\n\n1. 将查询文本转换为高维向量表示\n2. 在向量数据库中搜索语义相似的过往查询\n3. 如果相似度超过设定阈值，直接返回缓存结果\n4. 否则，将请求转发给LLM并将结果存入缓存\n\n这种方法能够识别诸如"你好"和"您好"、"什么是机器学习"和"请解释机器学习的概念"等语义等价的查询，显著提高缓存命中率。\n\n技术栈选择\n\nCacheIQ 采用了企业级的技术栈：\n\n- Kotlin 21：现代化的JVM语言，提供空安全、协程等特性\n- Spring Boot 3.2：成熟的Java生态Web框架\n- PostgreSQL + pgvector：关系型数据库配合向量扩展，支持高效的余弦相似度搜索\n- Redis：用于会话管理\n- Micrometer + Prometheus：全面的指标监控\n- Grafana：可视化监控仪表盘\n\n分层架构设计\n\n项目遵循整洁架构原则，分为四个层次：\n\nAPI层（ProxyController）：接收HTTP请求，处理输入验证和响应格式化\n\n应用层（SemanticCacheUseCase）：实现业务逻辑，协调缓存查找和LLM调用\n\n领域层（Domain）：定义核心实体和输入/输出端口接口\n\n基础设施层（Infrastructure）：包含各种适配器实现，包括Groq API适配器、PostgreSQL缓存适配器、指标监控适配器等\n\n快速部署与使用\n\nCacheIQ 提供了完整的 Docker Compose 配置，使得部署变得非常简单：\n\nbash\n1. 克隆仓库\ngit clone https://github.com/Mar10-Labs/cache-iq && cd cache-iq\n\n2. 启动服务\ndocker compose up -d\n\n3. 验证服务状态\ncurl http://localhost:8081/actuator/health\n\n\n服务启动后，用户可以通过标准的HTTP API与LLM交互：\n\nbash\n首次调用 - 缓存未命中（MISS）\ncurl -X POST http://localhost:8081/proxy/chat \\\n -H \"Content-Type: application/json\" \\\n -H \"X-Tenant-Id: demo\" \\\n -d '{\"messages\":[{\"role\":\"user\",\"content\":\"Hello\"}], \"model\":\"llama-3.3-70b-versatile\"}'\n\n重复调用 - 缓存命中（HIT）\ncurl -X POST http://localhost:8081/proxy/chat \\\n -H \"Content-Type: application/json\" \\\n -H \"X-Tenant-Id: demo\" \\\n -d '{\"messages\":[{\"role\":\"user\",\"content\":\"Hello\"}], \"model\":\"llama-3.3-70b-versatile\"}'\n\n\n监控与可观测性\n\nCacheIQ 内置了完善的监控能力。通过响应头，客户端可以了解缓存状态：\n\n- X-Cache：显示 HIT 或 MISS\n- X-Cache-Llm-Model：使用的LLM模型\n- X-Cache-Llm-Provider：服务提供商（groq、claude等）\n- X-Cache-Embedding-Model：嵌入模型信息\n\n此外，系统还暴露了 Prometheus 指标端点和 Grafana 仪表盘，运维团队可以实时监控缓存命中率、响应延迟、错误率等关键指标。\n\n成本优化的实际效果\n\n对于典型的LLM应用场景，语义缓存可以带来显著的成本节约：\n\n客服问答系统：用户经常询问相似的问题，语义缓存可以将缓存命中率提升至60-80%，意味着相应的API成本降低。\n\n内容生成工具：当多个用户请求类似的内容（如"写一封求职信"）时，缓存可以避免重复生成。\n\n教育辅导应用：学生对同一知识点的提问往往表述不同但意图相同，语义缓存能有效识别这些等价查询。\n\n项目路线图与展望\n\nCacheIQ 目前处于积极开发阶段，已实现的功能包括语义缓存代理、嵌入模拟、Groq API模拟、完整的监控体系。正在开发的功能包括：\n\n- 真实的ONNX嵌入模型（all-MiniLM-L6-v2）支持\n- 真实的Groq API集成\n- PII（个人身份信息）检测功能\n- 更全面的测试覆盖\n\n开源价值与意义\n\n作为一个开源项目，CacheIQ 为LLM应用开发者提供了一个可立即投入生产的缓存解决方案。它不仅降低了LLM产品的运营成本，还展示了向量数据库在实际应用中的强大能力。\n\n对于正在构建LLM产品的团队来说，CacheIQ 提供了一个经过深思熟虑的架构参考，展示了如何将语义搜索、缓存策略和监控体系有机地整合在一起。该项目的MIT许可证也允许企业自由使用和定制。