Pi Agent + DeepSeek 安装教程 与如何接入视觉能力

在对 4 款热门 Agent 框架（Pi Agent, Prime Agent, Deep Agents, Hermes Agent）在 30 个复杂 Agent 任务上进行了实测后，结果如下：

🏆 Pi Agent 为最大赢家：不仅通过率最高，速度最快，而且成本最低！

📊 核心数据对比：1️⃣ Pi Agent• 通过率：66.7% (20/30) • 中位成本：$0.012 / 任务 • 中位耗时：132s2️⃣ Prime Agent• 通过率：62.5% (15/24) • 中位成本：$0.045 / 任务 • 中位耗时：242s3️⃣ Deep Agents (LangChain)• 通过率：53.3% (16/30) • 中位成本：$0.018 / 任务 • 中位耗时：187s4️⃣ Hermes Agent• 通过率：50.0% (15/30) • 中位成本：$0.017 / 任务 • 中位耗时：176s

在模型相同的前提下，选对 Agent 调度框架可带来 50% → 66.7% 的成功率提升，且成本能降低近 4 倍。这也是给今天大家推荐的Pi Agent的原因。

Pi Agent 本身是一个强大的 AI Agent 工具包，它包含统一的大模型 API、Agent 运行环境、终端用户界面以及一个可自我扩展的交互式编程助手 。

第一部分：Pi Agent 安装教程

环境准备

在开始之前，请确保你的系统中已安装 Node.js 和 npm（建议使用 Node.js 18 或 20 以上的 LTS 版本）。

方法一：从源码编译安装（推荐）

如果你想体验最新功能或进行本地开发，官方推荐通过源码进行构建：

1. 克隆代码仓库 打开终端，将项目克隆到本地并进入目录：

1
2
git clone https://github.com/earendil-works/pi.gitcd pi

1. 安装依赖 为了保证软件供应链安全，官方推荐在安装依赖时加上 --ignore-scripts
   ，以防运行未受信任的生命周期脚本：

1
npm install --ignore-scripts

1. 构建项目 这一步会获取最新的模型数据目录，并编译所有的 monorepo 子包（如核心层、AI层、TUI 等）：

1
npm run build

(注：如果在离线或网络不佳的环境下，可以使用 npm run build:offline 利用本地缓存的模型数据进行构建。)

1. 运行与测试 构建完成后，你可以直接使用自带的脚本在任意目录启动 Pi Agent：

• Linux / macOS 运行: ./pi-test.sh
• Windows 运行: ./pi-test.bat 或 ./pi-test.ps1

方法二：通过 NPM 安装 CLI 工具

如果你只想作为普通用户使用它的编程助手，可以直接全局安装其发布的 npm 包：

1
npm install -g @earendil-works/pi-coding-agent

安装完成后，在终端直接输入 pi 即可启动。

第二部分：接入 DeepSeek API 教程

Pi 包含了一个统一的多模型 API 包 (@earendil-works/pi-ai)。由于 DeepSeek 官方提供了完全兼容 OpenAI 格式的 API 接口，我们可以通过环境变量覆盖的方式，非常无缝地将 Pi Agent 接入 DeepSeek。

1. 获取 API 密钥

前往 DeepSeek 开放平台，登录并生成你的专属 API Key（通常以 sk- 开头）。

2. 配置环境变量

你需要将 OpenAI 的默认调用地址重定向到 DeepSeek 的服务端点。在终端中配置以下环境变量：

在 Linux / macOS 中：

1
2
3
4
5
# 设置 DeepSeek 的 API Keyexport OPENAI_API_KEY="sk-你的deepseek-api-key"# 将基础 URL 指向 DeepSeek 的 API 接口export OPENAI_BASE_URL="https://api.deepseek.com/v1"

在 Windows (PowerShell) 中：

1
2
$env:OPENAI_API_KEY="sk-你的deepseek-api-key"$env:OPENAI_BASE_URL="https://api.deepseek.com/v1"

(注意：如果你将环境变量写入了 ~/.bashrc 或 ~/.zshrc，请记得 source 使其永久生效。)

3. 指定 DeepSeek 模型并运行

DeepSeek 主要有两个模型，推荐在代码辅助场景下使用 deepseek-coder（或者最新一代的 deepseek-chat）。

在启动 Pi 时，通过 --model 参数明确告诉它使用该模型：

如果你是全局安装：

1
pi --model deepseek-coder

