30 分钟跑通第一个 RAG 示例:从这份合集里挑最短的一条路
30 分钟跑通第一个 RAG 示例:从这份合集里挑最短的一条路
ai-engineering-hub 是一个收录了 93+ 个生产级 AI 项目的教程合集,覆盖 LLM、RAG、Agent 等方向,并按难度分为 Beginner(22 个)、Intermediate(48 个)、Advanced(23 个)三档。仓库 README 给出的官方上手建议是:先读 ai-engineering-roadmap 这张学习路线图,再从 Beginner Projects 里的 OCR 应用和 Simple RAG 开始动手。
对于只想"尽快把 RAG 跑通"的读者,这份合集的价值恰恰在于它把"同一个 RAG 最小闭环"用不同依赖组合写了好几遍——有的只要 Ollama,有的要起 Docker 容器,有的要申请云端 API key。选错路,光配环境就能耗掉你一下午。这篇文章做两件事:先按依赖轻重给 Basic RAG 章节的项目排个序,告诉你最短的那条路怎么走;然后逐行拆 simple-rag-workflow 的源码,把切分、向量化、检索、拼提示词四个环节讲透;最后给一套"怎么判断自己跑的是示例还是玩具"的自查方法,依据是仓库里自带的评估 notebook 和测试集。
先选哪一章:按依赖轻重排序的上手顺序
仓库 README 的 Beginner Projects 下有一个 "Basic RAG" 小节,共六个项目。它们演示的闭环几乎一样(载入文档 → 建索引 → 检索 → 生成回答),差别全在依赖上。按"从零开始要装/配多少东西"排序,大致是这样:
| 项目 | LLM 来源 | Embedding | 向量库 | 额外依赖 |
|---|---|---|---|---|
| simple-rag-workflow | 本地 Ollama(llama3.2) |
本地 BAAI/bge-small-en-v1.5 |
内存 | 无,Python 3.10+ |
| modernbert-rag | 本地 Ollama | 本地 nomic-ai/modernbert-embed-base |
内存 | 无 |
| github-rag | 云端 API | 云端 API | 内存 | 一个 API key |
| document-chat-rag | 本地 Ollama(llama3.3) |
本地 BAAI/bge-large-en-v1.5 |
Docker 跑 Qdrant | Docker |
| fastest-rag-stack | SambaNova 云推理 | 本地 BAAI/bge-large-en-v1.5 |
Docker 跑 Qdrant | SambaNova API key |
| llama-4-rag | Cerebras 云推理 | LlamaIndex 默认 | 内存 | CEREBRAS_API_KEY |
结论很直接:最短的一条路是 simple-rag-workflow。它的 README 前置条件只有两条——Python 3.10+ 和 Ollama,没有任何 Docker、没有 API key、没有云账号。装完 Ollama(一行 curl -fsSL https://ollama.com/install.sh | sh)、拉一个模型(ollama pull llama3.2)、起一个后台进程(ollama serve),整个环境侧的工作就结束了。
这条路线的"短"还体现在硬件门槛上:LLM 用的是 llama3.2(Llama 3.2 3B 级,本地 8GB 显存可跑),embedding 用的是 BAAI/bge-small-en-v1.5(约 33M 参数,CPU 就能算)。而 document-chat-rag 用的是 llama3.3,README 里写的拉取命令是 ollama pull llama3.3——这已经不是"30 分钟"级别的项目了。
AI Engineering Roadmap 学习路线图,展示从 Python 到生产级 AI 应用的完整路径
如果 30 分钟跑通之后你想继续,仓库里也留好了升级台阶:modernbert-rag 的代码结构和 document-chat-rag 几乎一一对应,唯一实质改动是把 embedding 换成了 nomic-ai/modernbert-embed-base(见 modernbert-rag/rag-modernbert.py 第 90 行),用来对比不同 embedding 模型的检索效果;fastest-rag-milvus-groq 则演示用 Milvus 二进制量化 + Groq 推理把检索压到 15ms 以内。路径是现成的,不需要另找教程。
最小闭环:切分、向量化、检索、拼提示词
下面拆解 simple-rag-workflow 的源码。整个实现就三个文件:simple-rag-workflow/workflow.py 是核心(约 98 行),simple-rag-workflow/workflow.ipynb 是交互式演示,README 里写着"Run the Jupyter notebook workflow.ipynb to see the RAG system in action"。
初始化:把 LLM 和 embedding 挂到全局 Settings
from llama_index.llms.ollama import Ollama
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
from llama_index.core.settings import Settings
llm = Ollama(model="llama3.2")
embed_model = HuggingFaceEmbedding(model_name="BAAI/bge-small-en-v1.5")
Settings.llm = llm
Settings.embed_model = embed_model
这是 LlamaIndex 的惯用模式:Settings 是全局配置对象,后面 VectorStoreIndex 建索引时会自动从这里取 embedding 模型,response synthesizer 生成回答时会自动从这里取 LLM。也就是说,"向量化用谁、生成用谁"这两件事在入口处一次定死,后面所有环节都不用再传参。
用 Workflow 把闭环拆成三个 step
workflow.py 没有写成线性脚本,而是用了 LlamaIndex 的 Workflow 基类,定义了三个 @step:
class RAGWorkflow(Workflow):
def __init__(self, model_name="llama3.2", embedding_model="BAAI/bge-small-en-v1.5"):
super().__init__()
self.llm = Ollama(model=model_name)
self.embed_model = HuggingFaceEmbedding(model_name=embedding_model)
Settings.llm = self.llm
Settings.embed_model = self.embed_model
self.index = None
第一步:ingest(切分 + 向量化)
@step
async def ingest(self, ctx: Context, ev: StartEvent) -> StopEvent | None:
dirname = ev.get("dirname")
if not dirname:
return None
documents = SimpleDirectoryReader(dirname).load_data()
self.index = VectorStoreIndex.from_documents(documents=documents)
return StopEvent(result=self.index)
RAG 闭环里的"切分"和"向量化"这两步,在这里被封装成了两行:SimpleDirectoryReader 负责读取目录里的文档(项目自带的 simple-rag-workflow/data/DeepSeek.pdf 就是演示语料),VectorStoreIndex.from_documents 内部依次完成节点切分(默认按 token 上限切分)和 embedding 计算,把结果放进内存向量索引。对初学者这是最省事的一档——不需要手写 NodeParser,也不需要理解 chunk size 细节;代价是你暂时摸不到"切分策略"这个 RAG 质量的最大变量,后面自查部分会提到这一点。
第二步:retrieve(检索)
@step
async def retrieve(self, ctx: Context, ev: StartEvent) -> RetrieverEvent | None:
query = ev.get("query")
index = ev.get("index") or self.index
...
retriever = index.as_retriever(similarity_top_k=2)
nodes = await retriever.aretrieve(query)
await ctx.set("query", query)
return RetrieverEvent(nodes=nodes)
检索这一步的关键参数就一个:similarity_top_k=2。查询文本被同一个 embedding 模型编码后,与索引里所有节点算相似度,取最相关的 2 个节点(NodeWithScore,即"节点 + 相似度分数")打包成 RetrieverEvent 传给下一步。同时它把 query 存进了 workflow 的上下文(ctx.set("query", query)),供第三步使用。
第三步:synthesize(拼提示词 + 生成)
@step
async def synthesize(self, ctx: Context, ev: RetrieverEvent) -> StopEvent:
summarizer = CompactAndRefine(streaming=True, verbose=True)
query = await ctx.get("query", default=None)
response = await summarizer.asynthesize(query, nodes=ev.nodes)
return StopEvent(result=response)
"拼提示词"这一步由 CompactAndRefine 完成:它把检索到的 2 个节点拼进 LlamaIndex 内置的 text_qa 模板(上下文 + 问题),交给 Settings.llm 生成回答,streaming=True 让回答可以逐块吐出来。
两个入口:ingest 和 query 分离
这个实现里最值得学的设计是入库和查询是两个独立入口,而不是耦合在一条流水线里。notebook 里的用法非常直观:
w = RAGWorkflow()
# 入口一:入库(只跑一次)
index = await w.run(dirname="data")
# 入口二:查询(可以反复跑)
result = await w.run(query="How was DeepSeekR1 trained?", index=index)
async for chunk in result.async_response_gen():
print(chunk, end="", flush=True)
workflow.py 末尾还包了两个 helper,把"入口分离"进一步简化成同步调用的观感:
workflow = RAGWorkflow()
await workflow.ingest_documents("data") # 入库
result = await workflow.query("How was DeepSeekR1 trained?") # 查询
注意 query 方法里有一句防御性检查:if self.index is None: raise ValueError("No documents have been ingested. Call ingest_documents first.")。这提醒了一个新手最容易踩的坑——先查询后入库会直接拿到空索引,retrieve step 里同样有对应的兜底逻辑("Index is empty, load some documents before querying!")。
闭环对照表
把四个环节和源码位置对应起来,最小 RAG 的完整映射如下:
| 环节 | 负责它的代码 | 文件位置 |
|---|---|---|
| 切分 | VectorStoreIndex.from_documents 内部默认的 node parser |
simple-rag-workflow/workflow.py ingest step |
| 向量化 | HuggingFaceEmbedding 经 Settings.embed_model 注入 |
同上,__init__ |
| 检索 | index.as_retriever(similarity_top_k=2) |
同上,retrieve step |
| 拼提示词 | CompactAndRefine + 内置 text_qa 模板 |
同上,synthesize step |
| 生成 | Ollama(model="llama3.2") 经 Settings.llm 注入 |
同上 |
如果你看过的 RAG 教程里出现过 reranker、Qdrant、自定义 PromptTemplate,可以先都忽略——它们在这个最小闭环里一个都不需要。想加自定义提示词模板,可以看仓库里另一个项目 document-chat-rag/app.py 的写法:
qa_prompt_tmpl_str = (
"Context information is below.\n"
"---------------------\n"
"{context_str}\n"
"---------------------\n"
"Given the context information above I want you to think step by step to answer the query in a crisp manner, incase case you don't know the answer say 'I don't know!'.\n"
"Query: {query_str}\n"
"Answer: "
)
qa_prompt_tmpl = PromptTemplate(qa_prompt_tmpl_str)
query_engine.update_prompts({"response_synthesizer:text_qa_template": qa_prompt_tmpl})
这里有个值得注意的细节:提示词里明确写了"不知道就回答 'I don't know!'"。把"允许说不知道"写进提示词,是 RAG 提示词里对抗幻觉最便宜的一招——github-rag/app.py 里的模板也是同一思路,只是换成了 "I don't have enough information about that aspect of the repository"。
自查:怎么判断自己跑的是示例还是玩具
跑通 ≠ 做对。30 分钟的示例里最容易被"流畅的回答"骗过去的是这个问题:它回答得有理有据,是因为检索真的生效了,还是模型靠自己的参数知识编的?仓库恰好自带了答案的工具链。
用 eval-data 做第一道检查
simple-rag-workflow 的 eval-data/test.csv 是一份结构化的问答测试集,每行三列:Question,Answer,Context。注意它问的不是泛泛的问题,而是 Paul Graham 自传里可逐句验证的硬事实,例如:
Question: What was the very first programming language Paul Graham used when he began learning to program on the IBM 1401? Answer: He used an early version of Fortran on the IBM 1401. Context: "The language we used was an early version of Fortran. You had to type programs on punch cards..."
Context 列直接给出了文档原文。这让"答案是否有据"变成一件可以人工核对的事:把回答和 Context 对照,如果回答里的每个事实点都能在 Context 里找到出处,检索链路就是通的。
用 evaluation.ipynb 做自动化评估
simple-rag-workflow/evaluation.ipynb 把这套流程做成了可复现的评估管线,关键有四步:
第一步,接入追踪。 通过回调把 LlamaIndex 的所有操作自动记下来:
from llama_index.core import Settings
from llama_index.core.callbacks import CallbackManager
from opik.integrations.llama_index import LlamaIndexCallbackHandler
opik_callback_handler = LlamaIndexCallbackHandler()
Settings.callback_manager = CallbackManager([opik_callback_handler])
第二步,灌测试集。 读 test.csv 并构造成数据集插入 Opik:
qa_pairs = [
{"input": row["Question"], "expected_output": row["Answer"], "context": row["Context"]}
for _, row in df.iterrows()
]
dataset.insert(qa_pairs)
第三步,定义被评估的应用。 就是把 workflow.query 包一层:
@track
async def my_llm_application(input: str) -> str:
response = await workflow.query(input)
return str(response)
第四步,跑四个指标:
from opik.evaluation.metrics import (
Hallucination,
AnswerRelevance,
ContextPrecision,
ContextRecall
)
evaluation = evaluate(
dataset=dataset,
task=evaluation_task,
experiment_name=model_name,
scoring_metrics=[hallucination_metric, answer_relevance_metric,
context_precision_metric, context_recall_metric],
experiment_config={"model": "gpt-3.5-turbo"}
)
这四个指标正好对应自查的四问:ContextPrecision 和 ContextRecall 问"检索回来的东西准不准、全不全",AnswerRelevance 问"回答扣不扣题",Hallucination 问"回答里有没有文档里没有的内容"。
这里还有一个 notebook 里容易被忽略的细节:load_workflow 支持切换 gemma3 和 llama3.2 两个模型跑同一套评估(experiment_name=model_name 按模型区分实验名)。这等于在提醒你:换模型/换 embedding 之后必须重跑评估,而不是默认"换了个更强的模型一定更好"——仓库里 gpt-oss-vs-qwen3、qwen3_vs_deepseek-r1 这些模型对比项目,方法论上都是同一套。
三条不依赖框架的快速自查
如果你不想现在就搭 Opik,以下三个手工检查就能覆盖大部分"玩具级"问题:
- 检索溯源检查:临时把
synthesize前的nodes打印出来(retrievestep 里nodes就是带分数和文本的NodeWithScore列表),看回答中的每个事实点是否真的出现在这 2 个节点里。如果出现节点里没有的细节,说明是模型在脑补。 - 越界问题检查:问一个语料里必然不存在的问题(比如对 DeepSeek.pdf 问"作者养的猫叫什么")。一个"能用"的 RAG 应该被提示词或常识约束成"不知道";如果它自信地编了一个,说明你的系统目前没有拒绝回答的能力,而最小闭环里
CompactAndRefine的默认模板并没有"不知道就说不知道"的约束——这正是上面提示词模板示例里那句 "say 'I don't know!'" 存在的意义。 - top_k 敏感性检查:把
similarity_top_k=2改成 1 或 5 各跑一遍同一个问题。如果回答质量对 top_k 完全不敏感,要么你的问题太简单(语料里随便哪个节点都能答),要么检索根本没起作用。
示例的边界在哪
最后给个明确的判断标准,区分"示例"和"玩具":
- 它还是示例的阶段:索引在内存里(
VectorStoreIndex不落盘,进程退出即消失)、切分用默认策略、单文档语料、无持久化会话。这些在simple-rag-workflow里全部成立,30 分钟内跑通目标下都是合理的取舍。 - 它升级为玩具的阶段:语料换成真实文档后发现"回答看起来对"但溯源对不上,而且你没有任何手段量化——没有测试集、没有指标、没有"允许说不知道"的提示词约束。这时候你需要的不是换更大的模型,而是仓库里已经给好的下一层积木:
document-chat-rag的自定义提示词模板、evaluation.ipynb的四指标评估,以及fastest-rag-stack/fastest-rag-milvus-groq里对向量库(Qdrant/Milvus + 二进制量化)的引入。
按依赖从轻到重的顺序——纯本地内存索引 → 本地模型 + 持久化向量库 → 云端推理 + 量化加速——这条路仓库里都已经铺好了,你要做的只是在每个阶段跑一次 eval-data 里的测试集,用数字而不是手感决定什么时候升级。
