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

文章目录

• [1. 高层概念](#1. 高层概念)
• • [1.1 大语言模型（LLMs）](#1.1 大语言模型（LLMs）)
  • [1.2 智能体应用（Agentic Applications）](#1.2 智能体应用（Agentic Applications）)
  • [1.3 智能体（Agents）](#1.3 智能体（Agents）)
  • [1.4 检索增强生成（RAG）](#1.4 检索增强生成（RAG）)
  • [1.5 五大核心应用形态](#1.5 五大核心应用形态)
• [2. 安装与环境配置](#2. 安装与环境配置)
• • [2.1 创建工程](#2.1 创建工程)
  • [2.2 安装](#2.2 安装)
  • • [2.2.1 方式一：Pip 快速安装](#2.2.1 方式一：Pip 快速安装)
    • [2.2.2 方式二：自定义按需安装](#2.2.2 方式二：自定义按需安装)
    • [2.2.3 方式三：源码编译安装](#2.2.3 方式三：源码编译安装)
  • [2.3 环境配置](#2.3 环境配置)
  • • [2.3.1 使用 OpenAI](#2.3.1 使用 OpenAI)
    • [2.3.2 使用阿里云百炼](#2.3.2 使用阿里云百炼)
• [3. 入门实战教程（阿里云百炼）](#3. 入门实战教程（阿里云百炼）)
• • [3.1 基础智能体：工具调用示例](#3.1 基础智能体：工具调用示例)
  • [3.2 增加多轮对话记忆](#3.2 增加多轮对话记忆)
  • [3.3 为智能体接入 RAG 检索能力](#3.3 为智能体接入 RAG 检索能力)
  • [3.4 RAG 索引持久化](#3.4 RAG 索引持久化)
  • [3.5 拓展方向](#3.5 拓展方向)
• 小结

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。

pip install llama-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

pip install llama-index-core llama-index-readers-file llama-index-llms-ollama llama-index-embeddings-huggingface

---

2.2.3 方式三：源码编译安装

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

1. 安装 poetry 环境管理工具

poetry self add poetry-plugin-shell
poetry shell

2. 安装核心库

pip install -e llama-index-core

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

poetry install --with dev,docs

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

pip install -e llama-index-integrations/readers/llama-index-readers-file
pip install -e llama-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/Linux
export OPENAI_API_KEY=你的密钥

# Windows
set OPENAI_API_KEY=你的密钥

兼容 OpenAI 协议的第三方接口，可使用 OpenAILike 系列类接入。

---

2.3.2 使用阿里云百炼

阿里云百炼平台一般有免费额度，这里搭配通义千问两套模型：

• qwen3.8-max：百万上下文旗舰多模态生成模型，承担检索结果综合推理、问答生成、Agent 任务编排。
• qwen3.7-text-embedding：新一代超长文本向量模型，最大支持 131072 token 输入，负责文档切片语义向量化与相似度检索。

---

3. 入门实战教程（阿里云百炼）

前置条件：完成环境安装。想要纯本地模型运行，可以查阅官方本地模型教程。

---

3.1 基础智能体：工具调用示例

安装依赖并配置百练密钥（在阿里云百炼控制台获取 API Key）：

pip install llama-index-core llama-index-llms-openai-like llama-index-embeddings-openai-like]
# Linux/Mac：
export DASHSCOPE_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 兼容端点：

import asyncio
import os

from dotenv import load_dotenv
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai_like import OpenAILike

# 加载 DASHSCOPE_API_KEY
load_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 模型，务必设为 True
    is_function_calling_model=True,    # ← 加这一行
)

# 定义计算器工具
def multiply(a: float, b: float) -> float:
    """两个数字相乘"""
    return a * b

# 构建智能体
agent = FunctionAgent(
    tools=[multiply],
    llm=llm,
    system_prompt="你是助手，可以完成两个数字相乘计算。",
)

async def main():
    response = await agent.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 ：

import asyncio
import os

from dotenv import load_dotenv
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.core.workflow import Context
from llama_index.llms.openai_like import OpenAILike

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,
)

def multiply(a: float, b: float) -> float:
    """两个数字相乘"""
    return a * b

agent = FunctionAgent(
    tools=[multiply],
    llm=llm,
    system_prompt="你是助手，可以完成两个数字相乘计算。",
)

async def main():
    # Context 持久化会话上下文：同一个 ctx 上的多次 run 共享记忆
    ctx = Context(agent)

    response = await agent.run("我叫Logan", ctx=ctx)
    print("第1轮:", str(response))

    # 同一个 ctx 再问 -- 能答出名字，说明记忆生效
    response = await agent.run("我的名字是什么？", ctx=ctx)
    print("第2轮:", str(response))

    # 记忆与工具调用可以共存
    response = await agent.run("我叫Logan，12乘以12等于多少？", ctx=ctx)
    print("第3轮:", str(response))

    # 对照组：不传 ctx 是全新会话，不记得之前说过的话
    response = await agent.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 检索能力

准备测试文档：

mkdir data
wget https://raw.githubusercontent.com/run-llama/llama_index/main/docs/examples/data/paul_graham/paul_graham_essay.txt -O data/paul_graham_essay.txt
# 若网络不通，放任意 .txt 文件到 data 目录即可

注意 ：RAG 需要 embedding 模型。若不配置，框架默认回退到 OpenAI 并报错，

必须同时把 embedding 也切到百炼（text-embedding-v3，1024 维，中英文）。

完整代码：

import asyncio
import os

from dotenv import load_dotenv
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, Settings
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.embeddings.openai_like import OpenAILikeEmbedding
from llama_index.llms.openai_like import OpenAILike

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_base
    is_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()

def multiply(a: float, b: float) -> float:
    """两个数字相乘"""
    return a * b

async def search_documents(query: str) -> str:
    """检索Paul Graham随笔文档"""
    response = await query_engine.aquery(query)
    return str(response)

agent = FunctionAgent(
    tools=[multiply, search_documents],
    llm=Settings.llm,
    system_prompt="你可以进行数学计算，也可以检索文档回答问题。",
)

async def main():
    response = await agent.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 Moon is a Harsh Mistress》中出现的智能计算机 Mike；
2. 一部 PBS 纪录片，展示了 Terry Winograd 使用 SHRDLU 系统。

**关于数学计算：**

7 × 8 = **56**

---

3.4 RAG 索引持久化

避免每次启动重复解析文档。推荐"有缓存则加载、无则构建并保存"的模式：

import asyncio
import os
from pathlib import Path

from dotenv import load_dotenv
from llama_index.core import (
    Settings, SimpleDirectoryReader, StorageContext,
    VectorStoreIndex, load_index_from_storage,
)
from llama_index.embeddings.openai_like import OpenAILikeEmbedding
from llama_index.llms.openai_like import OpenAILike

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"

if Path(PERSIST_DIR).exists() and any(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()

async def main():
    response = await query_engine.aquery("作者大学时期做了什么？")
    print(response)

if __name__ == "__main__":
    asyncio.run(main())

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

文件	大小	内容
docstore.json	137KB	文档库：data（分块文本）、metadata（节点元数据）、ref_doc_info（分块与源文档的溯源关系）
index_store.json	2KB	索引结构：IndexDict 等，记录"哪些节点属于哪个索引"及节点与向量的映射
default__vector_store.json	501KB	向量数据（体积最大）：embedding_dict（文本向量）、text_id_to_ref_doc_id（向量→源文档映射）、metadata_dict
graph_store.json	18B	知识图谱存储。本例未建图索引，为默认初始化的空壳
image__vector_store.json	72B	图像向量存储。本例无图像内容，为空壳

加载时 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，设计出可落地的生产级应用。

---