如果你是从源码运行：

1
./pi-test.sh --model deepseek-coder

4. 验证运行

进入 Pi 的 TUI（终端用户界面）后，你可以尝试给它下达一个简单的指令，例如：

“写一个 Python 的快速排序算法并保存为 qsort.py”

如果 Pi Agent 能够正常思考、调用工具（写入文件）并给出回复，说明 DeepSeek API 已经成功接入并完美驱动了 Agent 循环！

💡 安全建议： 根据 Pi 官方的声明，Pi Agent 默认以当前用户权限运行。因为 DeepSeek Coder 具备极强的代码编写和执行能力，如果让它操作复杂的本地工程，建议按照官方文档在 Docker 容器或 OpenShell 沙盒中运行 Pi，以避免 Agent 误删文件或破坏宿主机环境。

第三部分：为 Pi Agent 添加视觉能力 (基于 pi-deepseek-vision)

由于 DeepSeek 的核心模型通常是纯文本模型，默认无法处理图像（多模态）输入，但可以通过安装开源扩展 pi-deepseek-vision 来实现。

它的工作原理： 采用“视觉预处理”代理机制。它会调用 Pi Agent 中已配置好的其他视觉模型（比如 GPT-4o 或 Claude 3.5 Sonnet）作为 DeepSeek 的“眼睛”。该扩展会拦截你发送的图片，让视觉模型将其分析并转化为详细的纯文本描述，随后将带有纯文本描述的请求无缝转发给 DeepSeek。整个过程对 DeepSeek 而言是完全纯文本的。

1. 安装 Vision 扩展

在终端中，你可以直接使用 Pi 的内置扩展安装命令，从 GitHub 拉取并安装该项目：

1
pi install git:github.com/sanvibyfish/pi-deepseek-vision

(注：如果你的网络环境受限，也可以将代码克隆到本地，然后运行 pi install /绝对路径/到/pi-deepseek-vision)

2. 配置视觉预处理模型

该扩展通过读取固定的全局 JSON 文件来运行。你需要告诉它“用哪个模型作为眼睛”以及“哪些 DeepSeek 模型可以触发预处理”。

首先，创建配置目录（如果尚未存在）：

1
mkdir -p ~/.pi/agent

然后，创建并编辑配置文件 ~/.pi/agent/deepseek-vision.json，填入以下内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{  "visionModel": {    "provider": "openai",    "id": "gpt-4o"  },  "targetModels": [    "deepseek-coder",    "deepseek-chat",    "deepseek-v4-pro",    "deepseek-v4-flash"  ],  "language": "auto",  "maxAnalysisChars": 20000,  "cache": {    "capacity": 128,    "ttlSeconds": 900  }}

关键配置项说明：

• visionModel: 指定预处理视觉模型的 provider（提供商）和 id（模型名称）。前提是你必须已经在 Pi 中配置好了该提供商（如 OpenAI、Anthropic）的 API Key，且该模型原生支持图像输入。
• targetModels: 指定需要触发此扩展的目标模型列表。请确保你当前使用的 DeepSeek 模型名（如 deepseek-coder）包含在这个数组中。
• language: 图像分析结果的语言。设为 auto 会自动跟随上下文的对话语言（如输出中文分析）。
• cache: 内置了 LRU（最近最少使用）缓存功能。同一张图在有效时间内不会被重复调用 API 分析，节省 Token 和时间。

3. 重载配置与使用

保存配置文件后，回到正在运行的 Pi Agent 终端交互界面 ，输入以下命令使配置生效：

1
/reload

如何使用：

配置成功后，操作与原生多模态大模型毫无差异。在使用 DeepSeek 模型的对话中，你可以直接向终端拖入图片，或让 Pi 读取本地图片：

“读取 /path/to/screenshot.png，对比这张设计稿，帮我用 React 和 TailwindCSS 写出对应的前端组件代码。”

运行表现：

1. 扩展会触发，Pi 界面会提示当前正在分析图像的数量。
2. 原始图片会被替换为形如 [图片 1 — 由视觉模型分析：这是一个包含顶部导航和双列瀑布流布局的电商页面...] 的纯文本。
3. 纯文本被安全地传递给 DeepSeek 进行逻辑处理和代码生成。如果视觉处理环节失败，它会执行“安全阻断”（Fail-closed），绝不会将未处理的乱码或原始图像强行发送给不支持图像的 DeepSeek，从而保证工作流的稳定性。