LlamaIndex 系列【4】入门案例（阿里云百炼适配）

1. 高层概念

本节介绍构建大模型应用过程中反复出现的核心抽象。

1.1 大语言模型（LLMs）

LLM是催生LlamaIndex的基础技术。它是一类人工智能系统，能够理解、生成、处理自然语言；既可以依托训练数据作答，也能够使用查询阶段传入的外部数据进行回答。

1.2 智能体应用（Agentic Applications）

当大模型嵌入应用，用于决策、执行动作、与外部环境交互，这类应用统称为智能体应用。

典型特征：

• LLM增强：为模型挂载工具、记忆、动态提示词；
• 提示词链式调用：多轮模型调用串行执行，上一轮输出作为下一轮输入；
• 路由分发：依靠大模型判断程序下一步流转状态；
• 并行执行：支持并发执行多条任务链路；
• 分层编排：多层大模型协同调度下层任务；
• 自省校验：模型校验前置结果，动态修正执行路径。

在LlamaIndex中，通过Workflow编排任务与模型调用，实现各类智能体应用。

1.3 智能体（Agents）

智能体是「智能体应用」的具体实现实例。

智能体依托大模型、工具、记忆组件运行在推理循环中，半自主完成任务，标准运行流程：

1. 接收用户消息；
2. 结合历史对话、可用工具、用户输入，由LLM判断下一步动作；
3. 按需调用一个或多个工具；
4. 解析工具返回结果，持续决策；
5. 终止执行后，向用户返回最终答案。

1.4 检索增强生成（RAG）

RAG是基于LlamaIndex构建私有数据应用的核心方案。

不需要微调大模型，而是在查询阶段向模型注入相关私有数据；框架先对数据建立索引，仅把检索得到的相关片段连同问题送入LLM，避免全量数据传入。

1.5 五大核心应用形态

LlamaIndex根据官方顶层设计，将数据增强型大模型应用归纳为五大核心应用形态，覆盖从基础RAG问答、文档信息抽取到复杂智能体编排的主流开发场景：

1. Agents 智能体
   由LLM驱动的自主决策程序，绑定各类工具与记忆组件，运行推理循环动态选择执行动作，无需固定流程，适合复杂开放式任务。
2. Workflows 工作流
   事件驱动的通用编排底座，用于组织多阶段逻辑与LLM调用，所有智能体类应用均可基于Workflow实现，是框架底层核心抽象。
3. 结构化数据提取
   依托Pydantic定义目标数据结构，从PDF、网页等非结构化文档中类型安全地提取标准化信息，广泛用于文档自动化处理。
4. Query Engines 查询引擎
   端到端单次问答链路，标准RAG实现载体；接收自然语言查询，执行文档检索并返回答案与引用上下文，一问一答模式。
5. Chat Engines 对话引擎
   面向多轮交互会话，自动维护历史对话上下文，支持连续来回问答，适用于聊天机器人场景。

2. 安装与环境配置

LlamaIndex采用命名空间分包架构。

2.1 创建工程

Python版本：>=3.10,<4.0

2.2 安装

2.2.1 方式一：Pip 快速安装

执行pip install llama-index安装基础启动包；各类第三方集成组件可按需单独安装。所有集成清单可查阅 LlamaHub。

pipinstallllama-index

基础包包含：

• llama-index-core
• llama-index-llms-openai
• llama-index-embeddings-openai
• llama-index-readers-file

注意：llama-index-core内置NLTK、tiktoken资源文件，规避运行时网络下载。

安装完成：

2.2.2 方式二：自定义按需安装

不使用OpenAI、追求轻量化部署时，可以单独指定依赖。

示例：Ollama本地模型 +HuggingFace Embedding

pipinstallllama-index-core llama-index-readers-file llama-index-llms-ollama llama-index-embeddings-huggingface

2.2.3 方式三：源码编译安装

gitclone https://github.com/run-llama/llama_index.git

1. 安装poetry环境管理工具

poetry selfaddpoetry-plugin-shell poetry shell

2. 安装核心库

pipinstall-ellama-index-core

3.（可选）全套开发、文档依赖

