安装前先弄清 PrivateGPT 适合什么场景

PrivateGPT 是一类面向本地文档问答的 AI 工具。常见用法是把 PDF、Word、Markdown、文本资料导入到本机，再通过大模型进行检索和回答。

它的优势是资料不必上传到第三方平台，适合个人笔记整理、公司内部资料检索、项目文档问答、离线知识库实验等场景。

需要注意的是，它不是“装好就一定流畅”的轻量软件。运行效果与 Mac 芯片、内存、Python 环境、模型大小和依赖版本都有关系。

对 macOS 新手来说，推荐采用“Ollama 提供本机模型能力，PrivateGPT 提供文档问答界面”的方式部署。这样可以少处理底层推理编译问题，安装路径更清晰，也便于后续更换模型。

下文以 Apple Silicon 芯片的 Mac 为主要说明对象。Intel Mac 也可参考，但在模型速度和依赖兼容上需要更保守。

硬件与系统检查清单

第一项：确认 Mac 类型

点击左上角苹果图标，进入“关于本机”，查看芯片信息。M1、M2、M3、M4 属于 Apple Silicon，建议使用 arm64 版本终端和工具链。Intel Mac 则选择 x86_64 工具链，避免混装导致依赖报错。

第二项：确认内存

8GB 内存可以做入门测试，建议选择 3B 或 7B 级别的小模型，导入文档数量也不要太多。16GB 内存体验更稳。32GB 以上更适合长期运行较大的知识库。

第三项：确认系统版本

建议 macOS 13 或更新版本。旧系统可能在 Python、编译工具、证书和依赖安装上遇到更多问题。

第四项：预留磁盘空间

源码和虚拟环境通常需要数 GB。模型文件可能从几 GB 到十几 GB 不等。文档向量索引也会持续占用空间。建议至少预留 30GB 可用空间，避免安装到一半失败。

基础工具安装：先把地基打稳

打开“终端”，先安装 Apple 命令行工具：xcode-select --install。若弹出安装窗口，按提示完成即可。它提供编译依赖时需要的基础工具。

接着安装 Homebrew。若已经安装，可执行 brew --version 检查版本。没有安装时，可到 Homebrew 官方页面复制安装命令。安装完成后，建议执行 brew doctor 查看环境是否健康。

Apple Silicon 机型通常安装在 /opt/homebrew，Intel 机型通常安装在 /usr/local，不建议手动混用路径。

继续安装常用依赖：brew install git cmake pkg-config pyenv poetry。Git 用于获取源码，CMake 和 pkg-config 用于部分 Python 包编译，pyenv 用于管理 Python 版本，Poetry 用于项目依赖管理。

安装后分别执行 git --version、cmake --version、poetry --version，能看到版本号就说明基础工具可用。

配置 Python：建议使用 3.11 系列

PrivateGPT 这类项目对 Python 版本比较敏感，建议使用 Python 3.11，而不是系统自带 Python。执行 pyenv install 3.11.9，安装完成后新建项目目录，例如 mkdir -p ~/ai-labs && cd ~/ai-labs。随后执行 pyenv local 3.11.9，让该目录默认使用指定版本。

检查命令为 python --version，输出应为 Python 3.11.x。如果仍显示系统版本，通常是 shell 初始化没有配置好。可根据 pyenv 的提示，把初始化语句加入 ~/.zshrc，然后执行 source ~/.zshrc。

新手不要反复卸载系统 Python，也不要随意改 /usr/bin 下的文件，容易影响系统工具。

安装 Ollama 并拉取模型

进入 Ollama 官方页面下载 macOS 版本，安装后打开应用，确认菜单栏中能看到它正在运行。然后在终端执行 ollama --version。如果无法识别命令，重启终端或检查安装路径。

接着拉取一个对新手友好的对话模型：ollama pull llama3.1:8b。若内存较小，可以选择更小的模型。

再拉取嵌入模型：ollama pull nomic-embed-text。嵌入模型负责把文档切成可检索的向量，是本地知识库问答的关键组件。

完成后可执行 ollama list，确认两个模型都在列表中。

获取 PrivateGPT 源码并安装依赖

在 ~/ai-labs 目录下执行 git clone https://github.com/zylon-ai/private-gpt.git，然后进入目录：cd private-gpt。建议先查看项目说明文件，确认当前版本推荐的安装方式，因为开源项目依赖可能随时间调整。

