GPT-4.1 提示指南

GPT-4.1 模型系列在编码、指令遵循和长上下文能力方面，相比 GPT-4o 取得了显著的进步。在本提示指南中，我们整理了一系列通过广泛内部测试得出的重要提示技巧，以帮助开发者充分利用这一新模型系列的改进能力。

许多典型的最佳实践仍然适用于 GPT-4.1，例如提供上下文示例、使指令尽可能具体和清晰，以及通过提示诱导规划以最大化模型智能。然而，我们预计要充分发挥此模型的潜力，需要进行一些提示迁移。GPT-4.1 经过训练，比其前代模型更能准确、更字面地遵循指令，而前代模型倾向于更自由地从用户和系统提示中推断意图。但这也意味着 GPT-4.1 是高度可控的，并且对规范良好的提示响应迅速——如果模型行为与您的预期不同，一个坚定而明确地阐明您期望行为的句子几乎总是足以将模型引导回正轨。

请继续阅读以获取可供参考的提示示例，并请记住，虽然这些指导广泛适用，但没有一种建议适合所有情况。人工智能工程本质上是一门经验性学科，大型语言模型本质上是非确定性的；除了遵循本指南外，我们建议构建信息丰富的评估并经常进行迭代，以确保您的提示工程更改能为您的用例带来收益。

1. 代理工作流

GPT-4.1 是构建代理工作流的绝佳平台。在模型训练中，我们强调提供多样化的代理问题解决轨迹，我们的模型代理框架在 SWE-bench Verified 上实现了非推理模型的行业领先性能，解决了 55% 的问题。

系统提示提醒

为了充分利用 GPT-4.1 的代理能力，我们建议在所有代理提示中包含三种关键类型的提醒。以下提示专门针对代理编码工作流进行了优化，但可以轻松修改以适应通用的代理用例。

1. 持久性：这确保模型理解它正在进入一个多消息回合，并防止它过早地将控制权交还给用户。我们的示例是：

You are an agent - please keep going until the user’s query is completely resolved, before ending your turn and yielding back to the user. Only terminate your turn when you are sure that the problem is solved.

2. 工具调用：这鼓励模型充分利用其工具，并降低其产生幻觉或猜测答案的可能性。我们的示例是：

If you are not sure about file content or codebase structure pertaining to the user’s request, use your tools to read files and gather the relevant information: do NOT guess or make up an answer.

3. 规划 [可选]：如果需要，这可以确保模型在文本中显式地规划和反思每次工具调用，而不是仅通过一系列工具调用来链接完成任务。我们的示例是：

You MUST plan extensively before each function call, and reflect extensively on the outcomes of the previous function calls. DO NOT do this entire process by making function calls only, as this can impair your ability to solve the problem and think insightfully.

GPT-4.1 在代理环境中被训练成非常紧密地响应用户指令和系统提示。模型严格遵循这三个简单的指令，并将我们内部的 SWE-bench Verified 分数提高了近 20% —— 因此，我们强烈建议在任何代理提示的开头都包含清晰的提醒，涵盖上述三个类别。总的来说，我们发现这三个指令将模型从类似聊天机器人的状态转变为一个更“积极主动”的代理，能够自主、独立地推动交互。

工具调用

与之前的模型相比，GPT-4.1 在有效利用 OpenAI API 请求中作为参数传递的工具方面接受了更多训练。我们鼓励开发者专门使用 tools 字段来传递工具，而不是手动将工具描述注入提示并编写单独的解析器来处理工具调用，正如一些人过去报告的那样。这是最小化错误并确保模型在工具调用轨迹中保持分布内的最佳方式——在我们自己的实验中，与手动将模式注入系统提示相比，使用 API 解析的工具描述将 SWE-bench Verified 通过率提高了 2%。

开发者应清晰地命名工具以指示其用途，并在工具的“description”字段中添加清晰、详细的描述。同样，对于每个工具参数，应依靠良好的命名和描述来确保适当的使用。如果您的工具特别复杂，并且您想提供工具使用示例，我们建议您在系统提示中创建一个“# Examples”部分，并将示例放在那里，而不是将其添加到“description”字段中，该字段应保持详尽但相对简洁。提供示例有助于指示何时使用工具、是否在工具调用旁边包含用户文本以及不同输入适合的参数。请记住，您可以使用 Prompt Playground 中的“Generate Anything”来为您的新工具定义获得一个良好的起点。

提示诱导规划与思维链

如前所述，GPT-4.1 不是一个推理模型——也就是说，它不会在回答之前产生内部思维链——但在提示中，开发者可以通过使用上面显示的任何规划提示组件的变体来诱导模型生成显式的、逐步的计划。这可以被认为是模型在“大声思考”。在我们对 SWE-bench Verified 代理任务的实验中，诱导显式规划使通过率提高了 4%。

示例提示：SWE-bench Verified

下面，我们分享了我们在 SWE-bench Verified 上取得最高分时使用的代理提示，其中包含有关工作流和问题解决策略的详细说明。这种通用模式可用于任何代理任务。

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get(
        "OPENAI_API_KEY", "<your OpenAI API key if not set as env var>"
    )
)

