如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

函数调用

让模型能够使用新的功能和数据来执行指令并回应提示词。

函数调用(也称为工具调用)让 OpenAI 模型能够灵活地与外部系统交互,访问训练数据以外的数据。本指南介绍如何让模型访问应用提供的数据并执行应用支持的操作。您将了解如何使用由 JSON 模式定义的函数工具,以及支持自由格式文本输入和输出的自定义工具。

在 Agents API 会话中,请使用函数注册函数并处理会话中的操作请求。本指南中的示例展示了如何与 Responses API 和 Chat Completions 集成。

如果您的应用包含大量函数或较大的模式,可以将函数调用与工具搜索结合使用,推迟加载不常用的工具,直到模型需要时才加载。只有 gpt-5.4 及后续模型支持 tool_search。

GPT-6 Astra 和 GPT-6.1 Sol 必须通过 Responses API 调用工具。Chat Completions 示例使用 GPT-5.6 Terra,并关闭了推理。要更新现有集成,请参阅迁移指南。

工作原理

先来了解工具调用中的几个关键术语,再通过实际示例看看如何调用工具。

工具调用流程

工具调用是您的应用通过 OpenAI API 与模型进行多步交互的过程。整个流程大致分为五步:

  1. 向模型发送请求,并提供可调用的工具
  2. 接收模型返回的工具调用
  3. 使用工具调用提供的输入,在应用端执行代码
  4. 将工具输出放入第二次请求中,发送给模型
  5. 接收模型的最终响应(或更多工具调用)

函数调用流程图

使用 Responses 时,应用可以按任务需要重复这一流程,直到完成所需的工具调用。如果您希望使用框架来处理这个循环中反复出现的编排工作,请参阅 Responses API 与 Agents SDK 的比较。

函数工具示例

下面以 get_horoscope 函数为例,展示完整的工具调用流程。该函数可以查询指定星座的每日运势。

完整工具调用示例
from openai import OpenAI
import json

client = OpenAI()

# 1. Define a list of callable tools for the model
tools = [
    {
        "type": "function",
        "name": "get_horoscope",
        "strict": True,
        "description": "Get today's horoscope for an astrological sign.",
        "parameters": {
            "type": "object",
            "properties": {
                "sign": {
                    "type": "string",
                    "description": "An astrological sign like Taurus or Aquarius",
                },
            },
            "required": ["sign"],
            "additionalProperties": False,
        },
    },
]


def get_horoscope(sign):
    return f"{sign}: Next Tuesday you will befriend a baby otter."


# Create a running input list we will add to over time
input_list = [{"role": "user", "content": "What is my horoscope? I am an Aquarius."}]

# 2. Prompt the model with tools defined
response = client.responses.create(
    model="gpt-6.2-astra",
    tools=tools,
    input=input_list,
)

# Save function call outputs for subsequent requests
input_list += response.output

for item in response.output:
    if item.type == "function_call":
        if item.name == "get_horoscope":
            # 3. Execute the function logic for get_horoscope
            sign = json.loads(item.arguments)["sign"]
            horoscope = get_horoscope(sign)

            # 4. Provide function call results to the model
            input_list.append(
                {
                    "type": "function_call_output",
                    "call_id": item.call_id,
                    "output": horoscope,
                }
            )

response = client.responses.create(
    model="gpt-6.2-astra",
    instructions="Respond only with a horoscope generated by a tool.",
    tools=tools,
    input=input_list,
)

# 5. The model should be able to give a response!
print(response.output_text)

对于 GPT-5 或 o4-mini 等推理模型,如果模型的响应中包含工具调用,您必须将该响应中的所有推理项与工具调用输出一起发回给模型。有关如何保留模型生成这些推理项时所依据的对话历史,请参阅更改前缀的最佳实践。

定义函数

通常在每个 API 请求的 tools 参数中声明函数。使用工具搜索时,应用也可以在交互过程中按需加载先前推迟加载的函数。无论采用哪种方式,每个可调用函数的模式结构都相同。函数定义包含以下属性:

字段 说明
type 应始终为 function
name 函数名称(例如 get_weather)
description 详细说明何时以及如何使用函数
parameters 定义函数输入参数的 JSON 模式
strict 是否对函数调用强制使用严格模式

