LocalGPT - 私有文档智能平台

🚀 什么是LocalGPT？

LocalGPT是一个完全私密、本地部署的文档智能平台。使用最先进的AI技术，您可以对文件进行提问、总结并挖掘洞察——数据永远不会离开您的设备。

LocalGPT不仅是一款传统的RAG（检索增强生成）工具，还配备了一个混合搜索引擎，结合语义相似度、关键词匹配以及延迟分块技术，以实现长上下文的精准检索。一个智能路由系统会自动为每个查询选择RAG或直接LLM回答的方式，而上下文增强和句子级别的上下文修剪功能则只会呈现最相关的内容。此外，独立的验证环节进一步提升了答案的准确性。

该架构具有模块化和轻量级的特点，您只需启用所需的组件即可。凭借纯Python核心和极少的依赖项，LocalGPT可以在任何基础设施上轻松部署、运行和维护。系统对框架和库的依赖性极低，因此易于部署和维护。RAG系统完全由纯Python编写，无需任何额外的依赖。

▶️ 视频

观看此视频，开始使用LocalGPT吧。

首页	创建索引	聊天

✨ 功能

• 极致隐私：您的数据始终保留在本地计算机上，确保100%的安全性。
• 多模型支持：通过Ollama无缝集成多种开源模型。
• 多样化的嵌入模型：可选择多种开源嵌入模型。
• 重复利用LLM：下载一次LLM后，无需再次下载即可重复使用。
• 聊天历史：在会话中记住您之前的对话。
• API：LocalGPT提供API，可用于构建RAG应用。
• GPU、CPU、HPU及MPS支持：开箱即用，支持多种平台。您可以通过CUDA、CPU、HPU (Intel® Gaudi®)或MPS等硬件与您的数据进行交互！

📖 文档处理

• 多格式支持：PDF、DOCX、TXT、Markdown等多种格式（目前仅支持PDF）。
• 上下文增强：借助AI生成的上下文信息，提升文档理解能力，灵感来源于上下文检索。
• 批量处理：可同时处理多个文档。

🤖 AI驱动的聊天

• 自然语言查询：可以用日常英语提问。
• 来源标注：每个答案都会附上文档引用。
• 智能路由：自动在RAG和直接LLM回答之间切换。
• 查询分解：将复杂查询拆解为子问题，以获得更佳答案。
• 语义缓存：基于TTL的缓存机制，结合相似度匹配，加快响应速度。
• 会话感知历史：在多次交互中保持对话上下文的一致性。
• 答案验证：独立的验证环节确保答案的准确性。
• 多种AI模型：使用Ollama进行推理，HuggingFace用于嵌入和重排序。

🛠️ 开发友好

• RESTful API：提供完整的API访问权限，便于集成。
• 实时进度：文档处理过程中提供实时更新。
• 灵活配置：可自定义模型、分块大小和搜索参数。
• 可扩展架构：支持插件系统，方便添加自定义组件。

🎨 现代化界面

• 直观的Web界面：设计简洁、响应迅速。
• 会话管理：按主题组织对话。
• 索引管理：轻松管理文档集合。
• 实时聊天：流式响应，即时反馈。

🚀 快速入门

注意：目前安装仅在macOS上测试过。

前置条件

• Python 3.8及以上版本（已测试Python 3.11.5）
• Node.js 16及以上版本及npm（已测试Node.js 23.10.0，npm 10.9.2）
• Docker（可选，用于容器化部署）
• 8GB以上内存（建议16GB以上）
• Ollama（两种部署方式均需）

注意

在本分支合并到主分支之前，请克隆此分支进行安装：

git clone -b localgpt-v2 https://github.com/PromtEngineer/localGPT.git
cd localGPT

方法一：Docker部署

# 克隆仓库
git clone https://github.com/PromtEngineer/localGPT.git
cd localGPT

# 在本地安装Ollama（即使使用Docker也需安装）
curl -fsSL https://ollama.ai/install.sh | sh
ollama pull qwen3:0.6b
ollama pull qwen3:8b

# 启动Ollama
ollama serve

# 在新终端中启动Docker
./start-docker.sh

