文章目录1. 高层概念1.1 大语言模型LLMs1.2 智能体应用Agentic Applications1.3 智能体Agents1.4 检索增强生成RAG1.5 五大核心应用形态2. 安装与环境配置2.1 创建工程2.2 安装2.2.1 方式一Pip 快速安装2.2.2 方式二自定义按需安装2.2.3 方式三源码编译安装2.3 环境配置2.3.1 使用 OpenAI2.3.2 使用阿里云百炼3. 入门实战教程阿里云百炼3.1 基础智能体工具调用示例3.2 增加多轮对话记忆3.3 为智能体接入 RAG 检索能力3.4 RAG 索引持久化3.5 拓展方向小结1. 高层概念本节介绍构建大模型应用过程中反复出现的核心抽象。1.1 大语言模型LLMsLLM是催生LlamaIndex的基础技术。它是一类人工智能系统能够理解、生成、处理自然语言既可以依托训练数据作答也能够使用查询阶段传入的外部数据进行回答。1.2 智能体应用Agentic Applications当大模型嵌入应用用于决策、执行动作、与外部环境交互这类应用统称为智能体应用。典型特征LLM增强为模型挂载工具、记忆、动态提示词提示词链式调用多轮模型调用串行执行上一轮输出作为下一轮输入路由分发依靠大模型判断程序下一步流转状态并行执行支持并发执行多条任务链路分层编排多层大模型协同调度下层任务自省校验模型校验前置结果动态修正执行路径。在LlamaIndex中通过Workflow编排任务与模型调用实现各类智能体应用。1.3 智能体Agents智能体是「智能体应用」的具体实现实例。智能体依托大模型、工具、记忆组件运行在推理循环中半自主完成任务标准运行流程接收用户消息结合历史对话、可用工具、用户输入由LLM判断下一步动作按需调用一个或多个工具解析工具返回结果持续决策终止执行后向用户返回最终答案。1.4 检索增强生成RAGRAG是基于LlamaIndex构建私有数据应用的核心方案。不需要微调大模型而是在查询阶段向模型注入相关私有数据框架先对数据建立索引仅把检索得到的相关片段连同问题送入LLM避免全量数据传入。1.5 五大核心应用形态LlamaIndex根据官方顶层设计将数据增强型大模型应用归纳为五大核心应用形态覆盖从基础RAG问答、文档信息抽取到复杂智能体编排的主流开发场景Agents 智能体由LLM驱动的自主决策程序绑定各类工具与记忆组件运行推理循环动态选择执行动作无需固定流程适合复杂开放式任务。Workflows 工作流事件驱动的通用编排底座用于组织多阶段逻辑与LLM调用所有智能体类应用均可基于Workflow实现是框架底层核心抽象。结构化数据提取依托Pydantic定义目标数据结构从PDF、网页等非结构化文档中类型安全地提取标准化信息广泛用于文档自动化处理。Query Engines 查询引擎端到端单次问答链路标准RAG实现载体接收自然语言查询执行文档检索并返回答案与引用上下文一问一答模式。Chat Engines 对话引擎面向多轮交互会话自动维护历史对话上下文支持连续来回问答适用于聊天机器人场景。2. 安装与环境配置LlamaIndex采用命名空间分包架构。2.1 创建工程Python版本3.10,4.02.2 安装2.2.1 方式一Pip 快速安装执行pip install llama-index安装基础启动包各类第三方集成组件可按需单独安装。所有集成清单可查阅 LlamaHub。pipinstallllama-index基础包包含llama-index-corellama-index-llms-openaillama-index-embeddings-openaillama-index-readers-file注意llama-index-core内置NLTK、tiktoken资源文件规避运行时网络下载。安装完成2.2.2 方式二自定义按需安装不使用OpenAI、追求轻量化部署时可以单独指定依赖。示例Ollama本地模型 HuggingFace Embeddingpipinstallllama-index-core llama-index-readers-file llama-index-llms-ollama llama-index-embeddings-huggingface2.2.3 方式三源码编译安装gitclone https://github.com/run-llama/llama_index.git安装poetry环境管理工具poetry selfaddpoetry-plugin-shell poetry shell安装核心库pipinstall-ellama-index-core3.可选全套开发、文档依赖poetryinstall--withdev,docs按需本地安装各类集成包pipinstall-ellama-index-integrations/readers/llama-index-readers-file pipinstall-ellama-index-integrations/llms/llama-index-ollama2.3 环境配置2.3.1 使用 OpenAI没有OpenAI Key的话后面可以使用OpenAILike接入框架默认使用gpt-3.5-turbo生成文本text-embedding-ada-002实现向量检索。必须配置环境变量OPENAI_API_KEY。# MacOS/LinuxexportOPENAI_API_KEY你的密钥# WindowssetOPENAI_API_KEY你的密钥兼容OpenAI协议的第三方接口可使用OpenAILike系列类接入。2.3.2 使用阿里云百炼阿里云百炼平台一般有免费额度这里搭配通义千问两套模型qwen3.8-max百万上下文旗舰多模态生成模型承担检索结果综合推理、问答生成、Agent任务编排。qwen3.7-text-embedding新一代超长文本向量模型最大支持131072 token输入负责文档切片语义向量化与相似度检索。3. 入门实战教程阿里云百炼前置条件完成环境安装。想要纯本地模型运行可以查阅官方本地模型教程。3.1 基础智能体工具调用示例安装依赖并配置百练密钥在阿里云百炼控制台获取API Keypipinstallllama-index-core llama-index-llms-openai-like llama-index-embeddings-openai-like]# Linux/MacexportDASHSCOPE_API_KEYsk-xxx# CMD 命令行 set DASHSCOPE_API_KEYsk-xxxx# Windows PowerShell: $env:DASHSCOPE_API_KEYsk-xxx更推荐使用.env文件不受终端、启动方式影响项目根目录新建.env文件DASHSCOPE_API_KEYsk-3需要再安装python-dotenvpip install python-dotenv创建starter.py实现具备乘法计算工具的智能体。LLM通过OpenAILike接入百练的OpenAI兼容端点importasyncioimportosfromdotenvimportload_dotenvfromllama_index.core.agent.workflowimportFunctionAgentfromllama_index.llms.openai_likeimportOpenAILike# 加载 DASHSCOPE_API_KEYload_dotenv()api_keyos.environ[DASHSCOPE_API_KEY]# 接入阿里云百炼OpenAI 兼容模式llmOpenAILike(modelqwen3.8-max,# 支持 function calling 的通义千问模型api_keyapi_key,api_basehttps://ws-jfb8j8mx0n7e2k6a.cn-beijing.maas.aliyuncs.com/compatible-mode/v1,is_chat_modelTrue,# qwen 系列均为 chat 模型务必设为 Trueis_function_calling_modelTrue,# ← 加这一行)# 定义计算器工具defmultiply(a:float,b:float)-float:两个数字相乘returna*b# 构建智能体agentFunctionAgent(tools[multiply],llmllm,system_prompt你是助手可以完成两个数字相乘计算。,)asyncdefmain():responseawaitagent.run(1234 * 4567 等于多少)print(str(response))if__name____main__:asyncio.run(main())控制台输出1234×4567**5,635,678**执行流程用户问题 工具描述传入LLM- 模型选择工具并填充参数 - 执行函数 - 整合结果生成回答。框架推荐使用异步写法提升应用并发性能。FunctionAgent要求模型支持原生function calling百练的qwen-plus/qwen-max/qwen-turbo均支持。3.2 增加多轮对话记忆依靠Context对象持久化会话上下文实现连续对话。同一个ctx上的多次run()共享对话记忆不传ctx则每次都是全新会话。新建memory.pyimportasyncioimportosfromdotenvimportload_dotenvfromllama_index.core.agent.workflowimportFunctionAgentfromllama_index.core.workflowimportContextfromllama_index.llms.openai_likeimportOpenAILike load_dotenv()llmOpenAILike(modelqwen-plus,# 百炼模型专属端点替换 model 即可api_keyos.environ[DASHSCOPE_API_KEY],api_basehttps://dashscope.aliyuncs.com/compatible-mode/v1,# 参数名是 api_base传 base_url 会被静默忽略is_chat_modelTrue,is_function_calling_modelTrue,)defmultiply(a:float,b:float)-float:两个数字相乘returna*b agentFunctionAgent(tools[multiply],llmllm,system_prompt你是助手可以完成两个数字相乘计算。,)asyncdefmain():# Context 持久化会话上下文同一个 ctx 上的多次 run 共享记忆ctxContext(agent)responseawaitagent.run(我叫Logan,ctxctx)print(第1轮:,str(response))# 同一个 ctx 再问 -- 能答出名字说明记忆生效responseawaitagent.run(我的名字是什么,ctxctx)print(第2轮:,str(response))# 记忆与工具调用可以共存responseawaitagent.run(我叫Logan12乘以12等于多少,ctxctx)print(第3轮:,str(response))# 对照组不传 ctx 是全新会话不记得之前说过的话responseawaitagent.run(我的名字是什么)print(无ctx对照:,str(response))if__name____main__:asyncio.run(main())执行效果第1轮:你好Logan很高兴认识你。 第2轮:你的名字是 Logan ← 记忆生效 第3轮:Logan12乘以12等于144 ← 记忆与工具调用共存 无ctx对照:我并不知道您的名字...← 不传 ctx 即失忆Context内部维护会话的memory对话历史与state跨run()保留多智能体场景下还可作为共享黑板传递结构化状态。3.3 为智能体接入 RAG 检索能力准备测试文档mkdirdatawgethttps://raw.githubusercontent.com/run-llama/llama_index/main/docs/examples/data/paul_graham/paul_graham_essay.txt-Odata/paul_graham_essay.txt# 若网络不通放任意 .txt 文件到 data 目录即可注意RAG需要embedding模型。若不配置框架默认回退到OpenAI并报错必须同时把embedding也切到百炼text-embedding-v31024维中英文。完整代码importasyncioimportosfromdotenvimportload_dotenvfromllama_index.coreimportVectorStoreIndex,SimpleDirectoryReader,Settingsfromllama_index.core.agent.workflowimportFunctionAgentfromllama_index.embeddings.openai_likeimportOpenAILikeEmbeddingfromllama_index.llms.openai_likeimportOpenAILike load_dotenv()API_KEYos.environ[DASHSCOPE_API_KEY]API_BASEhttps://dashscope.aliyuncs.com/compatible-mode/v1# LLM 与 embedding 均接入百炼Settings.llmOpenAILike(modelqwen-plus,api_keyAPI_KEY,api_baseAPI_BASE,# ← 参数名是 api_baseis_chat_modelTrue,is_function_calling_modelTrue,# ← FunctionAgent 必需)Settings.embed_modelOpenAILikeEmbedding(model_nametext-embedding-v3,api_keyAPI_KEY,api_baseAPI_BASE,# ← embedding 同样是 api_base)# 构建RAG查询引擎自动使用 Settings 中的模型documentsSimpleDirectoryReader(data).load_data()indexVectorStoreIndex.from_documents(documents,show_progressTrue)query_engineindex.as_query_engine()defmultiply(a:float,b:float)-float:两个数字相乘returna*basyncdefsearch_documents(query:str)-str:检索Paul Graham随笔文档responseawaitquery_engine.aquery(query)returnstr(response)agentFunctionAgent(tools[multiply,search_documents],llmSettings.llm,system_prompt你可以进行数学计算也可以检索文档回答问题。,)asyncdefmain():responseawaitagent.run(作者大学时期做了什么7乘以8等于多少)print(response)if__name____main__:asyncio.run(main())智能体会自动判断何时调用计算工具、何时检索文档。执行效果Applying transformations:100%|██████████|1/1[00:0000:00,3.13it/s]Generating embeddings:100%|██████████|22/22[00:0200:00,8.44it/s]**关于作者大学时期做了什么**作者大学时原本打算学习哲学因为他认为哲学研究的是更根本、更宏大的真理。但上了哲学课程后他觉得这些课程很无聊于是转向了人工智能方向。激发他对人工智能兴趣的主要有两件事1.海因莱因的小说《The Moonisa Harsh Mistress》中出现的智能计算机 Mike2.一部 PBS 纪录片展示了 Terry Winograd 使用 SHRDLU 系统。**关于数学计算**7×8**56**3.4 RAG 索引持久化避免每次启动重复解析文档。推荐有缓存则加载、无则构建并保存的模式importasyncioimportosfrompathlibimportPathfromdotenvimportload_dotenvfromllama_index.coreimport(Settings,SimpleDirectoryReader,StorageContext,VectorStoreIndex,load_index_from_storage,)fromllama_index.embeddings.openai_likeimportOpenAILikeEmbeddingfromllama_index.llms.openai_likeimportOpenAILike load_dotenv()API_KEYos.environ[DASHSCOPE_API_KEY]API_BASEhttps://dashscope.aliyuncs.com/compatible-mode/v1# 注意即使加载已持久化的索引查询时仍要用 embed_model 向量化问题# 所以 LLM 与 embedding 的配置不能省Settings.llmOpenAILike(modelqwen-plus,api_keyAPI_KEY,api_baseAPI_BASE,is_chat_modelTrue,is_function_calling_modelTrue,)Settings.embed_modelOpenAILikeEmbedding(model_nametext-embedding-v3,api_keyAPI_KEY,api_baseAPI_BASE,)PERSIST_DIR./storageifPath(PERSIST_DIR).exists()andany(Path(PERSIST_DIR).iterdir()):print( 检测到已持久化的索引直接加载跳过文档解析...)storage_contextStorageContext.from_defaults(persist_dirPERSIST_DIR)indexload_index_from_storage(storage_context)else:print( 首次运行解析文档并构建索引...)documentsSimpleDirectoryReader(data).load_data()indexVectorStoreIndex.from_documents(documents,show_progressTrue)index.storage_context.persist(persist_dirPERSIST_DIR)# 持久化保存print(f 索引已保存到{PERSIST_DIR})query_engineindex.as_query_engine()asyncdefmain():responseawaitquery_engine.aquery(作者大学时期做了什么)print(response)if__name____main__:asyncio.run(main())storage/目录包含五个文件以75KB文档实测为例文件大小内容docstore.json137KB文档库data分块文本、metadata节点元数据、ref_doc_info分块与源文档的溯源关系index_store.json2KB索引结构IndexDict等记录“哪些节点属于哪个索引”及节点与向量的映射default__vector_store.json501KB向量数据体积最大embedding_dict文本向量、text_id_to_ref_doc_id向量→源文档映射、metadata_dictgraph_store.json18B知识图谱存储。本例未建图索引为默认初始化的空壳image__vector_store.json72B图像向量存储。本例无图像内容为空壳加载时load_index_from_storage会把这些JSON还原为内存中的DocumentStore/IndexStore/SimpleVectorStore跳过解析文档与embedding计算两个昂贵步骤查询时仍会调用Settings.embed_model对问题做向量化因此embedding配置不能省。加载时也别忘了 embedding 配置查询要把问题向量化才能检索所以Settings.embed_model在加载路径同样必需省掉会在查询时报错。如果使用第三方向量数据库可以直接从向量存储重建索引index VectorStoreIndex.from_vector_store(vector_store)注意向量维度需与百练text-embedding-v3的1024 维对齐。文档越大、解析与embedding成本越高持久化收益越大。3.5 拓展方向本文仅展示LlamaIndex基础能力基于框架还可以继续探索扩展更多自定义工具切换各类开源/闭源大模型通过系统提示词定制智能体行为开启流式输出搭建人机交互工作流实现多智能体协同系统。小结很多开发者把LlamaIndex简单等同于RAG框架但从官方定义可以看出RAG 只是「上下文增强」的子集。LlamaIndex的顶层目标是构建各类上下文增强型大模型应用涵盖问答、文档提取、智能体、事件驱动工作流等场景。理解这套顶层设计才能跳出Demo设计出可落地的生产级应用。