GPT-5 新参数和工具

我们正在为 GPT-5 系列引入新的开发者控件，让您能够更精细地控制模型响应——从塑造输出长度和风格到强制执行严格的格式。以下是最新功能的快速概述：

| # | 功能 | 概述 | 值 / 用途 |

支持的模型：

• gpt-5
• gpt-5-mini
• gpt-5-nano

支持的 API 端点

• 响应 API
• 聊天补全 API

注意：我们建议将响应 API 与 GPT-5 系列模型结合使用，以充分发挥模型的性能。

先决条件

让我们开始更新支持 GPT-5 新参数和工具的 OpenAI SDK。请确保您已将 OPENAI_API_KEY 设置为环境变量。

!pip install --quiet --upgrade openai pandas && \
echo -n "openai " && pip show openai | grep '^Version:' | cut -d' ' -f2 && \
echo -n "pandas " && pip show pandas | grep '^Version:' | cut -d' ' -f2

openai 1.99.2
pandas 2.3.1

1. 详细程度参数

1.1 概述

详细程度参数允许您提示模型在其回复中更具扩展性或更不具扩展性。

值：“低”、“中”、“高”

• 低 → 简洁的用户体验，最少的文字。
• 中 (默认) → 平衡的细节。
• 高 → 冗长，非常适合审计、教学或交接。

保持提示稳定，并使用参数而不是重写。

from openai import OpenAI
import pandas as pd
from IPython.display import display

client = OpenAI()

question = "写一首关于一个男孩和他第一只宠物狗的诗。"

data = []

for verbosity in ["low", "medium", "high"]:
    response = client.responses.create(
        model="gpt-5-mini",
        input=question,
        text={"verbosity": verbosity}
    )

    # 提取文本
    output_text = ""
    for item in response.output:
        if hasattr(item, "content"):
            for content in item.content:
                if hasattr(content, "text"):
                    output_text += content.text

    usage = response.usage
    data.append({
        "详细程度": verbosity,
        "示例输出": output_text,
        "输出令牌": usage.output_tokens
    })

# 创建 DataFrame
df = pd.DataFrame(data)

# 漂亮地显示带居中标题的表格
pd.set_option('display.max_colwidth', None)
styled_df = df.style.set_table_styles(
    [
        {'selector': 'th', 'props': [('text-align', 'center')]},  # 居中列标题
        {'selector': 'td', 'props': [('text-align', 'left')]}     # 左对齐表格单元格
    ]
)

display(styled_df)

输出令牌大致与详细程度成线性比例：低（560）→ 中（849）→ 高（1288）。

1.3 经验总结

新的详细程度参数可靠地扩展了模型输出的长度和深度，同时保持了正确性和推理质量——而无需更改底层提示。 在此示例中：

• 低详细程度会生成最小化的、功能性的脚本，没有额外的注释或结构。
• 中详细程度添加了说明性注释、函数结构和可重复性控件。
• 高详细程度生成了全面的、生产就绪的脚本，包含参数解析、多种排序方法、计时/验证、用法说明和最佳实践提示。

2. 自由格式函数调用

2.1 概述

GPT‑5 现在可以通过新的工具 "type": "custom" 将原始文本负载——从 Python 脚本到 SQL 查询——发送到您的自定义工具，而无需将数据包装在 JSON 中。这与经典的结构化函数调用不同，为与外部运行时交互提供了更大的灵活性，例如：

• code_exec 沙箱（Python、C++、Java 等）
• SQL 数据库
• Shell 环境
• 配置生成器

请注意，自定义工具类型不支持并行工具调用。

2.2 快速入门示例 - 计算圆的面积

下面的代码生成了一个简单的 Python 代码来计算圆的面积，并指示模型使用自由格式工具调用来输出结果。

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5-mini",
    input="请使用 code_exec 工具计算半径等于 strawberry 中 'r' 数量的圆的面积",
    text={"format": {"type": "text"}},
    tools=[
        {
            "type": "custom",
            "name": "code_exec",
            "description": "执行任意 Python 代码",
        }
    ]
)
print(response.output)