poetryinstall--withdev,docs

4. 按需本地安装各类集成包

pipinstall-ellama-index-integrations/readers/llama-index-readers-file pipinstall-ellama-index-integrations/llms/llama-index-ollama

2.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 Key）：

pipinstallllama-index-core llama-index-llms-openai-like llama-index-embeddings-openai-like]# Linux/Mac：exportDASHSCOPE_API_KEY=sk-xxx# CMD 命令行： set DASHSCOPE_API_KEY=sk-xxxx# Windows PowerShell: $env:DASHSCOPE_API_KEY="sk-xxx"

更推荐使用.env文件，不受终端、启动方式影响，项目根目录新建.env文件：

DASHSCOPE_API_KEY=sk-3

需要再安装python-dotenv：

pip install python-dotenv

创建starter.py，实现具备乘法计算工具的智能体。LLM通过OpenAILike
接入百练的OpenAI兼容端点：

importasyncioimportosfromdotenvimportload_dotenvfromllama_index.core.agent.workflowimportFunctionAgentfromllama_index.llms.openai_likeimportOpenAILike# 加载 DASHSCOPE_API_KEYload_dotenv()api_key=os.environ["DASHSCOPE_API_KEY"]# 接入阿里云百炼（OpenAI 兼容模式）llm=OpenAILike(model="qwen3.8-max",# 支持 function calling 的通义千问模型api_key=api_key,api_base="https://ws-jfb8j8mx0n7e2k6a.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",is_chat_model=True,# qwen 系列均为 chat 模型，务必设为 Trueis_function_calling_model=True,# ← 加这一行)# 定义计算器工具defmultiply(a:float,b:float)->float:"""两个数字相乘"""returna*b# 构建智能体agent=FunctionAgent(tools=[multiply],llm=llm,system_prompt="你是助手，可以完成两个数字相乘计算。",)asyncdefmain():response=awaitagent.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.py：

