ARTICLE · 1327350

DocsGPT 私有化文档问答实践教程

发布时间：2026-11-07 19:33:41 最近访问：2026-11-07 19:33:42

DocsGPT 私有化文档问答实践教程

极客深潜录 · HANDS-ON TUTORIAL

DocsGPT 私有化文档问答实践教程

让 AI 基于你的内部文档回答，且每个答案都带来源引用：从一键安装到 Agent 创建、OpenAI 兼容 API 调用与 guardrails 防护，全流程动手实战。

CHAPTER 01

环境准备与安装

DocsGPT 是基于文档的私有化开源 AI Agent 平台：文档、站点与连接的应用变成带来源引用的问答服务，API、Worker、数据库、向量库全部跑在你自己的环境里。本节用官方一键安装器把整套栈拉起来。

1.1 环境要求

项目	要求	说明
Docker	必需	一键安装器会先检查 Docker，再安装 docsgpt 命令
操作系统	macOS / Linux / Windows	Windows 使用 PowerShell 安装命令
Python	3.12+	仅源码方式部署需要
模型	云端或本地	OpenAI / Anthropic / Google / Groq，或 Ollama、vLLM 本地模型
端口	7091	本机部署默认入口 http://localhost:7091

1.2 安装

官方提供跨平台一键安装器：docsgpt up 会交互式询问「谁能访问 DocsGPT」与「用哪个模型」，一条命令完成安装与启动。

terminal — install

# macOS / Linux 一键安装$ curl -fsSL https://docs.ac/install | bash# Windows PowerShell$ irm https://docs.ac/install.ps1 | iex# 启动（询问访问范围与模型）$ docsgpt up# 查看版本、地址与健康状态$ docsgpt status

[WARNING] 版本提醒

安装器要求 Docker 已就绪；本机部署默认从 http://localhost:7091 打开。除一键安装外，官方还提供 Docker Compose、pip、Kubernetes 与 air-gapped 隔离网安装方式。

CHAPTER 02

跑通核心流程

栈跑起来后，把一份文档变成能回答问题的 Agent，再用 OpenAI 兼容 API 验证整条链路。

2.1 创建第一个 Agent

打开 http://localhost:7091，把一份 PDF 拖进知识库——内置 parser 支持 PDF、Office 文件、网页与音频。然后创建 Agent：每个 Agent 由提示词、知识、工具、模型四要素组成，绑定知识库后一键发布。对着它提问，每个回答都会引用来源文档。

2.2 用 OpenAI 兼容 API 验证

DocsGPT 暴露 OpenAI 兼容的 /v1 接口——把任意 OpenAI SDK 的 base_url 指向本机即可复用现有代码：

ask.py — 用 OpenAI SDK 调 DocsGPT

from openai import OpenAIclient = OpenAI( base_url="http://localhost:7091/v1", api_key="你的 DocsGPT Key",)resp = client.chat.completions.create( model="按平台配置填写", messages=[{"role": "user", "content": "退款流程需要哪些材料？"}],)print(resp.choices[0].message.content)

terminal — output

$ python ask.py办理退款需准备：1) 订单号；2) 支付凭证……来源：《售后手册》第 3 章退款流程

[TIP] 实践建议

先拿一份 10 页以内的小文档打通「上传 → 建索引 → 提问」全链路，确认回答带来源，再批量导入大知识库。

CHAPTER 03

进阶配置

仓库根目录的 .env-template 是配置全貌：模型密钥、worker 认证、嵌入策略与认证模式，都在这一份文件里。

3.1 配置文件

.env-template — 核心配置节选

API_KEY=你的 LLM API KeyLLM_NAME=docsgptVITE_API_STREAMING=true# 必填：worker 把完成的索引交给 API 用它，缺失则所有 ingest 失败# API 与 worker 两边必须同值，用 openssl rand -hex 32 生成INTERNAL_KEY=internal key# 其他机器访问时的对外地址（默认 http://localhost:7091）# API_URL=https://docs.example.com# 嵌入计算挪到 Celery worker：API 常驻内存约 660MB 降到 285MB# EMBEDDINGS_DELEGATE_TO_WORKER=true# EMBEDDINGS_QUEUE=embeddings# 认证：None / simple_jwt / session_jwt / oidc# AUTH_TYPE=None# JWT_SECRET_KEY=openssl rand -hex 32 生成

3.2 参数说明

参数	必填	说明
API_KEY	是	主 LLM 的 API Key，也支持按供应商分别配置
INTERNAL_KEY	是	worker 与 API 之间的认证密钥，两边同值，缺失则所有 ingest 失败
API_URL	否	对外访问地址，影响回调链接的拼装
EMBEDDINGS_NAME	否	嵌入模型，留空自动选型；切换必须重建索引
AUTH_TYPE	否	从无认证到 OIDC SSO 四档，多用户场景用 oidc

[INFO] 配置说明

嵌入模型切换有个隐蔽的坑：新旧模型同为 768 维时检索会「静默失败」——查询打向与存储向量不同的向量空间。切换模型后务必执行 python -m docsgpt.scripts.reembed 重建索引。

CHAPTER 04

进阶实战

单份文档跑通后，把 DocsGPT 变成持续同步的团队知识服务：连接器保新鲜、guardrails 保安全、多渠道发布到产品里。

接入连接器

连接 Google Drive、SharePoint、Confluence、GitHub、S3 等知识源并设置定时同步，告别手动重复导入。

建 Agent 并开防护

Agent 绑定知识库，按需开启 guardrails：标记、脱敏或阻断 PII、密钥、提示注入与无来源回答。

发布到产品

script 标签或 React 包把 chat widget 嵌入网站；OpenAI SDK 指向 /v1；或启用 MCP server 让 Claude、Cursor 直接检索知识。

手动上传

适合一次性资料与个人小库，上传即用，但知识不会自动更新。

连接器定时同步

适合团队规模的知识源，文档改动自动进索引，回答始终对齐最新版本。

云端模型

OpenAI、Anthropic、Groq 等开箱即用，效果优先，适合大多数场景。

本地模型

通过 Ollama、vLLM 等加载，数据不出内网，支持 air-gapped 隔离网部署。

CHAPTER 05

调试与常见问题

文档问答链路长（解析 → 分段 → 嵌入 → 检索 → 生成），出问题时先按这张表定位环节。

5.1 常见问题排查

问题	原因与解决方案
文档上传后 ingest 失败	INTERNAL_KEY 未设置，或 API 与 worker 两边值不一致。用 openssl rand -hex 32 生成后两边同值。
换嵌入模型后检索质量骤降	新旧模型同为 768 维导致静默失败，跑 python -m docsgpt.scripts.reembed 重建向量索引。
内存吃紧	API 默认自带嵌入模型约 660MB 常驻。开 EMBEDDINGS_DELEGATE_TO_WORKER=true 降到约 285MB，并确保 worker 消费 EMBEDDINGS_QUEUE。
外部机器打不开或回调链接错	API_URL 仍是 localhost。改成实际对外地址（代理后填 https 域名）并重启。