[ResponseReasoningItem(id='rs_6894e31b1f8081999d18325e5aeffcfe0861a2e1728d1664', summary=[], type='reasoning', content=[], encrypted_content=None, status=None), ResponseCustomToolCall(call_id='call_Gnqod2MwPvayp2JdNyA0z0Ah', input='# Counting \'r\'s in the word "strawberry" and computing circle area with that radius\nimport math\nr = "strawberry".count(\'r\')\narea = math.pi * r**2\n{"radius": r, "area": area, "area_exact": f"{r}*pi"}', name='code_exec', type='custom_tool_call', id='ctc_6894e31c66f08199abd622bb5ac3c4260861a2e1728d1664', status='completed')]

模型发出一个包含原始 Python 的 tool call。您在服务器端执行该代码，捕获打印的结果，并在后续的 responses.create 调用中将其发送回来。

2.3 微基准测试 – 三种语言的数组排序

为了说明自由格式工具调用的用法，我们将要求 GPT-5：

• 生成排序固定数组的 Python、C++ 和 Java 代码（各 10 次）。
• 仅打印每次迭代所需的时间（以毫秒为单位）。
• 调用所有三个函数，然后停止。

from openai import OpenAI
from typing import List, Optional

MODEL_NAME = "gpt-5"

# 将传递给所有模型调用的工具。它们被定义一次，
# 以便配置保存在一个地方。
TOOLS = [
    {
        "type": "custom",
        "name": "code_exec_python",
        "description": "执行 Python 代码",
    },
    {
        "type": "custom",
        "name": "code_exec_cpp",
        "description": "执行 C++ 代码",
    },
    {
        "type": "custom",
        "name": "code_exec_java",
        "description": "执行 Java 代码",
    },
]

client = OpenAI()

def create_response(
    input_messages: List[dict],
    previous_response_id: Optional[str] = None,
):
    """包装 ``client.responses.create``。

    参数
    ----------
    input_messages: List[dict]
        要馈送给模型的运行对话历史。
    previous_response_id: str | None
        传递*上一个*调用的 ``response.id``，以便模型可以保持对话线程。首次请求时省略。
    """
    kwargs = {
        "model": MODEL_NAME,
        "input": input_messages,
        "text": {"format": {"type": "text"}},
        "tools": TOOLS,
    }
    if previous_response_id:
        kwargs["previous_response_id"] = previous_response_id

    return client.responses.create(**kwargs)

# 递归调用
def run_conversation(
    input_messages: List[dict],
    previous_response_id: Optional[str] = None,
):

    response = create_response(input_messages, previous_response_id)

    # ``response.output`` 预计是一个列表，其中元素 0 是模型消息。
    # 元素 1（如果存在）表示工具调用。当模型完成工具调用时，该元素将被省略。
    tool_call = response.output[1] if len(response.output) > 1 else None

    if tool_call and tool_call.type == "custom_tool_call":
        print("--- tool name ---")
        print(tool_call.name)
        print("--- tool call argument (generated code) ---")
        print(tool_call.input)

        # 添加一个合成的*工具结果*，以便模型可以继续线程。

        input_messages.append(
            {
                "type": "function_call_output",
                "call_id": tool_call.call_id,
                "output": "done", # <-- replace with the result of the tool call
            }
        )

        # 使用更新后的对话进行递归调用，并跟踪响应 ID，以便模型了解之前的回合。
        return run_conversation(input_messages, previous_response_id=response.id)
    else:
        # 基本情况：没有进一步的工具调用 - 返回。
        return


prompt = """
编写代码，使用 code_exec 函数以三种语言（C++、Python 和 Java）对数组进行排序（各 10 次）。

始终只调用这三个函数一次：code_exec_python、code_exec_cpp 和 code_exec_java 工具来对每种语言的数组进行排序。调用完每种语言的这三个函数后停止。

仅打印排序数组所需的时间（毫秒）。

[448, 986, 255, 884, 632, 623, 246, 439, 936, 925, 644, 159, 777, 986, 706, 723, 534, 862, 195, 686, 846, 880, 970, 276, 613, 736, 329, 622, 870, 284, 945, 708, 267, 327, 678, 807, 687, 890, 907, 645, 364, 333, 385, 262, 730, 603, 945, 358, 923, 930, 761, 504, 870, 561, 517, 928, 994, 949, 233, 137, 670, 555, 149, 870, 997, 809, 180, 498, 914, 508, 411, 378, 394, 368, 766, 486, 757, 319, 338, 159, 585, 934, 654, 194, 542, 188, 934, 163, 889, 736, 792, 737, 667, 772, 198, 971, 459, 402, 989, 949]
"""