常见安装方式是使用 Poetry 创建隔离环境。可执行 poetry env use python，然后安装带界面、本机模型和嵌入能力的依赖：poetry install --extras "ui llms-ollama embeddings-ollama vector-stores-qdrant"。如果项目说明中给出 make setup 或其他命令，应以项目当前说明为准。

安装过程可能耗时较长，尤其是首次解析依赖和编译组件时。不要在中途频繁关闭终端。若出现编译相关错误，先确认 cmake、pkg-config、命令行工具是否已经安装，再重新执行安装命令。

配置文件与启动方式

PrivateGPT 通常通过配置文件或环境变量选择运行方案。若项目目录中有 settings-ollama.yaml、settings.yaml、example 文件，可先复制示例配置，再按 Ollama 地址、模型名称、嵌入模型名称进行核对。

Ollama 默认服务地址通常是 http://localhost:11434，模型名称要与 ollama list 中显示的名称一致，例如 llama3.1:8b 和 nomic-embed-text。

启动时可使用类似 PGPT_PROFILES=ollama poetry run python -m private_gpt 的方式。部分版本也支持 make run。启动成功后，终端通常会显示本地访问地址，例如 http://localhost:8001。

用浏览器打开该地址，若能看到上传文档、提问输入框或管理界面，说明主流程已经打通。

文档导入与效果验证

第一次测试不要直接导入大量资料。建议准备一份 3 到 10 页的 PDF 或 Markdown 文档，内容结构清晰，文件名使用英文或简单中文，避免特殊符号。

上传后等待索引完成，再提问文档中明确出现的问题，例如“这份文档分为哪几部分”“项目启动步骤是什么”。

如果回答明显偏离，先检查文档是否成功导入，再检查嵌入模型是否配置正确。若文档是扫描版 PDF，可能没有可提取文本，需要先做文本识别处理。若文档很长，回答不完整也很常见，可以按章节拆分，提升检索命中率。

常见问题排查

问题一：poetry install 失败

优先检查 Python 是否为 3.11，执行 poetry env info 查看虚拟环境路径；必要时删除当前虚拟环境后重装。

问题二：提示找不到 cmake 或编译失败

执行 brew install cmake pkg-config，并确认 xcode-select --install 已完成。

问题三：Ollama 模型无法调用

先执行 ollama list 确认模型存在，再执行 ollama run llama3.1:8b 测试模型是否可对话。若命令行可用但 PrivateGPT 不可用，重点检查配置中的模型名称和服务地址。

问题四：打开页面失败

确认终端中服务没有退出，查看是否有报错；再检查端口是否被占用，可用 lsof -i :8001 查看。若端口冲突，修改配置中的端口或关闭占用进程。

问题五：运行很慢

优先换更小模型，减少一次导入的文档量，关闭占内存较高的软件。

安全边界与使用建议

虽然 PrivateGPT 强调本地化，但并不意味着所有风险自动消失。不要把账号密钥、客户资料、合同原件、未授权内部文件直接导入测试环境。团队使用时，应明确资料来源、访问权限和清理规则，避免把临时测试目录变成长期资料堆放区。

模型回答也不能直接当作事实结论。它可能因为检索片段不足、文档格式异常或模型能力限制产生错误回答。重要内容应回到原文核对。

对于有版权或使用许可限制的模型和资料，也要遵守对应条款，不要把测试环境扩展成不合规的生产服务。

新手最终检查清单

部署完成后，按顺序确认：

• macOS 版本满足要求
• 终端架构与芯片一致
• Homebrew、Git、CMake、Poetry 可显示版本号
• Python 为 3.11
• Ollama 正在运行
• 对话模型和嵌入模型已拉取
• PrivateGPT 依赖安装无报错
• 配置中的模型名称与本机列表一致
• 本地页面可打开
• 小文档可上传并完成问答

如果以上检查全部通过，就已经具备基础可用环境。后续优化可以从三方面入手：一是选择更适合中文资料的模型，二是按主题整理文档并分批索引，三是定期备份配置和索引目录。

对 macOS 新手而言，先跑通小规模流程，再逐步扩大资料量，比一次追求复杂配置更稳妥。