SYS_PROMPT_SWEBENCH = """
You will be tasked to fix an issue from an open-source repository.

Your thinking should be thorough and so it's fine if it's very long. You can think step by step before and after each action you decide to take.

You MUST iterate and keep going until the problem is solved.

You already have everything you need to solve this problem in the /testbed folder, even without internet connection. I want you to fully solve this autonomously before coming back to me.

Only terminate your turn when you are sure that the problem is solved. Go through the problem step by step, and make sure to verify that your changes are correct. NEVER end your turn without having solved the problem, and when you say you are going to make a tool call, make sure you ACTUALLY make the tool call, instead of ending your turn.

THE PROBLEM CAN DEFINITELY BE SOLVED WITHOUT THE INTERNET.

Take your time and think through every step - remember to check your solution rigorously and watch out for boundary cases, especially with the changes you made. Your solution must be perfect. If not, continue working on it. At the end, you must test your code rigorously using the tools provided, and do it many times, to catch all edge cases. If it is not robust, iterate more and make it perfect. Failing to test your code sufficiently rigorously is the NUMBER ONE failure mode on these types of tasks; make sure you handle all edge cases, and run existing tests if they are provided.

You MUST plan extensively before each function call, and reflect extensively on the outcomes of the previous function calls. DO NOT do this entire process by making function calls only, as this can impair your ability to solve the problem and think insightfully.

# Workflow

## High-Level Problem Solving Strategy

1. Understand the problem deeply. Carefully read the issue and think critically about what is required.
2. Investigate the codebase. Explore relevant files, search for key functions, and gather context.
3. Develop a clear, step-by-step plan. Break down the fix into manageable, incremental steps.
4. Implement the fix incrementally. Make small, testable code changes.
5. Debug as needed. Use debugging techniques to isolate and resolve issues.
6. Test frequently. Run tests after each change to verify correctness.
7. Iterate until the root cause is fixed and all tests pass.
8. Reflect and validate comprehensively. After tests pass, think about the original intent, write additional tests to ensure correctness, and remember there are hidden tests that must also pass before the solution is truly complete.

Refer to the detailed sections below for more information on each step.

## 1. Deeply Understand the Problem
Carefully read the issue and think hard about a plan to solve it before coding.

## 2. Codebase Investigation

- Explore relevant files and directories.
- Search for key functions, classes, or variables related to the issue.
- Read and understand relevant code snippets.
- Identify the root cause of the problem.
- Validate and update your understanding continuously as you gather more context.

## 3. Develop a Detailed Plan

- Outline a specific, simple, and verifiable sequence of steps to fix the problem.
- Break down the fix into small, incremental changes.

## 4. Making Code Changes

- Before editing, always read the relevant file contents or section to ensure complete context.
- If a patch is not applied correctly, attempt to reapply it.
- Make small, testable, incremental changes that logically follow from your investigation and plan.

## 5. Debugging

- Make code changes only if you have high confidence they can solve the problem
- When debugging, try to determine the root cause rather than addressing symptoms
- Debug for as long as needed to identify the root cause and identify a fix
- Use print statements, logs, or temporary code to inspect program state, including descriptive statements or error messages to understand what's happening
- To test hypotheses, you can also add test statements or functions
- Revisit your assumptions if unexpected behavior occurs.

## 6. Testing

- Run tests frequently using `!python3 run_tests.py` (or equivalent).
- After each change, verify correctness by running relevant tests.
- If tests fail, analyze failures and revise your patch.
- Write additional tests if needed to capture important behaviors or edge cases.
- Ensure all tests pass before finalizing.

## 7. Final Verification

- Confirm the root cause is fixed.
- Review your solution for logic correctness and robustness.
- Iterate until you are extremely confident the fix is complete and all tests pass.

## 8. Final Reflection and Additional Testing

- Reflect carefully on the original intent of the user and the problem statement.
- Think about potential edge cases or scenarios that may not be covered by existing tests.
- Write additional tests that would need to pass to fully validate the correctness of your solution.
- Run these new tests and ensure they all pass.
- Be aware that there are additional hidden tests that must also pass for the solution to be successful.
- Do not assume the task is complete just because the visible tests pass; continue refining until you are confident the fix is robust and comprehensive.
"""

PYTHON_TOOL_DESCRIPTION = """This function is used to execute Python code or terminal commands in a stateful Jupyter notebook environment. python will respond with the output of the execution or time out after 60.0 seconds. Internet access for this session is disabled. Do not make external web requests or API calls as they will fail. Just as in a Jupyter notebook, you may also execute terminal commands by calling this function with a terminal command, prefaced with an exclamation mark.

In addition, for the purposes of this task, you can call this function with an `apply_patch` command as input.  `apply_patch` effectively allows you to execute a diff/patch against a file, but the format of the diff specification is unique to this task, so pay careful attention to these instructions. To use the `apply_patch` command, you should pass a message of the following structure as "input":

%%bash
apply_patch <<"EOF"

*** Begin Patch
[YOUR_PATCH]

*** End Patch
EOF

Where [YOUR_PATCH] is the actual content of your patch, specified in the following V4A diff format.

*** [ACTION] File: [path/to/file] -> ACTION can be one of Add, Update, or Delete.
For each snippet of code that needs to be changed, repeat the following:
[context_before] -> See below for further instructions on context.

- [old_code] -> Precede the old code with a minus sign.
+ [new_code] -> Precede the new, replacement code with a plus sign.
[context_after] -> See below for further instructions on context.

For instructions on [context_before] and [context_after]:

- By default, show 3 lines of code immediately above and 3 lines immediately below each change. If a change is within 3 lines of a previous change, do NOT duplicate the first change's [context_after] lines in the second change's [context_before] lines.
- If 3 lines of context is insufficient to uniquely identify the snippet of code within the file, use the @@ operator to indicate the class or function to which the snippet belongs. For instance, we might have:
@@ class BaseClass
[3 lines of pre-context]

- [old_code]
+ [new_code]
[3 lines of post-context]

- If a code block is repeated so many times in a class or function such that even a single @@ statement and 3 lines of context cannot uniquely identify the snippet of code, you can use multiple `@@` statements to jump to the right context. For instance:

@@ class BaseClass
@@  def method():
[3 lines of pre-context]

- [old_code]
+ [new_code]
[3 lines of post-context]

Note, then, that we do not use line numbers in this diff format, as the context is enough to uniquely identify code. An example of a message that you might pass as "input" to this function, in order to apply a patch, is shown below.

%%bash
apply_patch <<"EOF"

*** Begin Patch
*** Update File: pygorithm/searching/binary_search.py
@@ class BaseClass
@@     def search():

-        pass
+        raise NotImplementedError()

@@ class Subclass
@@     def search():

-        pass
+        raise NotImplementedError()

*** End Patch
EOF

File references can only be relative, NEVER ABSOLUTE. After the apply_patch command is run, python will always say "Done!", regardless of whether the patch was successfully applied or not. However, you can determine if there are issue and errors by looking at any warnings or logging lines printed BEFORE the "Done!" is output.
"""