# 访问应用
open http://localhost:3000

Docker管理命令：

# 查看容器状态
docker compose ps

# 查看日志
docker compose logs -f

# 停止容器
./start-docker.sh stop

方法二：直接开发（推荐用于开发环境）

# 克隆仓库
git clone https://github.com/PromtEngineer/localGPT.git
cd localGPT

# 安装Python依赖
pip install -r requirements.txt

# 已安装的关键依赖：
# - torch==2.4.1, transformers==4.51.0（AI模型）
# - lancedb（向量数据库）
# - rank_bm25, fuzzywuzzy（搜索算法）

# - sentence_transformers、重排序器（嵌入/重排序）
# - docling（文档处理）
# - colpali-engine（多模态处理——支持即将推出）

# 安装 Node.js 依赖
npm install

# 安装并启动 Ollama
curl -fsSL https://ollama.ai/install.sh | sh
ollama pull qwen3:0.6b
ollama pull qwen3:8b
ollama serve

# 启动系统（在新的终端中）
python run_system.py

# 访问应用
open http://localhost:3000

系统管理：

# 检查系统健康状况（全面诊断）
python system_health_check.py

# 检查服务状态和健康状况
python run_system.py --health

# 以生产模式启动
python run_system.py --mode prod

# 跳过前端（仅后台 + RAG API）
python run_system.py --no-frontend

# 查看聚合日志
python run_system.py --logs-only

# 停止所有服务
python run_system.py --stop
# 或者在运行 python run_system.py 的终端中按 Ctrl+C

服务架构： run_system.py 启动脚本管理四个关键服务：

• Ollama 服务器（端口 11434）：AI 模型服务
• RAG API 服务器（端口 8001）：文档处理与检索
• 后端服务器（端口 8000）：会话管理及 API 端点
• 前端服务器（端口 3000）：React/Next.js Web 界面

选项 3：手动启动各组件

# 终端 1：启动 Ollama
ollama serve

# 终端 2：启动 RAG API
python -m rag_system.api_server

# 终端 3：启动后端
cd backend && python server.py

# 终端 4：启动前端
npm run dev

# 访问地址 http://localhost:3000

详细安装步骤

1. 安装系统依赖

Ubuntu/Debian：

sudo apt update
sudo apt install python3.8 python3-pip nodejs npm docker.io docker-compose

macOS：

brew install python@3.8 node npm docker docker-compose

Windows：

# 安装 Python 3.8+、Node.js 和 Docker Desktop
# 然后使用 PowerShell 或 WSL2

2. 安装 AI 模型

推荐安装 Ollama：

# 安装 Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# 拉取推荐模型
ollama pull qwen3:0.6b          # 快速生成模型
ollama pull qwen3:8b            # 高质量生成模型

3. 配置环境变量

# 复制环境模板
cp .env.example .env

# 编辑配置
nano .env

关键配置选项：

# AI 模型（在 rag_system/main.py 中引用）
OLLAMA_HOST=http://localhost:11434

# 数据库路径（后端和 RAG 系统使用）
DATABASE_PATH=./backend/chat_data.db
VECTOR_DB_PATH=./lancedb

# 服务器设置（run_system.py 使用）
BACKEND_PORT=8000
FRONTEND_PORT=3000
RAG_API_PORT=8001

# 可选：覆盖默认模型
GENERATION_MODEL=qwen3:8b
ENRICHMENT_MODEL=qwen3:0.6b
EMBEDDING_MODEL=Qwen/Qwen3-Embedding-0.6B
RERANKER_MODEL=answerdotai/answerai-colbert-small-v1

4. 初始化系统

# 运行系统健康检查
python system_health_check.py

# 初始化数据库
python -c "from backend.database import ChatDatabase; ChatDatabase().init_database()"

# 测试安装
python -c "from rag_system.main import get_agent; print('✅ 安装成功！')"

# 验证完整设置
python run_system.py --health

🎯 开始使用

1. 创建第一个索引

索引 是一组已处理的文档，您可以与之进行对话。

使用 Web 界面：