下面是 get_weather 函数的定义示例:

{
  "type": "function",
  "name": "get_weather",
  "description": "Retrieves current weather for the given location.",
  "parameters": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City and country e.g. Bogotá, Colombia"
      },
      "units": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "Units the temperature will be returned in."
      }
    },
    "required": ["location", "units"],
    "additionalProperties": false
  },
  "strict": true
}

由于 parameters 由 JSON 模式定义,您可以使用属性类型、枚举、描述、嵌套对象和递归对象等多种特性。

定义命名空间

使用命名空间可以按业务领域对相关工具进行分组,例如 crm、billing 或 shipping。命名空间便于组织相似的工具。当模型需要在服务于不同系统或用途的工具之间做选择时,命名空间尤其有用,例如一个搜索工具用于 CRM,另一个用于支持工单系统。

{
  "type": "namespace",
  "name": "crm",
  "description": "CRM tools for customer lookup and order management.",
  "tools": [
    {
      "type": "function",
      "name": "get_customer_profile",
      "description": "Fetch a customer profile by customer ID.",
      "parameters": {
        "type": "object",
        "properties": {
          "customer_id": { "type": "string" }
        },
        "required": ["customer_id"],
        "additionalProperties": false
      }
    },
    {
      "type": "function",
      "name": "list_open_orders",
      "description": "List open orders for a customer ID.",
      "defer_loading": true,
      "parameters": {
        "type": "object",
        "properties": {
          "customer_id": { "type": "string" }
        },
        "required": ["customer_id"],
        "additionalProperties": false
      }
    }
  ]
}

工具搜索

如果需要让模型使用大量工具,可以通过 tool_search 推迟加载部分或全部工具。模型可以使用 tool_search 工具搜索相关工具,将其添加到模型上下文中,再加以使用。只有 gpt-5.4 及后续模型支持此功能。详情请参阅工具搜索指南。

定义函数的最佳实践

  1. 给函数起一个清楚具体的名称,并详细说明参数和用法。

    • 明确说明函数和每个参数的用途,注明参数格式,并解释输出的含义。
    • 在系统提示词中说明何时应使用每个函数,以及何时不应使用。 通常应当_明确_告诉模型具体要做什么。
    • 提供示例并涵盖边界情况,尤其是针对反复出现的错误。(**注意:**添加示例可能会降低推理模型的表现。)
    • 对于推迟加载的工具,请在函数描述中提供详细指引,并保持命名空间描述简洁。 命名空间帮助模型选择要加载的工具,函数描述则帮助模型正确使用已加载的工具。
  2. 遵循软件工程最佳实践。

    • 让函数易于理解,行为符合预期。(参见最小惊讶原则)
    • 使用枚举和对象结构来避免无效状态。例如,toggle_light(on: bool, off: bool) 允许传入无效的参数组合。
    • 请实习生试用。 只看您提供给模型的信息,实习生或其他人能否正确使用这个函数?(如果不能,他们会问哪些问题?请把答案补充到提示词中。)
  3. 减轻模型的负担,尽可能用代码处理。

    • 对于您已经知道的参数值,无需让模型填写。 例如,如果您已从上一步的菜单中获得 order_id,就不要再设置 order_id 参数。请将 submit_refund() 定义为无参数函数,并在代码中传递 order_id。
    • 合并总是按顺序调用的函数。 例如,如果 mark_location() 总是在 query_location() 之后调用,就可以把标记逻辑移到查询函数中。
  4. 减少初始可用的函数数量,以提高准确率。

    • 评估调用效果,比较函数数量不同时的表现。
    • 尽量让每一轮开始时可用的函数少于 20 个,这个数量仅供参考。
    • 使用工具搜索推迟加载规模较大或不常用的工具组,无需一开始就提供全部工具。
  5. 利用 OpenAI 资源。

    • 生成并不断改进函数模式时,可以使用 Playground。
    • 当函数数量很多或任务较复杂时,可以考虑通过微调提高函数调用的准确率。(参见示例教程)

Token 用量

