DocsGPT 开源私有化 AI 平台：核心特性、部署方式与容器化运行架构全解-酒店常州论坛

DocsGPT 开源私有化 AI 平台：核心特性、部署方式与容器化运行架构全解

【免费下载链接】DocsGPTPrivate AI platform for agents, assistants and enterprise search. Built-in Agent Builder, Deep research, Document analysis, Multi-model support, and API connectivity for agents.项目地址: https://gitcode.com/GitHub_Trending/do/DocsGPT

DocsGPT 是一个开源的私有化 AI 平台，面向智能体（Agent）、助手与企业级搜索场景，内置 Agent 构建器、深度研究、文档分析、多模型支持与 Agent API 连接能力。本文以仓库根目录的 README.md 为主体，完整梳理其特性体系与路线图，并结合 setup.sh、docker-compose-hub.yaml 等真实配置文件，逐步骤讲解如何克隆、配置并启动 DocsGPT，读懂其容器化运行时架构，最终获得一套可复制、可本地私有部署的完整实操方案。

平台定位与核心特性

DocsGPT 的定位是“Private AI for agents, assistants and enterprise search”（面向智能体、助手与企业搜索的私有化 AI），可以部署在任意环境中并实现完全的隐私控制。其核心特性在 README.md 中归纳为九类：

宽格式文档支持：可读取 PDF、DOCX、CSV、XLSX、EPUB、MD、RST、HTML、MDX、JSON、PPTX、图片，以及 MP3、WAV、M4A、OGG、WebM 等音频文件；
语音工作流：在聊天中录制语音输入，在后端完成语音转写，并将会议录音或语音笔记摄取为可搜索的知识；
Web 与数据集成：支持从 URL、sitemap、Reddit、GitHub 以及网页爬虫导入内容；
可靠答案：获取准确、无幻觉的回答，并可在干净的 UI 中查看来源引用；
精简的 API Key 管理：生成与你的配置、文档和模型绑定的密钥，简化聊天机器人与集成的搭建；
可执行工具：连接 API、工具与其他服务，让 LLM 具备实际行动能力；
预置集成：开箱即用的 HTML/React 聊天组件、搜索工具、Discord/Telegram 机器人等；
灵活部署：兼容主流云端 LLM（OpenAI、Google、Anthropic）与本地模型（Ollama、llama_cpp）；
安全且可扩展：支持私有安全运行，提供 Kubernetes 支持，面向企业级可靠性设计。

特性路线图

README.md 同时给出了已完成的 Roadmap（截至 2026 年 6 月均已打勾）：

Agent 工作流构建器（带条件节点，2026 年 2 月）
Research 研究模式（2026 年 3 月）
SharePoint 与 Confluence 连接器（2026 年 3–4 月）
用户数据的 Postgres 迁移（2026 年 4 月）
OpenTelemetry 可观测性（2026 年 4 月）
BYOM（自带模型，Bring Your Own Model，2026 年 4 月）
Agent 定时调度（RedBeat 支撑，2026 年 4 月）
通知与会话搜索（2026 年 5 月）
分析与日志重构，支持按 Agent 归因（2026 年 6 月）
OIDC / SSO 登录，含 SCIM 供应与用户组（2026 年 6 月）
管理仪表盘与基于角色的访问控制（RBAC，2026 年 6 月）
Agent 导入 / 导出（2026 年 6 月）
团队（Teams）与团队范围的共享和角色（2026 年 6 月）

这些路线图条目与仓库中实际存在的模块可以相互印证：例如 OIDC/SCIM 对应 application/api/oidc 与 application/api/scim，RBAC 与团队对应 application/api/user/teams 与迁移文件 0020_user_roles.py、0021_teams.py，定时调度对应 application/agents/tools/scheduler.py 与迁移 0010_schedules.py。

快速开始：环境准备与仓库克隆

DocsGPT 采用 Docker 部署，唯一的硬性前置条件是安装并运行 Docker。克隆仓库：

git clone https://gitcode.com/GitHub_Trending/do/DocsGPT.git cd DocsGPT

macOS / Linux：运行 setup.sh

./setup.sh

脚本会先播放一个开场动画，然后进入交互式主菜单。值得注意的是，从 setup.sh 的源码可以看到：如果检测到已存在且非空的.env文件，脚本会打印其前几行并要求用户确认是否覆盖——也就是说重复运行 setup 会重写.env，已有自定义配置的部署需先备份。