1. 打开 http://localhost:3000
2. 点击“创建新索引”
3. 上传您的文档（PDF、DOCX、TXT）
4. 配置处理选项
5. 点击“构建索引”

使用脚本：

# 简单脚本方式
./simple_create_index.sh "我的文档" "path/to/document.pdf"

# 交互式脚本
python create_index_script.py

使用 API：

# 创建索引
curl -X POST http://localhost:8000/indexes \
  -H "Content-Type: application/json" \
  -d '{"name": "我的索引", "description": "我的文档"}'

# 上传文档
curl -X POST http://localhost:8000/indexes/INDEX_ID/upload \
  -F "files=@document.pdf"

# 构建索引
curl -X POST http://localhost:8000/indexes/INDEX_ID/build

2. 开始聊天

当您的索引构建完成后：

1. 创建聊天会话：点击“新建聊天”或使用现有会话
2. 选择索引：选择要查询的文档集合
3. 提问：输入关于您文档的自然语言问题
4. 获取答案：接收带有来源引用的 AI 生成回复

3. 高级功能

自定义模型配置

# 为不同任务使用不同模型
curl -X POST http://localhost:8000/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "title": "高质量会话",
    "model": "qwen3:8b",
    "embedding_model": "Qwen/Qwen3-Embedding-4B"
  }'

批量文档处理

# 一次性处理多个文档
python demo_batch_indexing.py --config batch_indexing_config.json

API 集成

import requests

# 通过 API 与您的文档对话
response = requests.post('http://localhost:8000/chat', json={
    'query': '研究论文中的主要发现是什么？',
    'session_id': 'your-session-id',
    'search_type': 'hybrid',
    'retrieval_k': 20
})

print(response.json()['response'])

🔧 配置

模型配置

LocalGPT 支持多个 AI 模型提供商，并采用集中式配置：

Ollama 模型（本地推理）

OLLAMA_CONFIG = {
    "host": "http://localhost:11434",
    "generation_model": "qwen3:8b",        # 主文本生成
    "enrichment_model": "qwen3:0.6b"       # 轻量级路由/增强
}

外部模型（HuggingFace 直接调用）

EXTERNAL_MODELS = {
    "embedding_model": "Qwen/Qwen3-Embedding-0.6B",           # 1024 维度
    "reranker_model": "answerdotai/answerai-colbert-small-v1", # ColBERT 重排序器
    "fallback_reranker": "BAAI/bge-reranker-base"             # 备用重排序器
}

管道配置

LocalGPT 提供两种主要的管道配置：

默认管道（生产就绪）

"default": {
    "description": "具有混合搜索、AI 重排和验证功能的生产就绪管道",
    "storage": {
        "lancedb_uri": "./lancedb",
        "text_table_name": "text_pages_v3",
        "bm25_path": "./index_store/bm25"
    },
    "retrieval": {
        "retriever": "multivector",
        "search_type": "hybrid",
        "late_chunking": {"enabled": True},
        "dense": {"enabled": True, "weight": 0.7},
        "bm25": {"enabled": True}
    },
    "reranker": {
        "enabled": True,
        "type": "ai",
        "strategy": "rerankers-lib",
        "model_name": "answerdotai/answerai-colbert-small-v1",
        "top_k": 10
    },
    "query_decomposition": {"enabled": True, "max_sub_queries": 3},
    "verification": {"enabled": True},
    "retrieval_k": 20,
    "contextual_enricher": {"enabled": True, "window_size": 1}
}

快速管道（速度优化）

"fast": {
    "description": "具有最小开销的速度优化管道",
    "retrieval": {
        "search_type": "vector_only",
        "late_chunking": {"enabled": False}
    },
    "reranker": {"enabled": False},
    "query_decomposition": {"enabled": False},
    "verification": {"enabled": False},
    "retrieval_k": 10,
    "contextual_enricher": {"enabled": False}
}

搜索配置

SEARCH_CONFIG = {
    'hybrid': {
        'dense_weight': 0.7,
        'sparse_weight': 0.3,
        'retrieval_k': 20,
        'reranker_top_k': 10
    }
}

🛠️ 故障排除

常见问题

安装问题

