本地知识库问答机器人实战：LlamaIndex + Qwen1.5 搭建 RAG 系统

本地知识库问答机器人这个方向，我从去年开始断断续续折腾了好几轮，从最早的纯向量检索方案，到后面加上重排序、查询改写，踩过的坑基本能写一本小册子。这次拿 LlamaIndex 配 Qwen1.5 重新搭了一套，跑下来效果比预期稳不少，推理全部落在本地，文档不出内网，响应速度也能接受。这篇就把整个搭建过程、参数取舍和实际踩坑记录整理出来，给同样想在自己机器上跑一套私有问答系统的朋友做个参考。

先说清楚这套东西是什么：它本质上是一个 RAG（检索增强生成）系统，把本地的一批文档切碎、向量化、存进索引，用户提问时先检索出最相关的片段，再连同问题一起喂给本地部署的 Qwen1.5 生成答案。能做什么？企业内部文档问答、个人笔记检索、产品手册查询这类场景都能覆盖。适合谁看？有一定 Python 基础、手里有台带独立显卡的机器、想自己掌控数据流向的开发者。如果你只是想快速体验一下 RAG 效果，这套方案也能跑，但硬件门槛得先掂量清楚。

1. 整体方案设计与选型考量

1.1 为什么是 LlamaIndex 加 Qwen1.5 这个组合

选型这件事，我一开始也纠结过。LangChain 生态更大、教程更多，但它的抽象层太厚，一个简单的检索问答要套好几层 Chain，调试的时候堆栈信息看得人头皮发麻。LlamaIndex 的定位更聚焦，它就是冲着"索引 + 检索 + 生成"这条链路设计的，核心概念清晰：Document、Node、Index、QueryEngine，一层层往下走，出问题容易定位。对于知识库问答这种单一目标场景，LlamaIndex 的路径更短，代码量也更少。

Qwen1.5 这边，选它的理由很实际。第一是中文能力强，本地知识库大概率是中文文档，用英文为主的模型做中文问答，效果会打折扣。第二是尺寸档位全，0.5B 到 72B 都有，我手头是一张 24G 显存的卡，跑 7B 的量化版本绰绰有余，14B 的 4bit 量化也能塞进去。第三是社区支持好，Hugging Face 上直接能拉到，配合 transformers 或 llama.cpp 都能跑，部署路径成熟。

提示：模型尺寸不是越大越好。7B 在知识库问答场景下，只要检索质量过关，生成质量通常够用；盲目上大模型反而拖慢响应，交互体验变差。

1.2 检索链路的分层设计思路

整套系统的核心链路我拆成四层：文档解析层、索引构建层、检索召回层、生成回答层。这么拆不是为了好看，是为了每一层都能单独调、单独测。

文档解析层负责把 PDF、Word、Markdown 这些异构格式统一成纯文本，这里最容易出问题的是 PDF 的表格和分栏排版，解析出来经常是乱的。索引构建层做切块和向量化，切块大小直接决定检索粒度，这个参数后面细说。检索召回层是效果的关键，我用了向量检索加关键词检索的混合策略，再叠一层重排序。生成回答层就是把检索结果拼进 prompt，交给 Qwen1.5 输出。

为什么要在检索层做混合？纯向量检索对语义相近的表达很友好，但对专有名词、编号、型号这类精确匹配的东西不敏感。比如你问"XX-2000 型号的参数"，向量检索可能召回一堆语义相关但型号不对的段落。加上关键词检索（BM25 那类）做互补，召回率能明显提升。这个设计是我踩过坑之后加的，后面问题排查那节会具体讲。

1.3 本地部署的硬件与依赖盘点

硬件这块给个实测参考：7B 模型 4bit 量化，显存占用大概 5 到 6G，加上嵌入模型和重排序模型，总共 8G 左右能跑起来。嵌入模型我用的是 bge-small-zh，几百兆的体量，CPU 也能跑但慢，建议放 GPU。重排序模型 bge-reranker-base 也是几百兆级别。如果你的文档量在几千页以内，16G 内存加 8G 显存的机器足够。

