Pi接入自建模型全攻略：从配置规范到版本校验的完整路径

人工智能2026-09-186,209

一、为什么 “能连上” 不等于 “能上线”

Pi 作为轻量级终端 Coding Agent，其模型接入层采用 provider 抽象设计。任何兼容 OpenAI Chat Completions 协议的服务，理论上都可以通过 ~/.pi/agent/models.json 注册为自定义 provider，然后用 /model 命令切换调用。本地部署的 Ollama、vLLM、SGLang、LM Studio，或者远程的 API 网关，都可以走同一套配置路径。

但 “能连上” 和 “能上线” 之间存在一个容易被忽略的鸿沟。
问题出在模型标识上。Pi 的模型注册表只认精确的 provider/id 组合。如果展示名称和实际模型 ID 不一致，请求可能被路由到错误的模型，或者直接返回认证失败。DeepSeek 官方 API 文档明确要求将 model_name 设置为 deepseek-v4-pro 或 deepseek-v4-flash，对应的版本快照分别是 DeepSeek-V4-Pro-0813 和 DeepSeek-V4-Flash-0731。调用 ID 是 deepseek-v4-pro，版本号是 0813，两者不能混用。如果配置时把 DeepSeek V4 Pro 0813 整个字符串当作模型 ID 填入，Pi 的解析器会找不到对应条目。

Kimi 的模型 ID 同样需要精确匹配。kimi-k3 是调用名，其上下文窗口为 1M tokens，推理强度通过 reasoning_effort 参数控制，支持 low /high/max 三档，默认 max。Kimi 的前缀缓存是厂商侧能力，Pi 本身不控制缓存命中，但切换 reasoning_effort 档位会破坏缓存，因此建议在会话开始前确定档位。

版本意识必须前置到配置阶段。先确定具体模型 ID，再写 provider 配置，最后用最小请求验证连通性。顺序反过来，排查成本会急剧上升。

二、配置流程：四步建立可复现的接入链路

第一步：确定接入方式

Pi 支持四种协议风格：openai-completions、openai-responses、anthropic-messages 和 google-generative-ai。自建模型如果使用 Ollama 部署，走 openai-completions 即可，因为 Ollama 本身提供了 OpenAI 兼容端点，ollama launch pi --config 生成的配置块也是以 openai-completions 作为 api 字段的。如果通过 API 网关暴露，通常也选 openai-completions。

Ollama 本地部署的场景下，base URL 填 http://localhost:11434/v1，API key 写任意占位值（如 ollama）即可。Pi 仍然要求模型在出现在 /model 列表之前通过认证，因此无密钥的本地服务器要么保留一个占位值，要么通过 /login 保存密钥，要么在选模型时传 --api-key。远程网关则需要真实的 API key。

第二步：写入 models.json

配置文件路径为 ~/.pi/agent/models.json。最小配置只需要 provider 名称、base URL 和模型 ID 列表：

{
  "providers": {
    "my-local": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "placeholder",
      "models": [
        {
          "id": "qwen3.8-max",
          "name": "Qwen3.8 Max",
          "contextWindow": 131072,
          "maxTokens": 32768
        }
      ]
    }
  }
}

contextWindow 和 maxTokens 不填也能运行，但填了之后 Pi 才能在上下文压缩和输出截断时做出正确判断。对于长文本任务，这个字段的准确性直接影响可用性。

如果自建模型走 vLLM 或 SGLang 这类推理框架，可能需要额外配置 compat 块。Pi 官方文档指出，部分 OpenAI 兼容服务器不支持 developer 角色，需要将 compat.supportsDeveloperRole 设为 false，Pi 才会把系统提示词作为 system 消息发送。如果服务器同时不支持 reasoning_effort，还需要把 compat.supportsReasoningEffort 也设为 false。这个配置在 provider 层级设置后对该 provider 下所有模型生效，也可以在模型层级单独覆盖：

{
  "compat": {
    "supportsDeveloperRole": false,
    "supportsReasoningEffort": false
  }
}

如果需要接入多个模型源，可以在 providers 下并列多个条目。对于需要同时管理多个候选模型的团队，星链 API 的统一入口设计使得 Pi 可以在同一套 models.json 中并列多个 provider 块，切换时只改模型 ID，不需要重写 base URL 和认证配置。

第三步：处理认证

API key 的注入有两种方式。环境变量方式适合临时测试，持久化方式是写入 ~/.pi/agent/auth.json。需要注意优先级：auth.json 中已存在的凭证会覆盖环境变量。如果 key 更新后不生效，先检查 auth.json 里有没有旧条目。

models.json 中的 apiKey 字段支持环境变量引用语法，如 $MY_API_KEY 或 ${MY_API_KEY}。这比明文写入更安全，也便于在 CI/CD 环境中注入。

第四步：验证与调试

配置完成后执行 pi --list-models 确认模型已注册。如果模型没有出现，依次检查三件事：models.json 的 JSON 语法是否正确、auth.json 中是否有对应 provider 的 credential、provider 名称是否与 Pi 内置名称冲突（不要用 openai、anthropic、openrouter 作为自定义 provider 的 key）。

发送一条最小请求验证连通性。如果返回 401，查 auth.json；如果返回 404，查模型 ID；如果返回 429，查上游限流策略。