在底层实现中,函数会以模型训练时学过的语法注入系统消息。因此,可调用函数的定义会占用模型的上下文空间,并按输入 Token 计费。如果遇到 Token 数量限制,建议减少预先加载的函数数量,尽可能缩短描述,或使用工具搜索,仅在需要时加载其余工具。

如果工具规范中定义了大量函数,也可以通过微调减少 Token 用量。

处理函数调用

当模型调用函数时,您必须执行函数并返回结果。模型的响应可能不包含调用,也可能包含一次或多次调用,因此最好按可能有多次调用来处理。

响应的 output 数组中包含 type 值为 function_call 的项。每个这样的项都有一个 call_id(稍后提交函数结果时使用)、一个 name 和经过 JSON 编码的 arguments。

包含多次函数调用的响应示例
[
    {
        "id": "fc_12345xyz",
        "call_id": "call_12345xyz",
        "type": "function_call",
        "name": "get_weather",
        "arguments": "{\"location\":\"Paris, France\"}"
    },
    {
        "id": "fc_67890abc",
        "call_id": "call_67890abc",
        "type": "function_call",
        "name": "get_weather",
        "arguments": "{\"location\":\"Bogotá, Colombia\"}"
    },
    {
        "id": "fc_99999def",
        "call_id": "call_99999def",
        "type": "function_call",
        "name": "send_email",
        "arguments": "{\"to\":\"bob@email.com\",\"body\":\"Hi bob\"}"
    }
]

如果您使用工具搜索,还可能看到 tool_search_call 和 tool_search_output 项出现在 function_call 之前。函数加载后,按此处所示的方式处理函数调用即可。

执行函数调用并追加结果
input_messages += response.output

for tool_call in response.output:
    if tool_call.type != "function_call":
        continue

    name = tool_call.name
    args = json.loads(tool_call.arguments)

    result = call_function(name, args)
    input_messages.append(
        {
            "type": "function_call_output",
            "call_id": tool_call.call_id,
            "output": json.dumps(result),
        }
    )

上例使用一个假设的 call_function 函数将每次调用分派给相应的函数。下面是一种可能的实现:

执行函数调用并追加结果
def call_function(name, args):
    if name == "get_weather":
        return get_weather(**args)
    if name == "send_email":
        return send_email(**args)
    raise ValueError(f"Unknown function: {name}")

设置结果格式

在 function_call_output 消息中传递的结果通常应为字符串,具体格式由您决定,可以是 JSON、错误码、纯文本等。模型会根据需要解读该字符串。

对于返回图像或文件的函数,可以传递由图像或文件对象组成的数组来代替字符串。

如果函数没有返回值(例如 send_email),请返回一个表示成功或失败的字符串,例如 "success"。

让模型根据结果生成响应

将结果追加到 input 后,即可将更新后的输入发回给模型,以获取最终响应。

将结果发回给模型
response = client.responses.create(
    model="gpt-6.2-astra",
    input=input_messages,
    tools=responses_tools,
)
最终响应
"It's about 15°C in Paris, 18°C in Bogotá, and I've sent that email to Bob."

其他配置

工具选择

默认情况下,模型自行决定何时使用工具以及使用多少个工具。您可以使用 tool_choice 参数指定调用行为。

  1. 自动:(默认)可以不调用函数,也可以调用一个或多个函数。tool_choice: "auto"
  2. **必须调用:**调用一个或多个函数。 tool_choice: "required"
  3. **强制调用指定函数:**仅调用指定的函数一次。 tool_choice: {"type": "function", "name": "get_weather"}
  4. **允许使用的工具:**将模型可以调用的工具限制在可用工具的一个子集内。

何时使用 allowed_tools

您可以配置 allowed_tools 列表,让模型在不同请求中只能调用部分工具,同时保持传入的工具列表不变,以充分利用提示词缓存节省成本。

"tool_choice": {
    "type": "allowed_tools",
    "mode": "auto",
    "tools": [
        { "type": "function", "name": "get_weather" },
        { "type": "function", "name": "search_docs" }
    ]
  }
}

也可以将 tool_choice 设置为 "none",效果与不传入任何函数相同。

使用工具搜索时,tool_choice 仍适用于当前轮次可调用的工具。如果您已经加载了一部分工具,并希望模型仅使用这些工具,这一设置尤其有用。

