privateGPT
为本地大模型提供生产级 API 抽象层，Claude API 风格，支持 RAG、工具调用与 Age
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
为本地大模型提供生产级 API 抽象层，Claude API 风格，支持 RAG、工具调用与 Age
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
2024 年下半年，某中型金融科技公司的技术负责人老张遇到了一个棘手的问题：团队想基于内部合规文档构建一个智能问答系统，但公司数据安全政策明令禁止将敏感文档上传到任何第三方 API。OpenAI、Anthropic、Google 的云端服务全部被排除在外。
老张的团队花了两个月时间，基于开源大模型（Qwen2-7B）手动搭建了一套 RAG（检索增强生成）系统。然而，系统上线后他们发现：每次业务需求变更（比如换一种文档解析策略、调整向量检索参数、切换不同的 embedding 模型），开发团队都需要修改底层代码。系统缺乏标准化接口，各模块耦合严重，代码难以维护。更重要的是，产品经理希望能像调用 OpenAI API 那样简单地去切换不同的大模型后端——但他们自研的系统根本做不到这一点。
PrivateGPT 正是为解决这类痛点而生的。它的核心定位很清晰：不运行模型本身，而是为本地大模型提供一套生产级的 API 抽象层，让开发者可以像使用 Claude API 或 OpenAI API 那样，标准化地调用本地部署的大模型。
PrivateGPT 最早由独立开发者 Iman Martínez 发起于 2023 年，彼时正值开源大模型生态爆发期。开发者们发现，虽然 Llama.cpp、Ollama 等工具降低了本地部署模型的门槛，但缺乏一个统一的、面向应用层的高层抽象。PrivateGPT 借鉴了 Claude API 的设计哲学，将文件解析、RAG 检索、工具调用、Agent 编排等常见能力封装为标准化的 API 端点，开发者无需重复造轮子。
随着项目影响力扩大，团队成立了 Zylon 公司，将 PrivateGPT 定位为开源核心，Zylon 则在其基础上提供企业级商业发行版，包括 NVIDIA Triton + vLLM 推理加速、Kubernetes 部署、RBAC 权限管理、审计日志等企业刚需功能。截至 2026 年，PrivateGPT 在 GitHub 累计获得超过 57,000 颗星，成为本地 AI 应用层基础设施领域的标杆项目。
PrivateGPT 的能力可以分为几个层次来看：
API 层（核心价值）：项目提供一套与 OpenAI API 兼容的端点接口（/v1/chat/completions、/v1/models 等），同时参考 Claude API 模型实现了消息流式传输（Server-Sent Events）、异步调用、Token 计数等进阶能力。这意味着：开发者在云端 API 写好的应用代码，几乎不需要修改就能迁移到 PrivateGPT + 本地模型的组合上。
RAG 管道：PrivateGPT 内置了完整的文档处理和检索增强生成管线。支持的文档格式包括 PDF、Word、Excel、Markdown、HTML、纯文本等，通过 Apache Tika（经由 LlamaIndex Reader）进行内容提取。文件通过 embedding 模型（默认支持 Ollama 嵌入模型）向量化后存入向量数据库（默认 Chroma，可切换）。检索时支持 top_k 参数控制召回数量，并提供引用（citation）生成能力——每次回答都会标注引用来源的文档和段落位置。
工具系统（Tools）：PrivateGPT 实现了类似 Claude Function Calling 的工具调用机制，内置了 Web Search（网页搜索）、Web Fetch（网页抓取）、Code Interpreter（代码执行）三个标准工具。同时支持 MCP（Model Context Protocol）协议连接外部数据源，以及自定义 Tool 的注册和调用。此外还支持通过 SQLAlchemy 连接关系型数据库、直接读取 CSV 文件进行结构化数据分析。
Agent 编排：基于 LangChain 的 Agent 框架，PrivateGPT 支持链式（Chain）和 ReAct 风格的推理 Agent，可以将多个工具组合使用，完成复杂的多跳问答任务。
UI 工作台：虽然 PrivateGPT 的核心是 API，但项目也提供了一个开箱即用的 Workbench Web UI，基于 Gradio 框架开发，位于 /ui 路径。开发者可以用它快速测试 API 的各项能力。
从代码结构来看，PrivateGPT 采用标准的 FastAPI 应用框架，核心依赖包括：
| 组件 | 技术选型 | 作用 |
|---|---|---|
| Web 框架 | FastAPI + Uvicorn | 高性能异步 API 服务器 |
| LLM 编排 | LangChain + LlamaIndex | Agent 编排、文档解析、Prompt 管理 |
| 数据验证 | Pydantic | 请求/响应模型定义 |
| 向量数据库 | ChromaDB（默认） | 文档 embedding 存储 |
| 关系数据库 | SQLite（默认）/ PostgreSQL | 应用状态、对话历史持久化 |
| 异步任务 | Celery（可选） | 长时间运行的文档处理任务 |
| 前端 UI | Gradio | 内置 Workbench 可视化界面 |
核心模块位于 private_gpt/ 目录下，按职责划分为：
server/ — API 路由层，包含 chat、ingest、embeddings、models、skills、tools 等端点components/ — 业务组件层，包括 LLMComponent、EmbeddingComponent、VectorStoreComponent、StorageComponent 等，通过 Injector（依赖注入）框架管理组件生命周期chat/ — 对话数据模型cli/ — 命令行工具架构亮点在于组件化设计：所有 LLM、Embedding、VectorStore、Storage 等关键组件均实现了标准接口，通过依赖注入灵活替换实现。例如，要从 ChromaDB 切换到 Qdrant 或 Pinecone，只需修改配置而非代码。
PrivateGPT 提供多阶段 Dockerfile（基于 python:3.11.10-slim-bookworm），通过 EXTRAS 参数控制安装范围：
# 仅安装核心 API（最小化镜像）
docker build --build-arg EXTRAS=core -t private-gpt .
# 包含文档解析能力
docker build --build-arg EXTRAS=ingest -t private-gpt .
# 包含媒体处理（图片/音频/视频）
docker build --build-arg EXTRAS=media -t private-gpt .
# 全功能
docker build --build-arg EXTRAS=core,ingest,media,tools,database -t private-gpt .
镜像构建使用了 UV 包管理器的缓存机制，多阶段策略减少了最终镜像体积。部署时还需要一个 OpenAI 兼容的推理服务器（Ollama、llama.cpp server、vLLM 任选其一），GPU 是推荐配置——以 Qwen2-7B 为例，需要至少 8GB VRAM（RTX 3090 或同级别）。如果使用量化模型（Q4_K_M），6GB 左右的显存也可运行。
对于没有 GPU 的场景，PrivateGPT 也可以配合纯 CPU 推理使用，但响应延迟会明显增加。磁盘需求约 20GB（包含模型缓存）。
以 Ollama 为推理后端、Linux 系统为例，完整流程约需 10-15 分钟：
# 1. 安装 PrivateGPT（通过 UV）
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install --python 3.11 --find-links https://wheels.privategpt.dev/packages/ "private-gpt[core]"
# 2. 下载模型（Ollama）
ollama pull qwen2.5:7b
ollama pull mxbai-embed-large
# 3. 启动 Ollama 服务
ollama serve
# 4. 启动 PrivateGPT
OPENAI_API_BASE=http://localhost:11434/v1 OPENAI_EMBEDDING_API_BASE=http://localhost:11434/v1 private-gpt serve
# 5. 打开 http://localhost:8080/ui 测试
在 Web UI 中上传一份 PDF 文档，等待 embedding 完成（耗时取决于文档大小和模型速度），然后即可开始对话。API 调用示例：
curl -X POST http://localhost:8080/v1/chat/completions -H "Content-Type: application/json" -d '{
"messages": [{"role": "user", "content": "这份文档的核心结论是什么？"}],
"stream": false
}'
PrivateGPT 的定位决定了它的局限性：
不内置模型，需要额外配置：与一些"一条命令就跑起来"的 AI 工具不同，PrivateGPT 要求使用者自行部署和维护推理服务器。这增加了初始配置的成本，也意味着出现问题时需要排查多个组件（PrivateGPT + 推理服务 + Embedding 服务 + 向量数据库）。
对中文文档的支持存在差异：部分用户反馈，中文 PDF 的解析质量与英文文档有差距，尤其是扫描件（纯图片 PDF）需要配合 OCR 流程才能正确提取文字。
版本迭代较快带来的稳定性问题：PrivateGPT 在 2024-2025 年间经历了多次重大架构调整，从早期基于 LangChain 的实现逐步演进到 LlamaIndex + LangChain 双轨并行，社区反馈偶有"大版本升级后配置不兼容"的情况。
GPU 显存门槛：对于想运行更大模型（如 70B 参数）的用户，硬件成本仍然是一个障碍。虽然支持 llama.cpp 的量化方案，但量化后模型质量会有所下降。
PrivateGPT 的出现填补了本地大模型应用开发中"缺乏标准 API 抽象层"的空白。它代表了 AI 应用开发的一种重要范式：将推理层（模型）和应用层（API/工具/编排）解耦。这种解耦使得：
从增长曲线看，PrivateGPT 的星标数从 2024 年的约 20,000 增长到 2026 年的 57,000+，背后是本地 AI 应用需求的持续扩大。随着各大企业数据合规意识的增强，以及 llama.cpp、vLLM 等推理工具的成熟，"本地优先"的 AI 应用开发模式正在从极客圈走向更广阔的企业市场。PrivateGPT 作为这一趋势的基础设施层，其战略价值远超它本身的功能丰富度。
总结：PrivateGPT 是本地大模型应用开发者的效率利器。它将 Claude API 的开发体验带到了本地环境，配合 Ollama/vLLM 等推理服务，可以快速构建隐私优先的 RAG 系统、文档问答平台、AI Agent 应用。部署有一定门槛（需要理解 Docker、API 配置、GPU 资源），但一旦跑通，后续开发和迭代效率极高。对于有数据隐私需求、或希望摆脱云端 API 依赖的团队，PrivateGPT 值得深入研究。