MaaS_GP_5 API新特性

Minimal reasoning effort

reasoning.effort参数控制模型在生成响应之前生成多少推理相关的tokens。早期的推理模型（如 o3）仅支持 low, medium, and high

low 偏向于速度更快且推理tokens更少, while +high 则偏向于更全面的推理.

新的minimal设置会生成非常少的推理tokens，适用于需要最快响应时间的场景。通常情况下，让模型在必要时生成少量推理比完全不生成表现更好。默认设置为medium。

minimal设置在代码生成和指令遵循场景中表现尤为出色，能够严格按照给定指令执行。然而，在这种设置下，模型可能需要提示才能表现得更主动。即使在“minimal”模式下，也可以通过鼓励模型“思考”或在回答前列出步骤来提升推理质量。

curl --request POST \
--url https://genaiapi.cloudsway.net/v1/ai/xxx/chat/completions \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-type: application/json' \
--data '{
  "model": "gpt-5",
  "messages": [
    {
      "role": "user",
      "content": "How much gold would it take to coat the Statue of Liberty in a 1mm layer?"
    }
  ],
  "reasoning_effort": "minimal"
}'

Verbosity

Verbosity决定了生成的输出标记（tokens）的数量。减少标记数量可以降低整体延迟。虽然模型的推理方式基本保持不变，但模型会寻找更简洁的回答方式——这可能会根据你的使用场景提升或降低回答质量。以下是冗长度两端的适用场景：

高冗长度：适用于需要模型提供详细文档解释或执行大规模代码重构的场景。

低冗长度：适合需要简洁回答或简单代码生成的场景，例如 SQL 查询。

GPT-5 之前的模型默认使用中等冗长度。自 GPT-5 起，此选项可配置为high、medium或low。

在生成代码时，medium和high冗长度会生成更长、更结构化的代码，并附带内联注释；而low冗长度则会生成更简短、更精炼的代码，注释较少。

curl --request POST \
--url https://api.yisu.com/v1/ai/xxx/chat/completions \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-type: application/json' \
--data '{
  "model": "gpt-5",
  "messages": [
    { "role": "user", "content": "What is the answer to the ultimate question of life, the universe, and everything?" }
  ],
  "verbosity": "low"
}'

Custom tools

在 GPT-5 中，我们引入了一项新功能，称为自定义工具（Custom Tools）。该功能允许模型将任意原始文本作为工具调用的输入，同时在需要时仍然可以约束输出。

Freeform inputs

通过将工具定义为 type: custom，可以启用模型直接将纯文本输入发送到你的工具，而不再局限于结构化的 JSON 格式。借助这一功能，模型可以将任何原始文本——例如代码、SQL 查询、Shell 命令、配置文件，甚至是长篇文章——直接发送到你的工具。

这种功能赋予了工具调用更多的灵活性，适用于处理复杂或非结构化输入的场景。

{
    "type": "custom",
    "name": "code_exec",
    "description": "Executes arbitrary python code",
}

curl --request POST --url https://api.yisu.com/v1/ai/xxx/chat/completions --header "Authorization: Bearer $API_KEY" --header 'Content-type: application/json' --data '{
  "model": "gpt-5",
  "messages": [
    { "role": "user", "content": "Use the code_exec tool to calculate the area of a circle with radius equal to the number of r letters in blueberry" }
  ],
  "tools": [
    {
      "type": "custom",
      "custom": {
        "name": "code_exec",
        "description": "Executes arbitrary python code"
      }
    }
  ]
}'

Constraining outputs

GPT-5 支持上下文无关文法（Context-Free Grammars, CFGs）用于自定义工具，这允许你提供一份 Lark 文法，以将输出约束为特定的语法或领域专用语言（DSL）。

通过附加 CFG（例如 SQL 或 DSL 文法），可以确保助手生成的文本符合你的文法规则。

这项功能使得工具调用或结构化响应更加精确和受控，同时可以在 GPT-5 的功能调用中直接强制执行严格的语法或领域特定格式，从而在复杂或受限领域中提升控制力和可靠性。

Best practices for custom tools

编写简洁明确的工具描述：模型会根据你的描述选择发送内容；如果希望模型始终调用工具，请明确说明。

在服务器端验证输出：自由格式字符串功能强大，但需要采取措施防范注入攻击或不安全命令。

Allowed tools

tool_choice 参数下的 allowed_tools 允许你传递 N 个工具定义，但将模型限制为只能使用其中的 M 个（M < N）。

你可以在 tools 中列出完整的工具集，然后使用 allowed_tools 块来指定一个子集，并定义模式（mode）：

auto：模型可以从指定的工具中任意选择一个调用。

required：模型必须调用其中一个工具。

通过将所有可能的工具与当前可用的子集分离，你可以获得更高的安全性、可预测性以及更好的提示缓存效果。同时，你可以避免脆弱的提示工程问题，例如硬编码的调用顺序。GPT-5 能在对话过程中动态调用或要求特定功能，同时减少在长上下文中意外使用工具的风险。

Allowed tools在chatCompletions接口中使用

curl --location 'https://api.yisu.com/v1/ai/xxx/chat/completions' \
--header 'Authorization: Bearer $API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "model": "gpt-5",
    "messages": [
        {
            "role":"user",
            "content":"Please use the code_exec tool to calculate the area of a circle with radius equal to the number of '\''r'\''s in strawberry"
        }
    ],
    "tools": [
        {
            "type": "custom",
            "custom": {
                "name": "code_exec",
                "description": "Executes arbitrary python code"
            }
        },
        {
            "type": "function",
            "function": {
                "name": "get_weather",
                "description": "Get the current weather in a given location",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "The city and state, e.g. San Francisco, CA"
                        }
                    },
                    "required": [
                        "location"
                    ]
                }
            }
        }
    ],
    "tool_choice": {
        "type": "allowed_tools",
        "allowed_tools": {
            "mode": "auto",
            "tools": [
                {
                    "type": "function",
                    "function": {
                        "name": "get_weather"
                    }
                },
                {
                    "type": "custom",
                    "custom": {
                        "name": "code_exec"
                    }
                }
            ]
        }
    }
}'