pi-agent 思考参数适配

更新日期：2026-09-15。主要面向通过 pi-agent 消费网关模型的业务团队；HTTP / Python 示例仅用于独立排障。

接入原则：pi-agent 负责将用户选择的思考级别转换为实际渠道参数，网关负责已支持路径上的透传。业务无需再实现一套转换层。

版本兼容：下列 CLI 配置适用于支持这些字段的 pi coding-agent，请先核对安装版本；内嵌 pi-agent / pi-ai 服务按第 3.3 节处理。

示例中的 https://gateway.example.com 是占位地址，请替换为管理员提供的网关地址。使用真实地址和业务 Key 执行示例会产生模型调用费用。

1. 适用范围

使用前请确认目标模型已支持所需的思考参数。参数格式取决于实际模型服务，不能仅根据“兼容 OpenAI”推断；配置透传能力本身不等于开启模型思考。

本文的 HTTP 示例使用 OpenAI Chat Completions，不作为 Responses API 或跨协议转换的调用指南。不同模型的可用协议和参数支持情况，请向管理员确认。

2. 接入前提

请提供：业务使用的网关地址、模型 ID、调用协议和期望发送的思考参数。工单和排障记录中不得包含 API Key。

请向管理员确认以下接入信息：

1. 正确的网关地址、已授权的模型 ID 和调用协议。
2. 当前业务 Key 已获目标模型的访问权限。
3. 目标模型支持的思考开关、强度档位、预算及组合限制。
4. 所需思考参数的透传能力已启用。

业务请求只携带模型调用参数，使用网关签发的业务 Key；不需要管理员凭证或管理配置字段。

3. pi-agent 配置

3.1 模型与协议配置

CLI 用户先执行 pi --version 并留存版本，在自己的 ~/.pi/agent/models.json 合并新增 provider，保留原有配置。下面是 Qwen / 百炼开关模式的配置示例，不适用于所有模型服务：

{
  "providers": {
    "gateway-qwen": {
      "baseUrl": "https://gateway.example.com/v1",
      "api": "openai-completions",
      "apiKey": "$LLM_GATEWAY_KEY",
      "models": [
        {
          "id": "qwen3.8-flash",
          "reasoning": true,
          "compat": {
            "thinkingFormat": "qwen",
            "supportsReasoningEffort": false
          }
        }
      ]
    }
  }
}

前提：管理员确认该模型 ID 对业务 Key 开放且实际是支持 enable_thinking 的渠道。模型上下文和输出上限沿用已验证配置；示例省略这些数值，并不代表 pi 默认值等于供应商上限。

• reasoning: true 声明思考能力；thinkingFormat: "qwen" 使用 enable_thinking。
• 本例关闭 reasoning_effort 发送，只演示思考开关；选择 high 仅表示开启思考，不代表发送同名强度档位。
• 当前官方环境变量写法为 "$LLM_GATEWAY_KEY"，配置文件中不得保存真实密钥；旧版本需核对环境变量解析规则。

配置字段依据：pi 自定义模型说明。

本例发送的是 enable_thinking，不是 thinking。二者不是同义字段；切换模型时应重新确认参数格式，不应直接替换字段名称。

3.2 在 pi 中选择模型与思考级别

业务运行环境安全注入 LLM_GATEWAY_KEY 后：

pi --provider gateway-qwen --model qwen3.8-flash --thinking off

完成关闭思考的验证后，在独立会话中验证开启思考：

pi --provider gateway-qwen --model qwen3.8-flash --thinking high

当前官方 CLI 支持 /model 选模型、/thinking 或 Shift+Tab 切换思考级别。请以安装版本的 pi --help / /hotkeys 为准，版本升级应遵循业务依赖管理流程。pi CLI 说明

验收时区分以下三种能力：

需要精细强度时，优先沿用已验证的 pi provider 元数据；只有渠道支持时才配置 thinkingLevelMap / supportsReasoningEffort。应仅启用模型实际支持的能力，并限制界面可选档位与服务能力一致。预算与 effort 不一定可同时发送；先验证渠道契约。pi 思考兼容配置

3.3 业务服务内嵌 pi-agent / pi-ai

如果实际消费方不是 CLI，而是服务里的 Agent 实例：

