如何用 CAMEL SemanticCache 按语义相似度缓存 LLM 响应并验证命中率【免费下载链接】camel CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org项目地址: https://gitcode.com/GitHub_Trending/ca/camel当你用 CAMEL 构建应用时LLM 经常会收到大量表述不同但语义相同的请求。SemanticCache就是为这种场景设计的它把查询文本转成向量嵌入存入向量库查询时按余弦相似度检索只有相似度达到阈值才返回缓存的响应。本文基于仓库中的 SemanticCache 源码、端到端示例 和 单元测试走一遍「初始化缓存 → 写入条目 → 相似查询 → 读取命中率」的完整路径。准备条件根据安装文档 docs/get_started/installation.md 和示例脚本头部说明需要满足Python 版本3.10 and 3.14可用python3 --version检查安装 CAMELpip install camel-ai[all]功能齐全的安装方式核心安装为pip install camel-ai用pip show camel-ai验证示例脚本声明的前置依赖faiss-cpu或faiss-gpu向量存储以及可选的sentence-transformers本地嵌入模型。嵌入模型有两条路径示例脚本会按OPENAI_API_KEY是否存在自动选择设置了OPENAI_API_KEY使用OpenAIEmbedding需要联网未设置使用本地SentenceTransformerEncoder(model_nameall-MiniLM-L6-v2)无需 API key。快速跑通官方示例最短路径是直接运行仓库自带示例python examples/caches/semantic_cache_example.py示例按 9 步演示完整功能初始化嵌入模型打印嵌入维度→ 用FaissStorage创建向量存储余弦距离→ 创建SemanticCache阈值 0.85→ 写入 3 条样例 query-response 对 → 用 5 条测试查询验证命中与未命中 → 演示写入相似查询时的自动去重替换 → 打印缓存统计 → 演示find_similar→ 演示禁用与清空。预期输出形态示例文档中的运行结果具体相似度数值随嵌入模型而异与已缓存条目语义相同的查询如Whats the capital city of France?对应已缓存的What is the capital of France?输出✓ CACHE HIT (similarity: ...)并带出响应主题不同的查询如What is the weather like today?输出✗ CACHE MISS最后打印stats中的hits、misses、hit_rate和条目数。自己组装缓存最小可用代码以下是示例脚本中可直接复用的主路径示例源码 第 1–5 步的精简版from camel.caches import SemanticCache from camel.embeddings import SentenceTransformerEncoder from camel.storages import FaissStorage from camel.types import VectorDistance # 1. 嵌入模型本地 all-MiniLM-L6-v2无需 API key embedding_model SentenceTransformerEncoder(model_nameall-MiniLM-L6-v2) vector_dim embedding_model.get_output_dim() # 2. 内存 FAISS 向量存储余弦相似度 vector_storage FaissStorage( vector_dimvector_dim, distanceVectorDistance.COSINE, ) # 3. 创建语义缓存0.85 表示相似度需达到 85% 才算命中 cache SemanticCache( embedding_modelembedding_model, vector_storagevector_storage, similarity_threshold0.85, ) # 4. 写入 query-response 对返回条目 IDmetadata 为可选附加数据 cache_id cache.set( queryWhat is Python programming language?, responsePython is a high-level, interpreted programming language ..., metadata{source: example}, ) # 5. 用措辞不同但语义相似的查询检索 result cache.get_with_score(What is the Python programming language used for?) if result: response, similarity, record result # 命中返回 (响应, 相似度, 完整记录) else: response None # 未命中或无结果若使用 OpenAI 嵌入把第 1 步换成OpenAIEmbedding()即可需设置OPENAI_API_KEY。set()在缓存被禁用enabledFalse时返回Nonequery或response为空会抛出ValueError。验证命中率与命中/未命中行为单次查询判断get_with_score(query)命中时返回三元组(response, similarity, CacheRecord)其中CacheRecord含query、response、query_id、created_at、metadata字段未命中无结果或最高相似度低于阈值返回None。若只想要响应文本用get(query)返回str或None。整体命中率cache.stats返回字典包含hits、misses、hit_rate、size、enabled、similarity_threshold六个键hit_rate单独也有属性。命中率定义为hits / (hits misses)尚未查询过时为0.0。每次get/get_with_score调用无论命中与否都会更新计数。单元测试 test/caches/test_semantic_cache.py 给出了可对照的行为断言相似度0.95≥ 阈值0.85时get返回缓存响应stats[hits] 1相似度0.5 阈值时get返回Nonestats[misses] 1空字符串或纯空白查询直接返回None3次命中 7次未命中时hit_rate 0.3find_similar(query, top_k3)返回按相似度降序的(CacheRecord, similarity)列表且不受阈值过滤——即使相似度低于0.75的条目也会返回适合排查「为什么没命中」。去重替换行为set()写入前会检索是否已存在相似度达到阈值的条目若存在先删除旧条目再写入新条目。示例第 6 步演示了这一点对已缓存的What is Python programming language?写入新的What is Python?后cache.size仍为 3且get(What is Python?)返回更新后的响应。相似度低于阈值时则不替换只追加。边界条件与限制阈值取值similarity_threshold必须在0.0到1.0之间含端点构造时或后续赋值越界都会抛出ValueError默认值为0.85。阈值越高命中要求越严格。相似度归一化不同向量存储后端返回的分数范围可能不同SemanticCache内部会把相似度钳制到0.0–1.0后再与阈值比较。禁用与清空cache.enabled False后get/get_with_score/set均直接返回None不会读写向量库cache.clear()会删除全部条目并将hits、misses归零。存储位置示例使用内存 FAISS进程结束后缓存不保留metadata以 JSON 字符串形式存入 payload以兼容不支持嵌套字典的存储后端。异常处理嵌入生成或向量库查询失败时_query_similar记录 warning 并返回None查询表现为未命中不会抛出异常中断调用方。下一步各方法完整签名与返回类型见 SemanticCache API 参考基类BaseCache/CacheRecord的接口定义在 camel/caches/base.py可对照理解get、set、delete、clear的抽象契约若要把缓存接入真实 LLM 调用链路参考 CAMEL 安装与配置文档 中关于OPENAI_API_KEY等环境变量的设置方式。【免费下载链接】camel CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org项目地址: https://gitcode.com/GitHub_Trending/ca/camel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
如何用 CAMEL SemanticCache 按语义相似度缓存 LLM 响应并验证命中率？
如何用 CAMEL SemanticCache 按语义相似度缓存 LLM 响应并验证命中率【免费下载链接】camel CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org项目地址: https://gitcode.com/GitHub_Trending/ca/camel当你用 CAMEL 构建应用时LLM 经常会收到大量表述不同但语义相同的请求。SemanticCache就是为这种场景设计的它把查询文本转成向量嵌入存入向量库查询时按余弦相似度检索只有相似度达到阈值才返回缓存的响应。本文基于仓库中的 SemanticCache 源码、端到端示例 和 单元测试走一遍「初始化缓存 → 写入条目 → 相似查询 → 读取命中率」的完整路径。准备条件根据安装文档 docs/get_started/installation.md 和示例脚本头部说明需要满足Python 版本3.10 and 3.14可用python3 --version检查安装 CAMELpip install camel-ai[all]功能齐全的安装方式核心安装为pip install camel-ai用pip show camel-ai验证示例脚本声明的前置依赖faiss-cpu或faiss-gpu向量存储以及可选的sentence-transformers本地嵌入模型。嵌入模型有两条路径示例脚本会按OPENAI_API_KEY是否存在自动选择设置了OPENAI_API_KEY使用OpenAIEmbedding需要联网未设置使用本地SentenceTransformerEncoder(model_nameall-MiniLM-L6-v2)无需 API key。快速跑通官方示例最短路径是直接运行仓库自带示例python examples/caches/semantic_cache_example.py示例按 9 步演示完整功能初始化嵌入模型打印嵌入维度→ 用FaissStorage创建向量存储余弦距离→ 创建SemanticCache阈值 0.85→ 写入 3 条样例 query-response 对 → 用 5 条测试查询验证命中与未命中 → 演示写入相似查询时的自动去重替换 → 打印缓存统计 → 演示find_similar→ 演示禁用与清空。预期输出形态示例文档中的运行结果具体相似度数值随嵌入模型而异与已缓存条目语义相同的查询如Whats the capital city of France?对应已缓存的What is the capital of France?输出✓ CACHE HIT (similarity: ...)并带出响应主题不同的查询如What is the weather like today?输出✗ CACHE MISS最后打印stats中的hits、misses、hit_rate和条目数。自己组装缓存最小可用代码以下是示例脚本中可直接复用的主路径示例源码 第 1–5 步的精简版from camel.caches import SemanticCache from camel.embeddings import SentenceTransformerEncoder from camel.storages import FaissStorage from camel.types import VectorDistance # 1. 嵌入模型本地 all-MiniLM-L6-v2无需 API key embedding_model SentenceTransformerEncoder(model_nameall-MiniLM-L6-v2) vector_dim embedding_model.get_output_dim() # 2. 内存 FAISS 向量存储余弦相似度 vector_storage FaissStorage( vector_dimvector_dim, distanceVectorDistance.COSINE, ) # 3. 创建语义缓存0.85 表示相似度需达到 85% 才算命中 cache SemanticCache( embedding_modelembedding_model, vector_storagevector_storage, similarity_threshold0.85, ) # 4. 写入 query-response 对返回条目 IDmetadata 为可选附加数据 cache_id cache.set( queryWhat is Python programming language?, responsePython is a high-level, interpreted programming language ..., metadata{source: example}, ) # 5. 用措辞不同但语义相似的查询检索 result cache.get_with_score(What is the Python programming language used for?) if result: response, similarity, record result # 命中返回 (响应, 相似度, 完整记录) else: response None # 未命中或无结果若使用 OpenAI 嵌入把第 1 步换成OpenAIEmbedding()即可需设置OPENAI_API_KEY。set()在缓存被禁用enabledFalse时返回Nonequery或response为空会抛出ValueError。验证命中率与命中/未命中行为单次查询判断get_with_score(query)命中时返回三元组(response, similarity, CacheRecord)其中CacheRecord含query、response、query_id、created_at、metadata字段未命中无结果或最高相似度低于阈值返回None。若只想要响应文本用get(query)返回str或None。整体命中率cache.stats返回字典包含hits、misses、hit_rate、size、enabled、similarity_threshold六个键hit_rate单独也有属性。命中率定义为hits / (hits misses)尚未查询过时为0.0。每次get/get_with_score调用无论命中与否都会更新计数。单元测试 test/caches/test_semantic_cache.py 给出了可对照的行为断言相似度0.95≥ 阈值0.85时get返回缓存响应stats[hits] 1相似度0.5 阈值时get返回Nonestats[misses] 1空字符串或纯空白查询直接返回None3次命中 7次未命中时hit_rate 0.3find_similar(query, top_k3)返回按相似度降序的(CacheRecord, similarity)列表且不受阈值过滤——即使相似度低于0.75的条目也会返回适合排查「为什么没命中」。去重替换行为set()写入前会检索是否已存在相似度达到阈值的条目若存在先删除旧条目再写入新条目。示例第 6 步演示了这一点对已缓存的What is Python programming language?写入新的What is Python?后cache.size仍为 3且get(What is Python?)返回更新后的响应。相似度低于阈值时则不替换只追加。边界条件与限制阈值取值similarity_threshold必须在0.0到1.0之间含端点构造时或后续赋值越界都会抛出ValueError默认值为0.85。阈值越高命中要求越严格。相似度归一化不同向量存储后端返回的分数范围可能不同SemanticCache内部会把相似度钳制到0.0–1.0后再与阈值比较。禁用与清空cache.enabled False后get/get_with_score/set均直接返回None不会读写向量库cache.clear()会删除全部条目并将hits、misses归零。存储位置示例使用内存 FAISS进程结束后缓存不保留metadata以 JSON 字符串形式存入 payload以兼容不支持嵌套字典的存储后端。异常处理嵌入生成或向量库查询失败时_query_similar记录 warning 并返回None查询表现为未命中不会抛出异常中断调用方。下一步各方法完整签名与返回类型见 SemanticCache API 参考基类BaseCache/CacheRecord的接口定义在 camel/caches/base.py可对照理解get、set、delete、clear的抽象契约若要把缓存接入真实 LLM 调用链路参考 CAMEL 安装与配置文档 中关于OPENAI_API_KEY等环境变量的设置方式。【免费下载链接】camel CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org项目地址: https://gitcode.com/GitHub_Trending/ca/camel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
