基于 Qwen2.5 与 LlamaIndex 构建本地 RAG：文档问答全流程实战指南

基于 Qwen2.5 与 LlamaIndex 构建本地 RAG：文档问答全流程实战指南

【免费下载链接】Qwen1.5Qwen3 is the large language model series developed by Qwen team, Alibaba Cloud.项目地址: https://gitcode.com/GitHub_Trending/qw/Qwen1.5

本篇技术指南以 Qwen 官方仓库的 LlamaIndex 教程 为核心骨架，讲解如何使用Qwen2.5-7B-Instruct与 LlamaIndex 搭建检索增强生成（Retrieval-Augmented Generation，RAG）应用，让模型能够基于本地文档（PDF/TXT）和网页内容回答问题。读完本文，你将掌握从环境安装、LLM 与向量模型参数配置、索引构建与持久化，到最终执行查询的完整闭环，并理解其底层调用链与可调参数。

一、为什么用 LlamaIndex 做 RAG：把外部知识接入 Qwen2.5

大语言模型的知识受限于训练数据，无法覆盖私有文档、最新网页等内容。RAG 的思路是：先把外部文档切块并向量化，构建索引；查询时将用户问题向量化，检索最相关的文本块，作为上下文拼入提示词交给模型生成答案，从而在不重新训练的前提下扩展模型的知识边界。

LlamaIndex（原 GPT Index）是专为 RAG 设计的开源数据框架，提供统一的数据加载器（Readers）、文本切分器（Node Parser）、向量索引（VectorStoreIndex）与查询引擎（Query Engine）抽象。官方仓库在 docs/source/index.rst 的 Framework 章节中将 LlamaIndex 与 LangChain、Qwen-Agent、Function Calling 并列，作为"使用框架构建 RAG、Agent 等应用"的推荐路线之一，本指南即对应其中 framework/LlamaIndex 这一页的展开讲解。

值得一提的是，仓库还提供了同主题的 LangChain 版本地知识库问答方案，其处理链路为"加载文件 → 读取文本 → 切分文本 → 向量化 → 问题向量化 → 匹配 top-k → 拼入提示词 → 模型生成"。本文的 LlamaIndex 方案与之相比，代码更为精简：LlamaIndex 将上述链路封装为VectorStoreIndex+query_engine两个核心对象。

二、环境准备：安装 LlamaIndex 相关依赖

在动手之前，先安装与 LlamaIndex 相关的软件包。官方推荐的最小安装组合如下：

pip install llama-index pip install llama-index-llms-huggingface pip install llama-index-readers-web

• llama-index：核心包，包含索引、查询引擎、文档加载、文本切分等基础设施（llama_index.core）。
• llama-index-llms-huggingface：让 LlamaIndex 通过 Hugging Face Transformers 加载本地/开源 LLM（即文中的HuggingFaceLLM），这也是接入 Qwen2.5 的关键桥接包。
• llama-index-readers-web：提供网页读取器（SimpleWebPageReader），用于对网页内容构建索引。

如果后续要用到本地文档解析（如 PDF），通常还需pypdf等解析库，可按需补充安装。由于HuggingFaceLLM底层依赖 Transformers 加载模型，建议参照 Transformers 推理指南 中的环境要求：transformers>=4.51.0、推荐torch>=2.6且最好有 GPU 可用。

三、设置参数：LLM、Embedding 模型与文本切分

安装完成后，即可配置语言模型、向量模型及相关参数。官方给出的配置逻辑如下：

• 多语言对话：Qwen2.5-Instruct支持包括英文和中文在内的多语言对话。
• 向量模型按文档语言选择：英文文档推荐BAAI/bge-base-en-v1.5，中文文档则下载BAAI/bge-base-zh-v1.5；计算资源允许时也可改用bge-large或bge-small。
• 上下文窗口：Qwen2.5 模型系列原生支持最大 32K 上下文窗口；7B、14B、32B、72B 可扩展至 128K，但需要额外配置（如 RoPE 扩展）。
• 文本块大小：根据计算资源调整检索所用的文本块（chunk）大小。

3.1 编写 ChatML 格式的提示词模板（可选但推荐）

Qwen 系列模型使用 ChatML 格式（<|im_start|>/<|im_end|>特殊标记）组织对话。官方示例提供了两个辅助函数，用于把 LlamaIndex 的 messages / completion 转换为 Qwen2.5 认识的提示词格式：