python_bash_patch_tool = {
  "type": "function",
  "name": "python",
  "description": PYTHON_TOOL_DESCRIPTION,
  "parameters": {
      "type": "object",
      "strict": True,
      "properties": {
          "input": {
              "type": "string",
              "description": " The Python code, terminal command (prefaced by exclamation mark), or apply_patch command that you wish to execute.",
          }
      },
      "required": ["input"],
  },
}

# Additional harness setup:
# - Add your repo to /testbed
# - Add your issue to the first user message
# - Note: Even though we used a single tool for python, bash, and apply_patch, we generally recommend defining more granular tools that are focused on a single function

response = client.responses.create(
    instructions=SYS_PROMPT_SWEBENCH,
    model="gpt-4.1-2025-04-14",
    tools=[python_bash_patch_tool],
    input=f"Please answer the following question:\nBug: Typerror..."
)

response.to_dict()["output"]

[{'id': 'msg_67fe92df26ac819182ffafce9ff4e4fc07c7e06242e51f8b',
  'content': [{'annotations': [],
    'text': "Thank you for the report, but “Typerror” is too vague for me to start debugging right away.\n\n**To make progress, I need to:**\n1. Find the exact error message text (e.g. `'TypeError: ...'`).\n2. Find which file and which line/function/class the error occurred in.\n3. Figure out what triggered the error (test file, usage, reproduction steps).\n4. Find the root cause and details.\n\n**Next steps:**\n- Investigate error/log/test output files for a Python `TypeError` message.\n- Examine the relevant code sections for problematic type usage.\n- If possible, reproduce the bug locally.\n\n**Plan:**\n- First, I will search for test files and log output in the `/testbed` directory that may contain the full error message and stack trace.\n\nLet’s start by listing the contents of the `/testbed` directory to look for clues.",
    'type': 'output_text'}],
  'role': 'assistant',
  'status': 'completed',
  'type': 'message'},
 {'arguments': '{"input":"!ls -l /testbed"}',
  'call_id': 'call_frnxyJgKi5TsBem0nR9Zuzdw',
  'name': 'python',
  'type': 'function_call',
  'id': 'fc_67fe92e3da7081918fc18d5c96dddc1c07c7e06242e51f8b',
  'status': 'completed'}]

2. 长上下文

GPT-4.1 拥有性能卓越的 100 万 token 输入上下文窗口，可用于各种长上下文任务，包括结构化文档解析、重新排序、选择相关信息同时忽略不相关上下文以及使用上下文进行多跳推理。

最佳上下文大小

我们在长达 100 万 token 的上下文的“针尖麦芒”评估中观察到非常好的性能，并且在具有混合相关和不相关代码及其他文档的复杂任务中观察到非常强大的性能。然而，随着需要检索的项目增多，或执行需要了解整个上下文状态的复杂推理（例如，执行图搜索），长上下文性能可能会下降。

调整上下文依赖性

考虑回答问题可能需要的外部世界知识与内部世界知识的组合。有时模型需要利用自身的一些知识来连接概念或进行逻辑跳转，而在其他情况下，则希望仅使用提供的上下文。

# 指令
// 内部知识

- 仅使用提供的外部上下文中的文档来回答用户查询。如果您根据此上下文不知道答案，则必须回答“我没有足够的信息来回答”，即使用户坚持要求您回答该问题。
// 内部和外部知识

- 默认情况下，使用提供的外部上下文来回答用户查询，但如果需要其他基本知识来回答，并且您对答案有信心，则可以使用您自己的知识来帮助回答问题。

提示组织

尤其是在使用长上下文时，指令和上下文的放置会影响性能。如果您的提示中有长上下文，最好将指令放在所提供上下文的开头和结尾，因为我们发现这种方式比仅放在上面或下面效果更好。如果您只想放置一次指令，那么放在上下文上面比放在下面效果更好。

3. 思维链

如上所述，GPT-4.1 不是一个推理模型，但提示模型逐步思考（称为“思维链”）是模型将问题分解为更易于管理的块、解决它们并提高整体输出质量的有效方法，但代价是使用更多输出 token 会带来更高的成本和延迟。该模型经过训练，在代理推理和现实世界问题解决方面表现良好，因此它不需要太多提示即可表现出色。

我们建议在提示的末尾添加此基本思维链指令：

...

首先，仔细思考需要哪些文档来回答查询。然后，打印出每个文档的标题和 ID。然后，将 ID 格式化为列表。

然后，您应该通过审核特定示例和评估中的失败情况，并使用更明确的指令来解决系统性的规划和推理错误，从而改进您的思维链（CoT）提示。在无约束的 CoT 提示中，它可能会尝试不同的策略，如果您观察到一种有效的方法，您可以将该策略编入您的提示中。总的来说，错误往往源于误解用户意图、上下文收集或分析不足，或思考过程不足或不正确，因此请注意这些问题，并尝试通过更具指导性的指令来解决它们。

以下是一个指示模型在继续回答之前更系统地分析用户意图并考虑相关上下文的示例提示。

# 推理策略

1. 查询分析：分解并分析查询，直到您确信其含义。考虑提供的上下文以帮助澄清任何模糊或混淆的信息。
2. 上下文分析：仔细选择并分析一组潜在相关的文档。优化召回率——有些文档不相关也没关系，但必须包含正确的文档，否则您的最终答案将是错误的。每个文档的分析步骤：
    a. 分析：分析其与回答查询的相关性。
    b. 相关性评分：[高、中、低、无]

3. 综合：总结哪些文档最相关以及为什么，包括所有相关性评分为中或高的文档。

# 用户问题
{user_question}

# 外部上下文
{external_context}

首先，仔细思考需要哪些文档来回答查询，并严格遵循提供的推理策略。然后，打印出每个文档的标题和 ID。然后，将 ID 格式化为列表。

4. 指令遵循

