DeepSeek 提供 OpenAI 兼容接口可以复用 Pi 现成的 OpenAI 适配层无需为 DeepSeek 单独开发适配器。接入的核心工作只有两件在 models.json 中声明供应商与模型参数通过环境变量提供 API Key。整体架构如下图所示所谓「OpenAI 兼容接口」指供应商的 HTTP 接口协议与 OpenAI 保持一致。只要协议兼容任何支持 OpenAI 的工具都可以直接调用DeepSeek 就属于这一类。安装 PiPi 依赖 Node.js 运行环境安装前请先确认 Node.js 已就绪。安装 Node.js从 Node.js 官网下载对应系统的安装包使用默认选项安装即可。安装 Pi CLI在终端通过 npm 全局安装npm install -g --ignore-scripts earendil-works/pi-coding-agentLinux 和 macOS 用户也可以使用官方安装脚本一键安装curl -fsSL https://pi.dev/install.sh | sh验证安装执行以下命令能正常打印出版本号即表示安装成功pi --version输出类似0.83.0配置 DeepSeek 供应商Pi 通过 models.json 定义自定义模型供应商本节把 DeepSeek 以 OpenAI 兼容接口的形式接入。配置文件路径不同操作系统的配置路径不同请按系统对号入座操作系统配置文件路径Linux / macOS~/.pi/agent/models.jsonWindows%USERPROFILE%\.pi\agent\models.json编写 models.json把以下内容写入配置文件{ providers: { deepseek: { baseUrl: https://api.deepseek.com, api: openai-completions, apiKey: $DEEPSEEK_API_KEY, models: [ { id: deepseek-v4-pro, name: DeepSeek V4 Pro, contextWindow: 1000000, maxTokens: 384000, input: [text], reasoning: true, cost: { input: 1.74, output: 3.48, cacheRead: 0.145, cacheWrite: 0 }, compat: { requiresReasoningContentOnAssistantMessages: true, thinkingFormat: deepseek, reasoningEffortMap: { minimal: high, low: high, medium: high, high: high, xhigh: max } } }, { id: deepseek-v4-flash, name: DeepSeek V4 Flash, contextWindow: 1000000, maxTokens: 384000, input: [text], reasoning: true, cost: { input: 0.14, output: 0.28, cacheRead: 0.028, cacheWrite: 0 }, compat: { requiresReasoningContentOnAssistantMessages: true, thinkingFormat: deepseek, reasoningEffortMap: { minimal: high, low: high, medium: high, high: high, xhigh: max } } } ] } } }配置项解析下面对 models.json 中用到的主要字段逐一说明字段类型是否必填说明默认值baseUrlstring必填DeepSeek 的 OpenAI 兼容接口地址https://api.deepseek.comapistring必填对接协议声明使用 OpenAI Completions 兼容协议openai-completionsapiKeystring必填从同名环境变量读取密钥无需把 Key 明文写进配置文件$DEEPSEEK_API_KEYcontextWindownumber必填上下文窗口大小tokens1000000maxTokensnumber必填单次最大输出长度tokens384000reasoningboolean可选声明模型支持思维链推理能力truecostobject可选记录输入/输出/缓存命中等单价用于 Pi 界面估算花费—requiresReasoningContentOnAssistantMessagesboolean推荐多轮对话中 assistant 消息需要保留 reasoning_content 字段否则可能出现兼容性问题truethinkingFormatstring推荐按 DeepSeek 特有的思维内容格式解析、展示推理过程deepseekreasoningEffortMapobject推荐把 Pi 的推理强度档位映射到 DeepSeek 实际支持的档位—reasoningEffortMap 把 Pi 的五个推理档位minimal / low / medium / high / xhigh映射到 DeepSeek 支持的档位除 xhigh 映射为 max 外其余全部收敛到 high。模型选择配置声明了两个 DeepSeek 模型主要区别如下模型上下文窗口最大输出输入单价输出单价缓存命中单价适用场景deepseek-v4-pro1,000,000384,0001.743.480.145推理能力更强适合复杂任务deepseek-v4-flash1,000,000384,0000.140.280.028响应更快、成本更低单价单位为每百万 tokens美元。获取并设置 API Key先在 DeepSeek 开放平台申请 API KeyDeepSeek。Linux / macOS 在终端导出环境变量export DEEPSEEK_API_KEY你的 DeepSeek API KeyWindowsPowerShell设置方式$env:DEEPSEEK_API_KEY你的 DeepSeek API Key建议把导出命令写入 shell 配置如 ~/.bashrc、~/.zshrc 或 PowerShell Profile避免每次开新终端都重新设置。请把示例中的「你的 DeepSeek API Key」替换为真实密钥。API Key 属于敏感信息请妥善保管切勿提交到版本库。运行与测试配置完成后就可以启动 Pi 并切换到 DeepSeek 模型。启动 Pi进入项目目录:cd ~/runoob-test/直接执行 pi 命令pi切换到 DeepSeek 模型进入交互界面后按以下步骤切换输入 /model 打开模型选择器。选择 deepseek 供应商选择 DeepSeek-V4-Pro 或 DeepSeek-V4-Flash。接下来询问当前模型切换完成后就可以直接在这个极简终端框架里开始编码了。建议的测试步骤按下面的清单逐项验证接入是否完整可用测试项操作方法预期结果鉴权与连通性发送一句话例如「你好请介绍一下 runoob 学习平台」正常拿到回复无 401 / 403 类鉴权报错说明 apiKey、baseUrl 配置正确推理能力问一个需要多步推理的问题比如让它先分析再给方案输出可见的思维过程说明 thinkingFormat 与 reasoning 生效多轮工具调用让 Pi 连续调用工具完成读文件、跑命令、改代码、验证结果多轮对话稳定不因 reasoning_content 丢失而报错推理强度切换在 /model 中从 medium 切到 xhigh行为符合 reasoningEffortMap 映射xhigh 对应 DeepSeek 的 max成本核算跑几轮真实任务后查看花费统计界面统计与 cost 字段设置的单价相符其中「多轮工具调用」是验证 requiresReasoningContentOnAssistantMessages 配置是否正确的关键场景。常见问题排查接入过程中遇到问题可对照下面的清单快速定位。模型选择器里看不到 DeepSeek检查 models.json 路径是否正确Windows 与 Linux / macOS 的路径不同。同时确认 JSON 格式没有语法错误比如多余的逗号、未闭合的引号。鉴权失败确认 DEEPSEEK_API_KEY 环境变量已经正确设置。注意执行 pi 命令的终端会话必须与设置环境变量的会话是同一个。多轮工具调用报错优先检查 requiresReasoningContentOnAssistantMessages 与 thinkingFormat 是否已按上文配置齐全。