1. 环境准备与基础配置
在开始使用LlamaIndex之前,我们需要先搭建好开发环境。这个框架的核心是围绕大型语言模型(LLM)构建的,因此我们需要先准备好模型运行环境。
1.1 Ollama安装与模型下载
Ollama是一个本地运行大型语言模型的工具,我们可以通过以下命令安装和配置:
bash复制# 安装Ollama(具体安装方法取决于你的操作系统)
curl -fsSL https://ollama.com/install.sh | sh
# 启动Ollama服务
ollama serve
# 在另一个终端窗口下载qwen2.5:7b模型
ollama pull qwen2.5:7b
注意:qwen2.5:7b是一个7B参数量的中文优化模型,大小约4GB,下载时间取决于你的网络速度。
1.2 项目代码获取与依赖安装
接下来我们获取示例代码并设置Python虚拟环境:
bash复制git clone https://github.com/mingjiegao/llamaIndex_example
cd llamaIndex_example
# 创建并激活虚拟环境
python -m venv venv
source venv/bin/activate # Linux/macOS
# 或 venv\Scripts\activate # Windows
# 安装依赖
pip install -r requirements.txt
requirements.txt中主要包含以下关键包:
- llama-index-core:LlamaIndex核心库
- llama-index-llms-ollama:Ollama的LLM接口
- sentence-transformers:用于文本嵌入的模型
2. LlamaIndex基础对话示例
2.1 简单单轮对话
我们先从最基本的LLM对话开始,运行01_simple_llm_chat.py:
python复制from llama_index.core.llms import ChatMessage
from llama_index.llms.ollama import Ollama
llm = Ollama(model="qwen2.5:7b", temperature=0.7)
# 简单提问
response = llm.complete("请用一句话解释什么是Python")
print(f"回答: {response.text}")
输出示例:
code复制回答: Python是一种高级编程语言,强调代码可读性和简洁的语法(通常比Java或C++更简洁)。
2.2 带系统提示的对话
我们可以通过ChatMessage来构建更复杂的对话场景:
python复制messages = [
ChatMessage(
role="system",
content="你是一个幽默风趣的编程导师,擅长用生动的比喻解释技术概念。回答要简短有趣。"
),
ChatMessage(role="user", content="什么是变量?")
]
response = llm.chat(messages)
print(f"AI回答: {response.message.content}")
输出示例:
code复制AI回答: 变量啊,就像你的小钱包,你可以随时存点钱进去,也可以随时拿出去花。编程时,你给它赋值就是存钱,使用它的值就是取钱。只不过,这个钱包能装各种各样的"钱"——数字、文字甚至是一堆代码!
2.3 多轮对话保持上下文
LlamaIndex会自动维护对话历史,实现上下文感知:
python复制# 第一轮对话
messages = [
ChatMessage(role="user", content="我叫小明,我正在学习Python")
]
response = llm.chat(messages)
print(f"AI: {response.message.content}")
# 第二轮对话(保持上下文)
messages.append(response.message) # 添加AI回复到历史
messages.append(ChatMessage(role="user", content="我叫什么名字?"))
response = llm.chat(messages)
print(f"AI: {response.message.content}")
输出示例:
code复制AI: 你好,小明!很高兴听到你在学习Python。如果你有任何关于Python的问题或需要帮助的地方,随时可以问我。加油!
AI: 你叫小明。
2.4 流式输出实现打字机效果
对于长文本回答,我们可以使用流式输出提升用户体验:
python复制response_iter = llm.stream_chat(messages)
for chunk in response_iter:
print(chunk.delta, end="", flush=True)
3. RAG(检索增强生成)实战
RAG是LlamaIndex的核心功能之一,它结合了检索和生成的能力,让LLM能够基于特定文档内容生成回答。
3.1 初始化RAG系统
运行02_simple_rag.py时,系统会自动下载并配置以下组件:
- LLM模型:继续使用qwen2.5:7b
- Embedding模型:BAAI/bge-small-zh-v1.5(约100MB)
- 向量数据库:默认使用内存存储
3.2 文档加载与处理
示例代码中创建了3个简单的文档:
python复制documents = [
Document(text="Python是一种高级编程语言。它的设计哲学注重代码的可读性和简洁性..."),
Document(text="LlamaIndex可以用于构建数据驱动的应用程序,其核心功能包括数据连接、创建索引..."),
Document(text="Django是一个Web框架,提供了丰富的功能如ORM、Admin后台等...")
]
实际应用中,你可以加载各种格式的文档:
- PDF、Word、Excel等文件
- 网页内容
- 数据库记录
- API返回数据
3.3 构建向量索引
索引构建过程会自动完成以下步骤:
- 文本分块(chunking)
- 生成嵌入向量(embedding)
- 存储到向量数据库
python复制index = VectorStoreIndex.from_documents(documents)
提示:首次运行时会下载embedding模型,后续运行会直接使用缓存。
3.4 查询引擎与结果检索
创建查询引擎并提问:
python复制query_engine = index.as_query_engine()
response = query_engine.query("Python是什么?有什么特点?")
print(response)
输出结果包含:
- AI生成的回答
- 引用的文档片段
- 相似度分数
示例输出:
code复制Python 是一种高级编程语言。它的设计哲学注重代码的可读性和简洁性,并支持面向对象、函数式和过程式等多种编程范式。
相关来源:
- python_intro (相似度: 0.6708)
- django_intro (相似度: 0.5498)
3.5 多轮对话的RAG实现
LlamaIndex提供了ChatEngine来实现带记忆的RAG对话:
python复制chat_engine = index.as_chat_engine()
response = chat_engine.chat("LlamaIndex有哪些核心功能?")
print(response)
response = chat_engine.chat("这些功能中,哪个最常用?")
print(response)
4. Agent(智能代理)开发
Agent是LlamaIndex的另一个强大功能,它允许LLM根据需求动态调用工具完成任务。
4.1 工具定义与创建
在03_simple_agent.py中定义了4个工具:
python复制def get_current_time():
"""返回当前时间"""
return datetime.now().strftime("%Y-%m-%d %H:%M:%S")
def calculate(expression: str):
"""计算数学表达式"""
try:
return f"计算结果: {expression} = {eval(expression)}"
except:
return "计算失败,请检查表达式"
tools = [
FunctionTool.from_defaults(fn=get_current_time),
FunctionTool.from_defaults(fn=calculate),
# ...其他工具
]
4.2 Agent初始化
使用ReAct模式创建Agent:
python复制agent = ReActAgent.from_tools(
tools,
llm=llm,
verbose=True # 显示思考过程
)
4.3 Agent执行流程解析
当用户提问"北京今天天气怎么样?"时,Agent的执行逻辑如下:
- 思考(Thought): "用户想知道北京的天气,我需要调用get_weather工具"
- 行动(Action): 调用get_weather(city="北京")
- 观察(Observation): 获得"北京天气: 晴, 温度15°C, 湿度45%"
- 最终回答: "北京今天天气晴朗,气温15°C,湿度45%,适合出行。"
4.4 复杂任务处理示例
Agent可以处理需要多个工具协作的复杂查询:
python复制response = agent.chat("现在是什么时间?北京天气如何?")
执行过程:
- 先调用get_current_time获取时间
- 再调用get_weather获取天气
- 综合两个结果生成最终回答
5. 实用技巧与问题排查
5.1 性能优化建议
-
嵌入模型选择:
- 中文场景推荐:bge-small-zh-v1.5(平衡速度与精度)
- 英文场景推荐:all-MiniLM-L6-v2
-
分块策略调整:
python复制from llama_index.core import Settings Settings.chunk_size = 512 # 默认值 Settings.chunk_overlap = 20 # 块间重叠字符数 -
缓存配置:
python复制from llama_index.core import set_global_handler set_global_handler("simple") # 使用内存缓存
5.2 常见错误与解决方案
-
Ollama连接问题:
- 确保ollama serve正在运行
- 检查环境变量OLLAMA_HOST是否设置正确
-
嵌入模型下载失败:
bash复制# 手动下载模型 python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('BAAI/bge-small-zh-v1.5')" -
内存不足问题:
- 减小chunk_size
- 使用轻量级模型(如qwen2.5:1.8b)
- 考虑使用持久化向量数据库(如Chroma)
5.3 生产环境部署建议
-
模型服务化:
- 使用FastAPI封装LLM接口
- 启用模型并行提高吞吐量
-
索引持久化:
python复制index.storage_context.persist(persist_dir="./storage") # 加载时 from llama_index.core import StorageContext, load_index_from_storage storage_context = StorageContext.from_defaults(persist_dir="./storage") index = load_index_from_storage(storage_context) -
监控与日志:
- 记录查询历史
- 监控响应时间
- 设置速率限制
6. 扩展应用场景
6.1 知识库问答系统
结合RAG可以构建专业领域的问答系统:
- 上传产品手册、技术文档
- 建立专业术语索引
- 提供精准的领域知识问答
6.2 数据分析助手
通过Agent扩展数据分析能力:
- 连接数据库工具
- 集成可视化库
- 实现"用自然语言分析数据"的功能
6.3 自动化工作流
设计复杂的任务自动化流程:
- 邮件自动分类与回复
- 文档自动摘要
- 会议纪要生成
在实际项目中,我发现LlamaIndex的灵活性特别适合快速原型开发。例如,我们曾用两天时间就搭建了一个内部技术文档问答系统,相比从零开始开发节省了至少80%的工作量。不过需要注意的是,对于生产环境,建议对关键组件如embedding模型和向量数据库进行定制优化,以提升系统性能和准确性。