三、模型参数校验：以官方规格为锚点

自建模型接入后，需要对照官方参数表做一次能力校验。这一步不是形式主义，而是决定任务路由的前提。

DeepSeek V4 Pro 的官方规格包括 1M 上下文窗口、384K 最大输出、思考与非思考双模式、工具调用支持。其 OpenAI 兼容接口和 Anthropic 接口并存，但两者的工具调用参数结构不同，迁移时需要单独验证。

Kimi K3 的参数约束需要特别注意。根据 Kimi 官方模型参数参考，K3 的 temperature 固定为 1.0，不可修改；top_p 固定为 0.95；n 固定为 1；presence_penalty 和 frequency_penalty 均固定为 0。“Fixed” 的含义是参数不能被修改，传递任何其他值都会返回错误，因此不应显式传递这些参数。K3 的 reasoning_effort 支持会话级调节，但切换档位会破坏前缀缓存命中，建议在会话开始前确定档位。

GLM-5.3 是文本模型，思考功能始终开启，最大输出 128K。官方文档提示：如果应用当前使用 thinking.type: "disabled"，在将模型 ID 更新为 glm-5.3 之前，必须将其更改为 enabled，并将 reasoning_effort 设置为 low，否则请求将失败。接入前建议核对智谱最新接口文档，参数约束随版本可能变动。接入时需要在响应解析中处理 reasoning_content 字段。

Gemini 通过 OpenAI 兼容端点接入时，reasoning_effort 的取值不会由 Pi 自动映射到 Gemini 的 thinking_level。Pi 使用 thinkingLevelMap 来声明模型支持的思考档位，需要在 models.json 中显式配置。thinkingLevelMap 的 key 为 off / minimal / low / medium / high / xhigh / max，value 为发送给网关的 effort 字符串，或设为 null 来禁用该档。如果模型只支持部分档位，在 thinkingLevelMap 中只声明支持的档位即可，未声明的档位不会出现在 Pi 的思考级别菜单中。

把这些规格写进接入文档，而不是记在脑子里。模型升级或下线时，对照文档更新配置，而不是凭印象调整。

四、统一入口的边界与运维

通过 API 中转站统一接入多个模型时，Pi 的配置层面看起来更简洁 —— 一个 provider、一组模型 ID。但底层仍然存在版本映射、计量口径和限流策略的差异。

星链 API 的统一入口设计使得 Pi 可以用同一套 models.json 配置管理多个候选模型，切换时只需要改模型 ID，不需要重写 provider 块。调用日志可以在一个面板中对比不同模型的延迟和 token 消耗，这对做接入评估有实际帮助。星链 API 在企业生产环境中提供多节点调度能力，可支持 OpenAI、Claude、Gemini 等多个模型体系统一管理，后台支持查看输入 Token、输出 Token 以及缓存 Token 等详细数据。

但统一入口不消除差异。同一模型在直连和通过网关调用时，限流规则可能不同，账单单位也可能不同。建议在测试阶段分别记录直连和网关两种路径的端到端耗时、错误码分布和计费数据，而不是混在一张表里。

另一个运维要点是请求 ID 的保留。Pi 的会话日志默认不会自动存储上游原始请求 ID，需要在网关侧主动配置透传。网关转发时通常会注入自己的请求 ID，但上游厂商也有独立的请求 ID。出现故障时，两个 ID 结合才能区分是网关路由问题还是上游模型问题。Pi 的会话日志中记录的是网关侧 ID，排查上游问题需要额外从网关控制台导出关联数据。

模型更新后，不要静默替换生产路由。先在测试环境中用同一组提示词和验收规则跑一遍回归，对比通过率和人工修订量。如果没有明显退化，再切换；如果有退化，保留旧路由并标注 “待验证”。

五、一个可复查的接入检查清单

配置完成不等于接入完成。以下六项需要在发布前逐条确认：

模型 ID 精确性。请求和响应中的模型 ID 一致，且与官方文档中的 ID 匹配。DeepSeek 的旧别名 deepseek-chat 和 deepseek-reasoner 已下线，必须使用 deepseek-v4-pro 或 deepseek-v4-flash。
协议功能一致性。协议名称相同不代表工具调用、流式事件和错误体结构相同。用一个最小工具调用请求验证 schema 传递和参数回传顺序。
思考档位映射。对于 Gemini 等需要通过 thinkingLevelMap 声明思考档位的模型，检查 models.json 中的映射配置是否正确。如果 thinkingLevelMap 缺失或映射错误，reasoning_effort 参数将不生效，模型会以默认档位运行。
限流与配额。从上游官方页面获取并发和配额数据，不要从网关的展示页面推断。DeepSeek 官方价格页列出了 V4 Pro 的高峰与非高峰价格及并发限制，其他模型需要逐一查证。
数据处理边界。确认输入数据是否包含个人或业务敏感信息，日志保留策略是否符合合规要求，API key 的创建、查看和撤销权限是否明确。
回滚路径。如果新模型接入后出现不可接受的退化，能否在 5 分钟内切回旧配置。Pi 的 /model 命令支持会话内切换，但生产环境的路由切换需要在应用层做配置管理，而不是依赖人工操作。