主菜单提供五个选项（见 setup.sh#L113-L125）：

Welcome to DocsGPT Setup! How would you like to proceed? 1) Use DocsGPT Public API Endpoint (simple and free, uses pre-built Docker images from Docker Hub for fastest setup) 2) Serve Local (with Ollama) 3) Connect Local Inference Engine 4) Connect Cloud API Provider 5) Advanced: Build images locally (for developers)

Windows：运行 setup.ps1

Windows 用户执行功能等价的 PowerShell 脚本：

PowerShell -ExecutionPolicy Bypass -File .\setup.ps1

无论哪个脚本，都会自动完成.env配置、必要的下载与安装。

五种部署模式详解（源码级解读）

以下每个模式对应的行为均直接来自 setup.sh 的实现，可以看到脚本最终写入了哪些.env变量、启动了哪个 compose 文件。

模式 1：使用 DocsGPT 公共 API 端点（最简单、免费）

这是最省心的选项：无需 API key、无需下载本地模型。脚本写入（setup.sh#L447-L471）：

LLM_PROVIDER=docsgpt VITE_API_STREAMING=true

然后使用预构建镜像（Docker Hub）的 docker-compose-hub.yaml 执行pull+up -d。脚本默认推荐此路径，以避免本地构建错误、加快上手。

模式 2：本地 Ollama 服务（CPU / GPU）

选择后先选 CPU 或 GPU，再输入模型名（默认llama3.2:1b，约 1.3GB）。脚本会生成（setup.sh#L473-L567）：

API_KEY=xxxx LLM_PROVIDER=openai LLM_NAME=<你选择的模型，默认 llama3.2:1b> VITE_API_STREAMING=true OPENAI_BASE_URL=http://ollama:11434/v1 EMBEDDINGS_NAME=ibm-granite/granite-embedding-311m-multilingual-r2

并叠加可选 compose 文件 optional/docker-compose.optional.ollama-cpu.yaml 或ollama-gpu.yaml——前者以ollama/ollama镜像启动服务、映射11434端口并挂载ollama_data卷。脚本会等待 Ollama 容器进入 running 状态后，自动执行docker compose exec -it ollama ollama pull <model>拉取模型。GPU 模式的前提是机器有受支持的 GPU 且 Docker 已配置 GPU 支持。

模式 3：连接已有的本地推理引擎

如果你已在主机上运行了推理服务，该选项通过host.docker.internal回连宿主机。脚本为八种引擎预设了 OpenAI 兼容的 base URL（setup.sh#L581-L628）：

引擎	预设 OpenAI_BASE_URL
LLaMa.cpp	`http://host.docker.internal:8000/v1`
Ollama	`http://host.docker.internal:11434/v1`
TGI	`http://host.docker.internal:8080/v1`
SGLang	`http://host.docker.internal:30000/v1`
vLLM	`http://host.docker.internal:8000/v1`
Aphrodite	`http://host.docker.internal:2242/v1`
FriendliAI	`http://host.docker.internal:8997/v1`
LMDeploy	`http://host.docker.internal:23333/v1`

生成的.env为：

API_KEY=None LLM_PROVIDER=openai LLM_NAME=<模型名，可留空为 None 稍后修改> VITE_API_STREAMING=true OPENAI_BASE_URL=<对应引擎地址> EMBEDDINGS_NAME=ibm-granite/granite-embedding-311m-multilingual-r2

模型名允许留空（置为None），提示语明确说可以稍后在.env中修改。该模式统一走 OpenAI API 格式，因此任何 OpenAI 兼容端点（包括 Ollama、llama_cpp 等）都能接入。

模式 4：连接云端 API Provider

选择供应商后输入 API key（脚本提示密钥仅保存在本地.env）。各供应商的默认模型见下表（setup.sh#L663-L744）：

供应商	LLM_PROVIDER	默认 LLM_NAME
OpenAI	`openai`	`gpt-4o`
Google（Vertex AI / Gemini）	`google`	`gemini-2.0-flash`
Anthropic（Claude）	`anthropic`	`claude-3-5-sonnet-latest`
Groq	`groq`	`llama-3.1-8b-instant`
HuggingFace Inference API	`huggingface`	`meta-llama/Llama-3.1-8B-Instruct`
Novita	`novita`	`moonshotai/kimi-k2.5`

生成的.env：

API_KEY=<你的密钥> LLM_PROVIDER=<对应 provider> LLM_NAME=<默认模型> VITE_API_STREAMING=true

