LocalGPT 是一个完全私有、本地部署的文档智能平台，目标是让用户在不将数据传出本机的前提下，用先进的 AI 模型对自己的文件进行提问、总结和洞察挖掘。它被定位为超越传统 RAG（检索增强生成）的工具，核心是一套模块化、轻量的架构。
用途
LocalGPT 用于在本设备上与文档交互：提问、总结、从文件中发现信息。所有处理都在本地进行，数据不会离开用户机器，强调 100% 隐私。
主要能力
- 极致隐私：数据保留在本地计算机上，不向外传输。
- 模型支持灵活：可通过 Ollama 自由更换生成模型。
- 多样嵌入：支持 HuggingFace 嵌入模型（harrier-oss-v1、Qwen3-Embedding 系列）或任意 Ollama 嵌入标签。
- 复用 LLM：模型下载后可重复使用，无需反复下载。
- API：提供端口 8000 的 REST 网关和端口 8001 的 RAG API，便于构建自己的应用。
- 设备自适应：嵌入与重排序自动在 CUDA、Apple MPS、CPU 之间选择（依次尝试 CUDA、Apple MPS、CPU）。
文档处理方面：支持 PDF、DOCX、HTML/HTM、Markdown 和 TXT，由 Docling 解析；对没有文本层的 PDF 会走 Docling 的 OCR 流程，OCR 引擎从已安装的引擎中选择（macOS 上优先 OcrMac，然后是 EasyOCR、RapidOCR、tesserocr 或 tesseract CLI）。还提供上下文增强（由小 LLM 生成块级上下文）、默认关闭的 Late Chunking（文档级二次嵌入、存入伴生表）、以及文档概览（每篇文档的简短摘要，用于路由）。
AI 聊天能力包括：自然语言提问、来源归因（答案附带所依据的文本块）、智能路由（在 RAG 与直接 LLM 回答之间逐查询选择）、查询分解（把复杂问题拆成子问题，分别检索后合并候选，再做一次重排和一次综合）、Reciprocal Rank Fusion（向量与全文命中用 RRF 融合，无需调权重）、重排序（对融合后的候选集做交叉编码器重排，默认开启，按校准分数选择）、句子剪枝（可选的 Provence 剪枝，从每个块中丢弃不相关句子）、语义缓存（会话范围内、相似度阈值 0.98 的 TTL 缓存）、以及默认关闭的答案验证（第二遍在答案后附加 [Confidence: N%]）。
开发者友好方面：每个 UI 动作都是文档化的 HTTP 调用；通过 Server-Sent Events 以流式阶段暴露每条流水线阶段；模型、块大小、检索模式等可按请求配置；rag_system/main.py 保存所有默认值，并可由环境变量覆盖。界面提供简洁响应式的 Web UI、按主题组织对话的会话管理、索引管理、以及检索/重排/综合阶段的实时进度。
使用方式
运行环境要求：Python 3.10+（推荐 3.11，Docker 镜像使用 python:3.11-slim）、Node.js 20+ 与 npm、Docker（可选，用于容器化部署）、8GB+ 内存（推荐 16GB+）、Ollama（两种部署方式都必需）。
部署方式有三种：
- Docker 部署：若不想在宿主机安装 Ollama，可用 ./start-docker.sh（无参数）使用本地 Ollama；如果 11434 端口没有监听，会提示切换到容器化 Ollama，加 -y（或设置 NONINTERACTIVE=1）可在脚本和 CI 中无提示采用该回退。
- 直接开发（推荐用于开发）：run_system.py 启动器管理四个服务并把 PID 写入 logs/run_system.pid——Ollama 服务器（端口 11434，模型服务，已在运行则复用）、RAG API 服务器（端口 8001，索引、检索与 agent 循环）、后端服务器（端口 8000，会话、索引、上传、聊天历史）、前端服务器（端口 3000，Next.js Web 界面，可选，缺少 npm 时跳过）。启动时会检查 qwen3.5:9b 和 qwen3.5:4b 是否存在，缺失则执行 ollama pull。
- 手动分组件启动：所有命令需在仓库根目录运行，因为相对路径（backend/chat_data.db、lancedb/、index_store/、shared_uploads/）基于当前工作目录解析。
安装要点：只有两个 Ollama 模型需要显式拉取；嵌入模型（microsoft/harrier-oss-v1-0.6b，1.2 GB）首次使用时从 HuggingFace 下载；重排序器（约 7.5 GB）懒加载，在首次需要重排的查询时下载。所有设置都有可用的默认值，因此 LocalGPT 即使没有 .env 也能运行；如需覆盖，在仓库根目录创建 .env。NEXT_PUBLIC_* 值会在 next build 时烘焙进前端包，修改后需重新构建。更改 EMBEDDING_MODEL 会使现有索引失效，切换嵌入模型后需重建索引。
快速上手流程：打开 http://localhost:3000，点击 “Create New Index”，上传文档（PDF、DOCX、TXT、MD、HTML），配置处理选项，点击 “Build Index”；随后创建聊天会话、选择索引、用自然语言提问，获得带来源引用的回答。索引的嵌入模型是索引本身的属性，需在构建索引时选择。
适用场景
适合需要本地化、隐私优先的文档问答与检索的用户，例如处理技术 RFC、并购文档、服务手册、HR 政策、项目文档等语料。仓库中也提供了对应的评测语料。
限制
- RAG API 是单线程的，请求会被串行化：一次只能运行一个聊天或索引任务（后端网关是多线程的）。
- 视觉/多模态模型不在流水线内；PDF 解析和 OCR 由 Docling 处理。GLM-OCR 或 Qwen3-VL 等模型可作为预处理步骤加入，但目前未集成。
- 若重排序器加载失败，流水线会记录警告并继续、不再重排，而不是回退到另一个模型。
- 多向量（late-interaction）检索为实验性、由环境变量开关控制，需通过进程外 sidecar 提供；全部为实测但均非默认。
- 部分组件（Late Chunking、答案验证、跨引用跳转、文档升级、多向量检索）默认关闭，因其在评测中未体现出足够收益。
- 嵌入维度不硬编码，而是从已加载模型产出的向量测量；向已有 LanceDB 表追加不同宽度向量会报错并要求重建。
以上信息来自项目说明，其他细节（如具体定价、收费模式等）暂未提供。
