LocalGPT 本地部署后怎么用：模型加载与文档问答
LocalGPT 是一个在本地运行大语言模型并基于自己文档进行问答的开源项目。
它不像 Open WebUI 那样开箱即用，需要手动准备 Python 环境、模型文件和向量库。
本文假设你已经把 LocalGPT 代码拉取到本地，重点讲清楚模型放哪里、文档怎么导入、启动命令怎么跑，以及跑不起来时先查什么。
先确认运行环境与模型文件
LocalGPT 对 Python 版本和显存有一定要求。
建议在 Linux 或 WSL2 下操作，Python 使用 3.10 或 3.11，避免 3.12 的兼容问题。
先检查基础环境：
python3 --version
nvidia-smi如果 nvidia-smi 能正常输出显卡信息，说明驱动可用。
接着创建虚拟环境并安装依赖：
cd LocalGPT
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt模型文件是新手最容易卡住的地方。
LocalGPT 默认从 models/ 目录加载本地模型，你需要把下载好的 GGUF 或 HuggingFace 格式模型放到对应路径。
以 GGUF 为例，常见结构是：
LocalGPT/
models/
your-model.gguf
SOURCE_DOCUMENTS/
DB/模型文件名要和启动脚本里引用的名称一致，否则会报找不到模型。
显存低于 8GB 时，优先选 7B 以下的量化模型，不要直接上 13B。
导入文档并生成向量库
LocalGPT 的问答不是直接读原文，而是先把文档切块、向量化后存入 DB/ 目录。
待问答的文件放进 SOURCE_DOCUMENTS/，支持 txt、pdf、md 等常见格式。
导入命令通常为：
python ingest.py执行后终端会显示正在处理的文件数量和切块进度，完成后 DB/ 下会生成向量库文件。每次新增或修改文档后都要重新执行 ingest，否则问答仍然基于旧内容。
如果导入时报编码错误，把文档另存为 UTF-8 再试；
PDF 扫描件无法直接提取文字，需要先做 OCR。
启动问答并验证回答来源
向量库生成后，用启动脚本进入交互问答：
python run_localGPT.py首次加载模型会占用较多内存和时间，终端出现 Enter a query: 之类的提示即表示就绪。
输入一个你能在文档里找到答案的问题，观察两点：回答是否引用了文档中的具体内容；
终端是否打印出检索到的文档片段。
如果回答泛泛而谈、不引用原文，通常是检索没命中，先检查文档是否导入成功、问题表述是否和文档用词接近。
想换模型或调整检索条数时，查看启动脚本里的模型路径和 k 参数，改完保存再重新运行。
不要同时开多个实例，显存容易爆。
常见报错与避坑
No module named ...：虚拟环境没激活或依赖没装全，重新执行source venv/bin/activate和pip install -r requirements.txt。- 显存不足
CUDA out of memory：换更小的量化模型，或调低上下文长度和检索条数。 - 回答和文档无关：先确认
DB/是否在导入后更新，再检查问题是否过于笼统。 - 端口被占用：如果使用带 Web 界面的启动方式，用
lsof -i:端口号找到进程并处理。
避坑重点：不要在系统 Python 里直接装依赖；
不要把模型文件放在项目根目录却改错脚本路径；
重新导入文档前不需要手动删 DB/，但换 embedding 模型时必须清空重建。
验证是否真正可用
完成以上步骤后，用三个问题做快速验证：问一个文档里明确写出的数字或名称；
问一个需要跨段落归纳的问题；
问一个文档里没有的内容，看模型是否承认不知道。
前两个能答到点上、第三个不硬编，基本说明检索和生成链路正常。
LocalGPT 使用教程的核心不是装完就结束，而是把模型路径、文档导入和检索验证这三步对齐。
环境或模型文件有变化时，优先回看导入和启动两个环节，多数问题都能定位到具体的命令输出。