GPT-4.1 表现出卓越的指令遵循能力，开发者可以利用这一点来精确地塑造和控制其特定用例的输出。开发者通常会广泛提示代理推理步骤、响应语气和语调、工具调用信息、输出格式、要避免的主题等。然而，由于模型更字面地遵循指令，开发者可能需要明确指定做什么或不做什么。此外，为其他模型优化的现有提示可能无法立即与此模型一起使用，因为现有指令被更严格地遵循，并且不再像以前那样强烈地推断隐式规则。

推荐工作流

以下是我们为开发和调试提示中的指令推荐的工作流：

1. 从一个总体的“响应规则”或“指令”部分开始，提供高级指导和要点。
2. 如果您想更改更具体的行为，请添加一个部分来为该类别指定更多详细信息，例如“# 示例短语”。
3. 如果您希望模型遵循其工作流中的特定步骤，请添加一个有序列表并指示模型遵循这些步骤。
4. 如果行为仍不符合预期：
   1. 检查是否存在冲突、未充分说明或错误的指令和示例。如果存在冲突的指令，GPT-4.1 倾向于遵循更靠近提示末尾的指令。
   2. 添加演示期望行为的示例；确保示例中演示的任何重要行为也在您的规则中被引用。
   3. 通常不需要使用全大写或其他激励措施，如贿赂或小费。我们建议从不使用这些开始，只有在您的特定提示需要时才使用它们。请注意，如果您的现有提示包含这些技术，可能会导致 GPT-4.1 过度关注它们。

请注意，使用您偏好的 AI 驱动的 IDE 在迭代提示方面非常有帮助，包括检查一致性或冲突、添加示例或进行一致性更新，例如添加指令并更新指令以演示该指令。

常见故障模式

这些故障模式并非 GPT-4.1 所独有，但我们在此分享以供一般参考和方便调试。

• 指示模型始终遵循特定行为有时会引起不良影响。例如，如果被告知“您必须在回复用户之前调用工具”，模型可能会在没有足够信息的情况下产生幻觉工具输入或使用 null 值调用工具。添加“如果您没有足够的信息来调用工具，请向用户询问您需要的信息”应该可以缓解这种情况。
• 当提供示例短语时，模型可能会逐字使用这些引语，并开始让用户觉得重复。请确保指示模型根据需要进行变化。
• 在没有具体说明的情况下，一些模型会急于提供额外的文字来解释其决定，或者在响应中输出比预期更多的格式。提供说明和可能的示例以帮助缓解这种情况。

示例提示：客户服务

这演示了一个虚构的客户服务代理的最佳实践。请注意规则的多样性、具体性、使用附加部分以获得更多细节以及一个示例，该示例演示了结合了所有先前规则的精确行为。

尝试运行以下笔记本单元格——您应该会看到用户消息和工具调用，并且用户消息应以问候语开头，然后回显您的答案，然后提及您即将调用工具。尝试更改指令以塑造模型行为，或尝试其他用户消息，以测试指令遵循性能。

SYS_PROMPT_CUSTOMER_SERVICE = """You are a helpful customer service agent working for NewTelco, helping a user efficiently fulfill their request while adhering closely to provided guidelines.

# Instructions

- Always greet the user with "Hi, you've reached NewTelco, how can I help you?"
- Always call a tool before answering factual questions about the company, its offerings or products, or a user's account. Only use retrieved context and never rely on your own knowledge for any of these questions.
    - However, if you don't have enough information to properly call the tool, ask the user for the information you need.
- Escalate to a human if the user requests.
- Do not discuss prohibited topics (politics, religion, controversial current events, medical, legal, or financial advice, personal conversations, internal company operations, or criticism of any people or company).
- Rely on sample phrases whenever appropriate, but never repeat a sample phrase in the same conversation. Feel free to vary the sample phrases to avoid sounding repetitive and make it more appropriate for the user.
- Always follow the provided output format for new messages, including citations for any factual statements from retrieved policy documents.
- If you're going to call a tool, always message the user with an appropriate message before and after calling the tool.
- Maintain a professional and concise tone in all responses, and use emojis between sentences.
- If you've resolved the user's request, ask if there's anything else you can help with

# Precise Response Steps (for each response)

1. If necessary, call tools to fulfill the user's desired action. Always message the user before and after calling a tool to keep them in the loop.
2. In your response to the user
    a. Use active listening and echo back what you heard the user ask for.
    b. Respond appropriately given the above guidelines.

# Sample Phrases
## Deflecting a Prohibited Topic

- "I'm sorry, but I'm unable to discuss that topic. Is there something else I can help you with?"
- "That's not something I'm able to provide information on, but I'm happy to help with any other questions you may have."

## Before calling a tool

- "To help you with that, I'll just need to verify your information."
- "Let me check that for you—one moment, please."
- "I'll retrieve the latest details for you now."

## After calling a tool

- "Okay, here's what I found: [response]"
- "So here's what I found: [response]"

# Output Format

- Always include your final response to the user.
- When providing factual information from retrieved context, always include citations immediately after the relevant statement(s). Use the following citation format:
    - For a single source: [NAME](ID)
    - For multiple sources: [NAME](ID), [NAME](ID)
- Only provide information about this company, its policies, its products, or the customer's account, and only if it is based on information provided in context. Do not answer questions outside this scope.

# Example
## User
Can you tell me about your family plan options?

## Assistant Response 1
### Message
"Hi, you've reached NewTelco, how can I help you? 😊🎉\n\nYou'd like to know about our family plan options. 🤝 Let me check that for you—one moment, please. 🚀"

### Tool Calls
lookup_policy_document(topic="family plan options")

// After tool call, the assistant would follow up with:

## Assistant Response 2 (after tool call)
### Message
"Okay, here's what I found: 🎉 Our family plan allows up to 5 lines with shared data and a 10% discount for each additional line [Family Plan Policy](ID-010). 📱 Is there anything else I can help you with today? 😊"
"""

