LocalGPT - 私有文档智能平台

🚀 LocalGPT 是什么？

LocalGPT 是一个完全私有、本地部署的文档智能平台。您可以使用最先进的 AI 技术向您的文件提问、总结和挖掘洞见——所有数据都不会离开您的机器。

它不仅仅是一个传统的 RAG（检索增强生成）工具。LocalGPT 配备了混合搜索引擎，融合了语义相似性、关键词匹配和用于长文本精确检索的延迟分块技术。一个智能路由器会自动为每个查询在 RAG 和直接 LLM 回答之间做出选择，而上下文增强和句子级别的上下文剪枝则确保只呈现最相关的内容。独立的验证环节为答案增添了额外的准确性保障。

其架构是模块化且轻量级的——您只需启用需要的组件。凭借纯 Python 核心和极少的依赖，LocalGPT 在任何基础设施上都易于部署、运行和维护。该系统对框架和库的依赖极小，使其易于部署和维护。RAG 系统是纯 Python 的，不需要任何额外的依赖。

▶️ 视频

观看此视频以开始使用 LocalGPT。

主页	创建索引	聊天

✨ 特性

• 极致隐私：您的数据始终保留在您的计算机上，确保 100% 安全。
• 多样模型支持：通过 Ollama 无缝集成多种开源模型。
• 多种嵌入模型：可从一系列开源嵌入模型中选择。
• 复用您的 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 UI：简洁、响应式设计
• 会话管理：按主题组织对话
• 索引管理：轻松管理文档集合
• 实时聊天：流式响应，提供即时反馈

🚀 快速开始

注意：目前安装仅在 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

选项 1：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

选项 2：直接开发（推荐用于开发）

# 克隆仓库
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, rerankers (嵌入/重排序)
# - 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

模型加载问题

```bash

检查 Ollama 状态