并行函数调用

从 GPT-5 开始,在支持此功能的模型上,即使同时提供了内置工具,也可以并行调用函数。内置工具不能包含在同一批并行函数调用中。

模型可能会选择在一轮中调用多个函数。您可以将 parallel_tool_calls 设置为 false 来阻止这种行为,确保每轮最多发起一次工具调用。

**注意:**目前,如果您使用微调后的模型,并且模型在一轮中调用了多个函数,这些调用的严格模式将被禁用。

**关于 gpt-4.1-nano-2025-04-14 的说明:**启用并行工具调用时,这个 gpt-4.1-nano 快照有时会对同一工具发起多次调用。使用该快照时,建议禁用此功能。

严格模式

将 strict 设置为 true 后,函数调用会严格遵循函数模式。我们建议始终启用严格模式。

严格模式在底层使用结构化输出功能,因此有两项要求:

  1. additionalProperties 必须设置为 false,且 parameters 中的每个对象都必须如此设置。
  2. properties 中的所有字段都必须标记为 required。

对于可选字段,可以将 null 添加为 type 的一个选项(见下例)。

如果您发送 strict: true,但模式不符合上述要求,请求将被拒绝,错误信息会指出缺少哪些约束。如果省略 strict,默认行为取决于所用的 API。对于 Responses 请求,API 会尽可能将您提供的模式规范化,使其符合严格模式的要求。如果无法做到这一点,API 会回退到非严格模式,尽力按函数定义进行调用。发生回退时,响应中的工具定义会显示 strict: false。Chat Completions 请求默认使用非严格模式。如果希望 Responses 始终以非严格模式尽力调用函数,请显式设置 strict: false。

{
    "type": "function",
    "name": "get_weather",
    "description": "Retrieves current weather for the given location.",
    "strict": true,
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "City and country e.g. Bogotá, Colombia"
            },
            "units": {
                "type": ["string", "null"],
                "enum": ["celsius", "fahrenheit"],
                "description": "Units the temperature will be returned in."
            }
        },
        "required": ["location", "units"],
        "additionalProperties": false
    }
}

在 Playground 中生成的所有模式都已启用严格模式。

我们建议启用严格模式,但它有以下限制:

  1. 部分 JSON 模式特性尚不受支持。(参见支持的模式。)

对于微调后的模型,还需注意:

  1. 首次请求时,模式需要经过额外处理,之后会被缓存。如果每次请求使用的模式都不同,可能会增加延迟。
  2. 为提高性能,系统会缓存模式,因此模式不适用零数据保留。

流式传输

通过流式传输,您可以在模型填写参数时显示正在调用哪个函数,甚至可以实时显示参数,让用户看到调用进度。

流式传输函数调用的方式与流式传输普通响应类似。将 stream 设置为 true,即可接收不同的 event 对象。

流式传输函数调用
from openai import OpenAI

client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "get_weather",
        "strict": True,
        "description": "Get current temperature for a given location.",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "City and country e.g. Bogotá, Colombia",
                }
            },
            "required": ["location"],
            "additionalProperties": False,
        },
    }
]

stream = client.responses.create(
    model="gpt-6.2-astra",
    input=[{"role": "user", "content": "What's the weather like in Paris today?"}],
    tools=tools,
    stream=True,
)

for event in stream:
    print(event)