# 初始开发者消息。
messages = [
    {
        "role": "developer",
        "content": prompt,
    }
]

run_conversation(messages)

--- tool name ---
code_exec_python
--- tool call argument (generated code) ---
import time

arr = [448, 986, 255, 884, 632, 623, 246, 439, 936, 925, 644, 159, 777, 986, 706, 723, 534, 862, 195, 686, 846, 880, 970, 276, 613, 736, 329, 622, 870, 284, 945, 708, 267, 327, 678, 807, 687, 890, 907, 645, 364, 333, 385, 262, 730, 603, 945, 358, 923, 930, 761, 504, 870, 561, 517, 928, 994, 949, 233, 137, 670, 555, 149, 870, 997, 809, 180, 498, 914, 508, 411, 378, 394, 368, 766, 486, 757, 319, 338, 159, 585, 934, 654, 194, 542, 188, 934, 163, 889, 736, 792, 737, 667, 772, 198, 971, 459, 402, 989, 949]

start = time.perf_counter()
for _ in range(10):
    b = arr[:]  # copy
    b.sort()
elapsed_ms = int((time.perf_counter() - start) * 1000)
print(elapsed_ms, end="")
--- tool name ---
code_exec_cpp
--- tool call argument (generated code) ---
#include <iostream>
#include <vector>
#include <algorithm>
#include <chrono>
using namespace std;

int main() {
    vector<int> a = {448, 986, 255, 884, 632, 623, 246, 439, 936, 925, 644, 159, 777, 986, 706, 723, 534, 862, 195, 686, 846, 880, 970, 276, 613, 736, 329, 622, 870, 284, 945, 708, 267, 327, 678, 807, 687, 890, 907, 645, 364, 333, 385, 262, 730, 603, 945, 358, 923, 930, 761, 504, 870, 561, 517, 928, 994, 949, 233, 137, 670, 555, 149, 870, 997, 809, 180, 498, 914, 508, 411, 378, 394, 368, 766, 486, 757, 319, 338, 159, 585, 934, 654, 194, 542, 188, 934, 163, 889, 736, 792, 737, 667, 772, 198, 971, 459, 402, 989, 949};
    auto start = chrono::high_resolution_clock::now();
    for (int i = 0; i < 10; ++i) {
        auto b = a;
        sort(b.begin(), b.end());
    }
    auto end = chrono::high_resolution_clock::now();
    auto ms = chrono::duration_cast<chrono::milliseconds>(end - start).count();
    cout << ms;
    return 0;
}
--- tool name ---
code_exec_java
--- tool call argument (generated code) ---
import java.util.*;
public class Main {
    public static void main(String[] args) {
        int[] a = new int[] {448, 986, 255, 884, 632, 623, 246, 439, 936, 925, 644, 159, 777, 986, 706, 723, 534, 862, 195, 686, 846, 880, 970, 276, 613, 736, 329, 622, 870, 284, 945, 708, 267, 327, 678, 807, 687, 890, 907, 645, 364, 333, 385, 262, 730, 603, 945, 358, 923, 930, 761, 504, 870, 561, 517, 928, 994, 949, 233, 137, 670, 555, 149, 870, 997, 809, 180, 498, 914, 508, 411, 378, 394, 368, 766, 486, 757, 319, 338, 159, 585, 934, 654, 194, 542, 188, 934, 163, 889, 736, 792, 737, 667, 772, 198, 971, 459, 402, 989, 949};
        long start = System.nanoTime();
        for (int i = 0; i < 10; i++) {
            int[] b = Arrays.copyOf(a, a.length);
            Arrays.sort(b);
        }
        long elapsedMs = (System.nanoTime() - start) / 1_000_000L;
        System.out.print(elapsedMs);
    }
}

