为什么选择 LlamaIndex 跑本地模型
LlamaIndex 是目前广泛使用的 AI 知识库框架，核心功能是将本地文档、网页文本、数据库内容等资料高效整理成可检索的索引，再交由大模型生成回答。相比于直接向聊天工具上传文件，本地部署的最大优势是数据始终保留在自有设备或内网环境中，非常适合企业资料管理、项目文档整理、研发笔记归档、客服知识库构建等场景。需要明确的是，LlamaIndex 本身并非一个大模型，而是负责“读取资料、拆分文本、建立索引、召回内容、组织提示词、调用模型”的全流程框架。
本地模型运行通常涉及两类模型：一类是负责理解和生成回答的语言模型，例如 Llama、Qwen、Mistral 等；另一类是负责将文本转换为向量的嵌入模型，例如 bge、gte、e5 系列。前者决定了回答的质量和响应速度，后者直接影响检索的准确率。如果只配置生成模型而忽略嵌入模型，知识库的检索效果往往不稳定，容易出现答非所问的情况。
准备环境与安装依赖
建议使用 Python 3.10 或 3.11，并单独创建虚拟环境，以避免与其他项目的依赖冲突。Windows 用户推荐使用 Conda 或 venv，macOS 与 Linux 用户同样建议隔离环境。基础安装命令可按需执行：pip install llama-index。如果需要接入本地推理服务，可继续安装 llama-index-llms-ollama、llama-index-embeddings-huggingface、llama-index-vector-stores-chroma 等扩展包，以便灵活对接不同推理后端。
硬件方面，轻量级知识库在 16GB 内存的设备上即可运行，但生成速度主要取决于模型大小。7B 级模型使用 4bit 量化后对资源更加友好；如果显存有限，可优先选择 1.5B、3B 或 4B 参数量的模型。嵌入模型通常占用资源较少，但在批量处理大量文档时仍会消耗内存。初次搭建时建议不要直接使用超大模型，先让整体流程跑通，再逐步替换为更强大的模型。
模型下载与目录规划
模型来源应选择官方仓库、开发者主页或可信的镜像站，下载前务必确认授权条款、模型格式以及适配框架。常见格式包括 Hugging Face Transformers 格式、GGUF 格式以及部分推理框架专用格式。Transformers 格式便于与 Python 生态结合，GGUF 则更常用于 llama.cpp、Ollama 等本地推理方案。
建议统一规划目录结构，例如 /data/ai/models/llm 存放生成模型，/data/ai/models/embedding 存放嵌入模型，/data/ai/index 存放索引文件，/data/ai/docs 存放原始资料。Windows 用户可以使用 D:\AI\models\llm 这类路径。路径中尽量不要包含中文、空格和特殊符号，以免部分库读取失败。下载完成后，检查 config、tokenizer、权重文件是否齐全；若为 GGUF 文件，则需确认文件名中的量化等级，例如 Q4_K_M、Q5_K_M、Q8_0。
使用 Git LFS 下载大模型时，需要先安装 Git LFS，并确保磁盘空间充足。模型文件动辄数 GB 到数十 GB，下载中断可能产生不完整文件。如果遇到加载报错，应优先核对文件大小、校验值、模型格式以及本地推理框架版本，而不是盲目重装全部环境。
配置 LlamaIndex 调用本地模型
最稳妥的方式是先用本地推理服务承载语言模型，再让 LlamaIndex 通过接口调用。例如使用 Ollama 时，先在本机拉取并启动模型，然后在 Python 中配置对应的 LLM 对象。嵌入模型则可以直接通过本地路径加载，例如将 bge-small-zh、bge-m3 或 gte 系列放入固定目录，再在 LlamaIndex 中指定 model_name 为本地路径。
典型流程如下：第一步，设置嵌入模型；第二步，设置语言模型；第三步，读取 docs 目录中的文档；第四步，使用 VectorStoreIndex 建立索引；第五步，保存索引到 index 目录；第六步，创建 query_engine 进行问答。首次构建索引会相对较慢，后续只要资料没有变化，就可以直接加载已有索引，避免重复切分和向量化操作。
路径设置是新手最容易出错的地方。相对路径会受到启动目录的影响，生产环境建议使用绝对路径。如果项目需要迁移，可以把路径写入 .env 或配置文件中，例如 MODEL_DIR、EMBEDDING_DIR、INDEX_DIR、DOCS_DIR。这样更换机器时只需调整配置文件，无需改动核心代码。
文档切分与索引参数
知识库的效果不仅取决于模型，还取决于文本处理方式。LlamaIndex 会把长文档切分成多个片段，常见参数包括 chunk_size 和 chunk_overlap。中文资料可从 512 到 1024 token 的片段长度开始尝试，重叠部分设为 50 到 150 token。片段过短会丢失上下文，片段过长则会降低召回精度并增加推理成本。
如果资料是 PDF、Word、Markdown、网页导出文本，建议先进行清洗：删除页眉页脚、目录噪声、重复版权声明、无意义的表格残片。对于产品手册、接口说明、FAQ，可以按标题层级切分；对于会议纪要、规章制度、长篇报告，建议保留章节标题，让检索结果更容易定位到具体来源。
向量库可先使用内存或本地文件方式，数据量增大后再切换到 Chroma、Qdrant、Milvus 等专业方案。个人项目几千篇文档以内，轻量级本地向量库通常够用；团队级知识库则需要考虑并发访问、增量更新、备份和权限隔离等需求。
性能优化思路
性能优化首先要分清瓶颈所在。如果提问后很久才开始输出，可能是检索、重排或模型加载速度慢；如果开始输出后速度很慢，主要是生成模型的推理速度问题；如果构建索引慢，多半是嵌入模型的批处理能力和磁盘读写压力较大。
生成模型方面，小显存设备应优先选择量化模型，Q4 通常在速度和效果之间比较均衡，Q8 效果更好但显存占用更高。上下文长度不要一味拉满，知识库问答常用 4K 到 8K 已能覆盖多数场景。检索参数 top_k 也不宜过大，通常从 3 到 6 开始调试；召回片段太多会让提示词膨胀，反而使回答变慢、重点分散。
嵌入阶段可开启批量处理，但批量大小需根据内存调整。文档量很大时，建议按目录或时间分批建立索引，并记录已处理文件的哈希值，只对新增或修改的文档做增量更新。对于高频问题，可加入缓存机制，将相同或相似问题的结果缓存一段时间，减少重复推理的开销。
常见问题与排查
问题一：模型路径正确但加载失败。通常是格式不匹配，例如将 GGUF 文件交给 Transformers 加载，或缺少 tokenizer 文件。解决方法是确认当前加载器支持的格式，并检查模型目录结构是否完整。
问题二：回答内容与资料不一致。先检查嵌入模型是否适合中文场景，再查看切分结果是否把标题和正文过度分离。还可以开启引用来源输出功能，让每个回答显示召回的片段，便于判断是检索错误还是生成阶段发挥过度。
问题三：速度非常慢。先降低模型规模或量化等级，再减少 top_k、缩短上下文、关闭不必要的重排步骤。如果每次启动都重新加载模型，可以改为常驻本地推理服务，LlamaIndex 只负责请求调用。
问题四：索引更新后旧内容仍然出现。需要确认是否加载了旧的持久化目录，或者新增文档没有重新向量化。建议为索引建立版本号，更新前做好备份，更新后进行抽样测试验证。
安全边界与实用建议
本地知识库并不意味着绝对安全。资料导入前要确认来源合法，内部文档应按照权限分级存放，不要将所有资料混入同一个索引。涉及合同、客户信息、研发资料时，建议部署在受控网络环境中，并记录访问日志。模型生成结果也需要人工复核，尤其是用于制度解释、技术决策和对外回复时。
不要把系统提示词、密钥、内部接口地址直接写进公开仓库。配置文件应单独管理，必要时使用环境变量。如果需要多人共用，建议将文档上传、索引构建、问答访问拆分为不同角色，避免误删索引或导入不合规资料。
实际落地可以按照“小模型验证流程、中等模型提升效果、专用向量库支撑规模化”的路线推进。先用少量高质量文档测试检索准确率，再逐步扩大资料范围；先固定一套基准问题，再比较不同模型和参数的效果。这样搭建出的 LlamaIndex 本地方案更加可控，也更易于持续维护。