import torch from llama_index.core import Settings from llama_index.core.node_parser import SentenceSplitter from llama_index.llms.huggingface import HuggingFaceLLM from llama_index.embeddings.huggingface import HuggingFaceEmbedding # Set prompt template for generation (optional) from llama_index.core import PromptTemplate def completion_to_prompt(completion): return f"<|im_start|>system\n<|im_end|>\n<|im_start|>user\n{completion}<|im_end|>\n<|im_start|>assistant\n" def messages_to_prompt(messages): prompt = "" for message in messages: if message.role == "system": prompt += f"<|im_start|>system\n{message.content}<|im_end|>\n" elif message.role == "user": prompt += f"<|im_start|>user\n{message.content}<|im_end|>\n" elif message.role == "assistant": prompt += f"<|im_start|>assistant\n{message.content}<|im_end|>\n" if not prompt.startswith("<|im_start|>system"): prompt = "<|im_start|>system\nYou are Qwen, created by Alibaba Cloud. You are a helpful assistant.<|im_end|>\n" + prompt prompt = prompt + "<|im_start|>assistant\n" return prompt

这两个函数的作用：

• messages_to_prompt：将 LlamaIndex 内部的ChatMessage列表序列化为 ChatML 文本；若消息中缺少 system 消息，会自动补上官方 system 提示（"You are Qwen, created by Alibaba Cloud. You are a helpful assistant."），最后以<|im_start|>assistant\n收尾引导生成。
• completion_to_prompt：处理纯文本补全场景，直接包一层空 system 与 user/assistant 框架。

仓库中 examples/demo/cli_demo.py 的_chat_stream函数同样通过tokenizer.apply_chat_template(conversation, add_generation_prompt=True, tokenize=False)借助 ChatML 模板组织对话，与本示例的自定义提示词函数在格式上保持一致，可相互印证。

3.2 配置 Qwen2.5 作为 LLM

# Set Qwen2.5 as the language model and set generation config Settings.llm = HuggingFaceLLM( model_name="Qwen/Qwen2.5-7B-Instruct", tokenizer_name="Qwen/Qwen2.5-7B-Instruct", context_window=30000, max_new_tokens=2000, generate_kwargs={"temperature": 0.7, "top_k": 50, "top_p": 0.95}, messages_to_prompt=messages_to_prompt, completion_to_prompt=completion_to_prompt, device_map="auto", )

关键参数说明：

关于加载精度，Transformers 指南 明确指出不传torch_dtype="auto"时默认使用float32，会占用双倍显存且计算更慢；HuggingFaceLLM底层走 Transformers 加载，实际使用中若需精度优化，可在加载前配置torch_dtype="auto"以自动选用bfloat16。

3.3 配置 Embedding 模型与文本切分

# Set embedding model Settings.embed_model = HuggingFaceEmbedding( model_name = "BAAI/bge-base-en-v1.5" ) # Set the size of the text chunk for retrieval Settings.transformations = [SentenceSplitter(chunk_size=1024)]

• Settings.embed_model：检索用的向量模型。英文语料用BAAI/bge-base-en-v1.5，中文语料改用BAAI/bge-base-zh-v1.5。
• Settings.transformations：文档入库前的变换流水线，这里用SentenceSplitter按句子切分，chunk_size=1024控制文本块大小。chunk 越小检索粒度越细但上下文碎片化风险越高；chunk 越大上下文越完整但可能引入噪声并挤占context_window。建议结合显存与文档特征在 512～2048 之间调优，并保证"chunk 内容 + 提示词模板 + 历史对话"不超出context_window。

Settings是 LlamaIndex 的全局配置入口，后续构建索引与查询引擎时会自动读取这里设置的llm、embed_model与transformations，这也是代码中VectorStoreIndex.from_documents显式透传这两项配置之外仍能保持一致的底层机制。

四、构建索引：本地文件与网页

4.1 从本地文件夹构建索引

以下代码为本地名为document的文件夹中的文件（无论 PDF 还是 TXT 格式）构建索引：

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader documents = SimpleDirectoryReader("./document").load_data() index = VectorStoreIndex.from_documents( documents, embed_model=Settings.embed_model, transformations=Settings.transformations )

