news 2026/9/9 19:30:05

如何用 uv 从源码安装 PrivateGPT 并以热重载开发模式运行

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
如何用 uv 从源码安装 PrivateGPT 并以热重载开发模式运行

如何用 uv 从源码安装 PrivateGPT 并以热重载开发模式运行

【免费下载链接】privateGPTComplete API layer for private AI applications on local models: RAG, skills, tools, MCP, text-to-sql, and more. Works with any OpenAI-compatible inference server.项目地址: https://gitcode.com/GitHub_Trending/pr/privateGPT

如果你需要修改 PrivateGPT 源码、跑测试或边改代码边看效果，就需要从克隆的仓库出发，用 uv 安装依赖并以开发模式启动服务。这篇文章走通完整路径：安装 uv、克隆仓库、uv sync装依赖、先以普通模式确认服务能起来，最后用--reload参数开启文件变更自动重启的热重载模式。适用前提是：本机已经有一个 OpenAI 兼容的 LLM 服务在运行（官方文档默认以 Ollama 的http://localhost:11434/v1为例），因为 PrivateGPT 本身不运行模型，它通过OPENAI_API_BASE连接外部推理服务。

前置条件

  • Python 版本：pyproject.toml 声明requires-python = ">=3.11,<3.12"，项目只接受 3.11。uv 在uv sync时会自动按这个约束处理解释器。
  • 一个运行中的 LLM 服务：PrivateGPT 启动时会向OPENAI_API_BASE指向的服务发起GET /v1/models并自动注册返回的模型，服务没起来就会无模型可用（见 启动流程说明）。
  • git：用于克隆仓库。

安装 uv

按平台选择官方安装命令（来自 本地安装文档）：

# macOS / Linux curl -LsSf https://astral.sh/uv/install.sh | sh

安装后需要重启 shell，或执行source ~/.zshrc（macOS）/source ~/.bashrc（Linux）让uv命令生效。

# Windows PowerShell powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Windows 上安装后重启 PowerShell 会话即可。

克隆仓库并安装依赖

git clone https://gitcode.com/GitHub_Trending/pr/privateGPT cd privateGPT uv sync --frozen --extra core

说明：

  • 默认的源码安装使用coreextra，它包含了 OpenAI 兼容的 LLM/Embedding 客户端、tokenizer、Qdrant 向量库、文档摄入和工具集（定义见 pyproject.toml 的[project.optional-dependencies]）。
  • 按需追加功能 extra，文档给出的例子是队列支持：uv sync --frozen --extra core --extra queue。不需要时不要多加。
  • 装完可以在private_gpt/包和tests/目录上继续开发，uv sync创建的项目虚拟环境由uv run统一使用。

先以普通模式启动，确认基线可用

在开热重载之前，先用普通方式跑一次，排除环境问题：

# macOS / Linux OPENAI_API_BASE=http://localhost:11434/v1 uv run private-gpt serve
# Windows PowerShell $env:OPENAI_API_BASE = "http://localhost:11434/v1" uv run python -m private_gpt

启动后在浏览器打开 http://localhost:8080/ui 确认界面可访问。服务默认监听8080端口，API 基地址为http://localhost:8080。这一步能通，说明依赖、LLM 连接和配置都没有问题，后面的热重载才有意义。

开启热重载开发模式

文档给出的开发命令是：

# macOS / Linux OPENAI_API_BASE=http://localhost:11434/v1 \ PGPT_PROFILES=local \ uv run private-gpt serve --reload
# Windows PowerShell $env:OPENAI_API_BASE = "http://localhost:11434/v1" $env:PGPT_PROFILES = "local" uv run private-gpt serve --reload

其中--reload是serve命令的开发参数，文件发生变化时自动重启服务（见 CLI 文档 中 serve 的参数表）。

注意PGPT_PROFILES=local的含义：它告诉 PrivateGPT 在基础settings.yaml之上叠加加载settings-local.yaml（profile 命名规则是settings-{name}.yaml，默认定位在项目根目录，可用PGPT_SETTINGS_FOLDER覆盖，见 Settings & Profiles）。仓库本身并没有附带settings-local.yaml，如果该文件不存在，启动会报FileNotFoundError: Settings file not found for profile 'local'（见 Troubleshooting）。所以有两种做法：

  • 你还没有自定义配置：把PGPT_PROFILES=local这一行删掉，直接OPENAI_API_BASE=http://localhost:11434/v1 uv run private-gpt serve --reload即可；
  • 你想覆盖模型、可观测性等配置：先在项目根目录创建settings-local.yaml再启动，需要更细粒度模型设置时参考 Detailed Model Configuration 生成settings-model.yaml的做法。

