PrivateGPT 中文教程：把本地模型变成带知识库的 AI 接口

一、它到底解决什么问题

入门

你可能已经听说「本地跑大模型」这件事，也装过 Ollama 这类工具，发现它确实能对话。但真正想做一个能上传文档、能回答公司制度、能被自己写的脚本调用的系统时，会发现只有模型本身远远不够。

PrivateGPT 就是补上这一段的：它不负责运行模型，而是架在模型之上，提供一整套接口能力，比如带知识库的问答（RAG）、调用工具、执行 MCP 协议、把自然语言转成数据库查询等。

可以把三者的关系想成餐厅：

本地推理服务（Ollama、llama.cpp、vLLM）＝后厨的厨师，负责真正「炒菜」；
PrivateGPT ＝前台经理，负责点单、配菜、决定哪道菜端给谁；
你的应用或工作流 ＝客户，只管说想吃什么。

架构顺序是固定的：你的应用 → PrivateGPT 接口 → 任何兼容 OpenAI 格式的推理服务。只要后者实现了 /v1/chat/completions 和 /v1/models 两个接口，就能被 PrivateGPT 接管，所以后厨换成哪家都行。

二、安装前需要准备什么

入门

先说清楚前置条件，免得装到一半卡住：

一台能联网的电脑。安装过程要下载依赖包，Linux、macOS 都支持，Windows 用 PowerShell。
一个正在运行的 OpenAI 兼容推理服务。最省事的选择是 Ollama，因为它默认就提供兼容接口，装完拉个模型就能用。
Python 3.11。不用你自己手动装，下面用到的 uv 工具会自动准备，写在这里只是让你知道它为什么在命令里出现。

uv 是一个 Python 包管理器（可以理解成「自动帮你下载并隔离运行环境的安装器」），PrivateGPT 在 Linux 上通过它安装。

先装 Ollama 并拉一个模型，Mac 和 Linux 通常一行命令即可，装好后运行 ollama pull 拉取一个你机器跑得动的模型。建议先选 7B～8B 的小模型，显存或内存不够时大模型会非常卡。

三、安装 PrivateGPT

入门

macOS 用户走 Homebrew（Mac 上常用的软件安装器）：

brew tap zylon-ai/tap
brew install private-gpt

Linux 用户先装 uv，再用它装 PrivateGPT：

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]"

private-gpt[core] 里的 [core] 表示安装核心功能集合，对新手来说够用；等你确定需要某些扩展能力时，再按官方文档补装对应的可选组件即可。

装完验证一下，终端里敲：

private-gpt --help

能打印出用法说明，就说明命令已经进入系统路径，可以进入下一步。

四、启动服务并跑通第一次问答

入门

这一步的关键是把 PrivateGPT 指向你的推理服务。PrivateGPT 通过两个环境变量知道后厨在哪：

OPENAI_API_BASE：对话模型的地址；
OPENAI_EMBEDDING_API_BASE：向量化模型的地址（RAG 知识库需要把你的文档切成碎片并转成一串数字，负责这件事的模型叫 embedding 模型，通常也需要单独的服务）。

在 Linux 或 macOS 的终端里执行（端口号按你实际的推理服务来改）：

export OPENAI_API_BASE="http://localhost:<llm-port>/v1"
export OPENAI_EMBEDDING_API_BASE="http://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

提示：用 Ollama 时，对话和向量化通常都由同一个端口提供，两个变量填同一个地址即可。把 <llm-port> 替换成实际端口号，不要带着尖括号原样输入。

服务起来后，浏览器打开 http://localhost:8080/ui，你会看到一个自带的网页工作台。

PrivateGPT 自带的网页工作台界面

这个界面主要用来做三件事：发消息测试对话、从 /v1/models 列表里切换模型、上传文档试知识库问答。它定位是调试和演示，真正的「产品」是背后的 API 接口。

五、配置：理解配置文件在哪里改

进阶 · 推荐细读

跑通之后，你大概率会想改点东西：换模型、调系统提示词、改端口。这些都在配置文件里完成。

PrivateGPT 的配置思路是「分层覆盖」：先有一份出厂默认配置，然后你自己的本地配置文件覆盖它。好处是升级版本时不会把你改过的内容冲掉，你只需要维护那几行差异。

建议新手只动下面几类配置：

想做什么	改哪里
换对话模型、换向量化模型	模型相关配置项
改监听端口	服务端口配置项
让 AI 用固定口吻回答	系统提示词
让知识库检索更准	检索条数、切分长度

官方文档的 Quickstart 页面给出了完整的配置项清单和 Docker 部署方式；这里只强调原则：改之前先备份原文件，改完重启服务生效，每次只改一项再测，出问题容易定位。

如果你完全没写过代码，也可以先全部用默认值，只通过界面上的模型下拉框切换模型，等熟悉了再碰配置文件。

六、把接口接进你的运维体系

进阶 · 推荐细读

服务能跑只是起点，接下来要考虑它怎么长期、稳定地待在你的机器上。

开机自启与托管：如果是一台 Linux 服务器，常见做法是写一个 systemd 服务单元（systemd 是大多数 Linux 发行版的进程管理器，负责让程序崩溃后自动拉起、开机自动运行），把 private-gpt serve 作为其中一条启动命令，并在文件里写好那两个环境变量。

容器化部署：如果你的机器上已经有 Docker（一种把软件打包成「集装箱」、在任何机器上都能一致运行的工具），官方文档提供了对应的镜像部署方式，适合和已有的服务一起编排管理。

接入自动化工具：PrivateGPT 暴露的是标准 HTTP 接口，所以任何能发 HTTP 请求的东西都能调用它——比如 n8n 这类自动化编排工具，把「收到邮件 → 提取摘要 → 存入表格」这样的流程串起来：

用 n8n 调用 PrivateGPT 的自动化流程

给终端里的编程助手当后端：PrivateGPT 也能作为本地推理后端，给命令行里的 AI 编程工具使用，让代码补全和问答走你自己的模型，不经过云端。

Claude 等工具配合 PrivateGPT 使用的场景

接入任何系统前，先用 curl 或界面确认接口通了再往下走。顺序是：先保证 http://localhost:8080 有响应，再保证 /v1/models 能列出模型，最后才调试你的调用代码。

七、常见踩坑

深入 · 老手可选

S.A.O