# 检查 Python 版本
python --version  # 应为 3.8+

# 检查依赖项
pip list | grep -E "(torch|transformers|lancedb)"

# 重新安装依赖项
pip install -r requirements.txt --force-reinstall

模型加载问题

# 检查 Ollama 状态
ollama list
curl http://localhost:11434/api/tags

# 拉取缺失的模型
ollama pull qwen3:0.6b

数据库问题

# 检查数据库连接
python -c "from backend.database import ChatDatabase; db = ChatDatabase(); print('✅ 数据库正常')"

# 重置数据库（警告：这将删除所有数据）
rm backend/chat_data.db
python -c "from backend.database import ChatDatabase; ChatDatabase().init_database()"

性能问题

# 检查系统资源
python system_health_check.py

# 监控内存使用情况
htop  # 或 Windows 上的任务管理器

# 针对低内存系统进行优化
export PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:512

获取帮助

1. 查看日志：系统会在 logs/ 目录下创建结构化日志：

   • logs/system.log：主要系统事件和错误
   • logs/ollama.log：Ollama 服务器日志
   • logs/rag-api.log：RAG API 处理日志
   • logs/backend.log：后端服务器日志
   • logs/frontend.log：前端构建和运行时日志

2. 系统健康检查：运行全面诊断：

   python system_health_check.py  # 全面系统诊断
   python run_system.py --health  # 服务状态检查
   

3. 健康端点：检查各个服务的健康状况：

   • 后端：http://localhost:8000/health
   • RAG API：http://localhost:8001/health
   • Ollama：http://localhost:11434/api/tags

4. 文档：查阅 技术文档

5. GitHub 问题：报告 bug 并请求功能

6. 社区：加入我们的 Discord/Slack 社区

🔗 API 参考

核心端点

聊天 API

# 基于会话的聊天（推荐）
POST /sessions/{session_id}/chat
Content-Type: application/json

{
  "query": "讨论的主要议题有哪些？",
  "search_type": "hybrid",
  "retrieval_k": 20,
  "ai_rerank": true,
  "context_window_size": 5
}

# 旧版聊天端点
POST /chat
Content-Type: application/json

{
  "query": "讨论的主要议题有哪些？",
  "session_id": "uuid",
  "search_type": "hybrid",
  "retrieval_k": 20
}

索引管理

# 创建索引
POST /indexes
Content-Type: application/json
{
  "name": "我的索引",
  "description": "描述",
  "config": "default"
}

# 获取所有索引
GET /indexes

# 获取特定索引
GET /indexes/{id}

# 将文档上传到索引
POST /indexes/{id}/upload
Content-Type: multipart/form-data
files: [file1.pdf, file2.pdf, ...]

# 构建索引（处理上传的文档）
POST /indexes/{id}/build
Content-Type: application/json
{
  "config_mode": "default",
  "enable_enrich": true,
  "chunk_size": 512
}

# 删除索引
DELETE /indexes/{id}

会话管理

# 创建会话
POST /sessions
Content-Type: application/json
{
  "title": "我的会话",
  "model": "qwen3:0.6b"
}

# 获取所有会话
GET /sessions

# 获取特定会话
GET /sessions/{session_id}

# 获取会话文档
GET /sessions/{session_id}/documents

# 获取会话索引
GET /sessions/{session_id}/indexes

# 将索引关联到会话
POST /sessions/{session_id}/indexes/{index_id}

# 删除会话
DELETE /sessions/{session_id}

# 重命名会话
POST /sessions/{session_id}/rename
Content-Type: application/json
{
  "new_title": "更新后的会话名称"
}

高级功能

查询分解

系统可以将复杂查询拆分为子问题，以获得更好的答案：

POST /sessions/{session_id}/chat
Content-Type: application/json

{
  "query": "比较这些方法论并分析其有效性",
  "query_decompose": true,
  "compose_sub_answers": true
}

答案验证

使用独立的验证模型进行准确性验证：

POST /sessions/{session_id}/chat
Content-Type: application/json

{
  "query": "关键发现是什么？",
  "verify": true
}

上下文增强

在索引构建过程中对文档上下文进行增强，以提高理解能力：

