CAG

扔掉检索器，用缓存让大模型回答更快更简单

CAG（Cache-Augmented Generation）是一个旨在替代RAG（检索增强生成）的轻量级开源项目。它通过预先缓存知识库内容，在推理时直接利用缓存而非实时检索，从而简化了生成流程。该项目解决了RAG中检索延迟高、系统复杂度大、依赖外部向量数据库等问题。核心能力包括：将文档预加载到上下文缓存中、支持多种大语言模型后端、提供简单的API接口。其设计哲学是“少即是多”，在知识库规模适中、更新不频繁的场景下，能显著提升响应速度并降低运维成本。项目当前处于成长阶段，代码结构清晰，适合希望摆脱检索基础设施的开发者快速集成。

开源 free 搜索知识

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 1601

维护状态低维护

是否开源是

定价模式 free

项目数据

分类搜索知识

开发团队hhhuang

所属国家

官网地址

GitHubhttps://github.com/hhhuang/CAG

定价模式free

价格说明开源项目，MIT许可证，完全免费，可自行部署使用。

访问状态

是否开源是

开源协议MIT

主要语言Python

技术栈/模型cag,llm,rag

GitHub 星标★ 1601

30天Star增速

HF 下载量

上线时间2024-12-11 00:00:00

最近更新2026-09-22 00:00:00

维护状态低维护

中文支持

访问方式

移动端支持

综合评分

收录时间2026-08-09

浏览次数1

使用教程

难度：进阶约 15 分钟部署方式：命令行工具 8 步

环境要求

Python 环境（README 未指定具体版本，需能运行 pip）
已安装 requirements.txt 中的依赖
Hugging Face 访问令牌 HF_TOKEN（写入 .env 文件）
可选：Docker；GPU 用户需支持 --gpus all 的运行时

安装与启动步骤

1获取项目代码

从 GitHub 克隆仓库并进入项目目录，后续所有命令都在该目录下执行。
```
git clone https://github.com/hhhuang/CAG.git
cd CAG
```
2安装依赖

按 README 的 Installation 一节安装 requirements.txt 中列出的全部依赖。
```
pip install -r ./requirements.txt
```
3配置 .env

在项目根目录创建 .env，至少写入 HF_TOKEN，否则运行脚本时会抛出 Missing required environment variable 错误。
```
echo "HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxx" > .env
```

4运行 CAG 实验

kvcache.py 用于 CAG 实验；参数取自 README，--usePrompt 仅在不用缓存加速时添加。

python ./kvcache.py --kvcache "file" --dataset "hotpotqa-train" --similarity "bertscore" --modelname "meta-llama/Llama-3.1-8B-Instruct" --maxKnowledge 80 --maxParagraph 100 --maxQuestion 80 --randomSeed 0 --output "./kvcache_results.txt"

5运行 RAG 对比

rag.py 用于 RAG 实验，命令为 README 给出的完整示例，可换 --index 为 openai。

python ./rag.py --index "bm25" --dataset "hotpotqa-train" --similarity bertscore --maxKnowledge 80 --maxParagraph 100 --maxQuestion 80 --topk 3 --modelname "meta-llama/Llama-3.1-8B-Instruct" --randomSeed 0 --output "./rag_results.txt"

6构建 Docker 镜像

可选方式。构建前务必先填好 .env，否则容器启动时会因缺少 HF_TOKEN 报错。
```
docker build -t my-cag-app .
```
7运行容器

GPU 用户加 --gpus all，CPU 用户直接运行；镜像默认执行 kvcache.py。
```
docker run --gpus all -it --rm my-cag-app
```

8容器内跑 rag.py

覆盖 Dockerfile 默认 CMD，在容器里执行 RAG 实验脚本。

docker run --gpus all -it --rm my-cag-app python ./rag.py --index "bm25" --dataset "hotpotqa-train" --similarity bertscore --maxKnowledge 80 --maxParagraph 100 --maxQuestion 80 --topk 3 --modelname "meta-llama/Llama-3.1-8B-Instruct" --randomSeed 0 --output "./rag_results.txt"

关键配置

配置项	必填	说明	示例
`HF_TOKEN`	是	Hugging Face 访问令牌，脚本启动时会校验，缺失即报错退出	`hf_xxxxxxxxxxxxxxxxxxxx`

如何确认成功

脚本运行结束无异常，并在 --output 指定的路径生成结果文件；Docker 方式下容器能正常启动并进入。

常见问题

Q：运行时报 ValueError: Missing required environment variable: HF_T

A：说明 .env 中 HF_TOKEN 为空。请在构建镜像或运行脚本前先填好 .env 中的 HF_TOKEN，再重新执行。

Q：没有 GPU 能跑吗？

A：可以。README 给出了 CPU 用法：docker run -it --rm my-cag-app，即去掉 --gpus all 参数。

Q：怎么改跑 rag.py 而不是默认的 kvcache.py？

A：在 docker run 命令末尾追加 python ./rag.py 及参数，覆盖 Dockerfile 里的 CMD 指令即可，README 给出了完整示例。

Q：数据集可选哪些？

A：--dataset 支持 "hotpotqa-train" 或 "squad-train"；--similarity 给出的是 "bertscore"。

注意事项

CAG 需要把全部知识放进模型的上下文窗口，知识规模过大时不适合使用。
--maxKnowledge、--maxParagraph、--maxQuestion 的取值说明 README 指向 Note 部分，请结合该说明调整。
构建 Docker 镜像前必须先填好 .env，否则运行时会报缺少 HF_TOKEN。
Dockerfile 的 CMD 默认执行 kvcache.py，可用 docker run 命令覆盖。

核心亮点

省去向量数据库和检索管道，部署和维护成本大幅降低
推理延迟比RAG更低，因为省去了检索步骤
代码简洁，易于集成到现有LLM应用中

不足之处

知识库更新需重新构建缓存，不适合动态数据场景
缓存大小受限于模型上下文窗口，超大知识库不适用
文档/社区待观察

适用场景

固定知识库的问答机器人
低延迟要求的内部文档助手
离线或边缘环境下的轻量级生成任务

替代项目

RAGFlow、LlamaIndex、Haystack

项目介绍

CAG 是搜索知识领域的开源项目，由 hhhuang 开发，2024 年首次发布。

在全站 13,014 个收录项目中，它的 GitHub 星标数（1,601）位列前 30%，在搜索知识分类中处于中上游。

近 42 天，它的 GitHub 星标从 1,533 增加到 1,601，净增 68。

项目已超过三个月没有代码更新，维护节奏明显放缓，最近一次代码更新于 2026-09-22。MIT许可证，完全免费，可自行部署使用。

它主要面向的使用场景是：固定知识库的问答机器人。同类可对比的替代方案包括 RAGFlow、LlamaIndex、Haystack。

上一篇：rag-from-scratch

下一篇：korvus

CAG