后端为这些供应商各自实现了独立的 Provider 适配层，可以在 application/llm 目录中查阅：openai.py、anthropic.py、google_ai.py、groq.py、novita.py、llama_cpp.py，以及负责按 provider 名创建实例的工厂 llm_creator.py——这与 setup 脚本写入的LLM_PROVIDER取值一一对应。

模式 5：本地构建镜像（开发者向）

选择此项会使用可本地构建的 docker-compose.yaml（其中frontend与backend/worker均指定build:上下文而非image:），从源码构建前后端。适合修改 DocsGPT 内部实现、在离线环境运行、或验证本地变更。

高级配置菜单

选定主模式后，脚本会询问是否进入高级设置（setup.sh#L412-L444），包含六个子项。以下逐项说明其写入的.env变量与默认值。

向量存储（VECTOR_STORE）

选项	写入变量	说明
FAISS（默认，本地）	`VECTOR_STORE=faiss`	零配置
Elasticsearch	`VECTOR_STORE=elasticsearch`、`ELASTIC_URL`、`ELASTIC_CLOUD_ID`、`ELASTIC_USERNAME`、`ELASTIC_PASSWORD`、`ELASTIC_INDEX`（默认`docsgpt`）	URL 或 Cloud ID 二选一
Qdrant	`VECTOR_STORE=qdrant`、`QDRANT_URL`、`QDRANT_API_KEY`、`QDRANT_COLLECTION_NAME`（默认`docsgpt`）
Milvus	`VECTOR_STORE=milvus`、`MILVUS_URI`（默认`./milvus_local.db`）、`MILVUS_TOKEN`、`MILVUS_COLLECTION_NAME`（默认`docsgpt`）
LanceDB	`VECTOR_STORE=lancedb`、`LANCEDB_PATH`（默认`./data/lancedb`）、`LANCEDB_TABLE_NAME`（默认`docsgpts`）
PGVector	`VECTOR_STORE=pgvector`、`PGVECTOR_CONNECTION_STRING`	例如`postgresql://user:pass@host:5432/db`

这些选项对应后端 application/vectorstore 目录下的同名实现文件（如 qdrant.py、pgvector.py、milvus.py 等），由 vector_creator.py 工厂按VECTOR_STORE创建实例。

Embeddings（EMBEDDINGS_NAME）

Granite multilingual（默认，本地）：EMBEDDINGS_NAME=ibm-granite/granite-embedding-311m-multilingual-r2
OpenAI Embeddings：EMBEDDINGS_NAME=openai_text-embedding-ada-002，可选单独填写EMBEDDINGS_KEY（留空则复用 LLM 的API_KEY）
自定义远程 Embeddings（OpenAI 兼容）：填写EMBEDDINGS_NAME、EMBEDDINGS_BASE_URL、EMBEDDINGS_KEY
all-mpnet-base-v2（遗留本地，仅英文）：EMBEDDINGS_NAME=huggingface_sentence-transformers/all-mpnet-base-v2

本地与远程 embeddings 的实现分别位于 application/vectorstore/embeddings_local.py、application/vectorstore/embeddings_openai.py 与 application/vectorstore/embeddings_delegated.py。

其他四项

认证（AUTH_TYPE）：无认证（默认）、simple_jwt、session_jwt；后两者可手填或自动生成JWT_SECRET_KEY（脚本用openssl rand -hex 32生成，见 setup.sh#L291-L332）；
集成：Google Drive（GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET）、GitHub（GITHUB_ACCESS_TOKEN）；
文档处理：PARSE_PDF_AS_IMAGE=true（将 PDF 页面按图片解析，提升表格/图表抽取效果）、DOCLING_OCR_ENABLED=true（启用 Docling OCR）；
TTS：TTS_PROVIDER=google_tts（默认，免费）或TTS_PROVIDER=elevenlabs（需ELEVENLABS_API_KEY），对应 application/tts 下的 google_tts.py 与 elevenlabs.py。

另外，脚本进入高级设置前会确保.env中存在INTERNAL_KEY（worker 与 backend 之间的内部鉴权密钥，自动生成 64 位十六进制串，见 setup.sh#L403-L410）。

运行时容器架构

理解deployment/下的 compose 文件，就能看懂 DocsGPT 的运行时拓扑。以预构建版 docker-compose-hub.yaml 为准（本地构建版 docker-compose.yaml 结构一致，仅把镜像换成build:）：

