5分钟上手PrivateGPT：从安装到首次文档问答全流程

你是否还在为企业敏感文档无法安全使用AI而烦恼？是否担心数据上传云端导致泄密风险？PrivateGPT作为一款本地部署的文档问答工具，让你无需联网即可实现基于私有数据的智能问答。本文将带你5分钟内完成从环境搭建到首次文档交互的全流程，让企业级文档处理能力即刻落地。

读完本文你将掌握：

• 3步完成PrivateGPT本地化部署
• 文档智能导入与知识库构建
• 首次私密问答交互全流程
• 常见问题快速排查方案

项目简介与核心优势

PrivateGPT是一个生产级AI项目，允许你使用大型语言模型（LLM）对文档进行提问，即使在没有互联网连接的情况下也能正常工作。100%私密，数据绝不会离开你的执行环境。项目提供API接口，封装了RAG（检索增强生成） pipeline的所有复杂性，同时提供了一个可用的Gradio UI客户端来测试API。

核心功能模块包括：

• 文档摄入：内部管理文档解析、拆分、元数据提取、嵌入生成和存储
• 聊天与补全：使用摄入文档的上下文，抽象上下文检索、提示工程和响应生成
• 嵌入生成：基于文本生成嵌入向量
• 上下文块检索：根据查询返回最相关的文本块

项目架构采用FastAPI构建API，遵循OpenAI的API规范，RAG pipeline基于LlamaIndex构建，主要代码实现位于private_gpt/目录下。

环境准备与快速安装

基础环境要求

开始安装前，请确保你的系统满足以下要求：

• Python 3.11（建议通过pyenv安装）
• Poetry依赖管理工具
• Git版本控制工具
• Make命令支持

三步安装法

第一步：克隆代码仓库

git clone https://gitcode.com/gh_mirrors/pr/private-gpt
cd private-gpt

第二步：安装Python与依赖

# 安装Python 3.11
pyenv install 3.11
pyenv local 3.11

# 安装Poetry
curl -sSL https://install.python-poetry.org | python3 -

# 安装make（根据操作系统选择）
# MacOS: brew install make
# Windows: choco install make

第三步：安装PrivateGPT核心组件

我们推荐使用Ollama作为本地LLM后端，这是在本地运行PrivateGPT最简单的方式：

# 安装必要组件
poetry install --extras "ui llms-ollama embeddings-ollama vector-stores-qdrant"

配置与启动服务

Ollama配置

1. 首先从ollama.ai下载并安装Ollama
2. 安装所需模型：

ollama pull mistral
ollama pull nomic-embed-text

3. 启动Ollama服务：

ollama serve

启动PrivateGPT

在新的终端中，运行以下命令启动PrivateGPT：

PGPT_PROFILES=ollama make run

PrivateGPT将使用已有的settings-ollama.yaml配置文件，该文件已配置为使用Ollama LLM和Embeddings，以及Qdrant向量存储。服务启动后，UI将在 http://localhost:8001 可用。

文档导入与知识库构建

文档导入方法

PrivateGPT支持多种方式导入文档：

1. 通过UI界面上传：启动服务后，访问http://localhost:8001，在界面中找到文件上传区域，选择要导入的文档即可。

2. 通过命令行导入：使用提供的脚本批量导入文件夹中的文档：

poetry run python scripts/ingest_folder.py --folderpath your_document_folder

文档处理逻辑主要在private_gpt/components/ingest/ingest_component.py中实现，支持多种文档格式的解析与处理。

知识库管理

导入的文档会被自动处理为可检索的向量数据，存储在向量数据库中。PrivateGPT支持多种向量存储后端，包括Qdrant、Chroma和Postgres，默认配置使用Qdrant。相关配置可在settings.yaml中修改。

首次文档问答交互

基本问答操作

1. 打开浏览器，访问http://localhost:8001
2. 在左侧聊天输入框中输入你的问题
3. 点击发送按钮，等待模型生成回答

高级使用技巧

• 上下文控制：可以通过调整prompt参数控制上下文窗口大小，相关代码在private_gpt/components/llm/prompt_helper.py
• 多轮对话：系统会自动维护对话历史，支持多轮上下文连贯的对话
• 文档引用：回答中会自动引用相关文档片段，提高回答可信度

示例问答

假设我们导入了一份关于"公司产品定价策略"的文档，可以进行如下问答：

问："我们公司的产品定价原则是什么？"

答：（系统会从导入的文档中检索相关内容，并生成基于文档的回答）

常见问题与故障排除

服务启动问题

如果服务无法启动，请检查：

• Ollama服务是否已启动
• 所需模型是否已正确下载
• 端口8001是否被占用

文档导入失败

文档导入失败可能原因：

• 文档格式不受支持（目前支持PDF、TXT、MD等常见格式）
• 文档过大（可尝试拆分大型文档）
• 权限问题（确保应用有读取文档的权限）

详细的故障排除指南可参考官方文档：fern/docs/pages/manual/

总结与后续学习

通过本文的指导，你已经成功搭建了PrivateGPT环境，并完成了首次文档问答交互。PrivateGPT为企业和个人提供了安全、私密的文档处理解决方案，避免了数据泄露的风险。

后续可以深入学习的内容：

• 自定义模型配置：private_gpt/components/llm/
• API接口开发：private_gpt/server/
• 高级设置：settings.yaml

官方文档：fern/docs/pages/overview/welcome.mdx 项目教程：README.md

如果你在使用过程中遇到任何问题，欢迎参与社区讨论或查阅项目的问题跟踪。