模型输出了 Python、C++ 和 Java 的三个代码块，用于相同的算法。函数调用的输出被链接回模型作为输入，以允许模型继续进行，直到所有函数都被调用一次。

2.4 经验总结

GPT-5 中的自由格式工具调用允许您将原始文本负载——例如 Python 脚本、SQL 查询或配置文件——直接发送到自定义工具，而无需 JSON 包装。这为与外部运行时交互提供了更大的灵活性，并允许模型以您的工具期望的确切格式生成代码或文本。当不需要结构化 JSON 且自然文本输出可提高可用性时，它是理想选择。

3. 上下文无关文法 (CFG)

3.1 概述

上下文无关文法是定义语言中有效字符串的生成规则集合。每条规则将一个非终结符重写为一系列终结符（字面标记）和/或其他非终结符，独立于周围的上下文——因此称为上下文无关。CFG 可以捕获大多数编程语言的语法，并且在 OpenAI 自定义工具中，它们可以作为合同，强制模型仅生成语法可接受的字符串。

3.2 文法基础

支持的文法语法

• Lark - https://lark-parser.readthedocs.io/en/stable/
• Regex - https://docs.rs/regex/latest/regex/#syntax

我们在底层使用 LLGuidance 来约束模型采样：https://github.com/guidance-ai/llguidance。

不支持的 Lark 功能

• 正则表达式中的环视（(?=...)、(?!...) 等）
• 正则表达式中的惰性修饰符（*?、+?、??）。
• 终端优先级、模板、%declares、%import（除了 %import common）。

终结符与规则 & 贪婪词法分析

| 概念 | 要点 |

** 正确 vs 错误模式设计

✅ 一个有界终结符处理锚点之间的自由文本 start: SENTENCE SENTENCE: /[A-Za-z, ](the hero|a dragon)[A-Za-z, ](fought|saved)[A-Za-z, ](a treasure|the kingdom)[A-Za-z, ]./

❌ 不要将自由文本拆分到多个终结符/规则中 start: sentence sentence: /[A-Za-z, ]+/ subject /[A-Za-z, ]+/ verb /[A-Za-z, ]+/ object /[A-Za-z, ]+/

3.3 示例 - SQL 方言 — MS SQL vs PostgreSQL

以下代码示例是构建多方言 SQL 工具与 CFG 的规范参考。它演示了：

• 两个独立的文法定义（mssql_grammar_definition、postgres_grammar_definition），编码了 TOP 与 LIMIT 的语义。
• 如何在单个脚本中提示、调用和检查工具调用。
• 并排检查助手的响应。

为不同的 SQL 方言定义 LARK 文法

import textwrap

# ----------------- MS SQL 方言的文法 -----------------
mssql_grammar = textwrap.dedent(r"""
            // ---------- 标点符号和运算符 ----------
            SP: " "
            COMMA: ","
            GT: ">"
            EQ: "="
            SEMI: ";"

            // ---------- 开始 ----------
            start: "SELECT" SP "TOP" SP NUMBER SP select_list SP "FROM" SP table SP "WHERE" SP amount_filter SP "AND" SP date_filter SP "ORDER" SP "BY" SP sort_cols SEMI

            // ---------- 投影 ----------
            select_list: column (COMMA SP column)*
            column: IDENTIFIER

            // ---------- 表 ----------
            table: IDENTIFIER

            // ---------- 过滤器 ----------
            amount_filter: "total_amount" SP GT SP NUMBER
            date_filter: "order_date" SP GT SP DATE

            // ---------- 排序 ----------
            sort_cols: "order_date" SP "DESC"

            // ---------- 终结符 ----------
            IDENTIFIER: /[A-Za-z_][A-Za-z0-9_]*/
            NUMBER: /[0-9]+/
            DATE: /'[0-9]{4}-[0-9]{2}-[0-9]{2}'/
    """)