依赖方面，核心就几个：llama-index 主包、llama-index-llms-huggingface、llama-index-embeddings-huggingface、transformers、torch、sentence-transformers。版本上我建议锁一下，LlamaIndex 迭代很快，不同版本 API 有 breaking change，我用的 0.10.x 系列，接口相对稳定。torch 记得装对应 CUDA 版本的，不然 GPU 用不上，白瞎硬件。

2. 核心环节拆解与关键参数

2.1 文档切块：Chunk Size 到底怎么定

切块是 RAG 里最容易被低估的环节。切太大，一个块里混了好几个主题，检索出来噪声多，模型容易被无关内容带偏；切太小，上下文不完整，模型拿到的信息碎片化，答非所问。我的经验值是中文文档 512 到 768 个 token 之间，overlap 设 50 到 100 个 token。

为什么留 overlap？因为切块是按固定长度硬切的，一个完整的句子或段落很可能被切在边界上，overlap 能让边界附近的内容在两个块里都出现，避免信息断裂。这个道理跟剪视频留重叠帧一样，防止关键画面被切掉。

具体到 LlamaIndex 的配置，用 SentenceSplitter，参数这样设：

from llama_index.core.node_parser import SentenceSplitter splitter = SentenceSplitter( chunk_size=600, chunk_overlap=80, paragraph_separator="\n\n", secondary_chunking_regex="[^,.;。？！]+[,.;。？！]?" )

secondary_chunking_regex这个参数值得说一下，它让切块尽量在标点处断开，而不是硬切在句子中间。中文的句号、问号、感叹号都覆盖进去，切出来的块读起来更完整。实测下来，加了这层标点感知，检索命中率能提升几个百分点，尤其是问答类文档。

注意：不同文档类型要区别对待。技术手册这种条目化的内容，切块可以小一点，400 左右就够；叙述性的长文档，600 到 800 更合适。一刀切的参数在混合文档库里效果会打折。

2.2 嵌入模型的选择与向量维度权衡

嵌入模型决定了"语义相似"这件事算得准不准。中文场景我优先推荐 bge 系列，bge-small-zh-v1.5 是性价比之选，512 维向量，速度快，效果在中小规模知识库上够用。如果追求更高精度，bge-large-zh 是 1024 维，检索质量更好但索引构建慢、存储占用大。

维度这个事要算笔账：假设你有 1 万个文档块，512 维用 float32 存储，大概是 10000 × 512 × 4 字节，约 20MB；1024 维就是 40MB。单看不大，但向量检索时的距离计算量是跟维度成正比的，维度翻倍，检索延迟也差不多翻倍。所以不是维度越高越好，得在精度和速度之间找平衡。

LlamaIndex 里接 HuggingFace 嵌入模型：

from llama_index.embeddings.huggingface import HuggingFaceEmbedding embed_model = HuggingFaceEmbedding( model_name="BAAI/bge-small-zh-v1.5", max_length=512, embed_batch_size=32 )

embed_batch_size这个参数跟显存挂钩，32 是个稳妥值，显存富裕可以往上调，能加快索引构建速度。max_length要和切块大小匹配，切块 600 token 但嵌入模型只吃 512，超出的部分会被截断，等于白切。这个细节很多人忽略，导致长块的信息实际没进向量。

2.3 混合检索与重排序的叠加策略

前面提了混合检索的必要性，这里说具体实现。LlamaIndex 支持 VectorIndexRetriever 和 BM25Retriever 组合，用 QueryFusionRetriever 做融合。融合策略有两种：相对分数融合和倒数排名融合，我用的是后者，它对不同检索器的分数尺度不敏感，更稳。

