核心参数¶

调用 {base_url}/v1/chat/completions 时，可以通过请求参数控制模型输出，适配不同场景。本页适用于 Macaron-V1.1（macaron-v1.1、macaron-v1.1-venti、macaron-v1.1-coding-venti）和 glm-5.3。

Macaron-V1.1 基于 GLM-5.3 后训练，基座模型相同，参数与 GLM-5.3 一致。原有 Macaron-V1 系列和 glm-5.2 沿用各自基座模型的参数。模型 ID 见模型。

快速参考¶

参数	类型	默认值	描述
`thinking`	对象	`{"type": "enabled"}`	思考配置。思考始终开启，`clear_thinking` 控制是否保留历史思考内容。
`reasoning_effort`	字符串	`max`	推理程度：`low`、`high`、`max`。
`do_sample`	布尔值	`true`	是否采样。设为 `false` 时总是选择概率最高的 token。
`temperature`	浮点数	`1.0`	控制输出随机性，取值 `[0.0, 1.0]`。
`top_p`	浮点数	`0.95`	核采样阈值，取值 `[0.01, 1.0]`。
`max_tokens`	整数	`65536`	单次生成的最大 token 数，最大 `131072`。
`stream`	布尔值	`false`	是否以 SSE 流式返回。
`tool_stream`	布尔值	`false`	是否流式返回函数调用参数。
`tools`	数组	无	模型可调用的函数列表，最多 128 个。
`stop`	数组	无	停止词，最多 4 个。
`response_format`	对象	`{"type": "text"}`	`text` 或 `json_object`。

参数详解¶

thinking¶

thinking 控制模型的思维链推理。Macaron-V1.1 与 GLM-5.3 始终开启思考，思考强度由 reasoning_effort 控制。

类型： 对象

属性：

type（字符串）：enabled（默认）。思考不能关闭，传 disabled 的请求会失败。如需更快响应，请保持 enabled，并将 reasoning_effort 设为 low。
clear_thinking（布尔值）：是否清除历史轮次中的 reasoning_content。它只影响历史轮次的思考内容，不改变模型在当前轮次是否思考。
- true（默认）：忽略历史轮次的思考内容，仅将可见内容、工具调用与工具结果作为上下文。适合普通对话与轻量任务，可降低上下文长度与成本。
- false：保留式思考。历史轮次的思考内容随上下文一同提供给模型。必须在 messages 中完整、未修改、按原顺序回传历史 reasoning_content，缺失、裁剪、改写或重排会导致效果下降或无法生效。推荐在 Coding / Agent 场景使用。

{
  "model": "macaron-v1.1-venti",
  "thinking": {"type": "enabled", "clear_thinking": false},
  "reasoning_effort": "max"
}

最佳实践：

思考支持交错式思考：模型可以在工具调用之间、收到工具结果之后继续思考。使用工具时，请在返回工具结果的同时回传 assistant 的 reasoning_content。
多轮 Coding 或 Agent 会话中，设置 clear_thinking: false 并原样回传思考内容，以保持推理连贯并提高缓存命中率。

reasoning_effort¶

reasoning_effort 控制模型的推理程度。

类型： 字符串
可选值： low、high、max
- low：轻量推理。
- high：增强推理。
- max（默认）：深度推理。

最佳实践：

复杂任务（如 Coding）建议使用 max。
需要更快响应、减少思考时（如简单问答、改写措辞），使用 low。

curl <BASE_URL>/v1/chat/completions \
  -H "Authorization: Bearer <MACARON_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "macaron-v1.1-venti",
    "messages": [
      {"role": "user", "content": "帮我设计并编写一个个人博客网站，包含首页、文章列表、文章详情页"}
    ],
    "thinking": {"type": "enabled"},
    "reasoning_effort": "max",
    "max_tokens": 65536,
    "temperature": 1.0
  }'

do_sample¶

do_sample 决定是否对输出进行采样。

true（默认）：根据每个 token 的概率分布，结合 temperature、top_p 随机采样，输出更多样。适用于内容创作、对话等场景。
false：总是选择概率最高的下一个 token，此时忽略 temperature 和 top_p，输出确定性更高。

最佳实践：

需要一致、可复现输出的任务（如代码生成、翻译），设为 false。
希望输出更多样时，保持 true，并配合 temperature 或 top_p 使用。

temperature¶

temperature（温度）控制输出的随机性。

取值范围： [0.0, 1.0]，限两位小数，默认 1.0。
较低的值（如 0.2）：输出更集中、更确定，适合事实性问答。
较高的值（如 0.8）：输出更随机、更有创造性，适合创意写作和头脑风暴。

最佳实践：

temperature 和 top_p 只调整其中一个，不要同时调整。

top_p¶

top_p（核采样）从累积概率达到阈值的最小 token 集合中采样。

取值范围： [0.01, 1.0]，限两位小数，默认 0.95。
较低的值（如 0.2）：缩小候选范围，输出更集中。
较高的值（如 0.9）：扩大候选范围，输出更多样。

最佳实践：

temperature 和 top_p 只调整其中一个，不要同时调整。

max_tokens¶

max_tokens 限制模型单次调用生成的最大 token 数，思考 token 也计入其中。

默认值： 65536；最大值： 131072（128K）。建议设置不小于 1024。
max_tokens 只限制生成内容的长度，不包括输入。
模型在达到上限前完成回答会自然结束；达到上限时输出会被截断，finish_reason 为 length。
也可以使用 max_completion_tokens，作用相同。

token 是文本的基本单位，1 个 token 约等于 0.75 个英文单词或 1.5 个中文字符。

最佳实践：

为思考预留空间。思考始终开启，max_tokens 过小时，额度可能在回答开始前就被思考用完。

stream¶

stream 控制响应的返回方式。

false（默认）：一次性返回完整响应。
true：以流式（SSE）方式返回。

流式返回时，思考内容以 delta.reasoning_content 分片先到，之后是回答的 delta.content 分片，最后以 data: [DONE] 结束。

最佳实践：

对话界面、实时代码生成等应用，建议设为 true。

tool_stream¶

tool_stream 控制是否流式返回函数调用参数，而不是等每个调用生成完整后再返回。需要同时设置 stream: true。

false（默认）：每个工具调用完整生成后返回。
true：工具调用参数增量返回。

tools¶

tools 是模型可调用的函数列表，最多支持 128 个函数。tool_choice 控制模型如何选择工具，默认且仅支持 auto。

{
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "获取城市天气",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }],
  "tool_choice": "auto"
}

调用结果在 choices[0].message.tool_calls 中返回，finish_reason 为 "tool_calls"。请将每个结果作为 tool 消息返回，带上对应的 tool_call_id，并一同回传 assistant 消息及其 reasoning_content。

stop¶

stop 是停止词列表，最多 4 个。生成的文本中出现其中任一字符串时立即停止生成，格式如 ["stop_word1"]。

response_format¶

response_format 指定输出格式。

{"type": "text"}（默认）：普通文本。
{"type": "json_object"}：JSON 格式输出。请同时在提示词中说明期望的字段。

读取响应¶

回答在 choices[0].message.content，思考内容在 choices[0].message.reasoning_content。
usage.prompt_tokens 和 usage.completion_tokens 分别为输入和输出 token 数。输出 token 包含思考 token，思考部分单独记录在 usage.completion_tokens_details.reasoning_tokens。

核心参数¶

快速参考¶

参数详解¶

thinking¶

reasoning_effort¶

do_sample¶

temperature¶

top_p¶

max_tokens¶

stream¶

tool_stream¶

tools¶

stop¶

response_format¶

读取响应¶

相关概念¶