服务	镜像 / 构建	端口	职责
`frontend`	`arc53/docsgpt-fe:develop`	`5173`	Web UI，`VITE_API_HOST`指向`http://localhost:7091`
`backend`	`arc53/docsgpt:develop`	`7091`	Flask 后端 API 入口（application/app.py）
`worker`	同 backend 镜像	—	Celery worker，命令为`celery -A application.app.celery worker -l INFO -B -Q docsgpt,parsing,embeddings`
`redis`	`redis:6-alpine`	`6379`	同时充当 Celery broker（db0）、结果后端（db1）与缓存（db2）
`postgres`	`postgres:16-alpine`	`5432`	用户数据（`docsgpt/docsgpt`），带`pg_isready`健康检查

几个值得注意的细节：

Redis 一个实例三个角色：CELERY_BROKER_URL=redis://redis:6379/0、CELERY_RESULT_BACKEND=redis://redis:6379/1、CACHE_REDIS_URL=redis://redis:6379/2分别复用同一 Redis 的不同逻辑库（docker-compose-hub.yaml#L16-L36）。
worker 的多队列设计：compose 文件中明确注释了队列语义——parsing队列承载read_document/parse_document任务，缺了它read_document的 await 永远不返回；embeddings队列承载查询侧 embedding，默认开启委托到 worker（EMBEDDINGS_DELEGATE_TO_WORKER）时，缺了它所有搜索会在超时后失败。重度 OCR 场景可另起一个-Q parsing的 worker，用独立 worker 跑-Q embeddings则能把查询延迟与摄取池隔离（docker-compose.yaml#L39-L48）。
数据卷：backend/worker 共同挂载../application/indexes、../application/inputs、../application/vectors三个目录，持久化 FAISS 索引、输入文档与向量；Postgres 数据通过命名卷postgres_data持久化。
依赖顺序：backend 与 worker 都要求redis已启动、postgres健康检查通过后才启动。
沙箱代码执行是选配：code_executor/artifact_generator工具的沙箱执行默认不在栈中，需叠加optional/docker-compose.optional.sandbox.yaml（见 docker-compose-hub.yaml#L62-L67 注释与 deployment/sandbox/README.md）。

访问与停止应用

启动完成后，在浏览器打开http://localhost:5173/即可使用 DocsGPT Web 应用（前端 dev 服务器端口）。停止应用时，在DocsGPT目录运行：

docker compose -f deployment/docker-compose.yaml down

或者直接使用 setup 脚本结束时打印的完整命令（可能包含 Ollama 等叠加的 compose 文件）。

项目目录结构

README.md 给出的顶层结构如下，仓库实际内容与之一致：

application/—— 后端 Flask 应用：API 路由（application/api）、LLM 适配层（application/llm）、向量存储（application/vectorstore）、解析器（application/parser）、Agent 与工具（application/agents）、Celery worker（application/worker.py）与 Alembic 数据库迁移（application/alembic/versions）；
frontend/—— 基于 Vite + React 的 Web UI（frontend/package.json）；
extensions/—— 集成与组件，包括 Chatwoot 机器人（extensions/chatwoot）与 React 聊天组件（extensions/react-widget）；
scripts/—— 杂项工具脚本（数据库回填、e2e 环境等，scripts/db）；
deployment/—— Docker Compose 编排与 Kubernetes 清单（deployment/k8s 支持 README 中提到的 K8s 部署能力）。

贡献、规范与许可证

贡献方式、issue 与 PR 流程见 CONTRIBUTING.md；
社区行为准则见 CODE_OF_CONDUCT.md；
源代码采用MIT 许可证，详见 LICENSE。

小结

DocsGPT 通过setup.sh/setup.ps1把“选模型来源 → 写.env→ 起 Docker Compose”这条链路完全脚本化：五档模型接入模式（公共 API、Ollama、八种本地推理引擎、六家云端 Provider、本地构建镜像）覆盖了从零配置到完全离线的全部部署形态；.env中的LLM_PROVIDER、LLM_NAME、OPENAI_BASE_URL、VECTOR_STORE、EMBEDDINGS_NAME等变量与后端 llm_creator.py、vector_creator.py 工厂一一对应，修改任一变量即可切换模型与检索栈，而无需改动代码。容器架构上，frontend / backend / worker / redis / postgres 五服务分工明确，Celery 三队列（docsgpt、parsing、embeddings）把文档解析与查询 embedding 从主请求池剥离，为私有化企业检索与 Agent 场景提供了清晰的水平扩展路径。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析