# ----------------- PostgreSQL 方言的文法 -----------------
postgres_grammar = textwrap.dedent(r"""
            // ---------- 标点符号和运算符 ----------
            SP: " "
            COMMA: ","
            GT: ">"
            EQ: "="
            SEMI: ";"

            // ---------- 开始 ----------
            start: "SELECT" SP select_list SP "FROM" SP table SP "WHERE" SP amount_filter SP "AND" SP date_filter SP "ORDER" SP "BY" SP sort_cols SP "LIMIT" SP NUMBER SEMI

            // ---------- 投影 ----------
            select_list: column (COMMA SP column)*
            column: IDENTIFIER

            // ---------- 表 ----------
            table: IDENTIFIER

            // ---------- 过滤器 ----------
            amount_filter: "total_amount" SP GT SP NUMBER
            date_filter: "order_date" SP GT SP DATE

            // ---------- 排序 ----------
            sort_cols: "order_date" SP "DESC"

            // ---------- 终结符 ----------
            IDENTIFIER: /[A-Za-z_][A-Za-z0-9_]*/
            NUMBER: /[0-9]+/
            DATE: /'[0-9]{4}-[0-9]{2}-[0-9]{2}'/
    """)

3.4 生成特定的 SQL 方言

让我们定义提示，并调用函数来生成 MS SQL 方言

from openai import OpenAI
client = OpenAI()

sql_prompt_mssql = (
    "调用 mssql_grammar 为 Microsoft SQL Server 生成一个查询，该查询检索每个客户最近的五个订单，显示 customer_id、order_id、order_date 和 total_amount，"
    "其中 total_amount > 500 且 order_date 在 '2025-01-01' 之后。"
)

response_mssql = client.responses.create(
    model="gpt-5",
    input=sql_prompt_mssql,
    text={"format": {"type": "text"}},
    tools=[
        {
            "type": "custom",
            "name": "mssql_grammar",
            "description": "执行只读的 Microsoft SQL Server 查询，仅限于 SELECT 语句，包含 TOP 和基本的 WHERE/ORDER BY。您必须仔细推理查询并确保它遵守文法。",
            "format": {
                "type": "grammar",
                "syntax": "lark",
                "definition": mssql_grammar
            }
        },
    ],
    parallel_tool_calls=False
)

print("--- MS SQL Query ---")
print(response_mssql.output[1].input)

--- MS SQL Query ---
SELECT TOP 5 customer_id, order_id, order_date, total_amount FROM orders WHERE total_amount > 500 AND order_date > '2025-01-01' ORDER BY order_date DESC;

输出的 SQL 准确地使用了“SELECT TOP”结构。

sql_prompt_pg = (
    "调用 postgres_grammar 为 PostgreSQL 生成一个查询，该查询检索每个客户最近的五个订单，显示 customer_id、order_id、order_date 和 total_amount，"
    "其中 total_amount > 500 且 order_date 在 '2025-01-01' 之后。"
)

response_pg = client.responses.create(
    model="gpt-5",
    input=sql_prompt_pg,
    text={"format": {"type": "text"}},
    tools=[
        {
            "type": "custom",
            "name": "postgres_grammar",
            "description": "执行只读的 PostgreSQL 查询，仅限于 SELECT 语句，包含 LIMIT 和基本的 WHERE/ORDER BY。您必须仔细推理查询并确保它遵守文法。",
            "format": {
                "type": "grammar",
                "syntax": "lark",
                "definition": postgres_grammar
            }
        },
    ],
    parallel_tool_calls=False,
)

print("--- PG SQL Query ---")
print(response_pg.output[1].input)

--- PG SQL Query ---
SELECT customer_id, order_id, order_date, total_amount FROM orders WHERE total_amount > 500 AND order_date > '2025-01-01' ORDER BY order_date DESC LIMIT 5;

输出突出了相同的逻辑查询——不同的物理语法。提供不同的文法，以便模型只能为所选方言生成有效的语句。

| 方言 | 生成的查询 | 关键区别 |

3.5 示例 - Regex CFG 语法

以下代码示例演示了如何使用 Regex CFG 语法将自由格式工具调用限制为特定的时间戳模式。