输出事件
{"type":"response.output_item.added","response_id":"resp_1234xyz","output_index":0,"item":{"type":"function_call","id":"fc_1234xyz","call_id":"call_1234xyz","name":"get_weather","arguments":""}}
{"type":"response.function_call_arguments.delta","response_id":"resp_1234xyz","item_id":"fc_1234xyz","output_index":0,"delta":"{\""}
{"type":"response.function_call_arguments.delta","response_id":"resp_1234xyz","item_id":"fc_1234xyz","output_index":0,"delta":"location"}
{"type":"response.function_call_arguments.delta","response_id":"resp_1234xyz","item_id":"fc_1234xyz","output_index":0,"delta":"\":\""}
{"type":"response.function_call_arguments.delta","response_id":"resp_1234xyz","item_id":"fc_1234xyz","output_index":0,"delta":"Paris"}
{"type":"response.function_call_arguments.delta","response_id":"resp_1234xyz","item_id":"fc_1234xyz","output_index":0,"delta":","}
{"type":"response.function_call_arguments.delta","response_id":"resp_1234xyz","item_id":"fc_1234xyz","output_index":0,"delta":" France"}
{"type":"response.function_call_arguments.delta","response_id":"resp_1234xyz","item_id":"fc_1234xyz","output_index":0,"delta":"\"}"}
{"type":"response.function_call_arguments.done","response_id":"resp_1234xyz","item_id":"fc_1234xyz","output_index":0,"arguments":"{\"location\":\"Paris, France\"}"}
{"type":"response.output_item.done","response_id":"resp_1234xyz","output_index":0,"item":{"type":"function_call","id":"fc_1234xyz","call_id":"call_1234xyz","name":"get_weather","arguments":"{\"location\":\"Paris, France\"}"}}

处理普通响应时,需要将数据块拼接成一个 content 字符串。处理函数调用时,则需要将参数片段拼接起来,得到经过 JSON 编码的 arguments 对象。

当模型调用一个或多个函数时,每次函数调用都会触发一个 response.output_item.added 类型的事件,其中包含以下字段:

字段 说明
response_id 函数调用所属响应的 ID
output_index 输出项在响应中的索引,用于区分响应中的各次函数调用。
item 正在进行的函数调用项,包含 name、arguments 和 id 字段

随后,您会收到一系列 response.function_call_arguments.delta 类型的事件。每个事件都包含一个 delta,表示 arguments 字段的增量。这些事件包含以下字段:

字段 说明
response_id 函数调用所属响应的 ID
item_id 增量所属函数调用项的 ID
output_index 输出项在响应中的索引,用于区分响应中的各次函数调用。
delta arguments 字段的增量

下面的代码片段演示如何将多个 delta 汇总为最终的 tool_call 对象。

累积 tool_call 增量
final_tool_calls = {}

for event in stream:
    if (
        event.type == "response.output_item.added"
        and event.item.type == "function_call"
    ):
        final_tool_calls[event.output_index] = event.item
    elif event.type == "response.function_call_arguments.delta":
        index = event.output_index

        if final_tool_calls[index]:
            final_tool_calls[index].arguments += event.delta
汇总后的 final_tool_calls[0]
{
    "type": "function_call",
    "id": "fc_1234xyz",
    "call_id": "call_2345abc",
    "name": "get_weather",
    "arguments": "{\"location\":\"Paris, France\"}"
}

当模型完成函数调用时,会触发一个 response.function_call_arguments.done 类型的事件。该事件包含完整的函数调用,字段如下:

字段 说明
response_id 函数调用所属响应的 ID
output_index 输出项在响应中的索引,用于区分响应中的各次函数调用。
item 函数调用项,包含 name、arguments 和 id 字段。

自定义工具

自定义工具的工作方式与使用 JSON 模式定义的函数工具大致相同。使用自定义工具时,模型可以将任意字符串作为输入传给工具,无需预先指定输入结构。这样可以省去不必要的 JSON 封装,也可以使用下文介绍的自定义文法约束响应。

以下代码示例展示了如何创建一个自定义工具,用于接收模型返回的包含 Python 代码的字符串。

自定义工具调用示例
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6.2-astra",
    input="Use the code_exec tool to print hello world to the console.",
    tools=[
        {
            "type": "custom",
            "name": "code_exec",
            "description": "Executes arbitrary Python code.",
        }
    ],
)
print(response.output)

与前面的示例一样,output 数组中包含模型生成的工具调用。这一次,工具调用的输入是纯文本。

[
  {
    "id": "rs_6890e972fa7c819ca8bc561526b989170694874912ae0ea6",
    "type": "reasoning",
    "content": [],
    "summary": []
  },
  {
    "id": "ctc_6890e975e86c819c9338825b3e1994810694874912ae0ea6",
    "type": "custom_tool_call",
    "status": "completed",
    "call_id": "call_aGiFQkRWSWAIsMQ19fKqxUgb",
    "input": "print(\"hello world\")",
    "name": "code_exec"
  }
]

