GPTCache 语义缓存库完全指南：为 LLM 查询构建高性能缓存，显著降低 API 成本与响应延迟

AI 应用大模型【免费下载链接】GPTCacheSemantic cache for LLMs. Fully integrated with LangChain and llama_index.项目地址https://gitcode.com/gh_mirrors/gp/GPTCache点击查看免费下载GPTCache 是一个专为 LLM大语言模型查询构建语义缓存Semantic Cache的开源 Python 库它通过 embedding 向量化 向量相似度检索让语义相近的重复问题直接命中缓存而无需再次调用大模型服务。本文以仓库根目录 README.md 为主线结合 gptcache 源码实现完整讲解 GPTCache 的安装、三种典型用法精确匹配、相似搜索、temperature 控制、核心模块架构、cache.init()/Config/manager_factory等关键 API 参数以及横向扩展与性能评估指标帮助你快速把它落地到生产环境。为什么需要 GPTCacheChatGPT 等大语言模型功能强大能支撑各类应用开发但随着应用用户量增长与流量上升两类问题会越来越突出API 调用费用急剧增长多数 LLM 服务按请求次数与 Token 数计费高频重复查询意味着高昂成本响应缓慢LLM 实时生成内容本身耗时高并发下排队更明显且服务端普遍存在rate limit速率限制一旦触发额外请求会被阻塞造成服务中断。传统缓存系统通常依赖新旧查询完全相等的精确匹配来判定是否命中但 LLM 查询复杂多变、表述方式千差万别精确匹配的命中率极低。GPTCache 的解法是采用语义缓存先通过 embedding 算法把查询转成向量再用向量数据库做相似度检索找出语义相近的历史查询并直接复用其回答从而显著提升命中率与整体缓存效率。仓库将这种价值概括为四类核心收益见 README.md 的 What can this help with? 一节降低费用缓存查询结果减少发往 LLM 服务的请求与 Token 数量提升性能相似查询命中时直接从缓存取结果响应时间显著缩短多数场景下吞吐也优于直接调用 LLM便于开发与测试GPTCache 提供与 LLM API 形态一致的接口既能缓存 LLM 真实返回也能存储 mock 数据开发测试无需真实连接 LLM 服务改善扩展性与可用性缓存降低了对服务端 rate limit 的依赖可从容应对查询量增长。快速安装与环境准备安装只需一行命令pip install gptcache仓库还提醒了以下前提README Quick Start 的 NotePython 版本需3.8.1 及以上可用python --version检查默认仅安装支撑基础缓存功能的少量依赖用到额外功能时相关库会自动安装若因 pip 版本过低导致装库失败先执行python -m pip install --upgrade pip项目处于快速迭代期API 可能随时变化最新信息以 docs/release_note.md 等文档为准。开发者模式安装dev install想从源码安装当前仓库可执行# 克隆仓库dev 分支 git clone -b dev https://github.com/zilliztech/GPTCache.git cd GPTCache # 安装依赖与项目本身 pip install -r requirements.txt python setup.py install准备 OpenAI API Key运行示例前务必先确认环境变量已设置echo $OPENAI_API_KEY若未设置Unix/Linux/MacOS 使用export OPENAI_API_KEYYOUR_API_KEYWindows 使用set OPENAI_API_KEYYOUR_API_KEY。注意该方法仅临时生效如需永久生效需修改环境变量配置文件如 Mac 上的/etc/profile。三分钟上手核心初始化代码使用 GPTCache 的全部代码只有四行无需改动既有业务代码from gptcache import cache from gptcache.adapter import openai cache.init() cache.set_openai_key()其中cache是模块级单例对象定义于 gptcache/core.py 末行cache Cache()。cache.init()的所有参数都有默认值cache.set_openai_key()则把OPENAI_API_KEY环境变量写入 openai 库配置。从源码看Cache.init()gptcache/core.py暴露了完整的可定制钩子默认值与含义如下参数默认值作用cache_enable_funccache_all控制是否启用缓存如可按请求内容做条件判断pre_embedding_funclast_content请求预处理从 messages 中提取用于向量化的文本embedding_funcstring_embedding把文本转成 embedding 向量的函数data_managerget_data_manager()缓存数据管理模块存储 向量检索similarity_evaluationExactMatchEvaluation()相似度评估策略post_process_messages_functemperature_softmax命中后对候选结果做后处理configConfig()全局配置核心是similarity_threshold如果只做精确匹配缓存用默认配置即可需要语义匹配时则要显式配置 embedding、向量库与相似度评估详见下文示例。示例一OpenAI API 原始调用对照组先用最原始的 openai 调用建立基线感受直接调用 ChatGPT 的耗时import os import time import openai def response_text(openai_resp): return openai_resp[choices][0][message][content] question what‘s chatgpt # OpenAI API original usage 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)示例二OpenAI API GPTCache 精确匹配缓存只加三行引入与初始化代码第二次问完全相同的问题时答案直接取自缓存不再请求 ChatGPTimport 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)关键点在于from gptcache.adapter import openai——它提供了与 openai SDK 同名的适配器实现见 gptcache/adapter/openai.pyChatCompletion.create的调用方式与原生 API 完全一致因此可以无侵入地替换导入路径。示例三OpenAI API GPTCache 相似搜索缓存这是语义缓存的核心场景缓存了若干相似问题的答案后后续表述不同但语义相近的问题也能直接命中缓存。示例配置了 ONNX embedding、SQLite 标量存储 FAISS 向量库、以及基于检索距离的相似度评估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)这里的核心组件逐一拆解Onnx()默认使用GPTCache/paraphrase-albert-onnx模型生成句子向量见 gptcache/embedding/onnx.py其dimension属性来自 ALBERT 的 hidden_size用于确定向量库维度输入文本经 tokenizer 编码后送入 onnxruntime 推理再对 token embedding 做带 attention mask 的均值池化得到句向量get_data_manager(CacheBase(sqlite), VectorBase(faiss, dimension...))get_data_manager生成SSDataManager见 gptcache/manager/factory.pyCacheBase(sqlite)创建 SQLite 标量存储VectorBase(faiss, ...)创建 FAISS 向量索引SearchDistanceEvaluation()基于向量检索阶段得到的距离打分把距离裁剪到[0, max_distance]默认 4.0并取反得到相似度分数见 gptcache/similarity_evaluation/distance.pycache.set_openai_key()把环境变量写入 openai 库。示例四使用 temperature 控制是否走缓存语义缓存存在误命中风险temperature参数被设计为控制缓存跳过的概率见 gptcache/adapter/adapter.py 的实现逻辑取值范围为[0, 2]默认 0.0temperature 越高跳过缓存、直接请求大模型的概率越大temperature 2必定跳过缓存直接请求大模型temperature 0必定先查缓存再请求大模型处于0 temperature 2时通过temperature_softmax以概率决定本次是否跳过缓存。默认的post_process_messages_func即temperature_softmax它同时决定命中后如何在多个候选答案中做选择。示例代码如下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])本例改用manager_factory(sqlite,faiss, ...)见 gptcache/manager/factory.py一键组装数据管理它接受{标量存储},{向量存储}可追加,{对象存储}的字符串并自动把数据落在data_dir目录下sqlite.db、faiss.index 等比手动传CacheBase/VectorBase更省事。注释掉的Config(similarity_threshold0.2)提示我们可通过阈值调节命中严苛程度。核心配置 Config 详解Config见 gptcache/config.py承载缓存的全局配置项常用参数如下参数默认值说明log_time_funcNone自定义耗时日志函数similarity_threshold0.8相似度阈值范围[0, 1]。为 0 时没有任何命中为 1 时全部检索结果都算命中越界会抛CacheErrorpromptsNone请求中包含该列表中的提示词前缀时预处理阶段会将其去除templateNone请求中包含该模板时只保留模板中的参数值部分auto_flush20每新增多少条数据自动 flush 一次内存数据落盘enable_token_counterTrue是否启用 token 计数input_summary_lenNone对超长输入做摘要截断到指定长度context_lenNone上下文长度skip_list[system, assistant]序列预处理时跳过这些角色的消息data_checkFalse命中时校验 Cache Store 与 Vector Store 是否一致见 gptcache/adapter/adapter.py 的cache_health_checkdisable_reportFalse关闭命中报表记录用法示例from gptcache import Config configs Config(similarity_threshold0.6)从adapt的实现可以看出实际判定阈值由相似度评估器的分数区间换算而来gptcache/adapter/adapter.pysimilarity_threshold chat_cache.config.similarity_threshold min_rank, max_rank chat_cache.similarity_evaluation.range() rank_threshold (max_rank - min_rank) * similarity_threshold * cache_factor即rank_threshold (max_rank - min_rank) × similarity_threshold × cache_factor相似度分数不低于该阈值的候选才会被采纳且命中后会按分数降序排列再交给post_process_messages_func选择最终答案。GPTCache 工作原理从精确匹配到语义匹配在线服务普遍存在数据局部性用户高频访问热门内容缓存系统正是利用这一点降低后端压力。但传统缓存对 LLM 场景效果差因为 LLM 查询的表述千差万别精确匹配命中率极低。GPTCache 的方案是用embedding 算法把查询转换为向量用向量存储对查询向量做相似度检索找出语义相近的历史查询对检索结果做相似度评估决定是否命中缓存并返回缓存答案。整套流程在 gptcache/adapter/adapter.py 的adapt中实现调用链为pre_embedding_func预处理→embedding_func向量化→data_manager.search向量检索 top_k→similarity_evaluation.evaluation逐条打分→ 阈值过滤排序 →post_process_messages_func选答案→ 未命中时调用llm_handler并写回缓存。此外adapt还支持search_only只查不请求、cache_factor阈值缩放系数、next_cache多级缓存串联、session会话隔离等扩展参数。GPTCache 采用模块化设计每个模块都提供多种实现用户可自由组合也可自行实现接口定制。由于语义缓存存在误命中与漏命中仓库给出三个评估指标供开发者优化Hit Ratio命中率缓存成功满足请求的比例越高说明缓存越有效Latency延迟查询处理与取数耗时越低说明系统越高效Recall召回率应命中而实际命中的查询占比越高说明缓存服务得越到位。仓库附带了一个基准测试脚本 examples/benchmark/benchmark_sqlite_faiss_onnx.py 供你评估自己语义缓存的性能。模块架构总览GPTCache 六大模块LLM Adapter、Embedding Generator、Cache Storage、Vector Store、Cache Manager、Similarity Evaluator各模块均支持多种后端实现。LLM AdapterLLM 适配器统一不同 LLM 的 API 与请求协议提供标准化接入接口。当前已完成OpenAI ChatGPT API、LangChain、MiniGPT-4、Llamacpp、DollyHugging Face Hub、Bard、Anthropic 等仍在规划中。对应的适配实现分别位于 gptcache/adapter/ 目录如openai.py、langchain_models.py、dolly.py、llama_cpp.py、minigpt4.py。Multimodal Adapter多模态适配器实验性统一图像生成、音频转录等大模态模型接口已支持 OpenAI Image Create、OpenAI Audio Transcribe、Replicate BLIP、Stability Inference、Hugging Face Stable Diffusion Pipeline本地推理。Embedding GeneratorEmbedding 生成器从请求中提取向量用于相似度检索支持多种方案禁用 embeddingGPTCache 退化为关键词匹配缓存OpenAI embedding APIONNX默认GPTCache/paraphrase-albert-onnx模型Hugging Facetransformers、ViTModel、Data2VecAudioCohere embedding API、fastText、SentenceTransformers、Timm图像 embedding。对应实现见 gptcache/embedding/ 目录onnx.py、openai.py、huggingface.py、cohere.py、fasttext.py、sbert.py、timm.py、vit.py、data2vec.py、rwkv.py、paddlenlp.py、uform.py等。Cache Storage缓存存储存储 ChatGPT 等 LLM 的响应。当前已支持 SQLite、DuckDB、PostgreSQL、MySQL、MariaDB、SQL Server、Oracle、DynamoDBMongoDB、Redis、Minio、HBase、ElasticSearch 等仍在推进。实现见 gptcache/manager/scalar_data/。Vector Store向量存储从输入查询的 embedding 中找出 K 个最相似请求。已支持 Milvus、Zilliz Cloud、Milvus Lite、FAISS、Hnswlib、PGVector、Chroma、DocArray、Qdrant、Weaviate。实现见 gptcache/manager/vector_data/。Cache Manager缓存管理器控制 Cache Storage 与 Vector Store 的协作重点包含驱逐策略Eviction Policy内存缓存In-Memory基于 pythoncachetools目前按数据条数决定驱逐支持 LRU、FIFO、LFU、RR 策略见 gptcache/manager/eviction/memory_cache.py分布式缓存Distributed内存缓存无法水平扩展缓存信息局限于单个 pod分布式模式下借助 Redis、Memcached 等 key-value 存储使缓存信息在所有副本间一致见 gptcache/manager/eviction/redis_eviction.py 与 gptcache/manager/eviction/distributed_cache.py。从manager_factory的实现gptcache/manager/factory.py可以看到当标量存储与驱逐管理器同为 Redis 时会自动切换为no_op_eviction以避免重复操作内存驱逐则支持eviction_params中的max_size、clean_size、eviction如LRU等参数。Similarity Evaluator相似度评估器从 Cache Storage 与 Vector Store 收集数据用多种策略判定输入请求与历史请求的相似度决定是否命中。当前支持的相似度定义向量存储返回的检索距离SearchDistanceEvaluationgptcache/similarity_evaluation/distance.py基于 ONNXGPTCache/albert-duplicate-onnx模型的模型相似度输入与检索结果的精确匹配ExactMatchEvaluation对 embedding 应用 numpylinalg.norm得到的距离NumpyNormEvaluation。其余评估器如KReciprocalEvaluation、CohereRerankEvaluation、SequenceMatchEvaluation、TimeEvaluation、SbertCrossencoderEvaluation均位于 gptcache/similarity_evaluation/ 目录。注意并非所有模块组合都互相兼容例如禁用 Embedding 后 Vector Store 可能无法正常工作仓库正在实现组合健全性检查。面向 API 服务的轻量级 put / get 接口由于大模型 API 形态持续演进仓库建议优先使用通用、与模型无关的get/setAPIREADME 顶部 NOTE 明确说明不再为新型 API 增加支持示例见 examples/adapter/api.py。该接口定义在 gptcache/adapter/api.pyput(prompt, data)把(问题, 答案)写入缓存初始化时需将pre_embedding_func设为get_promptget(prompt)按问题取缓存答案同样要求pre_embedding_funcget_promptinit_similar_cache(...)快速初始化一套开箱即用的相似缓存默认组合为Onnxembedding sqlite,faiss数据管理 SearchDistanceEvaluation。基础用法from gptcache import cache, Config, Cache from gptcache.adapter.api import put, get, init_similar_cache from gptcache.processor.post import nop from gptcache.processor.pre import get_prompt def run_basic(): cache.init(pre_embedding_funcget_prompt) put(hello, foo) print(get(hello)) # output: foo def run_similar_match(): inner_cache Cache() init_similar_cache( cache_objinner_cache, post_funcnop, configConfig(similarity_threshold0) ) put(hello1, foo1, cache_objinner_cache) put(hello2, foo2, cache_objinner_cache) put(hello3, foo3, cache_objinner_cache) messages get(hello, cache_objinner_cache, top_k3) print(messages) # output: [foo1, foo2, foo3] if __name__ __main__: run_basic() run_similar_match()除put/get外adapt还支持通过cache_obj参数指定使用哪个 Cache 实例便于多实例隔离top_k控制检索候选数session支持会话级缓存search_onlyTrue可实现只检索不请求 LLM。基于 YAML 配置初始化缓存仓库还提供从 YAML 文件初始化相似缓存的入口init_similar_cache_from_config(config_dir)见 gptcache/adapter/api.py仓库根目录的 cache_config_template.yml 是官方模板# For model_src, evaluation, post_function, pre_function, # storage_config options, Check README for more. 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模板各字段与源码解析逻辑一一对应embedding或兼容旧名的model_source决定 embedding 模型embedding_config兼容旧名model_config传入模型参数storage_config交给manager_factory其中manager默认sqlite,faiss、data_dir默认gptcache_data且会自动把vector_params[dimension]设为 embedding 模型维度evaluation指定评估策略distance/np/exact/onnx等pre_function/post_function从gptcache.processor.pre/post中按名取函数config直接构造Config对象。深入阅读docs/usage.md如何更好地使用 GPTCachedocs/feature.md当前缓存支持的全部特性examples/README.md学习更高级的自定义缓存示例docs/horizontal-scaling-usage.md分布式缓存与水平扩展结合 Redis / Memcached 驱逐docs/bootcamp/覆盖 LangChain、Llama_index、OpenAI、Replicate、Temperature 等场景的完整 Notebook 实战教程docs/contributing.md参与项目贡献的指南。需要说明的是README 中Slash Your LLM API Costs by 10x , Boost Speed by 100x ⚡属于项目宣传标语实际收益取决于你的查询重复/相似分布与 embedding 模型质量建议用 examples/benchmark/benchmark_sqlite_faiss_onnx.py 在自有数据上测量 Hit Ratio、Latency 与 Recall 后再做预期判断。项目仍处于快速开发期当前仓库版本为0.1.44见 gptcache/init.py接入生产环境前请关注 docs/release_note.md 的 API 变更说明。赞分享AI 应用大模型【免费下载链接】GPTCacheSemantic cache for LLMs. Fully integrated with LangChain and llama_index.项目地址https://gitcode.com/gh_mirrors/gp/GPTCache点击查看免费下载相关推荐Bluetuith进阶使用如何通过命令行实现蓝牙设备自动化管理Bluetuith进阶使用如何通过命令行实现蓝牙设备自动化管理 Bluetuith是一款专为Linux系统设计的终端蓝牙管理器它提供了强大的命令行功能让用自定义查询从未如此简单jpa-spec的Predicate接口使用教程自定义查询从未如此简单jpa spec的Predicate接口使用教程 jpa spec是一个强大的JPA查询框架它通过Specification接口简化了语义缓存与传统缓存对比GPTCache解决LLM查询长尾问题的实践语义缓存与传统缓存对比GPTCache解决LLM查询长尾问题的实践 引言LLM时代的缓存困境 你是否曾遇到这样的情况用户反复询问相似的问题却每次都要耗费AI 应用大模型上一篇小米表盘可视化设计工具 Mi-Create 指南下一篇Robo 3T免费跨平台的 MongoDB 可视化管理工具给既要 Shell 又要图形界面的人创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考