get_policy_doc = {
    "type": "function",
    "name": "lookup_policy_document",
    "description": "Tool to look up internal documents and policies by topic or keyword.",
    "parameters": {
        "strict": True,
        "type": "object",
        "properties": {
            "topic": {
                "type": "string",
                "description": "The topic or keyword to search for in company policies or documents.",
            },
        },
        "required": ["topic"],
        "additionalProperties": False,
    },
}

get_user_acct = {
    "type": "function",
    "name": "get_user_account_info",
    "description": "Tool to get user account information",
    "parameters": {
        "strict": True,
        "type": "object",
        "properties": {
            "phone_number": {
                "type": "string",
                "description": "Formatted as '(xxx) xxx-xxxx'",
            },
        },
        "required": ["phone_number"],
        "additionalProperties": False,
    },
}

response = client.responses.create(
    instructions=SYS_PROMPT_CUSTOMER_SERVICE,
    model="gpt-4.1-2025-04-14",
    tools=[get_policy_doc, get_user_acct],
    input="How much will it cost for international service? I'm traveling to France.",
    # input="Why was my last bill so high?"
)

response.to_dict()["output"]

[{'id': 'msg_67fe92d431548191b7ca6cd604b4784b06efc5beb16b3c5e',
  'content': [{'annotations': [],
    'text': "Hi, you've reached NewTelco, how can I help you? 🌍✈️\n\nYou'd like to know the cost of international service while traveling to France. 🇫🇷 Let me check the latest details for you—one moment, please. 🕑",
    'type': 'output_text'}],
  'role': 'assistant',
  'status': 'completed',
  'type': 'message'},
 {'arguments': '{"topic":"international service cost France"}',
  'call_id': 'call_cF63DLeyhNhwfdyME3ZHd0yo',
  'name': 'lookup_policy_document',
  'type': 'function_call',
  'id': 'fc_67fe92d5d6888191b6cd7cf57f707e4606efc5beb16b3c5e',
  'status': 'completed'}]

5. 一般建议

提示结构

供参考，以下是构建提示的良好起点。

# 角色和目标

# 指令

## 用于更详细指令的子类别

# 推理步骤

# 输出格式

# 示例
## 示例 1

# 上下文

# 最终指令和提示以进行逐步思考

根据您的需求添加或删除部分，并进行实验以确定最适合您用例的结构。

分隔符

以下是选择提示最佳分隔符的一些通用指南。请参阅长上下文部分以了解该上下文类型的特殊注意事项。

1. Markdown：我们建议从这里开始，并使用 Markdown 标题来表示主要部分和子部分（包括更深层次的层级，直到 H4+）。使用内联反引号或反引号块来精确地包裹代码，并根据需要使用标准的编号或项目符号列表。
2. XML：这些也表现良好，并且我们已经通过此模型改进了对 XML 中信息的遵循程度。XML 便于精确地包裹一个包含开始和结束的部分，为标签添加元数据以提供额外上下文，并启用嵌套。以下是使用 XML 标签在示例部分中嵌套示例的示例，其中包含每个示例的输入和输出：

<examples>
<example1 type="Abbreviate">
<input>San Francisco</input>
<output>- SF</output>
</example1>
</examples>

3. JSON：JSON 结构化程度高，并且模型对其有很好的理解，尤其是在编码上下文中。但是，它可能更冗长，并且需要字符转义，这会增加开销。

关于添加大量文档或文件的输入上下文的指导：

• XML 在我们的长上下文测试中表现良好。
  • 示例：<doc id='1' title='The Fox'>The quick brown fox jumps over the lazy dog</doc>
• Lee 等人提出的这种格式（参考）在我们的长上下文测试中也表现良好。
  • 示例：ID: 1 | TITLE: The Fox | CONTENT: The quick brown fox jumps over the lazy dog
• JSON 的表现尤其差。
  • 示例：[{'id': 1, 'title': 'The Fox', 'content': 'The quick brown fox jumped over the lazy dog'}]

模型经过训练，能够稳健地理解各种格式的结构。通常，请自行判断，并考虑什么将为模型提供清晰的信息并使其“脱颖而出”。例如，如果您正在检索包含大量 XML 的文档，基于 XML 的分隔符可能效果不佳。

注意事项

• 在某些孤立的情况下，我们观察到模型有时会抗拒产生非常长、重复的输出，例如，逐一分析数百个项目。如果这对您的用例是必需的，请强烈指示模型完整输出这些信息，并考虑分解问题或使用更简洁的方法。
• 我们已经看到一些罕见的并行工具调用不正确的实例。我们建议对此进行测试，如果您遇到问题，请考虑将 parallel_tool_calls 参数设置为 false。

Appendix: 生成和应用文件差异

开发者向我们反馈说，准确且格式良好的差异生成是支持与编码相关任务的关键能力。为此，GPT-4.1 系列相对于之前的 GPT 模型在差异能力方面有了显著的改进。此外，虽然 GPT-4.1 在给定清晰的指令和示例的情况下生成任何格式的差异方面都表现出色，但我们在此开源了一种推荐的差异格式，模型已在该格式上进行了广泛训练。我们希望，特别是对于刚起步的开发者来说，这将大大减少自己创建差异的工作量。

应用补丁

请参阅下面的示例，了解正确应用我们推荐的工具调用的提示。