上下文无关文法

上下文无关文法(CFG)是一组规则,规定如何生成符合特定格式的有效文本。对于自定义工具,您可以提供 CFG 来约束模型传给工具的文本输入。

配置自定义工具时,可以通过 grammar 参数提供自定义 CFG。目前支持两种 CFG 语法:lark 和 regex。

Lark CFG

Lark 上下文无关文法示例
from openai import OpenAI

client = OpenAI()

grammar = """
start: expr
expr: term (SP ADD SP term)* -> add
| term
term: factor (SP MUL SP factor)* -> mul
| factor
factor: INT
SP: " "
ADD: "+"
MUL: "*"
%import common.INT
"""

response = client.responses.create(
    model="gpt-6.2-astra",
    input="Use the math_exp tool to add four plus four.",
    tools=[
        {
            "type": "custom",
            "name": "math_exp",
            "description": "Creates valid mathematical expressions",
            "format": {
                "type": "grammar",
                "syntax": "lark",
                "definition": grammar,
            },
        }
    ],
)
print(response.output)

此时,模型在工具调用中生成的输入应符合您定义的 Lark CFG:

[
  {
    "id": "rs_6890ed2b6374819dbbff5353e6664ef103f4db9848be4829",
    "type": "reasoning",
    "content": [],
    "summary": []
  },
  {
    "id": "ctc_6890ed2f32e8819daa62bef772b8c15503f4db9848be4829",
    "type": "custom_tool_call",
    "status": "completed",
    "call_id": "call_pmlLjmvG33KJdyVdC4MVdk5N",
    "input": "4 + 4",
    "name": "math_exp"
  }
]

文法使用 Lark 的一种变体来定义。模型采样由 LLGuidance 约束。以下 Lark 特性不受支持:

  • 词法分析器正则表达式中的环视断言
  • 词法分析器正则表达式中的惰性修饰符(*?、+?、??)
  • 终结符优先级
  • 模板
  • 导入(使用内置 %import 导入 common 中的定义除外)
  • %declare 声明

建议使用 Lark IDE 试验自定义文法。

控制文法复杂度

请只保留工具需要的规则和匹配模式。如果文法过于复杂,OpenAI API 可能会返回错误,因此在 API 中使用文法前,应先确认它与 API 兼容。

要把 Lark 文法调整到理想状态并不容易。简单的文法通常最可靠,而复杂的文法往往需要反复调整文法定义、提示词和工具描述,才能确保模型的输出不偏离其训练分布。

正确和错误的写法

正确写法(使用一个边界明确的终结符):

start: SENTENCE
SENTENCE: /[A-Za-z, ]*(the hero|a dragon|an old man|the princess)[A-Za-z, ]*(fought|saved|found|lost)[A-Za-z, ]*(a treasure|the kingdom|a secret|his way)[A-Za-z, ]*\./

切勿采用以下写法(拆分成多个规则或终结符)。这种写法试图通过规则将自由文本分配给不同的终结符。词法分析器会贪婪地匹配自由文本片段,您将无法控制匹配边界:

start: sentence
sentence: /[A-Za-z, ]+/ subject /[A-Za-z, ]+/ verb /[A-Za-z, ]+/ object /[A-Za-z, ]+/

词法分析器只根据终结符的定义切分输入,以小写字母命名的规则不会影响这一过程。如果需要匹配“锚点之间的自由文本”,请用一个完整的正则表达式终结符表示整个结构,让词法分析器按预期结构一次完成匹配。

终结符与规则

Lark 使用终结符表示词法分析器识别的词法单元(按惯例使用 UPPERCASE 命名),使用规则表示语法分析器的产生式(按惯例使用 lowercase 命名)。要确保文法仅使用受支持的特性并避免意外行为,最实用的做法是明确定义文法,避免不必要的复杂性,并让终结符与规则各司其职。

终结符使用 Rust regex 库的正则表达式语法,与 Python 的 re 模块所用的语法不同。

核心概念与最佳实践

词法分析先于语法分析