from openai import OpenAI
client = OpenAI()

timestamp_grammar_definition = r"^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01]) (?:[01]\d|2[0-3]):[0-5]\d$"

timestamp_prompt = (
        "调用 timestamp_grammar 为 2025 年 8 月 7 日上午 10 点保存一个时间戳。"
)

response_mssql = client.responses.create(
    model="gpt-5",
    input=timestamp_prompt,
    text={"format": {"type": "text"}},
    tools=[
        {
            "type": "custom",
            "name": "timestamp_grammar",
            "description": "以 24 小时格式保存日期 + 时间戳。",
            "format": {
                "type": "grammar",
                "syntax": "regex",
                "definition": timestamp_grammar_definition
            }
        },
    ],
    parallel_tool_calls=False
)

print("--- Timestamp ---")
print(response_mssql.output[1].input)

--- Timestamp ---
2025-08-07 10:00

3.5 最佳实践

Lark 文法可能很难完善。虽然简单的文法最可靠，但复杂的文法通常需要对文法定义本身、提示和工具描述进行迭代，以确保模型不会超出分布。

• 保持终结符有界——使用 /[^.\n]{0,10}*\./ 而不是 /.*\./。通过内容（否定字符类）和长度（{M,N} 量词）限制匹配。
• 优先使用显式字符类而不是 . 通配符。
• 显式地处理空格，例如使用 SP = " "，而不是全局的 %ignore。
• 描述您的工具：准确告知模型 CFG 接受的内容，并指示它进行大量推理以确保合规性。

故障排除

• API 因文法过于复杂而拒绝 —— 简化规则和终结符，删除 %ignore.*。
• 意外的标记 ―― 确认终结符没有重叠；检查贪婪词法分析器。
• 当模型偏离“分布外”（表现为模型产生过长或重复的输出，虽然语法有效但语义错误）时：
  • 收紧文法。
  • 迭代提示（添加少量示例）和工具描述（解释文法并指示模型进行推理以符合它）。
  • 尝试更高的推理努力（例如，从“中”提高到“高”）。

资源：

• Lark 文档 – https://lark-parser.readthedocs.io/en/stable/
• Lark IDE – https://www.lark-parser.org/ide/
• LLGuidance 语法 – https://github.com/guidance-ai/llguidance/blob/main/docs/syntax.md
• Regex (Rust crate) – https://docs.rs/regex/latest/regex/#syntax

3.6 经验总结

GPT-5 中的上下文无关文法 (CFG) 支持允许您将模型输出严格限制为匹配预定义的语法，确保只生成有效字符串。这对于强制执行编程语言规则或自定义格式特别有用，可以减少后期处理和错误。通过提供精确的文法和清晰的工具描述，您可以使模型可靠地保持在目标输出结构内。

4. 最小推理

4.1 概述

GPT-5 现在支持新的最小推理功能。在使用最小推理时，模型将输出很少或不输出推理令牌。这适用于开发者希望获得非常快的首次用户可见令牌时间的用例。注意：如果未提供推理努力程度，则默认值为中等。

from openai import OpenAI

client = OpenAI()

prompt = "将评论的情感分类为积极|中性|消极。只返回一个词。"


response = client.responses.create(
    model="gpt-5",
    input= [{ 'role': 'developer', 'content': prompt },
            { 'role': 'user', 'content': '这家餐厅的食物很棒！我推荐给所有人。' }],
    reasoning = {
        "effort": "minimal"
    },
)

# 提取模型的文本输出
output_text = ""
for item in response.output:
    if hasattr(item, "content"):
        for content in item.content:
            if hasattr(content, "text"):
                output_text += content.text

# 令牌使用详情
usage = response.usage

print("--------------------------------")
print("输出:")
print(output_text)

--------------------------------
输出:
positive

4.2 经验总结

最小推理使用很少或没有推理令牌运行 GPT-5，以最小化延迟并加快首次令牌时间。将其用于确定性、轻量级任务（提取、格式化、简短重写、简单分类），而无需解释。如果您不指定努力程度，它默认为中等——当您希望速度胜过深思熟虑时，请明确设置最小。