szczyglis-dev/py-gpt · 上手攻略

  • 仓库：szczyglis-dev/py-gpt
  • 链接：https://github.com/szczyglis-dev/py-gpt
  • 分类：AI 工具 · 桌面应用
  • 作者：Tom
  • 更新：2026-09-04

是什么

PyGPT 是一个开源桌面 AI 助手，用 Python 开发，支持 Linux / Windows 10-11 / Mac 三平台。它的工作方式类似 ChatGPT，但完全离线运行在你自己电脑上——API 密钥你自己管，数据不经过任何第三方服务器。

当前版本 2.8.6（build 2026-09-03），支持从 GPT-5、GPT-4、o1/o3/o4，到 Google Gemini、Anthropic Claude、xAI Grok、DeepSeek、Perplexity、Ollama 本地模型等数十种模型。核心能力包括：多模式对话、文件问答（RAG via LlamaIndex）、图像/视频生成、语音合成与识别、Web 搜索、插件系统、MCP 支持、计算机操控（Computer use）和自主 Agent 模式。

解决什么问题

大多数 AI 助手产品（ChatGPT Plus、Claude Pro、Gemini Advanced）都是在线 SaaS，数据经过服务商服务器，对隐私敏感的用户存在隐患。同时，很多开源 AI 项目（如 Ollama 支持的本地模型）需要命令行操作，门槛较高。

PyGPT 的定位是把最强大的 AI 模型能力封装到一个本地桌面应用里，既有图形界面的易用性，又保留了极高的扩展性（插件、MCP、API key 自带）。你可以用它替代 ChatGPT 作为日常 AI 助手，同时完全控制自己的数据。

快速安装

PyGPT 提供多种安装方式，根据你的平台和需求选择：

方式一：预编译二进制（最简单，推荐）

下载页：pygpt.net/#download

下载对应平台的压缩包或安装程序，解压/安装后直接运行即可。Linux 版需要 GLIBC >= 2.35。

⚠️ GLIBC 版本问题：如果你在较老的 Linux 发行版上遇到 GLIBC_2.35 not found 错误，说明系统 glibc 版本过低，换用 pip 从源码安装或升级系统。

方式二：Microsoft Store（Windows 用户）

直接从 Microsoft Store 安装，自动更新。

方式三：AppImage（Linux）

# 下载最新的 .AppImage 文件后
chmod +x ./PyGPT-X.X.X-x86_64.AppImage
./PyGPT-X.X.X-x86_64.AppImage

可用 appimageupdatetool 自动更新。

方式四：Snap（Linux）

sudo snap install pygpt
sudo snap refresh pygpt

Snap 版需手动连接硬件资源：

sudo snap connect pygpt:camera        # 摄像头
sudo snap connect pygpt:audio-record  # 麦克风
sudo snap connect pygpt:audio-playback # 音频输出

方式五：pip（跨平台，需要 Python 3.10–3.13）

python3 -m venv venv
source venv/bin/activate      # Linux/Mac
# .\venv\Scripts\activate    # Windows
pip install pygpt-net
pygpt

方式六：从源码（开发者）

git clone https://github.com/szczyglis-dev/py-gpt.git
cd py-gpt
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python3 run.py

核心用法

配置 API Key

  1. 启动应用 → Config → Settings → API Keys
  2. 在对应 Provider 标签下粘贴你的 API key（OpenAI / Anthropic / Google 等）
  3. 各平台获取地址： - OpenAI：platform.openai.com/account/api-keys - Anthropic / Google 等：在各自平台控制台生成

⚠️ 注意：Ollama 等本地模型不需要 API key，随便填一个值绕过空 key 提示即可。

10 种工作模式

模式 用途
Chat 标准对话，支持 vision inline（拍照/截图分析）和图像生成 inline
Chat with Files 基于 LlamaIndex 的本地文档问答，支持 pdf/txt/csv/html/md/docx/epub/xlsx/json 等
Realtime + Audio 实时语音对话（语音合成+识别）
Research Perplexity 风格的网络研究模式
Completion 纯补全（GPT 类）
Image & Video generation 图片/视频生成（gpt-image、Imagen、Veo3、Sora2 等）
Experts 预设专家角色
Computer use AI 操控你的电脑
Agents 多步骤 Agent 任务编排
Autonomous Mode 完全自主执行模式

常用功能命令