importasyncioimportosfromdotenvimportload_dotenvfromllama_index.core.agent.workflowimportFunctionAgentfromllama_index.core.workflowimportContextfromllama_index.llms.openai_likeimportOpenAILike load_dotenv()llm=OpenAILike(model="qwen-plus",# 百炼模型；专属端点替换 model 即可api_key=os.environ["DASHSCOPE_API_KEY"],api_base="https://dashscope.aliyuncs.com/compatible-mode/v1",# 参数名是 api_base，传 base_url 会被静默忽略！is_chat_model=True,is_function_calling_model=True,)defmultiply(a:float,b:float)->float:"""两个数字相乘"""returna*b agent=FunctionAgent(tools=[multiply],llm=llm,system_prompt="你是助手，可以完成两个数字相乘计算。",)asyncdefmain():# Context 持久化会话上下文：同一个 ctx 上的多次 run 共享记忆ctx=Context(agent)response=awaitagent.run("我叫Logan",ctx=ctx)print("第1轮:",str(response))# 同一个 ctx 再问 -- 能答出名字，说明记忆生效response=awaitagent.run("我的名字是什么？",ctx=ctx)print("第2轮:",str(response))# 记忆与工具调用可以共存response=awaitagent.run("我叫Logan，12乘以12等于多少？",ctx=ctx)print("第3轮:",str(response))# 对照组：不传 ctx 是全新会话，不记得之前说过的话response=awaitagent.run("我的名字是什么？")print("无ctx对照:",str(response))if__name__=="__main__":asyncio.run(main())

执行效果：

第1轮:你好，Logan！很高兴认识你。 第2轮:你的名字是 Logan！ ← 记忆生效 第3轮:Logan，12乘以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-v3，1024维，中英文）。

完整代码：

importasyncioimportosfromdotenvimportload_dotenvfromllama_index.coreimportVectorStoreIndex,SimpleDirectoryReader,Settingsfromllama_index.core.agent.workflowimportFunctionAgentfromllama_index.embeddings.openai_likeimportOpenAILikeEmbeddingfromllama_index.llms.openai_likeimportOpenAILike load_dotenv()API_KEY=os.environ["DASHSCOPE_API_KEY"]API_BASE="https://dashscope.aliyuncs.com/compatible-mode/v1"# LLM 与 embedding 均接入百炼Settings.llm=OpenAILike(model="qwen-plus",api_key=API_KEY,api_base=API_BASE,# ← 参数名是 api_baseis_chat_model=True,is_function_calling_model=True,# ← FunctionAgent 必需)Settings.embed_model=OpenAILikeEmbedding(model_name="text-embedding-v3",api_key=API_KEY,api_base=API_BASE,# ← embedding 同样是 api_base)# 构建RAG查询引擎（自动使用 Settings 中的模型）documents=SimpleDirectoryReader("data").load_data()index=VectorStoreIndex.from_documents(documents,show_progress=True)query_engine=index.as_query_engine()defmultiply(a:float,b:float)->float:"""两个数字相乘"""returna*basyncdefsearch_documents(query:str)->str:"""检索Paul Graham随笔文档"""response=awaitquery_engine.aquery(query)returnstr(response)agent=FunctionAgent(tools=[multiply,search_documents],llm=Settings.llm,system_prompt="你可以进行数学计算，也可以检索文档回答问题。",)asyncdefmain():response=awaitagent.run("作者大学时期做了什么？7乘以8等于多少？")print(response)if__name__=="__main__":asyncio.run(main())

智能体会自动判断何时调用计算工具、何时检索文档。执行效果：

Applying transformations:100%|██████████|1/1[00:00<00:00,3.13it/s]Generating embeddings:100%|██████████|22/22[00:02<00:00,8.44it/s]**关于作者大学时期做了什么：**作者大学时原本打算学习哲学，因为他认为哲学研究的是更根本、更宏大的真理。但上了哲学课程后，他觉得这些课程很无聊，于是转向了人工智能方向。激发他对人工智能兴趣的主要有两件事：1.海因莱因的小说《The Moonisa Harsh Mistress》中出现的智能计算机 Mike；2.一部 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_KEY=os.environ["DASHSCOPE_API_KEY"]API_BASE="https://dashscope.aliyuncs.com/compatible-mode/v1"# 注意：即使加载已持久化的索引，查询时仍要用 embed_model 向量化问题，# 所以 LLM 与 embedding 的配置不能省Settings.llm=OpenAILike(model="qwen-plus",api_key=API_KEY,api_base=API_BASE,is_chat_model=True,is_function_calling_model=True,)Settings.embed_model=OpenAILikeEmbedding(model_name="text-embedding-v3",api_key=API_KEY,api_base=API_BASE,)PERSIST_DIR="./storage"ifPath(PERSIST_DIR).exists()andany(Path(PERSIST_DIR).iterdir()):print(">> 检测到已持久化的索引，直接加载（跳过文档解析）...")storage_context=StorageContext.from_defaults(persist_dir=PERSIST_DIR)index=load_index_from_storage(storage_context)else:print(">> 首次运行：解析文档并构建索引...")documents=SimpleDirectoryReader("data").load_data()index=VectorStoreIndex.from_documents(documents,show_progress=True)index.storage_context.persist(persist_dir=PERSIST_DIR)# 持久化保存print(f">> 索引已保存到{PERSIST_DIR}")query_engine=index.as_query_engine()asyncdefmain():response=awaitquery_engine.aquery("作者大学时期做了什么？")print(response)if__name__=="__main__":asyncio.run(main())

storage/目录包含五个文件（以75KB文档实测为例）：

加载时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基础能力，基于框架还可以继续探索：

1. 扩展更多自定义工具；
2. 切换各类开源/闭源大模型；
3. 通过系统提示词定制智能体行为；
4. 开启流式输出；
5. 搭建人机交互工作流；
6. 实现多智能体协同系统。

小结

很多开发者把LlamaIndex简单等同于RAG框架，但从官方定义可以看出：RAG 只是「上下文增强」的子集。

LlamaIndex的顶层目标是构建各类上下文增强型大模型应用，涵盖问答、文档提取、智能体、事件驱动工作流等场景。理解这套顶层设计，才能跳出Demo，设计出可落地的生产级应用。