Makefile 快捷方式（仅 Unix）：

OPENAI_API_BASE=http://localhost:11434/v1 make dev

make dev实际执行的是 Makefile 中的dev目标：PYTHONUNBUFFERED=1 uv run private-gpt serve --reload --host 0.0.0.0 --port 8080。注意它比文档命令多绑定了--host 0.0.0.0，服务会监听所有网卡，在不可信网络环境下要留意这一点。

验证热重载是否生效

文档给出的成功条件是服务可用：启动后打开 http://localhost:8080/ui 能看到界面，API 在http://localhost:8080。修改private_gpt/下任意 Python 文件保存后，服务应自动重启，无需手动 Ctrl+C。

模型是否被正确发现，可以看启动日志，或用文档中列出的接口确认：

curl http://localhost:8080/v1/models

PrivateGPT 启动时会自动向 LLM 服务查询并注册所有返回的模型，GET /v1/models应列出这些模型。

常见问题

按 Troubleshooting 文档：

  • 启动后没有模型 / 报 "no models available"：依次确认 LLM 服务是否在运行（curl http://localhost:11434/v1/models应能返回）、OPENAI_API_BASE是否包含/v1、以及PGPT_LLM_AUTO_DISCOVER_MODELS是否被设成了false（默认true，会自动发现）。
  • FileNotFoundError: Settings file not found for profile 'xxx'：PGPT_PROFILES指向的settings-xxx.yaml在 settings 文件夹（默认项目根目录）中不存在。创建该文件或去掉PGPT_PROFILES环境变量。
  • [Errno 48] Address already in use：8080 端口被占用，用--port换端口，例如private-gpt serve --port 8081。

后续操作

依赖安装完成的基础上，make test、make format、make lint、make typecheck等 Makefile 目标可以直接用于开发和代码质量检查；需要给某个模型单独调 tokenizer、context window 或采样参数时，再按 Settings & Profiles 与 Detailed Model Configuration 生成并使用 profile。

【免费下载链接】privateGPTComplete API layer for private AI applications on local models: RAG, skills, tools, MCP, text-to-sql, and more. Works with any OpenAI-compatible inference server.项目地址: https://gitcode.com/GitHub_Trending/pr/privateGPT

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

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/9/9 19:28:27

JavaScript学习第五天避坑笔记：从报错到工程化的关键知识点

学JavaScript到第五天&#xff0c;我已经不再满足于控制台里打印hello world了。这一天手机里的搜索记录几乎被同一个开头的词塞满&#xff1a;javascript运行时报错、javascript函数、javascript:void(0)、vue javascript项目、为什么elmessage还是提示未定义……每一个热搜词…

作者头像 李华
网站建设 2026/9/9 19:28:13

无重复字符的最长子串：滑动窗口与哈希表优化实战

题名起得有点省&#xff0c;但我一看就懂——又是LeetCode Hot 100系列。如果点进来的朋友已经刷到第3题&#xff0c;说明正式进入“字符串双指针”这个经典战区了。这题作为滑动窗口的入门题&#xff0c;几乎每一场算法面试都有可能出现&#xff0c;不是因为它难&#xff0c;而…

作者头像 李华
网站建设 2026/9/9 19:28:06

Seelen UI完整指南：三步改造你的Windows桌面

Seelen UI完整指南&#xff1a;三步改造你的Windows桌面 【免费下载链接】Seelen-UI The Fully Customizable Desktop Environment for Windows 10/11. 项目地址: https://gitcode.com/GitHub_Trending/se/Seelen-UI Seelen UI 是面向 Windows 10/11 的完全可定制桌面环…

作者头像 李华
网站建设 2026/9/9 19:26:06

新手选云服务器避坑指南：建站、开发测试、游戏开服的5个关键点

新手怎么选云服务器&#xff1f;建站、开发测试和游戏开服的5个避坑点我做了这么多年服务器运维&#xff0c;见过太多新手上来就买了一台自己根本用不上的机器。有人买回来跑个WordPress博客&#xff0c;CPU常年占用不到2%&#xff1b;有人开游戏服&#xff0c;买的机型单核性能…

作者头像 李华
网站建设 2026/9/9 19:25:43

伴随灵敏度分析与时空放疗优化：PDE约束下梯度计算与Matlab实现

做放疗计划优化的同行&#xff0c;或者正在读医学物理、计算生物方向的研究生&#xff0c;应该对“灵敏度分析”这个词不陌生。但能把伴随灵敏度分析&#xff08;Adjoint Sensitivity Analysis&#xff09;和时空放射治疗优化结合起来&#xff0c;并且用Matlab完整实现的项目&a…

作者头像 李华