APPLY_PATCH_TOOL_DESC = """This is a custom utility that makes it more convenient to add, remove, move, or edit code files. `apply_patch` effectively allows you to execute a diff/patch against a file, but the format of the diff specification is unique to this task, so pay careful attention to these instructions. To use the `apply_patch` command, you should pass a message of the following structure as "input":

%%bash
apply_patch <<"EOF"

*** Begin Patch
[YOUR_PATCH]

*** End Patch
EOF

Where [YOUR_PATCH] is the actual content of your patch, specified in the following V4A diff format.

*** [ACTION] File: [path/to/file] -> ACTION can be one of Add, Update, or Delete.
For each snippet of code that needs to be changed, repeat the following:
[context_before] -> See below for further instructions on context.

- [old_code] -> Precede the old code with a minus sign.
+ [new_code] -> Precede the new, replacement code with a plus sign.
[context_after] -> See below for further instructions on context.

For instructions on [context_before] and [context_after]:

- By default, show 3 lines of code immediately above and 3 lines immediately below each change. If a change is within 3 lines of a previous change, do NOT duplicate the first change’s [context_after] lines in the second change’s [context_before] lines.
- If 3 lines of context is insufficient to uniquely identify the snippet of code within the file, use the @@ operator to indicate the class or function to which the snippet belongs. For instance, we might have:
@@ class BaseClass
[3 lines of pre-context]

- [old_code]
+ [new_code]
[3 lines of post-context]

- If a code block is repeated so many times in a class or function such that even a single @@ statement and 3 lines of context cannot uniquely identify the snippet of code, you can use multiple `@@` statements to jump to the right context. For instance:

@@ class BaseClass
@@  def method():
[3 lines of pre-context]

- [old_code]
+ [new_code]
[3 lines of post-context]

Note, then, that we do not use line numbers in this diff format, as the context is enough to uniquely identify code. An example of a message that you might pass as "input" to this function, in order to apply a patch, is shown below.

%%bash
apply_patch <<"EOF"

*** Begin Patch
*** Update File: pygorithm/searching/binary_search.py
@@ class BaseClass
@@     def search():

-          pass
+          raise NotImplementedError()

@@ class Subclass
@@     def search():

-          pass
+          raise NotImplementedError()

*** End Patch
EOF
"""

APPLY_PATCH_TOOL = {
    "name": "apply_patch",
    "description": APPLY_PATCH_TOOL_DESC,
    "parameters": {
        "type": "object",
        "properties": {
            "input": {
                "type": "string",
                "description": " The apply_patch command that you wish to execute.",
            }
        },
        "required": ["input"],
    },
}

参考实现：apply_patch.py

这是我们用于模型训练的 apply_patch 工具的参考实现。您需要将其制作为可执行文件，并在模型执行命令的 shell 中将其作为 apply_patch 提供：

#!/usr/bin/env python3

"""
A self-contained **pure-Python 3.9+** utility for applying human-readable
“pseudo-diff” patch files to a collection of text files.
"""

from __future__ import annotations

import pathlib
from dataclasses import dataclass, field
from enum import Enum
from typing import (
    Callable,
    Dict,
    List,
    Optional,
    Tuple,
    Union,
)


# --------------------------------------------------------------------------- #
#  Domain objects
# --------------------------------------------------------------------------- #
class ActionType(str, Enum):
    ADD = "add"
    DELETE = "delete"
    UPDATE = "update"


@dataclass
class FileChange:
    type: ActionType
    old_content: Optional[str] = None
    new_content: Optional[str] = None
    move_path: Optional[str] = None


@dataclass
class Commit:
    changes: Dict[str, FileChange] = field(default_factory=dict)


# --------------------------------------------------------------------------- #
#  Exceptions
# --------------------------------------------------------------------------- #
class DiffError(ValueError):
    """Any problem detected while parsing or applying a patch."""


# --------------------------------------------------------------------------- #
#  Helper dataclasses used while parsing patches
# --------------------------------------------------------------------------- #
@dataclass
class Chunk:
    orig_index: int = -1
    del_lines: List[str] = field(default_factory=list)
    ins_lines: List[str] = field(default_factory=list)


@dataclass
class PatchAction:
    type: ActionType
    new_file: Optional[str] = None
    chunks: List[Chunk] = field(default_factory=list)
    move_path: Optional[str] = None


@dataclass
class Patch:
    actions: Dict[str, PatchAction] = field(default_factory=dict)