from llama_index.core.retrievers import VectorIndexRetriever, BM25Retriever from llama_index.core.retrievers import QueryFusionRetriever from llama_index.core.retrievers import RecursiveRetriever vector_retriever = VectorIndexRetriever(index=vector_index, similarity_top_k=10) bm25_retriever = BM25Retriever.from_defaults(index=vector_index, similarity_top_k=10) fusion_retriever = QueryFusionRetriever( [vector_retriever, bm25_retriever], similarity_top_k=8, num_queries=1, mode="reciprocal_rerank" )

similarity_top_k这里设 10 是召回阶段，融合后取 8 个进重排序。为什么召回要多、进重排要少？召回阶段宁可多捞一些，把可能相关的都拿进来，重排序阶段再用更精细的模型筛。重排序模型 bge-reranker-base 是交叉编码器，它把问题和每个候选块拼在一起算相关性分数，比向量点积准得多，但计算量大，所以只对少量候选做。

重排序的接入：

from llama_index.postprocessor.flag_embedding_reranker import FlagEmbeddingReranker reranker = FlagEmbeddingReranker( model="BAAI/bge-reranker-base", top_n=4 )

top_n=4意味着最终只把 4 个最相关的块喂给生成模型。这个数字不是拍脑袋定的，块太多会稀释关键信息，还可能超出模型上下文窗口；块太少又可能漏掉答案。4 到 5 个是我实测下来比较均衡的值。

2.4 Qwen1.5 的加载与推理参数调优

模型加载用 transformers 直接拉，7B 的 Chat 版本 4bit 量化：

from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig import torch bnb_config = BitsAndBytesConfig( load_in_4bit=True, bnb_4bit_compute_dtype=torch.float16, bnb_4bit_quant_type="nf4", bnb_4bit_use_double_quant=True ) tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen1.5-7B-Chat") model = AutoModelForCausalLM.from_pretrained( "Qwen/Qwen1.5-7B-Chat", quantization_config=bnb_config, device_map="auto", trust_remote_code=True )

nf4量化类型配合双重量化，能在几乎不掉效果的前提下把显存压下来。device_map="auto"让 transformers 自己分配层到 GPU，单卡场景够用。

推理参数上，知识库问答场景我建议 temperature 设 0.1 到 0.3，低温度让输出更确定、更贴事实，减少胡编。top_p 设 0.8，max_new_tokens 设 512 到 768，够回答大多数问题又不至于生成冗长废话。repetition_penalty 设 1.05 到 1.1，防止模型陷入重复循环。

提示：知识库问答最怕模型"自由发挥"。prompt 里一定要明确约束"仅根据提供的上下文回答，上下文没有的信息就说不知道"，这比调温度更管用。

3. 完整搭建流程与实操记录

3.1 环境准备与依赖安装

先建虚拟环境，Python 3.10 是我验证过最稳的版本，3.11 也能跑但个别包有兼容问题。依赖安装顺序有讲究，torch 要先装，且要装 CUDA 版本，后面装 transformers 和 sentence-transformers 时它们会检测已有的 torch，不会重复拉 CPU 版。

conda create -n rag-qa python=3.10 -y conda activate rag-qa pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121 pip install llama-index llama-index-llms-huggingface \ llama-index-embeddings-huggingface \ llama-index-postprocessor-flag-embedding-reranker \ transformers accelerate bitsandbytes sentence-transformers \ pypdf docx2txt

accelerate和bitsandbytes是量化加载的依赖，别漏。pypdf和docx2txt是文档解析用的，按你实际文档格式增减。装完跑一句torch.cuda.is_available()确认 GPU 能用，返回 False 就说明 CUDA 版本对不上，得重装。

3.2 文档加载与预处理

文档加载用 SimpleDirectoryReader，它能自动识别目录下的多种格式：

from llama_index.core import SimpleDirectoryReader documents = SimpleDirectoryReader( input_dir="./knowledge_base", required_exts=[".pdf", ".docx", ".md", ".txt"], recursive=True ).load_data()

