> ## Documentation Index
> Fetch the complete documentation index at: https://ppio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Interleaved Thinking 支持

> 更新时间：2025-12-03 <br />
> 状态：已支持（兼容 OpenAI）

## 介绍

Interleaved Thinking 是一种先进的推理框架，使模型能够在每次调用工具前后进行显式的思考和决策。具备 Interleaved Thinking 能力的模型可以：

* 针对当前环境和工具的输出进行反思
* 基于最新的推理结果决定下一步行动
* 在多次工具调用过程中持续保持连贯的推理链路
* 通过 `reasoning_details` 或 `reasoning_content` 字段透明展示多步推理过程，便于跟踪和审查

这种能力将传统的函数调用模式提升为具备智能代理特征的工具使用方式，使复杂工作流程更加精准、可靠且具备更强的上下文感知能力。

## 重要概念

### 交替推理

传统方法先进行一次推理再调用工具，而交替推理则采用如下流程：

```BASH theme={null}
推理 → 工具调用 → 观察 → 推理 → 工具调用 → ...
```

这种方式使模型可以根据前一步工具返回的结果，动态调整后续策略。

### 推理详情（`reasoning_details`）

对于部分模型，模型思考内容会以单独结构体的形式返回：

```JSON theme={null}
"reasoning_details": [
  {
    "type": "reasoning.text",
    "format": "openai-responses-v1",
    "text": "Model’s step-by-step reasoning..."
  }
]
```

对于此类模型，支持在流式和非流式模式下返回该字段。

### 对话记忆

为保持推理链路的一致性，必须在后续请求中完整携带模型的全部响应，包括 `reasoning_details`、`tool_calls` 以及 `content` 字段。如果未能持续传递这些信息，可能会导致：

* 工具调用不正确
* 推理上下文丢失
* 工具调用递归或重复
* 可靠性下降

这一要求与 OpenAI 推理型接口的行为规范一致。

## API 行为

### 请求格式

用户侧无需做任何更改。Interleaved Thinking 支持标准的 OpenAI 兼容 Chat Completions API。

### 响应格式

模型响应中可能包含以下字段：

* `reasoning_content`: 原始思考内容
* `reasoning_details`: 结构化推理片段，该字段为可选项
* `tool_calls`: 工具调用计划
* `content`: 自然语言输出

这些字段扩展了标准的 OpenAI 格式。

## 示例请求（MiniMax-M2）

```JSON theme={null}
{
  "model": "minimax/minimax-m2",
  "messages": [
    {
      "role": "user",
      "content": "How's the weather in San Francisco?"
    },
    {
      "role": "assistant",
      "name": "MiniMax AI",
      "content": "",
      "tool_calls": [
        {
          "id": "call_function_asqvfevfc8af_1",
          "type": "function",
          "function": {
            "name": "get_weather",
            "arguments": "{\"location\": \"San Francisco, US\"}"
          }
        }
      ],
      "reasoning_details": [
        {
          "type": "reasoning.text",
          "id": "reasoning-text-1",
          "format": "openai-responses-v1",
          "index": 0,
          "text": "The user is asking about the weather in San Francisco..."
        }
      ]
    },
    {
      "role": "tool",
      "tool_call_id": "call_function_asqvfevfc8af_1",
      "content": "24℃, sunny"
    }
  ],
  "stream": true,
  "reasoning_split": true,
  "max_tokens": 1024,
  "temperature": 0.7,
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get weather for a specific location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": { "type": "string" }
          },
          "required": ["location"]
        }
      }
    }
  ]
}
```

## 非流式响应示例

```JSON theme={null}
{
  "id": "07a4dedfdb1498b045498dfd42497639",
  "object": "chat.completion",
  "created": 1764303147,
  "model": "MiniMax",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "",
        "name": "MiniMax",
        "tool_calls": [
          {
            "index": 0,
            "id": "call_function_9w7wq1j9zmpl_1",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"location\": \"ShangHai\"}"
            }
          }
        ],
        "reasoning_content": "The user asked for Shanghai weather...",
        "reasoning_details": [
          {
            "type": "reasoning.text",
            "text": "The user is asking about the weather in Shanghai...",
            "id": "reasoning-text-1",
            "format": "openai-responses-v1",
            "index": 0
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}
```

## 流式响应示例

```JSON theme={null}
{
  "id": "664c5ad870c1888fbcbd267d9829e354",
  "object": "chat.completion.chunk",
  "created": 1764303504,
  "model": "minimax-m2",
  "choices": [
    {
      "index": 0,
      "delta": {
        "role": "assistant",
        "reasoning_content": "...\n\nThe user has specifically asked...",
        "reasoning_details": [
          {
            "type": "reasoning.text",
            "text": ".\n\nThe user has specifically asked...",
            "id": "reasoning-text-1",
            "format": "openai-responses-v1",
            "index": 0
          }
        ]
      },
      "finish_reason": null
    }
  ]
}
```

## 接入说明

### 支持 Interleaved Thinking 的模型

所有通过 OpenAI 兼容 API 暴露 reasoning\_details 的模型，包括：

* MiniMax-M2
* （即将上线）Reasoning 系列
* 其他支持推理功能的合作模型

### 计费规则

按照模型的计费规定，reasoning token 会计入费用。\
启用 reasoning\_details 会增加 token 消耗。

### 错误处理

可能遇到的问题包括：

* 工具参数缺失
* 工具调用递归或重复
* 推理阶段假设错误

请确保应用验证工具参数，并妥善处理模型返回的错误。

### 最佳实践

**始终在下一个请求中包含完整的模型消息**

请携带：

* `content`
* `tool_calls`
* `reasoning_details`

**对于长链路推理推荐开启流式传输**

开启流式传输可以让客户端：

* 实时监控推理过程
* 及早发现工具规划错误
* 更快地给用户反馈

**结合服务端状态机保障稳定性**

对于生产系统，建议将 Interleaved Thinking 与确定性的防护机制结合使用，例如：

* 参数校验器
* 执行沙箱
* 最大递归深度保护

## 总结

Interleaved Thinking 显著提升了多步推理与工具调用的可靠性：

* 透明且可检查的逐步推理
* 在工具调用之间进行自适应规划
* 在长工作流中更强的上下文保持能力
* 完全兼容 OpenAI 风格的对话补全 API