# --------------------------------------------------------------------------- #
#  Patch text parser
# --------------------------------------------------------------------------- #
@dataclass
class Parser:
    current_files: Dict[str, str]
    lines: List[str]
    index: int = 0
    patch: Patch = field(default_factory=Patch)
    fuzz: int = 0

    # ------------- low-level helpers -------------------------------------- #
    def _cur_line(self) -> str:
        if self.index >= len(self.lines):
            raise DiffError("Unexpected end of input while parsing patch")
        return self.lines[self.index]

    @staticmethod
    def _norm(line: str) -> str:
        """Strip CR so comparisons work for both LF and CRLF input."""
        return line.rstrip("\r")

    # ------------- scanning convenience ----------------------------------- #
    def is_done(self, prefixes: Optional[Tuple[str, ...]] = None) -> bool:
        if self.index >= len(self.lines):
            return True
        if (
            prefixes
            and len(prefixes) > 0
            and self._norm(self._cur_line()).startswith(prefixes)
        ):
            return True
        return False

    def startswith(self, prefix: Union[str, Tuple[str, ...]]) -> bool:
        return self._norm(self._cur_line()).startswith(prefix)

    def read_str(self, prefix: str) -> str:
        """
        Consume the current line if it starts with *prefix* and return the text
        **after** the prefix.  Raises if prefix is empty.
        """
        if prefix == "":
            raise ValueError("read_str() requires a non-empty prefix")
        if self._norm(self._cur_line()).startswith(prefix):
            text = self._cur_line()[len(prefix) :]
            self.index += 1
            return text
        return ""

    def read_line(self) -> str:
        """Return the current raw line and advance."""
        line = self._cur_line()
        self.index += 1
        return line

    # ------------- public entry point -------------------------------------- #
    def parse(self) -> None:
        while not self.is_done(("*** End Patch",)):
            # ---------- UPDATE ---------- #
            path = self.read_str("*** Update File: ")
            if path:
                if path in self.patch.actions:
                    raise DiffError(f"Duplicate update for file: {path}")
                move_to = self.read_str("*** Move to: ")
                if path not in self.current_files:
                    raise DiffError(f"Update File Error - missing file: {path}")
                text = self.current_files[path]
                action = self._parse_update_file(text)
                action.move_path = move_to or None
                self.patch.actions[path] = action
                continue

            # ---------- DELETE ---------- #
            path = self.read_str("*** Delete File: ")
            if path:
                if path in self.patch.actions:
                    raise DiffError(f"Duplicate delete for file: {path}")
                if path not in self.current_files:
                    raise DiffError(f"Delete File Error - missing file: {path}")
                self.patch.actions[path] = PatchAction(type=ActionType.DELETE)
                continue

            # ---------- ADD ---------- #
            path = self.read_str("*** Add File: ")
            if path:
                if path in self.patch.actions:
                    raise DiffError(f"Duplicate add for file: {path}")
                if path in self.current_files:
                    raise DiffError(f"Add File Error - file already exists: {path}")
                self.patch.actions[path] = self._parse_add_file()
                continue

            raise DiffError(f"Unknown line while parsing: {self._cur_line()}")

        if not self.startswith("*** End Patch"):
            raise DiffError("Missing *** End Patch sentinel")
        self.index += 1  # consume sentinel

    # ------------- section parsers ---------------------------------------- #
    def _parse_update_file(self, text: str) -> PatchAction:
        action = PatchAction(type=ActionType.UPDATE)
        lines = text.split("\n")
        index = 0
        while not self.is_done(
            (
                "*** End Patch",
                "*** Update File:",
                "*** Delete File:",
                "*** Add File:",
                "*** End of File",
            )
        ):
            def_str = self.read_str("@@ ")
            section_str = ""
            if not def_str and self._norm(self._cur_line()) == "@@":
                section_str = self.read_line()

            if not (def_str or section_str or index == 0):
                raise DiffError(f"Invalid line in update section:\n{self._cur_line()}")

            if def_str.strip():
                found = False
                if def_str not in lines[:index]:
                    for i, s in enumerate(lines[index:], index):
                        if s == def_str:
                            index = i + 1
                            found = True
                            break
                if not found and def_str.strip() not in [
                    s.strip() for s in lines[:index]
                ]:
                    for i, s in enumerate(lines[index:], index):
                        if s.strip() == def_str.strip():
                            index = i + 1
                            self.fuzz += 1
                            found = True
                            break

            next_ctx, chunks, end_idx, eof = peek_next_section(self.lines, self.index)
            new_index, fuzz = find_context(lines, next_ctx, index, eof)
            if new_index == -1:
                ctx_txt = "\n".join(next_ctx)
                raise DiffError(
                    f"Invalid {'EOF ' if eof else ''}context at {index}:\n{ctx_txt}"
                )
            self.fuzz += fuzz
            for ch in chunks:
                ch.orig_index += new_index
                action.chunks.append(ch)
            index = new_index + len(next_ctx)
            self.index = end_idx
        return action

    def _parse_add_file(self) -> PatchAction:
        lines: List[str] = []
        while not self.is_done(
            ("*** End Patch", "*** Update File:", "*** Delete File:", "*** Add File:")
        ):
            s = self.read_line()
            if not s.startswith("+"):
                raise DiffError(f"Invalid Add File line (missing '+'): {s}")
            lines.append(s[1:])  # strip leading '+'
        return PatchAction(type=ActionType.ADD, new_file="\n".join(lines))


# --------------------------------------------------------------------------- #
#  Helper functions
# --------------------------------------------------------------------------- #
def find_context_core(
    lines: List[str], context: List[str], start: int
) -> Tuple[int, int]:
    if not context:
        return start, 0

    for i in range(start, len(lines)):
        if lines[i : i + len(context)] == context:
            return i, 0
    for i in range(start, len(lines)):
        if [s.rstrip() for s in lines[i : i + len(context)]] == [
            s.rstrip() for s in context
        ]:
            return i, 1
    for i in range(start, len(lines)):
        if [s.strip() for s in lines[i : i + len(context)]] == [
            s.strip() for s in context
        ]:
            return i, 100
    return -1, 0


def find_context(
    lines: List[str], context: List[str], start: int, eof: bool
) -> Tuple[int, int]:
    if eof:
        new_index, fuzz = find_context_core(lines, context, len(lines) - len(context))
        if new_index != -1:
            return new_index, fuzz
        new_index, fuzz = find_context_core(lines, context, start)
        return new_index, fuzz + 10_000
    return find_context_core(lines, context, start)


def peek_next_section(
    lines: List[str], index: int
) -> Tuple[List[str], List[Chunk], int, bool]:
    old: List[str] = []
    del_lines: List[str] = []
    ins_lines: List[str] = []
    chunks: List[Chunk] = []
    mode = "keep"
    orig_index = index

    while index < len(lines):
        s = lines[index]
        if s.startswith(
            (
                "@@",
                "*** End Patch",
                "*** Update File:",
                "*** Delete File:",
                "*** Add File:",
                "*** End of File",
            )
        ):
            break
        if s == "***":
            break
        if s.startswith("***"):
            raise DiffError(f"Invalid Line: {s}")
        index += 1

        last_mode = mode
        if s == "":
            s = " "
        if s[0] == "+":
            mode = "add"
        elif s[0] == "-":
            mode = "delete"
        elif s[0] == " ":
            mode = "keep"
        else:
            raise DiffError(f"Invalid Line: {s}")
        s = s[1:]

        if mode == "keep" and last_mode != mode:
            if ins_lines or del_lines:
                chunks.append(
                    Chunk(
                        orig_index=len(old) - len(del_lines),
                        del_lines=del_lines,
                        ins_lines=ins_lines,
                    )
                )
            del_lines, ins_lines = [], []

        if mode == "delete":
            del_lines.append(s)
            old.append(s)
        elif mode == "add":
            ins_lines.append(s)
        elif mode == "keep":
            old.append(s)

    if ins_lines or del_lines:
        chunks.append(
            Chunk(
                orig_index=len(old) - len(del_lines),
                del_lines=del_lines,
                ins_lines=ins_lines,
            )
        )

    if index < len(lines) and lines[index] == "*** End of File":
        index += 1
        return old, chunks, index, True

    if index == orig_index:
        raise DiffError("Nothing in this section")
    return old, chunks, index, False


