LlamaIndex入门:RAG专用框架的核心API专栏:AI/LLM工程化实战 - 从Prompt到Agent的完整落地指南模块5 LangChain/LlamaIndex框架篇 第50篇摘要摘要:LlamaIndex面向RAG的Document/Node/Index/Retriever/QueryEngine一套五件套,用SimpleDirectoryReader加载文档、VectorStoreIndex.from_documents建向量索引、query_engine.query做问答,是RAG落地最快的捷径,本专栏限时¥59.90(原价¥99)TL;DR 核心要点速览LlamaIndex是RAG专用框架,而LangChain是通用编排框架,定位不在同一层,选前者做检索快、选后者做编排灵活Document是原始文档,LlamaIndex会自动把长文档切成Node,DefaultNode是RAG的单位,切分策略直接决定检索质量Index是落地的数据组织,VectorStoreIndex是主力,建一次序把文本向量化存进向量库供后续查询Retriever负责查,query_engine是它之上的门面,喂一句问话,内部自动走检索加合成两条管线SimpleDirectoryReader一行就能把本地文件夹里的txt/md/pdf装成一系列Document,是真下地库唯一入口最小RAG三步叫齐,load_data建Document、from_documents建Index、query()问答,共十来行代码就能跑通我在接入LlamaIndex后,检索型问答的搭建代码从手搓几百行缩到几十行,功能还更全本专栏限时¥59.90(原价¥99)开篇故事:一个被重复造轮子磨秃的RAG2024年很长一段时间,我对框架心怀戒备,觉得什么都该自己写才踏实。做检索问答(RAG)时,我硬是用LangChain的组件一个仓库一个仓库地拼,文档解析、切分、向量化、检索、合成,每一环都自己折腾。跑通的那天我很得意,但回头一看,光是加载本地文件夹文档再切分就写了近百行,还只是为了服务一个小型FAQ机器人。后来同事让我试一下LlamaIndex,我心不在焉地点开文档,看到SimpleDirectoryReader(“.”, “data”)一下就把一整个本地目录读成一堆Document,再VectorStoreIndex.from_documents往下一按,向量索引就成了,最后query_engine.query(“…”)一句问话就出答案。我那个三天手搓的RAG,核心就这么几行。我挠头想,之前那些时间花得真冤。现在再说框架没用、还不如自己写我第一个不同意。LlamaIndex把RAG这条链路抽象得恰到好处,Document、Node、Index、Retriever、QueryEngine五个概念一拎出来,整条管线在各组件的位置就一清二楚。今天这篇把五个核心API讲透,带一份能真正落地跑通的RAG代码,也把LlamaIndex和LangChain的定位差别说清,别再重复我踩过的轮子。一、LlamaIndex是RAG专用框架先摆正定位,这也是好多人一开始迷路的根源。LangChain的核心卖点是编排,它把LLM调用、工具、链、Agent这些通用能力统筹起来,什么都能连。而LlamaIndex从出生就把目标押在数据加上LLM这一件事上,尤其擅长做好检索问答,是检索增强生成这个赛道的专业选手。1.1 定位差异一句话说通俗点,LangChain是瑞士军刀加特林,哪都能用;LlamaIndex是专攻检索的高炮,在RAG这一亩三分地里又快又省心。真要搭一个涉及多Agent、复杂审批流的系统,你还是得回到LangChain或LangGraph;可但凡任务是让模型基于一堆私有文档回答问题,LlamaIndex留的那条专用链路几乎永远比LangChain临时拼最快。1.2 用在哪、不用在哪LlamaIndex的舒适区很明确,本地文档问答、知识库检索增强、结构化数据加LLM。它交给你一套被封得很好的抽象,大部分时候你不用关心切分和检索的细节。反过来说,要完全定制旋钮、要深度接入别的市场链路,它又会变成一层要绕开的壳。我的取舍很简单,检索问答类重活优先给LlamaIndex,编排类重活交给LangChain/LangGraph,两边各干各的最擅长的活。二、五个核心概念:Document Node Index Retriever QueryEngineLlamaIndex的地基就是这五个名词,从原始文件到最终答案,一条主线把它们串起来。把这五个位置在脑子里对应清楚,后面所有API都是在这条主线的某个环节加配置。2.1 Document原始文档Document是一份文档的总称,可以来自文件、网页、数据库,是最上游的输入单位。它不光装正文,通常还带metadata元数据(来源文件名、路径、时间戳),这些元数据在后面做溯源、过滤、引用时非常值钱。你一般不会手工去建它,而是靠一个加载器从数据源把它倒出来。2.2 Node检索单位Node是RAG真正干活的单位,LlamaIndex收进来的长Document会被自动切成多段Node,每段才是向量化和检索的最小颗粒。常见叫法有TextNode文档和NodeParser切分器,默认按固定大小切分。切得越细,单段越聚焦匹配越准,但上下文越不完整;切得越粗相反。这个粒度平衡是RAG调优的第一道旋钮,后面第23篇讲分块策略时展开细说。2.3 Index数据组织Index是对Document做一层组织后的产物,决定了数据该怎么被存、怎么被找。主力是VectorStoreIndex,它会调嵌入模型把每个Node向量化,再存进向量库。索引是一次建造、长期使用的存在,建好后你不必每次问答都重建,反复用它来生成检索器和问答引擎。2.4 Retriever检索器Retriever是负责找的那一环,输入一句查询,输出最相关的若干Node。默认是向量相似度检索,你也可以换成关键词、混合检索等变体。它只负责把候选相关片段捞出来,不负责组织答案,是后面合成环节的原料生产线。2.5 QueryEngine问答引擎QueryEngine是面向用户的门面,内部把检索和合成两层拧在一起。合成这一层把查回来的Node拼进上下文,再交给LLM组织成一段通顺答案。对绝大多数人来说,每天调的最多的就这两个,as_query_engine建引擎,query()提问,绝大多数RAG需求到此为止。三、完整代码:加载文档建索引再问答概念理清,一句话落地一个完整RAG。三步分别是SimpleDirectoryReader加载本地文件夹、VectorStoreIndex.from_documents建向量索引、query_engine.query()做问答。默认走OpenAI的向量与LLM,需要OPENAI_API_KEY;没有key就按末尾的注释切到本地模型。# rag_llamaindex.py# LlamaIndex 入门 RAG: 读本地文档 - 建向量索引 - 问答# 安装: pip install llama-index llama-index-embeddings-openai llama-index-llm-openai# 运行: python rag_llamaindex.py## 需要环境变量 OPENAI_API_KEY, 或用本地模型替换(见文件末尾注释)# 先在自己目录下建一个 data 文件夹, 随便放几篇txt/md再跑importos# 读环境变量, 判断是否配置了keyfromllama_index.coreimportSimpleDirectoryReader# 读本地文档fromllama_index.coreimportVectorStoreIndex# 建向量索引fromllama_index.coreimportSettings# 统一配置模型# 第0步: 配置向量模型和LLM(都走OpenAI, 读取环境里的key)fromllama_index.embeddings.openaiimportOpenAIEmbeddingfromllama_index.llms.openaiimportOpenAI Settings.embed_modelOpenAIEmbedding(modeltext-embedding-3-small)Settings.llmOpenAI(modelgpt-4o-mini,temperature0)# 第1步: 加载文档, 把 data 文件夹下的文件读成一系列DocumentdocumentsSimpleDirectoryReader(data).load_data()print(f已加载{len(documents)}篇文档)# 打印篇数便于确认读取成功# 第2步: 建索引, LlamaIndex自动把长文档切成Node并向量化存进向量库indexVectorStoreIndex.from_documents(documents)# 第3步: 生成问答引擎, 内部自动走 检索合成 的RAG管线query_engineindex.as_query_engine()# 第4步: 提问, 拿到基于真实文档的回答respquery_engine.query(这家公司的主营业务是什么?)print(resp)跑之前确认三件事,自己目录下开了data文件夹并放了文档,装了上面那三个库,配好了OPENAI_API_KEY。跑完会先打印已加载几篇文档,随后query那句问话给出基于文档内容的回答,并且能自带出处来源。这套代码就是LlamaIndex能少到什么程度的地板,大量页面级RAG需求到这一步其实已经够了。没有OpenAI key的本地替代,把第0步换成下面的配置就能用本地模型跑整套流程,前提是本机装了Ollama并拉好了模型。# 本地方案: 无OPENAI_API_KEY时, 用Ollama本地模型跑同样的RAG# 需安装: pip install llama-index-llm-ollama llama-index-embeddings-ollamafromllama_index.coreimportSettingsfromllama_index.llms.ollamaimportOllamafromllama_index.embeddings.ollamaimportOllamaEmbedding Settings.llmOllama(modelqwen2.5:7b,request_timeout120.0)# 本地对话Settings.embed_modelOllamaEmbedding(modelnomic-embed-text)# 本地向量四、独家踩坑:Node切块太粗导致两张表的内容搅成一锅我拿到然后处理一份产品手册的RAG时,发现回答总把两个不同产品的规格搅在一起,说什么都掺着对方的参数。排查发现我的文档每页超长,LlamaIndex默认按固定大小切分,把两份产品的段落切进同一个Node,向量化后一片混浊,检索捞回来的片段自然不干不净。复现也很容易,把两份主题完全不同的长文档并排放进data,试用默认切分问答,你会看到答案走样。修法在切分和检索两头,一头给NodeParser配更小的chunk_size并且让chunk之间留一点overlap,让切分更细、边界更稳;另一头给Document带上来源type元数据,检索后按type过滤掉不相干的类别。我两个都做了之后,回答终于各归各的,不再串味。教训一句话,Node粒度直接决定检索纯度,别让默认参数替你决定文档该怎么分。五、对比分析:LlamaIndex 与 手搓RAG很多同学纠结要不要上LlamaIndex,我这里把自己用LangChain组件手搓和直接用LlamaIndex拉一张表对比,账就好算了。对比项手搓RAG(基于LangChain)LlamaIndex直接做加载并切分文档要自己拼加载器切分器,上百行一行load_data自动切好建索引自己调向量化存库from_documents一步好检索问答自己串检索器和LLMquery()一句到位可定制性高,什么都自己控中,留了扩展点但默认够用上手速度慢,链路自己铺快,十行出能用的RAG维护成本高,每环自己守低,抽象封装好取舍很清楚。想做通用复杂系统的编排,并想彻底掌控每一环,手搓或LangChain有它的位置。但纯做检索问答、且希望快速出活又不太折腾底层,我这边的答案是LlamaIndex。把几十上百行的链路收回十行,还不牺牲检索能力,这是它最实打实的价值,也是我后来所有RAG论文默认的第一选择。六、为什么订阅本专栏LlamaIndex资料不少,但大多是照着文档跑一遍就以为会的状态,把Document/Node/Index/Retriever/QueryEngine每个抽象单独拎出来讲,连起来却没人告诉你Node切多粗会串味、没key怎么接本地模型这些真实工程问题。对比项公开零散资料本专栏五件套定位名词讲解Document到QueryEngine一条主线贯穿可运行RAG常缺key或缺本地方案提供OpenAI与本地模型双方案踩坑复盘少有Node切块太粗导致串味的真实事故与LangChain各讲各的一张表对齐定位与选型上手口诀分散加载建索引问答三步走一点算透原价¥99,现在限时¥59.90,把手搓RAG从上百行缩到十行的关键,连同五个核心API和真实踩坑一起交付给你。30秒完成订阅,今天就能开始,让LlamaIndex帮你把检索问答这条路修成一条快车道。相关推荐49 LangGraph进阶:人在回路与多Agent编排21 RAG入门:检索增强生成的完整落地23 分块策略:如何切分文档提升检索质量立即订阅从Document到QueryEngine,五个概念把整条RAG管线点得明明白白,加载文档、建向量索引、问答查询三步叫齐,十行代码就出一个能用的检索问答。再借本地模型替代,不花一分钱也能跑通全流程。限时¥59.90,30秒完成订阅,今天就能开始,把LlamaIndex这条RAG快车道开进你的技能清单。