我是安徽最忧郁程序员无隅目录前言一、先跑通模型配置二、管好 API Key四种来源如何生效三、判断内网接口能否直连四、差异怎么处理先改配置再考虑转换层五、明确边界没有工具调用会失去什么前言企业模型平台说自己“兼容 OpenAI”把地址填进 Pi Agent 后却可能报 400、收不到流式输出或者只能聊天、不能调用工具。接入前真正需要确认的是Pi 发出的请求和网关返回的流能否组成完整的 Agent 对话。本文以 Piv0.87.1的配置与 SDK 为例给出从模型配置、密钥管理到接口核对和改造方案的判断方法。一、先跑通模型配置Pi 已内置的 Provider通常先用/login配凭证、用/model选模型。只有接企业网关、本地服务或尚未内置的端点时才需要在~/.pi/agent/models.json里增加自定义 Provider。Pi 官方的模型连接说明也是按这个顺序组织的。下面用一个示意性的企业网关说明配置结构。apiKey引用运行 Pi 的进程环境变量实际接入时baseUrl和模型id都要以网关文档和测试结果为准。{providers:{enterprise:{baseUrl:https://llm.example.com/v1,api:openai-completions,apiKey:$INTERNAL_LLM_KEY,models:[{id:internal-chat,name:企业聊天模型,contextWindow:128000,maxTokens:16384}]}}}这里有三层含义enterprise是 Provider 名api选择 Pi 用哪套协议组装请求和解析响应models列出该 Provider 可选的模型。provider/id组合用于定位模型例如enterprise/internal-chat。若模型支持图像或推理再依据真实能力补input、reasoning等元数据不能仅凭名称猜测。对自定义模型name可省略contextWindow和maxTokens有默认值但应尽量填写服务端真实限制否则上下文压缩和输出上限的判断可能与网关不一致。配置实现SDK 中找到模型对象和模型已有可用凭证是两回事。getModel()只按 Provider 和 ID 查找切换会话模型时setModel()还会检查目标 Provider 的鉴权。如果没有 Key切换会报错。已有会话切换模型后后续请求使用新模型原有对话记录继续留在会话中。ModelRuntime 源码、AgentSession 源码consttargetmodelRuntime.getModel(enterprise,internal-chat);if(!target)thrownewError(请检查 models.json 中的 Provider 和模型 ID);awaitsession.setModel(target);// 目标 Provider 无凭证时会报错awaitsession.prompt(请概括这段文档);这段代码适用于已经创建好modelRuntime和session的 SDK 程序。切换前先判空也让“模型未定义”和“模型没有凭证”成为两个可区分的问题。二、管好 API Key四种来源如何生效配置好了模型还要让 Pi 找到对应的凭证。常见来源有四种运行时注入、auth.json、models.json中的apiKey、内置 Provider 对应的环境变量。同一 Provider 出现多个来源时优先级从高到低依次如下图。这是 Piv0.87.1的默认解析顺序扩展注册的 Provider 可以有自己的鉴权逻辑。官方模型文档这个顺序最容易踩的坑是给内置 Provider 同时设置了环境变量又在models.json中写了字面apiKey最终会使用models.json的值。若希望密钥只由环境注入可以使用apiKey: $INTERNAL_LLM_KEY这样的显式插值自定义 Provider 名不会自动推出一个同名环境变量。Pi 官方文档也支持${NAME}形式和按请求执行的凭证命令但先用简单的环境插值更容易排查。官方示例本地开发时/login写入的auth.json适合集中管理凭证models.json则只保留可公开的模型定义。两类文件都要按实际内容决定是否纳入版本控制含真实密钥的配置文件不要提交仓库。如果 SDK 程序需要在启动后注入 Key使用setRuntimeApiKey()并等待异步操作完成SDK 凭证示例。constkeyprocess.env.INTERNAL_LLM_KEY;if(!key)thrownewError(缺少 INTERNAL_LLM_KEY);awaitmodelRuntime.setRuntimeApiKey(enterprise,key);运行时覆盖属于ModelRuntime的凭证状态多用户服务不能把所有用户的 Key 依次写进一个共享 Runtime然后假定它会自动按会话隔离。三、判断内网接口能否直连“OpenAI 兼容”常常只表示网关能接受一部分 OpenAI 风格的请求。Pi 的openai-completions路线会按 Chat Completions 方式发送消息并读取流式分块OpenAI 官方的Chat Completions 接口说明可用来理解端点与消息结构但企业网关是否真正支持这些字段仍以实际测试为准。先核对下面四项再谈compat核对项需要从文档和实际响应确认什么失败时的含义端点baseUrl后能否拼出/chat/completions不要把完整端点直接填作baseUrl路径不符需要调整网关路由或加转换层鉴权网关要求 Bearer Key、其他请求头还是签名流程先核对apiKey、headers签名流程可能需要扩展流式输出请求stream: true后是否持续返回data: {...}形式的 SSE 分块没有流式能力不能仅靠compat补出真实流消息与响应是否接受messages的角色和内容文本是否在流式choices[].delta中返回字段或角色体系不同需要做协议转换工具循环是否接受tools能否返回tool_calls并接受下一轮的工具结果只能完成普通聊天不能直接承担 Pi 的工具型 Agent可以先在 Postman 或企业网关调试工具中发一个最小文本请求把以下 JSON 作为请求体端点、鉴权头和模型 ID 使用企业文档给出的真实值。这里的示例是核对格式不是对某个企业服务已经成功调用的记录。{model:internal-chat,messages:[{role:user,content:请回复连接成功}],stream:true}成功时应观察到一段段可解析的流式事件而不只是最后一次性收到完整 JSON。然后再加tools做第二次测试并把返回的tool_calls和工具结果送入下一轮只测通一句问答尚不能证明 Agent 能用。如果普通文本已报404先查路径报401/403先查鉴权报字段错误的400再看兼容参数。Pi 请求组装实现一个容易误判的地方是Pi 不会对所有服务固定发送同一套可选参数。在v0.87.1的实现里stream: true是这条协议的基本请求方式stream_options、store、max_completion_tokens、tools等则受到兼容设置、调用选项或当前工具集影响。排查时应以实际请求体为准不能把示意请求当成每次调用的完整模板。Pi 源码四、差异怎么处理先改配置再考虑转换层前面的核对不是为了得到一个笼统的“兼容/不兼容”标签而是为了分清差异只是某个字段还是整个协议形态都不同。下图把处理路线放在一起前两项检查没有通过时不能跳过它们直接调compat。compat适合已经能完成主要请求与响应、只在少数字段上有差异的网关。比如网关只认旧的输出上限字段或者拒绝stream_options可以在对应模型的定义中按测试结果增加开关{id:internal-chat,name:企业聊天模型,compat:{maxTokensField:max_tokens,supportsUsageInStreaming:false}}上面是模型条目的片段放在models.json的models数组中并非完整文件。maxTokensField只在请求设置输出上限时决定发送哪个字段supportsUsageInStreaming: false会停止请求流式 usage适合网关因stream_options报错的情况但不会凭空得到用量统计。supportsDeveloperRole、supportsReasoningEffort等也应只在观察到对应差异后设置。特别是supportsStore、supportsStrictMode的默认值会按端点或模型能力处理不要机械地把原文中的一组开关全部复制过去。Pi 兼容字段定义、请求构造实现如果网关使用特殊路径、完全不同的消息结构或非标准流式事件compat不负责把整套协议翻译过去。此时可以让网关提供标准端点或者在中间放一层转换服务把 Pi 的请求转成网关格式再把网关的流式响应转回 Pi 所选协议的格式。转换层要处理双向转换只改请求、不改返回流通常仍无法完成对话。协议长期自成体系时还可以写 Pi 的 Provider 扩展。Pi 官方建议已有协议能表达时继续复用内置实现只有需要自定义流、动态模型发现或特殊鉴权时才增加 Provider 实现。自定义 Provider 文档五、明确边界没有工具调用会失去什么有些模型可以稳定流式聊天却不支持工具调用。此时可在 SDK 中清空活动工具让后续请求不再携带当前工具定义AgentSession 实现。session.setActiveToolsByName([]);这能让一个纯聊天场景继续使用该模型但会话里的read、bash、edit、write等工具也无法被模型调用自定义工具同样不会执行。原有对话如果包含工具调用历史网关仍可能因历史消息格式报错因此还要用新会话或实际历史记录测试。Pi 请求构造实现真正的 Agent 工具循环包括模型提出工具调用、程序执行工具、把结果送回模型、模型继续回答。清空工具集相当于主动放弃这条循环。如果业务必须依赖工具而模型或网关根本不会产生可靠的工具调用转换层也无法创造模型本身没有的能力应换支持工具调用的模型或升级网关。基于提示词约定“输出一段 JSON 当工具调用”可以作为自建方案但需要自己实现解析、校验、执行和循环不能当作 Pi 原生工具调用的等价替代。回到开头的问题企业内网模型能否接入 Pi Agent答案取决于你要它完成什么。普通聊天先验证路径、鉴权和流式工具型 Agent 再验证完整工具循环。主体协议已通时models.json加少量compat就够协议形态不同时需要网关改造、转换层或 Provider 扩展。这个判断应来自实际请求和响应而不是接口文档上的“兼容”两个字。