30 分钟跑通第一个 RAG 示例:从这份合集里挑最短的一条路

原创2026-11-02 09:06:131,384 阅读
文章标签:示例工程人工智能大模型

30 分钟跑通第一个 RAG 示例:从这份合集里挑最短的一条路

AI Engineering Hub 横幅,展示 LLM、RAG、Agent 等主题方向

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,以下三个手工检查就能覆盖大部分"玩具级"问题:

  1. 检索溯源检查:临时把 synthesize 前的 nodes 打印出来(retrieve step 里 nodes 就是带分数和文本的 NodeWithScore 列表),看回答中的每个事实点是否真的出现在这 2 个节点里。如果出现节点里没有的细节,说明是模型在脑补。
  2. 越界问题检查:问一个语料里必然不存在的问题(比如对 DeepSeek.pdf 问"作者养的猫叫什么")。一个"能用"的 RAG 应该被提示词或常识约束成"不知道";如果它自信地编了一个,说明你的系统目前没有拒绝回答的能力,而最小闭环里 CompactAndRefine 的默认模板并没有"不知道就说不知道"的约束——这正是上面提示词模板示例里那句 "say 'I don't know!'" 存在的意义。
  3. 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 里的测试集,用数字而不是手感决定什么时候升级。

登录后查看全文
ai-engineering-hub