recursive=True会递归子目录，适合文档按主题分文件夹存放的情况。加载完建议先打印几段看看解析质量，PDF 尤其要检查，扫描版 PDF 解析出来可能是空的，那种得先做 OCR，这套流程不覆盖。

预处理这一步我加了个小动作：清洗掉多余的空行和页眉页脚。很多 PDF 每页都有重复的页眉，不清掉会污染检索结果，模型可能把页眉当成正文内容。简单用正则处理一下：

import re def clean_text(text): text = re.sub(r'\n{3,}', '\n\n', text) text = re.sub(r'^\s*第\s*\d+\s*页.*$', '', text, flags=re.MULTILINE) return text.strip() for doc in documents: doc.text = clean_text(doc.text)

这个清洗逻辑是按常见页眉格式写的，你实际文档的页眉样式不同就改正则。别小看这一步，我第一版没做清洗，检索出来的结果里混着页眉，回答质量明显受影响。

3.3 索引构建与持久化

索引构建是把文档块向量化并建索引的过程，用 VectorStoreIndex：

from llama_index.core import VectorStoreIndex, Settings, StorageContext from llama_index.core import load_index_from_storage Settings.embed_model = embed_model Settings.node_parser = splitter Settings.llm = None # 构建阶段不需要 LLM index = VectorStoreIndex.from_documents(documents, show_progress=True) index.storage_context.persist(persist_dir="./index_storage")

Settings.llm = None这行是个小技巧，构建索引时用不到生成模型，设成 None 能避免它去加载模型，省显存也省时间。构建完持久化到磁盘，下次启动直接加载，不用重新算向量：

storage_context = StorageContext.from_defaults(persist_dir="./index_storage") index = load_index_from_storage(storage_context)

持久化目录里会生成几个 json 和向量文件，文档量大的话这个目录可能几百兆，正常。索引构建时间跟文档量和硬件相关，我这边 2000 页左右的文档，7B 卡上大概跑了十几分钟，主要耗在向量化上。

3.4 查询引擎组装与 Prompt 设计

把检索器、重排序器、生成模型串起来，组成查询引擎：

from llama_index.core.query_engine import RetrieverQueryEngine from llama_index.core import PromptTemplate qa_prompt = PromptTemplate( "你是一个严谨的知识库问答助手。请仅根据下面提供的上下文回答问题。\n" "如果上下文中没有相关信息，直接回答\"根据现有资料无法回答该问题\"，不要编造。\n" "回答时尽量引用上下文中的原文表述。\n\n" "上下文：\n{context_str}\n\n" "问题：{query_str}\n" "回答：" ) query_engine = RetrieverQueryEngine.from_args( retriever=fusion_retriever, node_postprocessors=[reranker], text_qa_template=qa_prompt, llm=llm )

prompt 里那几句约束是效果的关键。"仅根据上下文"防止模型用预训练知识瞎答，"无法回答就说不知道"降低幻觉率，"引用原文"让答案更可追溯。这三条我反复调过措辞，现在的版本在测试集上幻觉率明显低于不加约束的版本。

查询调用很简单：

response = query_engine.query("你们产品的保修期是多久？") print(response)

返回的 response 对象里还带 source_nodes，能看到检索到了哪些块，调试时很有用。

3.5 流式输出与交互体验优化

生成模型出字慢，一次性等完整答案体验差，改成流式输出：

response = query_engine.query("保修政策是什么？") response.print_response_stream()

流式输出让用户看到字一个个蹦出来，感知延迟大幅降低。如果要做成 Web 服务，把流式接口接到前端 SSE 上就行，LlamaIndex 的 response 对象支持迭代取 token。

另外我加了个简单的多轮对话支持，用 CondenseQuestionChatEngine，它会把历史对话压缩成一个独立问题再检索，避免指代消解问题。比如用户先问"保修期多久"，再问"那延保呢"，第二个问题单独看没有主语，压缩后会变成"延保的保修期是多久"，检索才准。

