PrivateGPT 1.0基于 OpenAI 兼容推理服务器的本地 AI 应用 API 层完全指南【免费下载链接】privateGPTComplete API layer for private AI applications on local models: RAG, skills, tools, MCP, text-to-sql, and more. Works with any OpenAI-compatible inference server.项目地址: https://gitcode.com/GitHub_Trending/pr/privateGPT本文以 PrivateGPT 仓库根目录的 README 为核心完整覆盖其产品定位、四步快速上手流程、settings.yaml配置体系、REST API 端点全貌、Claude API 兼容性矩阵与 worker 异步架构并结合仓库源码与 OpenAPI 规范说明各能力的实现边界帮助开发者在自建的本地模型之上直接搭建私有 AI 应用后端。一、产品定位是应用 API 层不是推理服务器PrivateGPT 的核心定位可以用 README 中的一句话概括它是把本地模型变成生产级 AI 应用的开源 API 层API 设计遵循 Claude API 模型。其架构分层如下引自 README 原文Your app / agent / workflow / UI | PrivateGPT API | OpenAI-compatible inference server (Ollama, llama.cpp, vLLM, …)有三个关键边界必须理解PrivateGPT 本身不运行模型。它通过OPENAI_API_BASE环境变量连接到任意 OpenAI 兼容的推理服务器——只要该服务器实现了/v1/chat/completions和/v1/models两个端点即可工作。这一点在 settings.yaml 中有直接印证openai.api_base的默认值是 OpenAI 官方地址而快速上手时你会把它覆盖为http://localhost:llm-port/v1。API 才是真正交付的产品。PrivateGPT 自带一个内置工作台 UI挂载在/ui路径下用于测试、演示和快速本地使用官方明确说明UI 是演示器API 才是产品开发者应基于 API 构建自己的应用。它运行在 FastAPI 之上。从源码结构看HTTP 服务入口是 private_gpt/main.py其中通过launcher.create_app()创建 FastAPI 应用CLI 的serve命令则直接以 uvicorn 加载该应用见 private_gpt/cli/commands/serve.py 中的uvicorn.run(private_gpt.main:app, ...)。README 中同时给出了它与相邻生态的关系图Ollama / LM Studio / LocalAI / vLLM / llama.cpp local inference layer PrivateGPT local AI application API layer即 Ollama 等项目回答的是如何跑起一个模型而 PrivateGPT 回答的是如何在这个模型上构建有用的 AI 应用——两者是配合关系而非替代关系。二、PrivateGPT 提供的能力全景README 列出了 PrivateGPT 提供的七类能力每一类都能在仓库源码与 OpenAPI 规范中找到对应实现能力说明仓库内对应实现标准 Messages API支持流式、异步任务、token 计数openapi.json 中/v1/messages、/v1/messages/async、/v1/messages/count_tokens等文件与制品artifact摄入文档上传、解析、入库private_gpt/components/ingest/、private_gpt/components/readers/带引用citations的检索与 Agentic RAG检索结果可溯源private_gpt/components/engines/citations/内置工具网络搜索、网页抓取、代码执行对标 Claude API 内置工具private_gpt/components/tools/、private_gpt/components/web/、private_gpt/components/code_execution/自定义工具与 MCP 连接器接入 MCP 协议服务器private_gpt/server/mcp/、private_gpt/components/tools/anthropic_tools.py数据库与 CSV 的结构化访问内置 text-to-sql 与表格分析无需外挂工具private_gpt/components/database/、private_gpt/components/tabular/Embeddings 与编排独立的 embedding 端点与调用编排private_gpt/components/embedding/、private_gpt/server/embeddings/值得注意的是数据库查询与 CSV/表格分析在 Claude API 中需要借助外部工具实现而 PrivateGPT 将其作为内置能力提供见下文兼容性矩阵。三、快速上手四步跑通 PrivateGPT3.1 前提一个正在运行的 OpenAI 兼容 LLM 服务器最简起点是 Ollama。以 Ollama 为例拉取模型并启动服务引自 README 与 quickstart.mdx# Example with Ollama ollama pull qwen3.5:35b # LLM (~24 GB) ollama pull mxbai-embed-large # Embeddings (~670 MB) ollama serve # 默认监听 11434 端口除 Ollama 外quickstart 文档还给出了 llama.cpp 与 vLLM 的示例llama.cpp 需要启动两个llama-server实例一个跑 LLM一个带--embeddings参数跑嵌入模型vLLM 则用两个 Docker 容器分别承载 LLMQwen/Qwen3.5-35B-A3B-GPTQ-Int4与嵌入模型--task embed。一个实用限制Ollama 不暴露 tokenizer 端点因此 PrivateGPT 会退回到近似 token 计数可能影响上下文窗口管理这一点在 quickstart.mdx 中作为 Warning 明确标注。3.2 安装 PrivateGPTpyproject.toml 声明requires-python 3.11,3.12即必须使用 Python 3.11安装命令中的--python 3.11正是为此。macOS 使用 Homebrewbrew tap zylon-ai/tap brew install private-gptLinux / Windows 使用 uv# Linux 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]# Windows (PowerShell) powershell -ExecutionPolicy ByPass -c irm https://astral.sh/uv/install.ps1 | iex uv tool install --python 3.11 --find-links https://wheels.privategpt.dev/packages/ private-gpt[core][core]是一个安装风味install flavor从 pyproject.toml 的可选依赖定义可以看到它实际聚合了model-openai/model-openai-compatibleOpenAI SDK 基座与兼容型 LLM、Embedding 工厂tokenizer本地 tokenizer 支持transformersvectorstore-qdrantQdrant 向量存储客户端ingest文档/标记语言/MarkItDown/PDF 检查器全套解析能力toolsMCP 连接tool-mcp、表格分析tool-tabular含 pandasai、数据库tool-database含 PostgreSQL/MySQL/MSSQL/DB2 驱动、网页抓取Playwright。也就是说private-gpt[core]已经覆盖了能对话、能摄入、能检索、能用内置工具的最小完整能力集更细粒度的 extras如media、observability、storage-s3、queue-celery可按需追加。3.3 启动 PrivateGPT核心只有两个环境变量OPENAI_API_BASE指向 LLM 服务OPENAI_EMBEDDING_API_BASE指向 Embedding 服务若两者共用同一服务可以填同一个地址。# macOS / Linux OPENAI_API_BASEhttp://localhost:llm-port/v1 \ OPENAI_EMBEDDING_API_BASEhttp://localhost:embedding-port/v1 \ private-gpt serve# Windows (PowerShell) $env:OPENAI_API_BASE http://localhost:llm-port/v1 $env:OPENAI_EMBEDDING_API_BASE http://localhost:embedding-port/v1 private-gpt serve模型无需在配置文件中手工声明settings.yaml 中llm.auto_discover_models与embedding.auto_discover_models默认均为true服务启动时会从推理服务器的/v1/models自动发现全部可用模型models: []配置段因此可以留空。private-gpt serve的实际行为可以从 private_gpt/cli/commands/serve.py 确认它支持以下参数参数默认值作用--host0.0.0.0绑定地址--port读取settings中的server.port默认 8080HTTP 端口--reload关闭开发模式热重载--log-levelinfodebug \| info \| warn \| error--pid-file无写入 PID 文件供 systemd/launchd 管理重复启动时会检测旧 PID 并拒绝3.4 打开 UI 与验证 API启动成功后访问http://localhost:8080/uiserver.ui.path默认即/ui。API 本体位于http://localhost:8080遵循 Anthropic API 规范。这个 UI 适合用于发送消息Sending messages从/v1/models选择模型上传文档Uploading documents测试带引用的检索Testing retrieval with citations按会话粒度启用工具Enabling tools per chat配置数据库、MCP 连接器、技能skills与自定义工具通过 API Debugger 检查请求与响应。四、配置体系settings.yaml 与${ENV:default}语法PrivateGPT 的全部运行时行为由一份 YAML 配置驱动仓库根目录的 settings.yaml加载逻辑定义在 private_gpt/settings/settings.py。配置文件支持${ENV_VAR:default}语法——先取环境变量取不到则回落到默认值这使得所有关键配置项都可以纯用环境变量覆盖无需改文件。与生产部署最相关的默认值如下服务与访问控制serverserver: port: ${PORT:8080} cors: enabled: ${PGPT_CORS_ENABLED:true} allow_origins: [*] auth: enabled: false # 默认关闭启用后每个请求须携带 Authorization 头 secret: Basic c2VjcmV0OmtleQ ui: enabled: ${PGPT_UI_ENABLED:true} path: ${PGPT_UI_PATH:/ui} api_doc: enabled: ${PGPT_SWAGGER_ENABLED:true} # Swagger 默认开启/docs、/redoc、/openapi.json network: offline_mode: ${PGPT_OFFLINE_MODE,HF_HUB_OFFLINE:false} proxy: ... # 企业代理 ssl: ... # 证书与校验server.auth的鉴权实现是 HTTP Basicsecret字段存放期望收到的完整Authorization头值默认示例对应用户名secret、密码key配置文件中附有生成 Base64 头的命令注释。模型接入openai/llm/embeddingopenai: api_base: ${OPENAI_API_BASE:https://api.openai.com/v1} api_key: ${OPENAI_API_KEY:} embedding_api_base: ${OPENAI_EMBEDDING_API_BASE:} request_timeout: ${OPENAI_REQUEST_TIMEOUT:600.0} # 单次请求 10 分钟适配本地大模型 llm: default_model: ${PGPT_LLM_DEFAULT:} # 留空则依赖自动发现 auto_discover_models: true embedding: default_model: ${PGPT_EMBEDDING_DEFAULT:} ingest_mode: simple检索与向量存储retrieval/vectorstore/qdrantretrieval: top_k: ${PGPT_RETRIEVAL_TOP_K:32} vectorstore: database: ${PGPT_VECTORSTORE:qdrant} embed_dim: ${PGPT_EMBED_DIM:1024} # 必须与所用 embedding 模型匹配 multitenancy: logical default_collection: zgptvector qdrant: url: ${PGPT_QDRANT_URL:} path: ${PGPT_QDRANT_PATH:local_data/qdrant} # 未配 url 时默认本地模式 distance_metric: cosine默认即 Qdrant 本地模式数据落在local_data/qdrant零外部依赖即可起步接入独立 Qdrant 服务只需设置PGPT_QDRANT_URL。工具与执行沙箱code_execution/web_fetch/web_search/database_querycode_execution: provider: local timeout: 60 internet_enabled: false # 代码执行默认无外网 preinstalled_packages: pandas,numpy,scipy,scikit-learn,... # 预装数据分析栈 web_fetch: enabled: false # 网页抓取工具默认关闭 web_search: enabled: false # 网络搜索工具默认关闭 provider: mock database_query: timeout_seconds: 1000 max_mb_result: 150即内置的 web 工具族默认处于关闭/模拟状态属于显式启用类功能这为私有部署提供了安全默认值。异步与消息流stream/scheduler/tasks_results_brokerstream: broker: ${PGPT_ASYNC_BROKER:memory} # 消息流暂存memory 或 redis stream_expiration: 3600 scheduler: ingestion: mode: local # local 进程内执行 chat: mode: local tools: mode: local tasks_results_broker: mode: ${PGPT_TASKS_RESULTS_BROKER_MODE:rabbitmq}默认全部为local/memory单机部署无需 Redis/RabbitMQ切换到 Celery/Redis/RabbitMQ 后则进入分布式 worker 模式见第七节。五、REST API 面38 个端点全解析仓库内的 fern/openapi/openapi.json标题为 Private-GPT API 1.0.1共定义了38 条路径。按 API Reference 文档 的分组口径整理如下分组端点功能MessagesPOST /v1/messages、POST /v1/messages/async、POST /v1/messages/count_tokens、POST /v1/messages/validate对话流式、异步提交、token 计数、请求校验异步消息生命周期GET /v1/messages/async/{message_id}/status、GET .../stream、POST .../cancel、DELETE .../delete查询异步消息状态、SSE 拉取结果流、取消与删除ModelsGET /v1/models、GET /v1/models/{model_id}列出与检查模型Artifacts制品/v1/artifacts/ingest及/async、list、content、chunked-content、convert、delete及/async、readers文档摄入、列出、读取内容/分块、格式转换、删除Files/v1/files、/v1/files/namespaces、/v1/files/{file_id}PUT/GET/DELETE、/v1/files/{file_id}/content文件对象的命名空间管理与内容下载EmbeddingsPOST /v1/embeddings文本向量化Tools/v1/tools/semantic-search、/v1/tools/web-search、/v1/tools/web-fetch、/v1/tools/database-query、/v1/tools/tabular-data-analysis独立可调用的工具端点语义检索、网络搜索、网页抓取、SQL 查询、表格分析PrimitivesPOST /v1/primitives/search底层分块级检索Skills/v1/skillsPOST/GET、/v1/skills/validate、/v1/skills/{skill_id}GET/DELETE、版本管理端点可复用指令集的创建、校验与版本化补全POST /v1/complete裸文本补全几个值得展开的点异步消息是完整生命周期/v1/messages/async提交后返回任务标识客户端可以用status轮询、用stream通过 SSE 增量拉取、用cancel/delete做生命周期管理。这套端点与stream.broker、scheduler.*配置一一对应——默认memorybroker 下流式结果暂存于进程内存stream_expiration3600 秒生产环境建议换成 Redis。Tools 端点可脱离对话单独调用例如/v1/tools/semantic-search让你直接把 PrivateGPT 当作检索服务嵌入自有系统而不必经过一次完整的 messages 对话。鉴权启用后所有请求携带 Bearer Token例如curl http://localhost:8080/v1/messages \ -H Authorization: Bearer your-token \ -H Content-Type: application/json \ -d {...}对应 api-reference.mdx 给出的settings.yaml开启方式server.auth.enabled: true并设置secret。六、Claude API 兼容性矩阵README 给出了 PrivateGPT 与 Claude API 的逐项对照✅ 支持 · ⚙️ 部分/进行中 · ❌ 不支持这是评估哪些云侧能力可以平移过来的权威依据领域能力Claude APIPrivateGPTModels模型选择✅✅MessagesMessages API✅✅Messages流式Streaming✅✅Messages批处理 / 异步✅✅ asyncMessagesToken 计数✅✅Knowledge文件 / 制品✅✅KnowledgePDF 与文档摄入✅✅Knowledge带引用的检索✅✅KnowledgeEmbeddings✅✅Tools工具调用✅✅Tools流式中的工具✅✅Tools内置网络搜索✅✅Tools网页抽取 / 抓取✅✅Tools自定义工具✅✅Data数据库查询需借助工具✅ 内置DataCSV / 表格分析需借助工具 / 代码✅ 内置AgentsAPI 内的 MCP✅✅Agents远程 MCP 服务器✅✅AgentsSkills✅⚙️ 基础Output结构化输出✅✅ 依赖推理服务器Models视觉Vision✅✅ 依赖模型OptimizationPrompt 缓存✅❌Reasoning扩展思考✅✅PlatformToken 鉴权✅✅PlatformOAuth / 组织✅❌由此可以推断两条实践结论其一凡是需要结构化输出或视觉理解的能力实际效果取决于你接入的推理服务器所跑模型的能力而非 PrivateGPT 本身其二⚙️标记的 Skills 等方向是当前贡献最容易被上游接纳的区域。七、异步任务与 Worker 架构README 的messages APIstreaming, async背后是一套可插拔的任务执行体系从源码可以还原其结构CLI 命令面private_gpt/cli/main.py 注册了serve、run、help三个常驻命令并在检测到 celery 依赖时才注册worker命令——即异步 worker 能力由安装 extras 决定[queue-celery]、[queue-rabbitmq]。Worker 模式private_gpt/worker/modes.py 注册了三种 worker 模式arq基于 Redis 的轻量异步任务依赖arq仓库含完整的private_gpt/arq/实现celery标准 Celery worker自动附加 healthcheck 服务uvicorn 加载private_gpt.celery.healthcheck:app默认端口 8090并读取celery配置段max_tasks_per_child等flowerCelery 监控面板默认 5555 端口。 通过环境变量PGPT_WORKER_MODE选择模式见 private_gpt/cli/commands/worker.py。调度器切换scheduler.ingestion / chat / tools三个配置项分别控制文档摄入、对话、工具执行三类任务走local进程内还是队列对应private_gpt/components/ingestion/ingestion_scheduler.py等实现与private_gpt/celery/tasks/、private_gpt/arq/tasks/两套任务目录。基础设施依赖redis段用于缓存cache.provider默认memoryTTL 86400 秒与 Redis 信号量semaphore.mode默认memory分布式限流时切redisrabbitmq段是tasks_results_broker默认指向的结果通知通道。这套设计的实际含义是单机开发零依赖水平扩展只改配置——把三个 scheduler 切到队列模式、stream broker 切到 Redis、安装queueextras 后启动private-gpt worker即得到多节点部署而 HTTP 服务代码无需改动。八、集成作为既有工具的本地后端PrivateGPT 的定位决定了它可以寄生在开发者与终端用户已有的工具链里。README 列出的一等集成包括Claude Code把本地模型作为终端 Agent 编码的后端Claude Desktop / Cowork让 Claude 桌面应用与 Cowork 连接私有模型Claude for Microsoft 365在 Word、Excel、Outlook、PowerPoint 内运行私有 AIOpenCode终端本地 AI 编码助手。此外任何能对接本地 OpenAI 兼容 Provider 的工具都可以直接使用 PrivateGPTn8n、VS Code、Cline 等工作流/编码工具均在此列README 明确该列表非穷举。其原理正是一节中强调的兼容性契约PrivateGPT 的/v1/messages之上同时保持着 OpenAI 兼容的模型发现与对话接口使第三方工具只需改一个 base URL 就能把云 API换成你自己的 API。九、定位比较、项目历史与 Zylon 的关系与推理服务器项目Ollama、LM Studio、LocalAI、vLLM、llama.cpp的关系是上层与下层前者回答如何跑模型PrivateGPT 回答如何在这个模型上构建有用的 AI 应用官方建议是组合使用——用你喜欢的推理服务器跑模型再把 PrivateGPT 指过去。与 Onyx、Open WebUI 的区别在于产品哲学后者是 app-first以聊天界面与企业搜索为最终交付物而 PrivateGPT 是 API-first——它是这类自托管 AI 应用之下的标准化本地后端而不是最终产品本身。项目历史PrivateGPT 起源于 2023 年的离线与文档对话PoC曾成为当年最受关注的 AI 仓库之一当前仓库版本 1.0.1见 pyproject.toml是彻底重构后的API 层形态。项目由 Zylon 团队维护两者分工明确PrivateGPT开源应用 API 层——messages、摄入、工具、检索、引用、数据库访问、表格分析、MCP、skills、自定义工具Zylon商业在 PrivateGPT 之上叠加企业级 AI 基础设施——基于 NVIDIA Triton vLLM 的集成推理服务器、Kubernetes 生产部署、LDAP/AD 与 RBAC、SIEM 审计日志、SharePoint/Confluence 等连接器、气隙air-gapped运行等。选型口径要开源的本地 AI 应用层与开发者 API用 PrivateGPT要围绕它的部署、治理、运维、审计与支持的完整企业平台则是 Zylon 的范畴。十、继续深入仓库内的文档与测试入口本仓库自带完整文档站源码Fern 构建可作为 README 的延伸阅读材料fern/docs/pages/getting-started/quickstart.mdx四步 Quickstart 的完整版含 Ollama / LM Studio / llama.cpp / vLLM 四种 Provider 的配置对比fern/docs/pages/api-reference/api-reference.mdx端点分组与鉴权说明fern/docs/pages/providers/ 目录各推理 Provider 的能力矩阵与限制如 Ollama 无 tokenizer 端点fern/docs/pages/tools/ 与 fern/docs/pages/configuration/数据库工具依赖、代码执行沙箱与完整配置参考tests/ 目录覆盖聊天拦截器、引用引擎、工具管线、SSE、异步 worker 等关键链路的测试用例可帮助理解各模块的真实行为边界fern/openapi/openapi.json机器可读的完整 OpenAPI 规范是编写客户端代码时的最终事实来源。总结而言PrivateGPT 提供的是一套云侧 Claude API 能力的本地开源对应物用两个环境变量接入任意 OpenAI 兼容推理服务器即可获得 messages流式/异步/计数、制品摄入、带引用检索、内置工具、MCP、text-to-sql 与表格分析一整套应用级 API默认单机零依赖可跑生产环境仅需调整配置即可切换到 Redis/RabbitMQ/Celery 的分布式形态。【免费下载链接】privateGPTComplete API layer for private AI applications on local models: RAG, skills, tools, MCP, text-to-sql, and more. Works with any OpenAI-compatible inference server.项目地址: https://gitcode.com/GitHub_Trending/pr/privateGPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考