1. 确认实际包名、锁定版本及模型注册方式；服务是否读取 ~/.pi/agent/models.json 取决于集成实现。
2. 在服务已有的模型 / provider 注册处配置网关 URL、业务 Key、模型 ID、协议和兼容元数据。
3. 把业务界面的思考选择传入当前版本的 Agent thinking-level 或 pi-ai reasoning 入口；沿用现有调用链，避免重复注入思考参数。
4. 在提供请求观察能力的版本中，通过 payload hook 或 mock 检查序列化后的参数；只记录白名单参数，排除密钥、用户正文和完整思维链。
5. 验证流式 thinking 事件、工具调用和多轮历史能继续被服务正确消费。

pi-ai 提供统一思考接口和 provider-specific 接口，两者参数名不能混用。请按项目锁定版本的文档选择 import 和方法签名。pi-ai 接口说明

4. HTTP 与 SDK 调用示例

将占位地址替换为管理员提供的实际地址：

SDK 的 base_url 不应包含 /chat/completions。首次联调使用明确的模型 ID，不使用 auto / auto:*；自动路由不负责转换供应商思考参数。

以下示例中的 thinking: {"type":"enabled"} 仅适用于已确认接受该格式的渠道，不是全模型通用格式。有的渠道要求其他开关或始终思考，应替换成该渠道的参数契约。

4.1 curl / 原始 HTTP

先在运行环境安全注入 LLM_GATEWAY_KEY，并设置 LLM_GATEWAY_MODEL 为已确认的模型 ID。以下命令不写入真实密钥：

: "${LLM_GATEWAY_KEY:?请先配置网关业务 Key}"
: "${LLM_GATEWAY_MODEL:?请先配置已授权的网关模型 ID}"

curl --fail-with-body -sS --max-time 180 \
  https://gateway.example.com/v1/chat/completions \
  -H "Authorization: Bearer ${LLM_GATEWAY_KEY}" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"${LLM_GATEWAY_MODEL}\",
    \"messages\": [{\"role\": \"user\", \"content\": \"请计算 17×23，并简要说明方法。\"}],
    \"thinking\": {\"type\": \"enabled\"},
    \"stream\": false
  }"

该示例要求模型 ID 不包含 JSON 特殊字符。生产代码请使用 JSON 序列化，避免直接拼接用户输入。180 秒仅是客户端示例超时，不代表网关或供应商的超时承诺。

原始 HTTP 的 thinking 放在 JSON 顶层，无需人为包装成 extra_body。

4.2 Python OpenAI SDK

Python SDK 的非标准字段通过 extra_body 传入。SDK 会将其中字段合并到最终 HTTP JSON 顶层；这与上一节 curl 等价。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LLM_GATEWAY_KEY"],
    base_url="https://gateway.example.com/v1",
    timeout=180.0,
    max_retries=0,  # 联调阶段关闭自动重试，方便逐次核对
)

response = client.chat.completions.create(
    model=os.environ["LLM_GATEWAY_MODEL"],
    messages=[{"role": "user", "content": "请计算 17×23，并简要说明方法。"}],
    extra_body={"thinking": {"type": "enabled"}},
)
print(response.model_dump_json(indent=2))

extra_body 不应重复嵌套，thinking 应仅配置一次，避免参数冲突。

4.3 思考强度与预算

thinking、reasoning_effort、enable_thinking、thinking_budget 不是同义字段。以渠道文档和联调确认的组合为准：

• 若渠道支持标准 reasoning_effort，Python SDK 可使用该命名参数；值域由具体模型决定，不同模型不一定支持相同的强度档位。
• 若渠道要求 enable_thinking 或 thinking_budget，Python SDK 用 extra_body，原始 HTTP 用顶层字段；不得将这些字段直接替换为 thinking。
• budget_tokens 等嵌套预算也只在渠道明确支持时发送。Anthropic 参数结构不适用于所有 OpenAI 兼容模型。
• 不同时发送相互冲突的多套思考开关；由 pi 的模型适配器生成一套与目标服务兼容的参数。

5. 验收标准

GET /v1/models 可用来检查模型是否对当前 Key 可见，但不能证明透传开关开启或参数已被供应商接受。模型生成的自述内容不能作为参数生效的判定依据。

流式调用增加 stream=true；Python SDK 可同时传 stream_options={"include_usage": True}，迭代结果并读取最终 usage。usage 块可能没有 choices；供应商不返回思考明文也不代表未思考。计量应以响应 usage 为依据，而非界面显示的文本长度。

请使用实际业务环境完成上述验收，尤其是流式、工具调用和多轮对话。

6. 故障排查与配置恢复

如需恢复原来的调用方式，移除业务侧新增的思考字段，恢复原有 pi 模型配置；必要时请管理员协助。注意：不传 thinking 不等于关闭模型思考。若业务需要明确关闭思考，必须使用该模型支持的关闭参数并完成验证。