• SimpleDirectoryReader("./document")：递归读取目录下的文本类文件（含 PDF、TXT 等），返回文档列表。
• VectorStoreIndex.from_documents(documents, embed_model=..., transformations=...)：对文档执行切分 → 向量化 → 建索引三步，产出可用于检索的向量索引。

4.2 从网页列表构建索引

若知识来源是一批网页，改用SimpleWebPageReader（来自前面安装的llama-index-readers-web包）：

from llama_index.readers.web import SimpleWebPageReader from llama_index.core import VectorStoreIndex, SimpleDirectoryReader documents = SimpleWebPageReader(html_to_text=True).load_data( ["web_address_1","web_address_2",...] ) index = VectorStoreIndex.from_documents( documents, embed_model=Settings.embed_model, transformations=Settings.transformations )

html_to_text=True表示抓取网页时剥离 HTML 标签、仅保留正文文本，避免把样式与脚本噪声向量化。将实际网址填入列表即可批量入库。

4.3 保存与加载索引

向量索引构建成本较高（需要跑一遍 embedding），生产场景应持久化复用：

from llama_index.core import StorageContext, load_index_from_storage # save index storage_context = StorageContext.from_defaults(persist_dir="save") # load index index = load_index_from_storage(storage_context)

StorageContext.from_defaults(persist_dir="save")将索引及相关元数据落盘到save目录；load_index_from_storage(storage_context)从同一目录恢复索引，之后即可直接查询，无需重新加载文档与重算向量。

五、执行 RAG 查询

索引就绪后，将其包装为查询引擎即可进行问答：

query_engine = index.as_query_engine() your_query = "<your query here>" print(query_engine.query(your_query).response)

• index.as_query_engine()：在索引之上封装检索 + 生成能力。查询时内部会：对问题向量化 → 在索引中检索最相关文本块 → 结合 ChatML 模板拼入上下文 → 交由 Qwen2.5 生成答案。
• query_engine.query(your_query)：返回响应对象，.response为最终答案文本。Qwen2.5 会基于检索到的文档内容作答，而不是凭空生成，这正是 RAG 的价值所在。

六、进阶与联动：从单机脚本到生产部署

• 切换知识库语言：英文语料保持bge-base-en-v1.5；中文语料把HuggingFaceEmbedding的model_name换成BAAI/bge-base-zh-v1.5，无需改动其余代码。
• 扩大上下文窗口：Qwen2.5 的 7B/14B/32B/72B 在原生 32K 基础上可扩展至 128K（需额外配置，如 RoPE 扩展），配合更大的chunk_size可支撑超长文档的检索问答；具体开启方式参见 Transformers 长上下文章节。
• 对比 LangChain 方案：若偏好链式组装（自定义RetrievalQA、FAISS 向量库、自研切分器），仓库提供了完整的 LangChain 版实现，其模板约束"无法从已知信息得出答案时不要编造"的思路同样适用于 LlamaIndex 场景，可作为提示词工程参考。
• 服务化部署：本地 RAG 单机脚本验证通过后，可选用 vLLM / SGLang 将 Qwen2.5 以 OpenAI 兼容 API 形式对外服务，再配合 LlamaIndex 的OpenAI类 LLM 接入，实现检索与推理分离的部署形态；相关启动命令见 vLLM 部署 与 SGLang 部署。
• 升级到 Qwen3 的注意点：官方在 docs/source/framework/LlamaIndex.rst 顶部已标注"待为 Qwen3 更新"，意味着本文示例的messages_to_prompt/completion_to_prompt是针对 Qwen2.5 ChatML 模板的；Qwen3 的默认模板带思考模式（<think>标签、enable_thinking开关），迁移时需替换提示词组装逻辑，具体差异见 Qwen3 Quickstart。

结语

至此，一条完整的 RAG 链路已经跑通：pip 安装依赖 → Settings 配置 LLM/Embedding/切分 → SimpleDirectoryReader/SimpleWebPageReader 加载语料 → VectorStoreIndex 建索引（可持久化）→ as_query_engine 问答。官方在 LlamaIndex 教程 的结尾提示：现在就可以用自己的文档与 Qwen2.5 对话，并继续阅读官方文档探索模型检索的更多高级用法。

【免费下载链接】Qwen1.5Qwen3 is the large language model series developed by Qwen team, Alibaba Cloud.项目地址: https://gitcode.com/GitHub_Trending/qw/Qwen1.5