文件问答（Chat with Files） 在 Chat with Files 模式下，通过 LlamaIndex 索引本地文件并对话。可上传 txt、pdf、csv、html、md、docx、json、epub、xlsx 等格式，也支持网页和视频音频内容。

插件系统 内置插件：Files I/O（读写本地文件）、Code Interpreter（执行 Python 代码）、Web Search（DuckDuckGo/Google/Bing）、GitHub、Telegram、Slack、MCP 等。可在 Plugins 菜单中开启。

MCP 支持 在 Settings → Plugins 中开启 MCP 插件，配置 MCP 服务器地址即可。

本地 Ollama 模型 在 Config → Settings → API Keys 中，切换到 Ollama provider，填入本地 Ollama 服务地址（默认 http://localhost:11434），无需 API key。可用模型包括 Gemma 4、Qwen 3.6、Llama 4、Mistral Small 3.2、DeepSeek、Bielik 等。

常见问题处理

Linux 上 Qt xcb 报错：

sudo apt install libxcb-cursor0

Linux 上音频问题：

sudo apt install portaudio19-dev libasound2 libasound2-plugins

Windows 上 VC++ Redistributable 缺失： 从 Microsoft 官网 安装最新 VC++ Redistributable。

Linux Snap 版权限问题： 编辑 /var/lib/snapd/apparmor/profiles/snap.pygpt.pygpt，添加缺失的路径访问规则后重载。

WebEngine 渲染问题（Linux）：

python3 run.py --legacy=1
# 或在 config.json 中设置
# "render.engine": "legacy",
# "render.open_gl": false,

典型适用场景

  • 日常 AI 助手：完全本地运行，隐私友好，不需要订阅 ChatGPT Plus
  • 本地文档 RAG：用 Chat with Files 模式对本地论文、笔记、代码库进行问答
  • Ollama 本地模型 GUI：给本地跑的 llama/qwen/deepseek 模型一个图形界面
  • 多模型对比：在同一个应用里快速切换对比 GPT-4o / Claude 3.5 / Gemini 的回答
  • AI 编程辅助：内置 Code Interpreter + 文件读写，适合辅助编程任务
  • 无网络环境：飞机上、隔离内网中，用本地模型 + 离线文档工作

坑与注意

  1. API 费用自付：PyGPT 本身免费，但调用 GPT-4o / Claude 等需要你自己有对应平台的 API key 并支付用量费用，本地 Ollama 模型免费。
  2. GLIBC 2.35 要求：编译好的 Linux 二进制版需要较新的 glibc，老系统（Ubuntu 20.04 以前）需要从 pip 安装。
  3. Python 版本限制：源码安装需要 Python >= 3.10 且 < 3.14。
  4. macOS 无预编译版：macOS 用户只能从 pip 或源码运行，无 AppImage/二进制包。
  5. 隐私边界：虽然应用本身是本地的，但调用 OpenAI/Anthropic API 时对话内容会经过这些服务商的服务器；只有 Ollama 完全离线。
  6. Plugin 安全：插件可以读写本地文件、执行系统命令，从非可信来源安装插件存在风险。
  7. Windows VC++ Redistributable：PySide6（Qt）依赖 VC++ Redistributable，Windows 上第一次运行可能需要手动安装。

与同类对比

工具 平台 模型支持 隐私性 扩展性
PyGPT Linux/Win/Mac 几乎所有主流 API + Ollama API 模式需联网，Ollama 完全本地 插件 + MCP 强
ChatGPT Desktop Win/Mac 仅 OpenAI 中（在线） 弱
Claude Desktop Win/Mac 仅 Anthropic 中（在线） MCP 支持
Lobechat 浏览器/桌面 OpenAI 兼容 中（自托管可选） 插件系统
Ollama 终端 仅本地模型 高（完全离线） 无 GUI
** AnythingLLM** 浏览器 多 API + Ollama 高（本地） RAG 强，缺多模式

PyGPT 的最大优势是覆盖最广：从 GPT-5 到 Ollama 全支持，加上 10 种工作模式和完整的插件系统，是功能最丰富的开源桌面 AI 助手之一。

一句话推荐结论

如果你需要一个功能最全、跨平台、开源的本地 AI 桌面助手，PyGPT 是目前最好的选择——尤其是当你同时用 OpenAI API 和本地 Ollama 模型、又需要 RAG 文件问答和多模态能力时，一款工具全搞定。