在应用任何 CFG 规则之前,词法分析器就已经匹配了终结符(采用贪婪匹配,以最长匹配为准)。如果您试图把一个终结符拆分到多个规则中来控制它的匹配范围,这些规则无法指导词法分析器。词法分析器只依据终结符的正则表达式进行匹配。

从自由文本中匹配片段时,优先使用单个终结符

如果需要识别嵌在任意文本中的特定模式(例如在自然语言中,锚点之间可以出现任意内容),请用单个终结符表示该模式。不要将自由文本终结符与语法分析规则交错使用。贪婪匹配的词法分析器不会按您预期的边界切分,模型的输出也很可能偏离训练分布。

使用规则组合独立的词法单元

规则适合将边界明确的终结符(数字、关键字、标点符号等)组合成更大的结构。要约束两个终结符之间的内容,不宜使用规则。

让终结符职责单一、边界明确且定义完整

优先使用明确的字符类和有界量词(例如 {0,10},避免到处使用无界的 *)。如果需要匹配“直到句点为止的任意文本”,优先采用 /[^.\n]{0,10}*\./ 这样的写法,避免使用 /.+\./,以防匹配范围不断扩大。

用规则组合词法单元,避免用规则控制正则表达式的内部匹配过程

合理使用规则的示例:

start: expr
NUMBER: /[0-9]+/
PLUS: "+"
MINUS: "-"
expr: term (("+"|"-") term)*
term: NUMBER

显式处理空白字符

不要依赖范围不受限制的 %ignore 指令。无界的忽略指令可能会使文法过于复杂,也可能导致模型输出偏离训练分布。建议在每个允许出现空白字符的位置显式加入相应的终结符。

故障排查

  • 如果 API 因文法过于复杂而拒绝请求,请简化规则和终结符,并移除无界的 %ignore 指令。
  • 如果调用自定义工具时出现意外的词法单元,请确认各终结符的匹配范围没有重叠,并检查词法分析器的贪婪匹配行为。
  • 如果模型输出偏离训练分布(例如输出过长或不断重复,语法有效但语义错误):
    • 收紧文法约束。
    • 调整提示词(添加少样本示例)和工具描述(解释文法,并指示模型进行推理并遵循文法)。
    • 尝试提高推理强度(例如从“中”调至“高”)。

正则表达式 CFG

正则表达式上下文无关文法示例
from openai import OpenAI

client = OpenAI()

grammar = r"^(?P<month>January|February|March|April|May|June|July|August|September|October|November|December)\s+(?P<day>\d{1,2})(?:st|nd|rd|th)?\s+(?P<year>\d{4})\s+at\s+(?P<hour>0?[1-9]|1[0-2])(?P<ampm>AM|PM)$"

response = client.responses.create(
    model="gpt-6.2-astra",
    input="Use the timestamp tool to save a timestamp for August 7th 2025 at 10AM.",
    tools=[
        {
            "type": "custom",
            "name": "timestamp",
            "description": "Saves a timestamp in date + time in 24-hr format.",
            "format": {
                "type": "grammar",
                "syntax": "regex",
                "definition": grammar,
            },
        }
    ],
)
print(response.output)

此时,模型在工具调用中生成的输入应符合您定义的正则表达式 CFG:

[
  {
    "id": "rs_6894f7a3dd4c81a1823a723a00bfa8710d7962f622d1c260",
    "type": "reasoning",
    "content": [],
    "summary": []
  },
  {
    "id": "ctc_6894f7ad7fb881a1bffa1f377393b1a40d7962f622d1c260",
    "type": "custom_tool_call",
    "status": "completed",
    "call_id": "call_8m4XCnYvEmFlzHgDHbaOCFlK",
    "input": "August 7th 2025 at 10AM",
    "name": "timestamp"
  }
]

与 Lark 语法一样,此处的正则表达式使用 Rust regex 库的语法,与 Python 的 re 模块所用的语法不同。

以下正则表达式特性不受支持:

  • 环视断言
  • 惰性修饰符(*?、+?、??)

核心概念与最佳实践

匹配模式必须写在一行内

如果需要匹配输入中的换行符,请使用转义序列 \n。不要使用允许匹配模式跨行书写的详细模式或扩展模式。

以普通模式字符串的形式提供正则表达式

不要将匹配模式包在 // 中。