4. 常见问题排查与避坑实录

4.1 检索不准的典型原因与排查路径

检索不准是最高频的问题，表现是答非所问或者答"无法回答"。排查我按这个顺序走：先看 source_nodes 里召回了什么，如果召回的内容本身就不相关，问题在检索层；如果召回相关但答案没生成对，问题在生成层。

检索层的问题又分几种。切块太大导致噪声多，就调小 chunk_size；嵌入模型对领域词汇不敏感，考虑换更大模型或做微调；专有名词匹配不上，检查 BM25 检索器有没有正常工作。我遇到过一次 BM25 没生效，原因是中文分词没配好，BM25 默认按空格分词，中文整句被当成一个词，等于没检索。解决办法是给 BM25 配个中文分词器，或者用 jieba 预处理。

生成层的问题多半是 prompt 没约束好，或者 top_n 太大把无关内容喂进去了。把 top_n 从 6 降到 4，答案聚焦度会明显提升。

4.2 显存溢出与推理速度优化

显存溢出常见于三个环节：模型加载、索引构建、并发查询。模型加载溢出就降量化位数或者换小模型；索引构建溢出就把 embed_batch_size 调小；并发查询溢出就得做请求队列，别让多个查询同时占显存。

推理速度优化我试过几个手段。一是开 flash attention，transformers 里加attn_implementation="flash_attention_2"，速度有提升但要求显卡架构支持。二是用 vLLM 替代 transformers 做推理后端，吞吐量提升明显，但部署复杂度高一些，单用户场景收益不大。三是把 max_new_tokens 压到实际需要的最小值，很多回答 300 token 就够，设 768 是浪费。

下面这张表是我实测的几个配置对比，供参考：

4.3 模型幻觉的抑制手段

幻觉就是模型编造上下文里没有的信息，这在知识库问答里是致命的。抑制手段我总结了四条，按有效性排序：prompt 约束最直接，明确说"不知道就说不知道"；降低 temperature 减少随机性；提高检索质量，让上下文里真有答案；加后处理校验，对生成的答案做一次事实性检查。

第四条实现起来麻烦，我目前用的是轻量版：让模型在回答末尾标注引用的上下文片段编号，人工抽检时能快速定位答案来源。如果答案引用的片段跟内容对不上，基本就是幻觉。

注意：不要指望完全消除幻觉。7B 级别的模型在复杂问题上仍会出错，关键场景建议保留人工复核环节，或者把答案置信度低的情况标记出来。

4.4 中文文档解析的坑

PDF 解析的坑最多。分栏排版的 PDF，解析出来文字顺序是乱的，左右栏内容交错在一起。表格解析出来是一堆错位的文本。扫描版 PDF 直接是空白。这几种情况我的处理方式是：分栏文档用 pdfplumber 按坐标重排，表格用 camelot 单独抽，扫描版走 OCR 流程。这些都不在 LlamaIndex 默认能力里，得自己补。

Word 文档相对好处理，docx2txt 基本够用，但要注意图片里的文字抽不出来，如果文档关键信息在图里，得单独处理。Markdown 最省心，本身就是结构化文本，解析几乎无损。

还有一个隐蔽的坑：编码问题。有些老文档是 GBK 编码，直接读会乱码，加载时指定 encoding 或者先转码。这个坑我踩过一次，索引建完了发现全是乱码，白跑一遍。

4.5 常见问题速查表

这套系统我前后调了大概两周，最大的体会是：RAG 的效果上限由检索质量决定，生成模型只是把检索到的信息组织成通顺的话。很多人一上来就换更大的模型，其实先把切块、嵌入、重排序这三步调好，7B 模型也能给出很靠谱的答案。另外索引一定要持久化，每次重建既费时又费显存，调参阶段尤其明显。最后分享一个小技巧：建一个几十条的测试问答对，每次改参数都跑一遍，用命中率量化效果，比凭感觉调靠谱得多。