控制推理模型努力程度 (Chat Completions)

接口描述

给定一个提示，该模型将返回一个或多个预测的补全回复（支持控制推理模型的思考努力程度）。

官方文档参考：OpenAI Reasoning Guides
接口状态：已发布 (released)

请求说明

请求方式：POST
请求地址：https://api.codingplanx.ai/v1/chat/completions

请求头 (Headers)

参数名称	必填	类型	示例值	描述
`Content-Type`	是	`string`	`application/json`	数据格式
`Accept`	是	`string`	`application/json`	接收格式
`Authorization`	否	`string`	`Bearer {{YOUR_API_KEY}}`	身份验证凭证

请求体参数 (Body)

数据格式：application/json

参数名称	必填	类型	描述
`model`	是	`string`	要使用的模型的 ID（例如 `o4-mini` 等）。
`messages`	是	`array`	至今为止对话所包含的消息列表。包含 `role` (如 user/assistant) 和 `content` (消息内容)。
`tools`	是	`array`	模型可以调用的一组工具（函数）列表。用于提供模型可以为其生成 JSON 输入的函数。
`tool_choice`	是	`object`	控制模型调用哪个函数。`none` 表示不调用，`auto` 表示自动选择。
`reasoning_effort`	否	`string`	核心参数：控制推理模型在生成回复时的努力程度（思考深度）。常见可选值为 `low`、`medium`、`high`。
`temperature`	否	`number`	采样温度，介于 0 和 2 之间。较高的值（如 0.8）输出更随机，较低的值（如 0.2）输出更集中和确定。建议与 `top_p` 仅修改其中一个。
`top_p`	否	`number`	核采样。0.1 意味着只考虑构成前 10% 概率质量的标记。建议与 `temperature` 仅修改其中一个。
`n`	否	`integer`	默认为 1。为每个输入消息生成多少个聊天补全选择。
`stream`	否	`boolean`	默认为 false。如果设置为 true，将以 Server-Sent Events (SSE) 形式发送部分消息增量，并在 `data: [DONE]` 终止流。
`stop`	否	`string`	最多 4 个序列的字符串，API 将在此处停止进一步生成标记。
`max_tokens`	否	`integer`	聊天补全中生成的最大标记数。输入和生成标记的总长度受模型的上下文长度限制。
`presence_penalty`	否	`number`	-2.0 到 2.0 之间的数字。正值会根据新标记是否已出现进行惩罚，增加谈论新主题的可能性。
`frequency_penalty`	否	`number`	-2.0 到 2.0 之间的数字。正值根据文本目前的存在频率惩罚新标记，降低重复相同内容的可能性。
`logit_bias`	否	`object`	接受一个 JSON 对象，将标记 ID 映射到偏差值（-100 到 100），用于修改指定标记出现在补全中的可能性。
`user`	否	`string`	代表最终用户的唯一标识符，帮助监控和检测滥用行为。
`response_format`	否	`object`	指定模型必须输出的格式。例如 `{"type": "json_object"}` 启用 JSON 模式。
`seen`	否	`integer`	测试阶段功能（类似 seed）。指定后系统将尽最大努力确定性地进行采样，以便相同参数返回相同结果。

请求示例

{
  "model": "o4-mini",
  "max_tokens": 500,
  "messages": [
    {
      "role": "user",
      "content": "你好，请详细解释一下量子计算的原理。"
    }
  ],
  "temperature": 1.0,
  "stream": false,
  "reasoning_effort": "medium"
}

响应说明

响应体参数

数据格式：application/json

参数名称	类型	描述
`id`	`string`	本次请求的唯一标识符。
`object`	`string`	对象类型，通常为 `chat.completion`。
`created`	`integer`	创建时间的时间戳。
`choices`	`array`	补全结果列表。
└ `index`	`integer`	当前选择在列表中的索引。
└ `message`	`object`	模型生成的回复消息体。包含 `role` 和 `content`。
└ `finish_reason`	`string`	停止生成的原因（例如 `stop`, `length`）。
`usage`	`object`	Token 消耗统计。
└ `prompt_tokens`	`integer`	提示词消耗的 Token 数。
└ `completion_tokens`	`integer`	模型生成消耗的 Token 数。
└ `total_tokens`	`integer`	总计消耗的 Token 数。

响应示例 (HTTP 200 OK)

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "\r
\r
Hello there, how may I assist you today?"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 12,
        "total_tokens": 21
    }
}

FAQs (常见问题解答)

1. `reasoning_effort` 参数的作用是什么？

reasoning_effort 用于控制具备高级推理能力（Reasoning）的模型（如 OpenAI 的 o1/o4 系列模型）在给出最终答案前，花费多少计算资源和时间来进行内在思考。通常支持 low、medium、high 三种级别。设置为 high 时，模型会进行更深度的逻辑推导，适合解决复杂的数学或编程问题；但相应的响应时间也会增加。

2. 为什么开启 `stream: true` 后，收到的不是标准的 JSON 响应？

当开启流式传输 (stream: true) 时，API 会使用 Server-Sent Events (SSE) 协议持续返回数据块（Chunks）。每个数据块以 data: {...} 的形式发送，当所有内容传输完毕时，会发送一条 data: [DONE] 消息。开发者需要通过逐行读取并解析 data: 后面的 JSON 字符串来拼接完整回复。

3. 文档中提到 `temperature` 和 `top_p` 建议只修改其中一个，为什么？

这两个参数都是用来控制模型输出内容的随机性和多样性的。temperature 通过缩放 logits 来改变概率分布，而 top_p（核采样）通过截断累积概率较低的词汇来限制候选池。同时调整这两个参数会使模型的行为难以预测和控制，因此最佳实践是固定其中一个（通常保持默认），只调整另一个来满足对“随机性”的控制需求。

4. 如果遇到 `finish_reason` 返回 `"length"` 是什么意思？

这表示模型的回复被强行截断了。原因通常有两个：一是生成的 Token 数量达到了请求参数中设置的 max_tokens 上限；二是你的请求提示词（Prompt）加上模型生成的回复，总 Token 数超过了该模型允许的最大上下文窗口限制。此时建议缩短历史对话记录，或者调大 max_tokens 参数。

5. 如何强制模型返回 JSON 格式的数据？

你可以通过在请求体中传入 "response_format": {"type": "json_object"} 来开启 JSON 模式。非常重要：在开启此模式的同时，你必须在 messages（通常是 system 或 user 提示中）明确使用自然语言要求模型输出 JSON。否则，模型可能会陷入无限生成空白符的死循环，直到达到 Token 限制。