GPTCache 语义缓存实战指南：为 LLM 查询构建精准命中与相似检索缓存

AI 应用大模型【免费下载链接】GPTCacheSemantic cache for LLMs. Fully integrated with LangChain and llama_index.项目地址https://gitcode.com/gh_mirrors/gp/GPTCache点击查看免费下载GPTCache 是一个为 LLM 查询构建语义缓存Semantic Cache的开源 Python 库它以极简的 API 接入方式大幅降低 LLM API 调用费用并显著提升响应速度同时已完整集成 LangChain 与 llama_index。本文将以 docs/index.rst 为核心主线结合仓库源码深入讲解语义缓存的原理、安装配置、快速上手、六大模块架构与性能评估方法帮助你从零掌握 GPTCache 的接入与调优。为什么需要 LLM 语义缓存ChatGPT 等大语言模型LLM具备极强的通用性催生了大量上层应用。但随着应用流量增长LLM API 调用的开销会迅速放大且在高并发场景下LLM 服务的响应延迟也会明显上升。GPTCache 正是为了解决这两个核心痛点而设计它将 LLM 的响应结果缓存下来让相似的查询直接命中缓存从而减少请求与 token 消耗、缩短响应时间。传统缓存系统通常依赖精确匹配Exact Match只有当新查询与缓存查询完全一致时才能命中。但对于 LLM 查询而言用户提问方式千变万化、措辞高度灵活精确匹配的命中率极低。GPTCache 因此采用语义缓存策略通过 embedding 算法把查询转换为向量再用向量存储做相似度检索从而把语义相近而非字面相同的查询也纳入命中范围显著提升缓存命中率与整体效率。快速安装与环境准备GPTCache 的安装非常轻量一条命令即可完成pip install gptcache从 setup.py 与 requirements.txt 可以看出默认安装只引入支撑基础缓存功能的少量核心依赖当使用额外特性如 Faiss 向量库、ONNX 模型、SQLAlchemy 存储等时相关依赖库会在运行期自动安装例如 gptcache/utils/dependency_control.py 中封装的import_faiss、import_onnxruntime、import_sqlalchemy等惰性导入函数。开发环境安装源码方式# clone GPTCache repo git clone -b dev https://github.com/zilliztech/GPTCache.git cd GPTCache # install the repo pip install -r requirements.txt python setup.py install环境要求与注意事项Python 版本需为3.8.1 或更高可用python --version确认。若因 pip 版本过低导致依赖安装失败先执行python -m pip install --upgrade pip。运行 OpenAI 示例前必须先设置OPENAI_API_KEY环境变量Unix/Linux/macOS 用export OPENAI_API_KEYYOUR_API_KEYWindows 用set OPENAI_API_KEYYOUR_API_KEY。注意这种设置方式仅对当前终端会话有效如需永久生效需修改环境变量配置文件例如 macOS 上的/etc/profile。快速开始三步接入 GPTCacheGPTCache 的接入成本极低。以 OpenAI ChatCompletion 为例无需修改任何已有业务代码只需引入缓存模块并完成初始化from gptcache import cache from gptcache.adapter import openai cache.init() cache.set_openai_key()cache.init()完成 GPTCache 核心对象的初始化。从 gptcache/core.py 的Cache.init()可以看到默认配置为cache_enable_funccache_all始终启用缓存、pre_embedding_funclast_content取消息列表最后一条内容作为缓存键、embedding_funcstring_embedding字符串 embedding、data_managerget_data_manager()默认 MapDataManager、similarity_evaluationExactMatchEvaluation()精确匹配评估、post_process_messages_functemperature_softmax。cache.set_openai_key()读取OPENAI_API_KEY环境变量并注入全局openai客户端详见 gptcache/core.py#L114-L129。之后把from openai import openai替换为from gptcache.adapter import openai即可。适配层gptcache/adapter/openai.py中的ChatCompletion、Completion、Audio、Image、Moderation都是对官方 OpenAI SDK 的包装类命中缓存时由_construct_resp_from_cache等函数按 OpenAI 返回格式重构响应对象保证调用方无需改动解析逻辑。三种实战缓存模式模式一OpenAI 原始调用无缓存基准import os import time import openai def response_text(openai_resp): return openai_resp[choices][0][message][content] question what‘s chatgpt openai.api_key os.getenv(OPENAI_API_KEY) start_time time.time() response openai.ChatCompletion.create( modelgpt-3.5-turbo, messages[ { role: user, content: question } ], ) print(fQuestion: {question}) print(Time consuming: {:.2f}s.format(time.time() - start_time)) print(fAnswer: {response_text(response)}\n)这是后续对比的基线每次提问都会真实请求 ChatGPT延迟与费用完全暴露在 LLM 服务端。模式二精确匹配缓存Exact Matchimport time def response_text(openai_resp): return openai_resp[choices][0][message][content] print(Cache loading.....) # To use GPTCache, thats all you need # ------------------------------------------------- from gptcache import cache from gptcache.adapter import openai cache.init() cache.set_openai_key() # ------------------------------------------------- question whats github for _ in range(2): start_time time.time() response openai.ChatCompletion.create( modelgpt-3.5-turbo, messages[ { role: user, content: question } ], ) print(fQuestion: {question}) print(Time consuming: {:.2f}s.format(time.time() - start_time)) print(fAnswer: {response_text(response)}\n)当两次提问完全一致时第二次将从缓存直接返回不再请求 ChatGPT。默认的ExactMatchEvaluation实现见 gptcache/similarity_evaluation/exact_match.py它要求缓存问题与查询问题逐字一致。模式三相似检索缓存Similar Search精确匹配对措辞敏感GPTCache 的核心价值在于语义相似检索。使用 ONNX embedding 将问题向量化以 SQLite 存标量数据、FAISS 存向量并用SearchDistanceEvaluation评估相似度import time def response_text(openai_resp): return openai_resp[choices][0][message][content] from gptcache import cache from gptcache.adapter import openai from gptcache.embedding import Onnx from gptcache.manager import CacheBase, VectorBase, get_data_manager from gptcache.similarity_evaluation.distance import SearchDistanceEvaluation print(Cache loading.....) onnx Onnx() data_manager get_data_manager(CacheBase(sqlite), VectorBase(faiss, dimensiononnx.dimension)) cache.init( embedding_funconnx.to_embeddings, data_managerdata_manager, similarity_evaluationSearchDistanceEvaluation(), ) cache.set_openai_key() questions [ whats github, can you explain what GitHub is, can you tell me more about GitHub, what is the purpose of GitHub ] for question in questions: start_time time.time() response openai.ChatCompletion.create( modelgpt-3.5-turbo, messages[ { role: user, content: question } ], ) print(fQuestion: {question}) print(Time consuming: {:.2f}s.format(time.time() - start_time)) print(fAnswer: {response_text(response)}\n)在第一批whats github请求得到 ChatGPT 回答后后面几个措辞不同但语义相近的问题如 can you explain what GitHub is会直接命中缓存。从实现角度拆解这一流程gptcache/adapter/adapter.py#L12-L286 的adapt()函数预处理pre_processlast_content取出消息列表最后一条 user 内容作为缓存键候选EmbeddingembeddingOnnx.to_embeddings将文本向量化gptcache/embedding/onnx.py 使用GPTCache/paraphrase-albert-onnx模型tokenizer 为GPTCache/paraphrase-albert-small-v2向量的维度即config.hidden_size向量检索searchFAISS 执行 ANN 近似最近邻搜索gptcache/manager/vector_data/faiss.py 中IDMap,FlatMETRIC_L2索引默认top_k为 5相似度评估evaluationSearchDistanceEvaluation把检索距离映射为相似度得分gptcache/similarity_evaluation/distance.pymax_distance4.0默认positiveFalse得分 max_distance - distance得分越高越相似阈值过滤按Config.similarity_threshold计算rank_threshold得分达到阈值才判定为命中后处理post_process默认temperature_softmax从多个候选答案中挑选temperature 为 0 时取相似度最高者命中回报命中时通过cache_data_convert把缓存答案构造成 OpenAI 格式响应返回。模式四temperature 动态控制缓存行为GPTCache 允许在请求级传递temperature参数来动态控制跳过缓存、直连大模型的概率temperature取值范围为[0, 2]默认值0.0。temperature 越高跳过缓存搜索、直接请求大模型的可能性越大temperature2时必定直连大模型temperature0时必定先查缓存。import time from gptcache import cache, Config from gptcache.manager import manager_factory from gptcache.embedding import Onnx from gptcache.processor.post import temperature_softmax from gptcache.similarity_evaluation.distance import SearchDistanceEvaluation from gptcache.adapter import openai cache.set_openai_key() onnx Onnx() data_manager manager_factory(sqlite,faiss, vector_params{dimension: onnx.dimension}) cache.init( embedding_funconnx.to_embeddings, data_managerdata_manager, similarity_evaluationSearchDistanceEvaluation(), post_process_messages_functemperature_softmax ) # cache.config Config(similarity_threshold0.2) question whats github for _ in range(3): start time.time() response openai.ChatCompletion.create( modelgpt-3.5-turbo, temperature 1.0, # Change temperature here messages[{ role: user, content: question }], ) print(Time elapsed:, round(time.time() - start, 3)) print(Answer:, response[choices][0][message][content])底层实现见 gptcache/processor/post.py#L62-L89 的temperature_softmax当temperature 0时对得分做softmax(x / temperature)概率采样temperature 0时直接取得分最高的答案。而在adapt()中gptcache/adapter/adapter.py#L39-L53temperature同样参与cache_skip的判定0 temperature 2时按概率跳过缓存temperature 2必定跳过temperature 0必定查询缓存。默认post_process_messages_func即为temperature_softmax。更多集成场景除 OpenAI 外GPTCache 已提供 LangChain、llama_index、Replicate、Stability、Diffusers、Dolly、llama.cpp、MiniGPT-4 等生态的适配器对应源码位于 gptcache/adapter 目录实战示例可参考 examples/adapter、examples/integrate 以及 docs/bootcamp 下的 Bootcamp 教程涵盖 QA 生成、SQL Chain、网页问答、图像生成、语音转文字、温度参数实验等。仓库同时提供get/put通用 APIgptcache/adapter/api.py官方建议新 API 接入优先使用它。六大核心模块架构GPTCache 采用模块化设计每个模块都有标准接口与多种实现用户可自由组合甚至自定义实现架构总览见 docs/GPTCacheStructure.png。1. LLM AdapterLLM 适配器统一不同 LLM 的 API 与请求协议通过标准化接口接入模型。当前支持OpenAI ChatGPT API[x]LangChain[x]MiniGPT-4[x]llama.cpp[x]Dolly[x]其他 LLM如 Hugging Face Hub、Bard、Anthropic尚未支持[ ]2. Multimodal Adapter多模态适配器实验性统一图像生成、音频转录等大模型多模态 APIOpenAI Image Create API[x]OpenAI Audio Transcribe API[x]Replicate BLIP API[x]Stability Inference API[x]Hugging Face Stable Diffusion Pipeline 本地推理[x]对应实现可见 gptcache/adapter/diffusers.py、gptcache/adapter/replicate.py、gptcache/adapter/stability_sdk.py 等。3. Embedding GeneratorEmbedding 生成器从请求中提取向量用于相似检索支持多种方案禁用 embedding将 GPTCache 退化为关键词匹配缓存[x]OpenAI embedding API[x]ONNXGPTCache/paraphrase-albert-onnx模型[x]Hugging Face embeddingtransformers、ViTModel、Data2VecAudio[x]Cohere embedding API[x]fastText embedding[x]SentenceTransformers embedding[x]Timm 图像 embedding[x]全部实现位于 gptcache/embedding 目录统一继承BaseEmbedding并提供to_embeddings与dimension属性。4. Cache Storage缓存存储存储 LLM 响应命中时取出用于相似度评估并返回给请求方。当前支持SQLite[x]、DuckDB[x]、PostgreSQL[x]、MySQL[x]、MariaDB[x]、SQL Server[x]、Oracle[x]MongoDB、Redis、Minio、HBase、ElasticSearch 尚在规划中[ ]SQL 系存储统一由 gptcache/manager/scalar_data/sql_storage.py 基于 SQLAlchemy 实现核心表包括_question问题、embedding、时间戳、_answer答案与类型、_session等。此外仓库还包含 gptcache/manager/scalar_data/redis_storage.py 与 gptcache/manager/scalar_data/mongo.py。5. Vector Store向量存储从输入 embedding 中找出 K 个最相似请求为相似度评估提供候选。支持Milvus生产级开源向量数据库[x]Zilliz Cloud基于 Milvus 的全托管云向量数据库[x]Milvus Lite可内嵌 Python 应用的轻量版[x]FAISS高效稠密向量相似检索库[x]Hnswlib近似最近邻 C/Python 库[x]PGVectorPostgres 向量相似检索[x]ChromaAI 原生开源 embedding 数据库[x]DocArray多模态数据表示库[x]Qdrant、Weaviate 也已在仓库中出现对应实现gptcache/manager/vector_data/qdrant.py、gptcache/manager/vector_data/weaviate.py6. Cache Manager 与 Similarity EvaluatorCache Manager负责协调 Cache Storage 与 Vector Store 的读写并通过 gptcache/manager/factory.py 提供工厂方法manager_factory与get_data_manager统一装配。逐出策略Eviction Policy方面内存缓存支持 LRU、FIFO、LFU、RR 策略基于cachetools默认 LRUmax_size默认 1000分布式缓存支持 Redis 与 memcached保证多副本间缓存一致对应 gptcache/manager/eviction/redis_eviction.py 与 gptcache/manager/eviction/distributed_cache.py。Similarity Evaluator汇集 Cache Storage 与 Vector Store 数据判定请求是否命中缓存支持Vector Store 检索距离[x]ONNXGPTCache/albert-duplicate-onnx模型的语义相似度[x]输入与缓存请求的精确匹配[x]对 embedding 应用 numpylinalg.norm的距离[x]BM25 等其余度量[ ]注意并非所有模块组合都互相兼容例如禁用了 Embedding 后 Vector Store 可能无法正常工作。组合前的合理性检查目前仍在开发中。配置详解与工厂装配Config 核心参数Configgptcache/config.py是 GPTCache 的全局配置对象关键参数如下参数默认值说明similarity_threshold0.8相似度阈值范围 [0, 1]为 0 时无命中为 1 时全部返回为命中。越界会抛出CacheErrorpromptsNone请求内容包含列表中的 prompt 字符串时将其移除后再做缓存键templateNone请求包含模板时只保留模板中的参数值作为缓存键auto_flush20每新增 20 条数据自动 flush 一次enable_token_counterTrue是否统计 token 节省量input_summary_lenNone将输入摘要为指定长度skip_list[system, assistant]序列预处理时跳过的角色context_lenNone上下文长度多轮对话data_checkFalse缓存一致性健康检查校验向量库与标量库是否同步disable_reportFalse是否禁用命中报告落库两种 DataManager 装配方式方式一get_data_manager(CacheBase(...), VectorBase(...))显式构造存储对象from gptcache.manager import get_data_manager, CacheBase, VectorBase from gptcache.embedding import Onnx onnx Onnx() data_manager get_data_manager(CacheBase(sqlite), VectorBase(faiss, dimensiononnx.dimension))方式二manager_factory(sqlite,faiss, ...)以字符串一键装配并自动管理本地数据文件gptcache/manager/factory.pyfrom gptcache.manager import manager_factory # sqlite 标量 faiss 向量自动在 data_dir 下创建 sqlite.db 与 faiss.index data_manager manager_factory(sqlite,faiss, data_dir./workspace, vector_params{dimension: 128})manager参数支持map纯内存 MapDataManager或{scalar},{vector}/{scalar},{vector},{object}组合本地向量类型faiss/hnswlib/docarray会自动设置index_path对象存储local会自动设置path。工厂同样支持 Redis 逐出manager_factory(redis,faiss, eviction_managerredis, ...)当标量存储与逐出管理器同为 Redis 时框架会自动切换为no_op_eviction以避免冗余操作。YAML 配置驱动初始化仓库根目录提供 cache_config_template.yml 模板配合init_similar_cache_from_configgptcache/adapter/api.py#L194-L257可实现配置化初始化embedding: onnx embedding_config: # Set model kws here including model, api_key if needed storage_config: data_dir: gptcache_data manager: sqlite,faiss vector_params: # Set vector storage related params here evaluation: distance evaluation_config: # Set evaluation metric kws here pre_function: get_prompt post_function: first config: similarity_threshold: 0.8 # Set other config here对应的快速初始化函数init_similar_cache默认使用Onnxembedding manager_factory(sqlite,faiss, data_dirapi_cache)SearchDistanceEvaluation可在服务化场景中一键就绪。性能评估三大指标与基准脚本语义缓存不可避免地存在命中时的假阳性false positives与未命中时的假阴性false negatives。GPTCache 提供三个指标帮助开发者量化与优化缓存系统Hit Ratio命中率缓存成功满足请求数占总请求数的比例越高说明缓存越有效Latency延迟查询处理与数据取回耗时越低说明系统响应越快Recall召回率应由缓存服务的请求中被缓存实际服务的比例越高说明缓存正确服务了恰当内容。仓库提供了可直接运行的基准脚本 examples/benchmark/benchmark_sqlite_faiss_onnx.py流程为从mock_data.json读取问题-答案对 → 通过cache.import_data批量灌入缓存SQLite FAISS Onnx embeddingsimilarity_threshold0.95→ 逐条用相似问题请求统计正/负命中数、平均耗时并输出cache.report.average_embedding_time()、cache.report.average_search_time()等分阶段耗时。该脚本还演示了如何包装SearchDistanceEvaluation叠加 ONNX 模型评估gptcache/similarity_evaluation/onnx.py以提升准确率代价是命中率下降。分阶段计时能力来自 gptcache/report.py 的Report它统计 pre/embedding/search/data/evaluation/post/llm/save 各阶段的次数与平均耗时并累计缓存命中次数hint_cache_count单元测试见 tests/unit_tests/test_core.py。典型收益与应用场景GPTCache 面向 LLM 应用开发与运维场景提供四项核心收益降低费用LLM 服务大多按请求数与 token 数计费缓存查询结果后发送给 LLM 服务的请求与 token 大幅减少实现更经济的 API 使用提升性能命中缓存时响应直接从缓存取出省去与大模型服务的实时交互多数场景下吞吐优于标准 LLM 服务灵活的研发与测试环境GPTCache 提供与 LLM API 同构的接口可存储真实生成数据与 mock 数据使应用在不连接 LLM 服务的情况下即可开发与测试提升可扩展性与可用性LLM 服务常设速率限制rate limits命中上限会导致请求被阻塞、服务中断GPTCache 可随用户规模平滑扩展规避限流导致的停机。延伸阅读Usage 使用指南更全面地使用 GPTCacheFeature 功能清单当前缓存支持的全部特性Examples 示例集学习更贴合业务的自定义缓存横向扩展与分布式部署Redis/memcached 分布式缓存与水平扩展Bootcamp 教程docs/bootcamp 下覆盖 LangChain、llama_index、OpenAI、Replicate、Temperature 等主题的 Notebook通用 API 示例examples/adapter/api.py需要注意的是项目仍处于快速迭代期API 可能随时调整请以最新文档与 发布记录 为准官方建议新模型接入优先使用get/put通用 API以规避 LLM API 形态快速演化带来的适配成本。赞分享AI 应用大模型【免费下载链接】GPTCacheSemantic cache for LLMs. Fully integrated with LangChain and llama_index.项目地址https://gitcode.com/gh_mirrors/gp/GPTCache点击查看免费下载相关推荐GPTCache 语义缓存库完全指南为 LLM 查询构建高性能缓存显著降低 API 成本与响应延迟GPTCache 语义缓存库完全指南为 LLM 查询构建高性能缓存显著降低 API 成本与响应延迟 GPTCache 是一个专为 LLM大语言模型查询构AI 应用大模型PrivateGPT语义缓存提升相似查询响应速度PrivateGPT语义缓存提升相似查询响应速度 你是否经常在使用PrivateGPT时遇到重复查询响应缓慢的问题是否希望在不牺牲准确性的前提下大幅提升对话人工智能大模型RAG本地部署LLM 网关后端Bend 安装后遇到 Command bend not found 怎么排查Bend 安装后遇到 Command bend not found 怎么排查 按照 README.md https://link.gitcode.com/i/AI 应用大模型上一篇华硕笔记本终极性能调校指南G-Helper完整使用手册下一篇Ryujinx图形渲染架构深度实战从Shader编译到GPU模拟的完整解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考