基于 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 GenerationRAG应用让模型能够基于本地文档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 将上述链路封装为VectorStoreIndexquery_engine两个核心对象。二、环境准备安装 LlamaIndex 相关依赖在动手之前先安装与 LlamaIndex 相关的软件包。官方推荐的最小安装组合如下pip install llama-index pip install llama-index-llms-huggingface pip install llama-index-readers-webllama-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 推理指南 中的环境要求transformers4.51.0、推荐torch2.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_promptTrue, tokenizeFalse)借助 ChatML 模板组织对话与本示例的自定义提示词函数在格式上保持一致可相互印证。3.2 配置 Qwen2.5 作为 LLM# Set Qwen2.5 as the language model and set generation config Settings.llm HuggingFaceLLM( model_nameQwen/Qwen2.5-7B-Instruct, tokenizer_nameQwen/Qwen2.5-7B-Instruct, context_window30000, max_new_tokens2000, generate_kwargs{temperature: 0.7, top_k: 50, top_p: 0.95}, messages_to_promptmessages_to_prompt, completion_to_promptcompletion_to_prompt, device_mapauto, )关键参数说明参数示例值作用与建议model_nameQwen/Qwen2.5-7B-Instruct模型标识可以是 Hugging Face 仓库 ID 或本地路径。仓库 examples/demo/cli_demo.py 的默认 checkpoint 也是Qwen/Qwen2.5-7B-Instructtokenizer_nameQwen/Qwen2.5-7B-Instruct分词器标识通常与模型一致context_window30000模型上下文窗口上限需小于等于模型支持的 32K若需更大窗口7B/14B/32B/72B 可到 128K须另行配置 RoPE 扩展max_new_tokens2000单次生成的最大新 token 数可按回答长度需求调整generate_kwargs{temperature: 0.7, top_k: 50, top_p: 0.95}采样参数。temperature 控制随机性top_k / top_p 控制候选集裁剪追求稳定问答时可适当调低 temperaturedevice_mapauto由 Transformers/accelerate 自动分配设备。可参考 Transformers 指南device_map与device不可同时使用CPU 推理可传devicecpu或device_mapcpu关于加载精度Transformers 指南 明确指出不传torch_dtypeauto时默认使用float32会占用双倍显存且计算更慢HuggingFaceLLM底层走 Transformers 加载实际使用中若需精度优化可在加载前配置torch_dtypeauto以自动选用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_size1024)]Settings.embed_model检索用的向量模型。英文语料用BAAI/bge-base-en-v1.5中文语料改用BAAI/bge-base-zh-v1.5。Settings.transformations文档入库前的变换流水线这里用SentenceSplitter按句子切分chunk_size1024控制文本块大小。chunk 越小检索粒度越细但上下文碎片化风险越高chunk 越大上下文越完整但可能引入噪声并挤占context_window。建议结合显存与文档特征在 5122048 之间调优并保证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_modelSettings.embed_model, transformationsSettings.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_textTrue).load_data( [web_address_1,web_address_2,...] ) index VectorStoreIndex.from_documents( documents, embed_modelSettings.embed_model, transformationsSettings.transformations )html_to_textTrue表示抓取网页时剥离 HTML 标签、仅保留正文文本避免把样式与脚本噪声向量化。将实际网址填入列表即可批量入库。4.3 保存与加载索引向量索引构建成本较高需要跑一遍 embedding生产场景应持久化复用from llama_index.core import StorageContext, load_index_from_storage # save index storage_context StorageContext.from_defaults(persist_dirsave) # load index index load_index_from_storage(storage_context)StorageContext.from_defaults(persist_dirsave)将索引及相关元数据落盘到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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考