# 在索引构建时启用
POST /indexes/{id}/build
{
  "enable_enrich": true,
  "window_size": 2
}

晚期分块

通过在嵌入后再进行分块来更好地保留上下文：

# 在管道中配置
"late_chunking": {"enabled": true}

流式聊天

POST /chat/stream
Content-Type: application/json

{
  "query": "请解释该方法论",
  "session_id": "uuid",
  "stream": true
}

批量处理

# 使用批量索引脚本
python demo_batch_indexing.py --config batch_indexing_config.json

# 示例批量配置（batch_indexing_config.json）：
{
  "index_name": "示例批量索引",
  "index_description": "示例批量索引配置",
  "documents": [
    "./rag_system/documents/invoice_1039.pdf",
    "./rag_system/documents/invoice_1041.pdf"
  ],
  "processing": {
    "chunk_size": 512,
    "chunk_overlap": 64,
    "enable_enrich": true,
    "enable_latechunk": true,
    "enable_docling": true,
    "embedding_model": "Qwen/Qwen3-Embedding-0.6B",
    "generation_model": "qwen3:0.6b",
    "retrieval_mode": "hybrid",
    "window_size": 2
  }
}

# 批量处理的API端点
POST /batch/index
Content-Type: application/json

{
  "file_paths": ["doc1.pdf", "doc2.pdf"],
  "config": {
    "chunk_size": 512,
    "enable_enrich": true,
    "enable_latechunk": true,
    "enable_docling": true
  }
}

有关完整的API文档，请参阅API_REFERENCE.md。

🏗️ 架构

LocalGPT采用模块化、可扩展的架构：

graph TB
    UI[Web界面] --> API[后端API]
    API --> Agent[RAG代理]
    Agent --> Retrieval[检索管道]
    Agent --> Generation[生成管道]

    Retrieval --> Vector[向量搜索]
    Retrieval --> BM25[BM25搜索]
    Retrieval --> Rerank[重排序]

    Vector --> LanceDB[(LanceDB)]
    BM25 --> BM25DB[(BM25索引)]

    Generation --> Ollama[Ollama模型]
    Generation --> HF[Hugging Face模型]

    API --> SQLite[(SQLite数据库)]

检索代理概述

graph TD
    classDef llmcall fill:#e6f3ff,stroke:#007bff;
    classDef pipeline fill:#e6ffe6,stroke:#28a745;
    classDef cache fill:#fff3e0,stroke:#fd7e14;
    classDef logic fill:#f8f9fa,stroke:#6c757d;
    classDef thread stroke-dasharray: 5 5;

    A(开始：Agent.run) --> B_asyncio.run(_run_async);
    B --> C{_run_async};

    C --> C1[获取聊天历史];
    C1 --> T1[构建分类提示 <br/> 查询 + 文档概览 ];
    T1 --> T2["(asyncio.to_thread)<br/>LLM分类：RAG还是LLM_DIRECT？"]; class T2 llmcall,thread;
    T2 --> T3{决策?};

    T3 -- RAG --> RAG_Path;
    T3 -- LLM_DIRECT --> LLM_Path;

    subgraph RAG Path
        RAG_Path --> R1[格式化查询 + 历史];
        R1 --> R2["(asyncio.to_thread)<br/>生成查询嵌入"]; class R2 pipeline,thread;
        R2 --> R3{{检查语义缓存}}; class R3 cache；
        R3 -- 命中 --> R_Cache_Hit(返回缓存结果);
        R_Cache_Hit --> R_Hist_Update;
        R3 -- 未命中 --> R4{是否启用分解 <br/> 启用？};

        R4 -- 是 --> R5["(asyncio.to_thread)<br/>分解原始查询"]; class R5 llmcall,thread;
        R5 --> R6{{运行子查询 <br/> 并行RAG管道}}；class R6 pipeline,thread；
        R6 --> R7[收集结果和文档];
        R7 --> R8["(asyncio.to_thread)<br/>组合最终答案"]; class R8 llmcall,thread；
        R8 --> V1(RAG答案);

        R4 -- 否 --> R9["(asyncio.to_thread)<br/>运行单个查询 <br/>(RAG管道)"]; class R9 pipeline,thread；
        R9 --> V1;

        V1 --> V2{{验证 <br/> await verify_async}}；class V2 llmcall；
        V2 --> V3(最终RAG结果);
        V3 --> R_Cache_Store{{存储到语义缓存}}；class R_Cache_Store cache；
        R_Cache_Store --> FinalResult；
    end

    subgraph Direct LLM Path
        LLM_Path --> L1[格式化查询 + 历史];
        L1 --> L2["(asyncio.to_thread)<br/>生成直接LLM答案 <br/> (无RAG)"]; class L2 llmcall,thread；
        L2 --> FinalResult(最终直接结果)；
    end

    FinalResult --> R_Hist_Update(更新聊天历史);
    R_Hist_Update --> ZZZ(结束：返回结果);