# --------------------------------------------------------------------------- #
#  Patch → Commit and Commit application
# --------------------------------------------------------------------------- #
def _get_updated_file(text: str, action: PatchAction, path: str) -> str:
    if action.type is not ActionType.UPDATE:
        raise DiffError("_get_updated_file called with non-update action")
    orig_lines = text.split("\n")
    dest_lines: List[str] = []
    orig_index = 0

    for chunk in action.chunks:
        if chunk.orig_index > len(orig_lines):
            raise DiffError(
                f"{path}: chunk.orig_index {chunk.orig_index} exceeds file length"
            )
        if orig_index > chunk.orig_index:
            raise DiffError(
                f"{path}: overlapping chunks at {orig_index} > {chunk.orig_index}"
            )

        dest_lines.extend(orig_lines[orig_index : chunk.orig_index])
        orig_index = chunk.orig_index

        dest_lines.extend(chunk.ins_lines)
        orig_index += len(chunk.del_lines)

    dest_lines.extend(orig_lines[orig_index:])
    return "\n".join(dest_lines)


def patch_to_commit(patch: Patch, orig: Dict[str, str]) -> Commit:
    commit = Commit()
    for path, action in patch.actions.items():
        if action.type is ActionType.DELETE:
            commit.changes[path] = FileChange(
                type=ActionType.DELETE, old_content=orig[path]
            )
        elif action.type is ActionType.ADD:
            if action.new_file is None:
                raise DiffError("ADD action without file content")
            commit.changes[path] = FileChange(
                type=ActionType.ADD, new_content=action.new_file
            )
        elif action.type is ActionType.UPDATE:
            new_content = _get_updated_file(orig[path], action, path)
            commit.changes[path] = FileChange(
                type=ActionType.UPDATE,
                old_content=orig[path],
                new_content=new_content,
                move_path=action.move_path,
            )
    return commit


# --------------------------------------------------------------------------- #
#  User-facing helpers
# --------------------------------------------------------------------------- #
def text_to_patch(text: str, orig: Dict[str, str]) -> Tuple[Patch, int]:
    lines = text.splitlines()  # preserves blank lines, no strip()
    if (
        len(lines) < 2
        or not Parser._norm(lines[0]).startswith("*** Begin Patch")
        or Parser._norm(lines[-1]) != "*** End Patch"
    ):
        raise DiffError("Invalid patch text - missing sentinels")

    parser = Parser(current_files=orig, lines=lines, index=1)
    parser.parse()
    return parser.patch, parser.fuzz


def identify_files_needed(text: str) -> List[str]:
    lines = text.splitlines()
    return [
        line[len("*** Update File: ") :]
        for line in lines
        if line.startswith("*** Update File: ")
    ] + [
        line[len("*** Delete File: ") :]
        for line in lines
        if line.startswith("*** Delete File: ")
    ]


def identify_files_added(text: str) -> List[str]:
    lines = text.splitlines()
    return [
        line[len("*** Add File: ") :]
        for line in lines
        if line.startswith("*** Add File: ")
    ]


# --------------------------------------------------------------------------- #
#  File-system helpers
# --------------------------------------------------------------------------- #
def load_files(paths: List[str], open_fn: Callable[[str], str]) -> Dict[str, str]:
    return {path: open_fn(path) for path in paths}


def apply_commit(
    commit: Commit,
    write_fn: Callable[[str, str], None],
    remove_fn: Callable[[str], None],
) -> None:
    for path, change in commit.changes.items():
        if change.type is ActionType.DELETE:
            remove_fn(path)
        elif change.type is ActionType.ADD:
            if change.new_content is None:
                raise DiffError(f"ADD change for {path} has no content")
            write_fn(path, change.new_content)
        elif change.type is ActionType.UPDATE:
            if change.new_content is None:
                raise DiffError(f"UPDATE change for {path} has no new content")
            target = change.move_path or path
            write_fn(target, change.new_content)
            if change.move_path:
                remove_fn(path)


def process_patch(
    text: str,
    open_fn: Callable[[str], str],
    write_fn: Callable[[str, str], None],
    remove_fn: Callable[[str], None],
) -> str:
    if not text.startswith("*** Begin Patch"):
        raise DiffError("Patch text must start with *** Begin Patch")
    paths = identify_files_needed(text)
    orig = load_files(paths, open_fn)
    patch, _fuzz = text_to_patch(text, orig)
    commit = patch_to_commit(patch, orig)
    apply_commit(commit, write_fn, remove_fn)
    return "Done!"


# --------------------------------------------------------------------------- #
#  Default FS helpers
# --------------------------------------------------------------------------- #
def open_file(path: str) -> str:
    with open(path, "rt", encoding="utf-8") as fh:
        return fh.read()


def write_file(path: str, content: str) -> None:
    target = pathlib.Path(path)
    target.parent.mkdir(parents=True, exist_ok=True)
    with target.open("wt", encoding="utf-8") as fh:
        fh.write(content)


def remove_file(path: str) -> None:
    pathlib.Path(path).unlink(missing_ok=True)


# --------------------------------------------------------------------------- #
#  CLI entry-point
# --------------------------------------------------------------------------- #
def main() -> None:
    import sys

    patch_text = sys.stdin.read()
    if not patch_text:
        print("Please pass patch text through stdin", file=sys.stderr)
        return
    try:
        result = process_patch(patch_text, open_file, write_file, remove_file)
    except DiffError as exc:
        print(exc, file=sys.stderr)
        return
    print(result)


if __name__ == "__main__":
    main()

其他有效的差异格式

如果您想尝试使用不同的差异格式，我们在测试中发现 Aider 的 polyglot benchmark 中使用的 SEARCH/REPLACE 差异格式，以及一种没有内部转义的伪 XML 格式，都具有很高的成功率。

这些差异格式共享两个关键方面：(1) 它们不使用行号，并且 (2) 它们同时提供要替换的确切代码和要替换的确切代码，并在两者之间使用清晰的分隔符。

SEARCH_REPLACE_DIFF_EXAMPLE = """
path/to/file.py

SEARCH def search(): pass ======= def search(): raise NotImplementedError() <<<<<<< REPLACE """

PSEUDO_XML_DIFF_EXAMPLE = """ path/to/file.py def search(): pass def search(): raise NotImplementedError() """ ```