🤝 贡献

我们欢迎所有技能水平的开发者贡献！LocalGPT是一个开源项目，受益于社区参与。

🚀 贡献者快速入门

# 分支并克隆仓库
git clone https://github.com/PromtEngineer/localGPT.git
cd localGPT

# 设置开发环境
pip install -r requirements.txt
npm install

# 安装Ollama及模型
curl -fsSL https://ollama.ai/install.sh | sh
ollama pull qwen3:0.6b qwen3:8b

# 验证设置
python system_health_check.py
python run_system.py --mode dev

📋 如何贡献

1. 🐛 报告Bug：使用我们的Bug报告模板
2. 💡 请求功能：使用我们的功能请求模板
3. 🔧 提交代码：遵循我们的开发工作流程
4. 📚 改进文档：帮助完善我们的文档

📖 详细指南

关于全面的贡献指南，包括：

• 开发设置与工作流程
• 编码标准与最佳实践
• 测试要求
• 文档标准
• 发布流程

👉 请参阅我们的CONTRIBUTING.md指南

📄 许可证

本项目采用MIT许可证——详情请参阅LICENSE文件。对于模型，请查看其各自的许可证。

📞 支持

• 文档：技术文档
• 问题：GitHub问题
• 讨论：GitHub讨论
• 商业部署与定制：联系我们

brew install python@3.11 node npm docker docker-compose

sudo apt update
sudo apt install python3.11 python3-pip nodejs npm docker.io docker-compose

# 安装 Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# 拉取推荐模型 (轻量版与高质量版)
ollama pull qwen3:0.6b
ollama pull qwen3:8b

# 启动 Ollama 服务
ollama serve

git clone -b localgpt-v2 https://github.com/PromtEngineer/localGPT.git
cd localGPT

# 启动 Docker 容器
./start-docker.sh

# 访问应用
open http://localhost:3000

docker compose ps          # 查看容器状态
docker compose logs -f     # 查看实时日志
./start-docker.sh stop     # 停止服务

# 1. 安装 Python 依赖
pip install -r requirements.txt

# 2. 安装前端依赖
npm install

# 3. 确保 Ollama 已在另一终端运行 (ollama serve)

# 4. 启动系统
python run_system.py

# 5. 访问应用
open http://localhost:3000

python run_system.py --health       # 检查系统健康状态
python run_system.py --mode prod    # 生产模式启动
python run_system.py --no-frontend  # 仅启动后端和 RAG API
python run_system.py --stop         # 停止所有服务

# 简单模式
./simple_create_index.sh "My Documents" "path/to/document.pdf"

# 交互模式
python create_index_script.py

# 创建索引
curl -X POST http://localhost:8000/indexes \
  -H "Content-Type: application/json" \
  -d '{"name": "My Index", "description": "My documents"}'

# 上传文件 (替换 INDEX_ID 为实际返回的 ID)
curl -X POST http://localhost:8000/indexes/INDEX_ID/upload \
  -F "files=@document.pdf"

# 构建索引
curl -X POST http://localhost:8000/indexes/INDEX_ID/build

curl -X POST http://localhost:8000/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "title": "High Quality Session",
    "model": "qwen3:8b",
    "embedding_model": "Qwen/Qwen3-Embedding-4B"
  }'