OpenAI 开发者平台面经

📖 "Use the Responses API for direct model requests like this text-generation call." — 原文

📖 "If you're building any text generation app, we recommend using the Responses API over the older Chat Completions API." — 原文

📖 "One important note is that reasoning models perform better and demonstrate higher intelligence when used with the Responses API." — 原文

from openai import OpenAI
client = OpenAI()

response = client.responses.create(
    model="gpt-5.6",
    input="Write a one-sentence bedtime story about a unicorn."
)

print(response.output_text)

📖 "An array of content generated by the model is in the output property of the response." — 原文

📖 "The output array often has more than one item in it! It can contain tool calls, data about reasoning tokens generated by reasoning models, and other items. It is not safe to assume that the model's text output is present at output[0].content[0].text." — 原文

📖 "Some of our official SDKs include an output_text property on model responses for convenience, which aggregates all text outputs from the model into a single string." — 原文

[
  {
    "id": "msg_67b73f697ba4819183a15cc17d011509",
    "type": "message",
    "role": "assistant",
    "content": [
      {
        "type": "output_text",
        "text": "Under the soft glow of the moon, Luna the unicorn danced through fields of twinkling stardust, leaving trails of dreams for every child asleep.",
        "annotations": []
      }
    ]
  }
]

📖 "The instructions parameter gives the model high-level instructions on how it should behave while generating a response, including tone, goals, and examples of correct responses. Any instructions provided this way will take priority over a prompt in the input parameter." — 原文

📖 "You could think about developer and user messages like a function and its arguments in a programming language." — 原文

from openai import OpenAI
client = OpenAI()

response = client.responses.create(
    model="gpt-5.6",
    reasoning={"effort": "low"},
    input=[
        {
            "role": "developer",
            "content": "${semicolonsDevMsg}"
        },
        {
            "role": "user",
            "content": "${semicolonsPrompt}"
        }
    ]
)

print(response.output_text)

📖 "Note that the instructions parameter only applies to the current response generation request. If you are managing conversation state with the previous_response_id parameter, the instructions used on previous turns will not be present in the context." — 原文

📖 "Text generation and embeddings models process text in chunks called tokens. Tokens represent commonly occurring sequences of characters." — 原文

📖 "As a rough rule of thumb, 1 token is approximately 4 characters or 0.75 words for English text." — 原文

📖 "One limitation to keep in mind is that for a text generation model the prompt and the generated output combined must be no more than the model's maximum context length." — 原文

📖 "Designing a prompt is essentially how you "program" a model, usually by providing instructions or some examples of how to successfully complete a task." — 原文

📖 "Prompt engineering is the process of writing effective instructions for a model, such that it consistently generates content that meets your requirements." — 原文

📖 "Because the content generated from a model is non-deterministic, prompting to get your desired output is a mix of art and science." — 原文

📖 "Pinning your production applications to specific model snapshots (like gpt-5.5-2026-04-23 for example) to ensure consistent behavior" — 原文

📖 "Give the model access to external data and functions by attaching tools. Use built-in tools like web search or file search, or define your own for calling APIs, running code, or integrating with third-party systems." — 原文

from openai import OpenAI
client = OpenAI()

response = client.responses.create(
    model="gpt-5.6",
    tools=[{"type": "web_search"}],
    input="What was a positive news story from today?"
)

print(response.output_text)

📖 "Use server-sent events to stream model responses to users fast." — 原文

📖 "Use WebRTC or WebSockets for super fast speech-to-speech AI apps." — 原文

from openai import OpenAI
client = OpenAI()

stream = client.responses.create(
    model="gpt-5.6",
    input=[
        {
            "role": "user",
            "content": "Say 'double bubble bath' ten times fast.",
        },
    ],
    stream=True,
)

for event in stream:
    print(event)

📖 "An embedding is a vector representation of a piece of data (e.g. some text) that is meant to preserve aspects of its content and/or its meaning. Chunks of data that are similar in some way will tend to have embeddings that are closer together than unrelated data." — 原文

flowchart LR
    A[文本字符串] --> B[embedding 模型]
    B --> C[embedding 向量]
    C --> D[向量空间按距离比相似度]
    D --> E[search / clustering / classification]

flowchart TD
    A[多轮对话需求] --> B{谁保存历史?}
    B -->|客户端自持| C[手动: input 拼接 user/assistant
或追加 output 数组]
    B -->|服务端持久对象| D[Conversations API
durable identifier]
    B -->|服务端链式续接| E[previous_response_id
threaded conversation]

📖 "OpenAI provides a few ways to manage conversation state, which is important for preserving information across multiple messages or turns in a conversation." — 原文

📖 "While each text generation request is independent and stateless, you can still implement multi-turn conversations by providing additional messages as parameters to your text generation request." — 原文

📖 "By using alternating user and assistant messages, you capture the previous state of a conversation in one request to the model." — 原文

history = [{"role": "user", "content": "tell me a joke"}]
response = client.responses.create(model="gpt-5.6", input=history, store=False)
# Add all response output items, including encrypted reasoning items, to the conversation
history += response.output
history.append({"role": "user", "content": "tell me another"})
second_response = client.responses.create(model="gpt-5.6", input=history, store=False)

📖 "Another way to manage conversation state is to share context across generated responses with the previous_response_id parameter. This parameter lets you chain responses and create a threaded conversation." — 原文

📖 "Even when using previous_response_id, all previous input tokens for responses in the chain are billed as input tokens in the API." — 原文

📖 "Response objects are saved for 30 days by default." — 原文

response = client.responses.create(model="gpt-5.6", input="tell me a joke")
second_response = client.responses.create(
    model="gpt-5.6",
    previous_response_id=response.id,
    input=[{"role": "user", "content": "explain why this is funny."}],
)

📖 "Streaming responses lets you start printing or processing the beginning of the model's output while it continues generating the full response." — 原文

📖 "The Responses API uses semantic events for streaming. Each event is typed with a predefined schema, so you can listen for events you care about." — 原文

stream = client.responses.create(
    model="gpt-5.6",
    input=[{"role": "user", "content": "Say 'double bubble bath' ten times fast."}],
    stream=True,
)
for event in stream:
    print(event)

📖 "To stream completions, set stream=True when calling the chat completions or completions endpoints." — 原文

📖 "Extract chunks from the delta field rather than the message field." — 原文

📖 "As you can see above, streaming responses have a delta field rather than a message field." — 原文

collected_messages = []
for chunk in response:
    chunk_message = chunk.choices[0].delta.content  # extract the message
    collected_messages.append(chunk_message)
# clean None in collected_messages
collected_messages = [m for m in collected_messages if m is not None]
full_reply_content = ''.join(collected_messages)

📖 "When you do so, an extra chunk will be streamed as the final chunk." — 原文

📖 "The value for the usage field on all chunks except for the last one will be null." — 原文

📖 "The choices field on the last chunk will always be an empty array []." — 原文

response = client.chat.completions.create(
    model='gpt-4o-mini',
    messages=[{'role': 'user', 'content': "What's 1+1? Answer in one word."}],
    temperature=0,
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in response:
    print(f"choices: {chunk.choices}\nusage: {chunk.usage}")

📖 "This max tokens number includes input, output, and reasoning tokens." — 原文

📖 "Tokens generated in excess of the context window limit may be truncated in API responses." — 原文

gpt-4o-2024-08-06: 最多 16,384 output tokens；总 context window 128k tokens
输入过大 → 超出窗口 → 输出可能被截断 (truncated)

📖 "Conversations store items, which can be messages, tool calls, tool outputs, and other data." — 原文

📖 "Conversation objects and items in them are not subject to the 30 day TTL. Any response attached to a conversation will have its items persisted with no 30 day TTL." — 原文

conversation = openai.conversations.create()
response = openai.responses.create(
  model="gpt-5.6",
  input=[{"role": "user", "content": "What are the 5 Ds of dodgeball?"}],
  conversation="conv_689667905b048191b4740501625afd940c7533ace33a2dab"
)

📖 "Note that streaming the model's output in a production application makes it more difficult to moderate the content of the completions, as partial completions may be more difficult to evaluate. This may have implications for approved usage." — 原文

📖 "the scores arrive after the full generated output is available. They aren't included with partial output deltas." — 原文

方案A: 边流边展示  → 首字节延迟低，但部分输出无法即时审核（风险）
方案B: 待完整输出+moderation 分数返回再放行 → 可审核，但失去流式低延迟

📖 "Function calling (also known as tool calling) provides a powerful and flexible way for OpenAI models to interface with external systems and access data outside their training data." — 原文

📖 "A function call or tool call refers to a special kind of response we can get from the model if it examines a prompt, and then determines that in order to follow the instructions in the prompt, it needs to call one of the tools we made available to it." — 原文

📖 "A function call output or tool call output refers to the response a tool generates using the input from a model's tool call." — 原文

[
  { "role": "user", "content": "what's the weather in Paris?" },
  { "type": "function_call", "call_id": "call_12345xyz", "name": "get_weather", "arguments": "{\"location\":\"Paris, France\"}" },
  { "type": "function_call_output", "call_id": "call_12345xyz", "output": "{\"temperature\": \"25\", \"unit\": \"C\"}" }
]

📖 "Tool calling is a multi-step conversation between your application and a model via the OpenAI API." — 原文

📖 "With Responses, your application can continue this flow for as many tool calls as the task requires." — 原文

# 2. 带 tools 请求
response = client.responses.create(model="gpt-5.6", tools=tools, input=input_list)
input_list += response.output  # 把模型输出存回，供后续请求使用
for item in response.output:
    if item.type == "function_call" and item.name == "get_horoscope":
        sign = json.loads(item.arguments)["sign"]
        horoscope = get_horoscope(sign)          # 3. 执行
        input_list.append({                       # 4. 回传结果
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": horoscope,
        })
# 5. 再次请求拿最终回复
response = client.responses.create(model="gpt-5.6", tools=tools, input=input_list)

📖 "Functions are usually declared in the tools parameter of each API request." — 原文

📖 "Because the parameters are defined by a JSON schema, you can leverage many of its rich features like property types, enums, descriptions, nested objects, and, recursive objects." — 原文

{
  "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
}

📖 "When the model calls a function, you must execute it and return the result. Since model responses can include zero, one, or multiple calls, it is best practice to assume there are several." — 原文

📖 "The result you pass in the function_call_output message should typically be a string, where the format is up to you (JSON, error codes, plain text, etc.). The model will interpret that string as needed." — 原文

📖 "If your function has no return value (e.g. send_email), simply return a string that indicates success or failure. (e.g. "success")" — 原文

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": str(result)
    })

📖 "Setting strict to true will ensure function calls reliably adhere to the function schema, instead of being best effort. We recommend always enabling strict mode." — 原文

📖 "You can denote optional fields by adding null as a type option (see example below)." — 原文

{
    "type": "function",
    "name": "get_weather",
    "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
    }
}

📖 "By default the model will determine when and how many tools to use. You can force specific behavior with the tool_choice parameter." — 原文

📖 "You can also set tool_choice to "none" to imitate the behavior of passing no functions." — 原文

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

📖 "The model may choose to call multiple functions in a single turn. You can prevent this by setting parallel_tool_calls to false, which ensures exactly zero or one tool is called." — 原文

📖 "Newer models such as gpt-5, gpt-4.1 or gpt-4o can call multiple functions in one turn." — 原文

[
 ChatCompletionMessageFunctionToolCall(function=Function(arguments='{"location": "San Francisco, CA", "format": "fahrenheit", "num_days": 4}', name='get_n_day_weather_forecast'), type='function'),
 ChatCompletionMessageFunctionToolCall(function=Function(arguments='{"location": "Glasgow, UK", "format": "celsius", "num_days": 4}', name='get_n_day_weather_forecast'), type='function'),
]

📖 "tools is an optional parameter in the Chat Completion API which can be used to provide function specifications. The purpose of this is to enable models to generate function arguments which adhere to the provided specifications. Note that the API will not actually execute any function calls. It is up to developers to execute function calls using model outputs." — 原文

📖 "in the response, as well as a tool_calls object that has the name of the function and the generated function arguments." — 原文

tool_calls = response_message.tool_calls
if tool_calls:
    tool_call_id = tool_calls[0].id
    tool_function_name = tool_calls[0].function.name
    tool_query_string = json.loads(tool_calls[0].function.arguments)['query']
    if tool_function_name == 'ask_database':
        results = ask_database(conn, tool_query_string)
        messages.append({
            "role":"tool", "tool_call_id":tool_call_id,
            "name": tool_function_name, "content":results
        })
        model_response_with_function_call = client.chat.completions.create(
            model=GPT_MODEL, messages=messages,
        )

📖 "Aim for fewer than 20 functions available at the start of a turn" — 原文

📖 "This means callable function definitions count against the model's context limit and are billed as input tokens." — 原文

# 反例：让模型填一个你其实已经知道的值
# submit_refund(order_id: str)
# 正例：无参数函数，order_id 由应用代码补上
def submit_refund():
    ...  # order_id 从上一步菜单上下文用代码传入

📖 "Streaming function calls is very similar to streaming regular responses: you set stream to true and get different event objects." — 原文

📖 "Instead of aggregating chunks into a single content string, however, you're aggregating chunks into an encoded arguments JSON object." — 原文

const finalToolCalls = {};
for await (const event of stream) {
    if (event.type === 'response.output_item.added') {
        finalToolCalls[event.output_index] = event.item;
    } else if (event.type === 'response.function_call_arguments.delta') {
        const index = event.output_index;
        if (finalToolCalls[index]) {
            finalToolCalls[index].arguments += event.delta;
        }
    }
}

📖 "Non‑reasoning web search: The non-reasoning model sends the user’s query to the web search tool, which returns the response based on top results. There’s no internal planning and the model simply passes along the search tool’s responses. This method is fast and ideal for quick lookups." — 原文

📖 "Deep research is a specialized, agent-driven method for in-depth, extended investigations by reasoning models. The model conducts web searches as part of its chain of thought, often tapping into hundreds of sources. Deep research can run for several minutes and is best used with background mode." — 原文

from openai import OpenAI
client = OpenAI()

response = client.responses.create(
    model="gpt-5.6",
    tools=[{"type": "web_search"}],
    input="What was a positive news story from today?"
)

print(response.output_text)

flowchart TD
    A[用户 query] --> B{哪种搜索?}
    B -->|快速查询| C[non-reasoning: 转述 top results]
    B -->|复杂工作流| D[agentic: 边推理边搜索, 自行决定继续]
    B -->|深度调查| E[deep research: 数百来源, 数分钟, background]

📖 "For new Responses API integrations, use { "type": "web_search" }. The earlier web_search_preview tool remains available for legacy integrations, but it does not support newer controls such as filters, external_web_access, and return_token_budget." — 原文

📖 "Chat Completions search models always search before responding; Responses search is a tool" — 原文

# tool_choice: "auto" 时 search 是可选的；需要强制搜索时用 required
curl "https://api.openai.com/v1/responses" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "gpt-5.6",
        "tools": [{"type": "web_search"}],
        "input": "what was a positive news story from today?"
}'

📖 "It enables models to retrieve information in a knowledge base of previously uploaded files through semantic and keyword search." — 原文

📖 "This is a hosted tool managed by OpenAI, meaning you don't have to implement code on your end to handle its execution." — 原文

from openai import OpenAI
client = OpenAI()

response = client.responses.create(
    model="gpt-5.6",
    input="What is deep research by OpenAI?",
    tools=[{
        "type": "file_search",
        "vector_store_ids": ["<vector_store_id>"]
    }]
)
print(response)

📖 "The Code Interpreter tool allows models to write and run Python code in a sandboxed environment to solve complex problems in domains like data analysis, coding, and math." — 原文

📖 "The Code Interpreter tool requires a container object. A container is a fully sandboxed virtual machine that the model can run Python code in." — 原文

curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-5.6",
    "tools": [{
      "type": "code_interpreter",
      "container": { "type": "auto", "memory_limit": "4g" }
    }],
    "instructions": "You are a personal math tutor. When asked a math question, write and run code using the python tool to answer the question.",
    "input": "I need to solve the equation 3x + 11 = 14. Can you help me?"
  }'

📖 "By default, the model's response will include inline citations for URLs found in the web search results. In addition to this, the url_citation annotation object will contain the URL, title and location of the cited source." — 原文

📖 "- A web_search_call output item with the ID of the search call, along with the action taken in web_search_call.action. The action is one of:" — 原文

[
  {
    "type": "web_search_call",
    "id": "ws_67c9fa0502748190b7dd390736892e100be649c1a5ff9609",
    "status": "completed",
    "action": {
      "type": "search",
      "query": "latest news about AI"
    }
  },
  {
    "id": "msg_67c9fa077e288190af08fdffda2e34f20be649c1a5ff9609",
    "type": "message",
    "status": "completed",
    "role": "assistant",
    "content": [
      {
        "type": "output_text",
        "text": "On March 6, 2025, several news...",
        "annotations": [
          {
            "type": "url_citation",
            "start_index": 2606,
            "end_index": 2758,
            "url": "https://...",
            "title": "Title..."
          }
        ]
      }
    ]
  }
]

📖 "search_context_size controls how much context from web search results is made available to the model before it generates a response. Use low for simple lookups, medium for a balanced default, and high when the answer may require more detail from search results. This setting does not set an exact token count or guarantee a specific number of sources or citations." — 原文

📖 "Use unlimited selectively because it can increase latency and cost. For long-running multi-search tasks, use background mode (background: true) so the request can keep running asynchronously and you can retrieve the final response later." — 原文

from openai import OpenAI
client = OpenAI()

response = client.responses.create(
    model="gpt-5.6",
    tools=[{
        "type": "web_search",
        "search_context_size": "low",
    }],
    input="What movie won best picture in 2025?",
)

print(response.output_text)

📖 "This automatically creates a new container, or reuses an active container that was used by a previous code_interpreter_call item in the model's context. Leaving out memory_limit keeps the default 1 GB tier for the container." — 原文

📖 "A container expires if it is not used for 20 minutes. When this happens, using the container in v1/responses will fail." — 原文

from openai import OpenAI
client = OpenAI()

container = client.containers.create(name="test-container", memory_limit="4g")

response = client.responses.create(
    model="gpt-5.6",
    tools=[{
        "type": "code_interpreter",
        "container": container.id
    }],
    tool_choice="required",
    input="use the python tool to calculate what is 4 * 3.82. and then find its square root and then find the square root of that result"
)

print(response.output_text)

📖 "Using the file search tool with the Responses API, you can customize the number of results you want to retrieve from the vector stores. This can help reduce both token usage and latency, but may come at the cost of reduced answer quality." — 原文

📖 "While you can see annotations (references to files) in the output text, the file search call will not return search results by default." — 原文

response = client.responses.create(
    model="gpt-5.6",
    input="What is deep research by OpenAI?",
    tools=[{
        "type": "file_search",
        "vector_store_ids": ["<vector_store_id>"],
        "filters": {
            "type": "in",
            "key": "category",
            "value": ["blog", "announcement"]
        }
    }]
)
print(response)

📖 "With the filters parameter you can configure up to 100 allowed_domains or up to 100 blocked_domains. When formatting domains, omit the HTTP or HTTPS prefix." — 原文

📖 "Set external_web_access: false on the web_search tool to run in offline/cache‑only mode." — 原文

curl "https://api.openai.com/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-5.6",
    "reasoning": { "effort": "low" },
    "tools": [
      {
        "type": "web_search",
        "filters": {
          "allowed_domains": [
            "pubmed.ncbi.nlm.nih.gov",
            "clinicaltrials.gov",
            "www.who.int",
            "www.cdc.gov",
            "www.fda.gov"
          ],
          "blocked_domains": [
            "reddit.com",
            "quora.com",
            "wikipedia.org"
          ]
        }
      }
    ],
    "tool_choice": "auto",
    "include": ["web_search_call.action.sources"],
    "input": "Please perform a web search on how semaglutide is used in the treatment of diabetes."
  }'

📖 "Connectors are OpenAI-maintained MCP wrappers for popular services like Google Workspace or Dropbox, like the connectors available in ChatGPT." — 原文

📖 "Remote MCP servers can be any server on the public Internet that implements a remote Model Context Protocol (MCP) server." — 原文

📖 "However, instead of passing a server_url as you would to call a remote MCP server, you pass a connector_id which uniquely identifies a connector available in the API." — 原文

curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
  "model": "gpt-5.6",
    "tools": [
      {
        "type": "mcp",
        "server_label": "dmcp",
        "server_description": "A Dungeons and Dragons MCP server to assist with dice rolling.",
        "server_url": "https://dmcp-server.deno.dev/mcp",
        "require_approval": "never"
      }
    ],
    "input": "Roll 2d4+1"
  }'

📖 "If the model decides to use a Connector or MCP server, it will first make a request to list available tools from the server, which will create a mcp_list_tools output item." — 原文

📖 "The Responses API works with remote MCP servers that support either the Streamable HTTP or the HTTP/SSE transport protocols." — 原文

📖 "As long as this item is present in the model's context, we will not call tools/list on the server again. This is akin to caching at the user-conversation level." — 原文

flowchart TD
    A[tools 里声明 mcp server] --> B[探测 transport:
Streamable HTTP / HTTP-SSE]
    B --> C[调用 tools/list
生成 mcp_list_tools]
    C -->|item 留在上下文| C
    C --> D{模型决定调用工具?}
    D -->|是| E[生成 mcp_call
arguments + output]
    D -->|否| F[直接返回最终答案]
    E --> D

{
  "id": "mcp_68a6102d8948819c9b1490d36d5ffa4a0679e572a900e618",
  "type": "mcp_call",
  "approval_request_id": null,
  "arguments": "{\"diceRollExpression\":\"2d4 + 1\"}",
  "error": null,
  "name": "roll",
  "output": "4",
  "server_label": "dmcp"
}

📖 "By default, OpenAI will request your approval before any data is shared with a connector or remote MCP server." — 原文

📖 "You can then respond to this by creating a new Response object and appending an mcp_approval_response item to it." — 原文

📖 "If and when you feel comfortable trusting a remote MCP server, you can choose to skip the approvals for reduced latency." — 原文

{
  "type": "mcp",
  "server_label": "deepwiki",
  "server_url": "https://mcp.deepwiki.com/mcp",
  "require_approval": {
    "never": {
      "tool_names": ["ask_question", "read_wiki_structure"]
    }
  }
}

curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
    "model": "gpt-5.6",
    "previous_response_id": "resp_682d498bdefc81918b4a6aa477bfafd904ad1e533afccbfa",
    "input": [{
      "type": "mcp_approval_response",
      "approve": true,
      "approval_request_id": "mcpr_682d498e3bd4819196a0ce1664f8e77b04ad1e533afccbfa"
    }]
  }'

📖 "Some MCP servers can have dozens of tools, and exposing many tools to the model can result in high cost and latency." — 原文

📖 "This reduces token overhead, improves response time, and narrows the model’s decision space." — 原文

curl https://api.openai.com/v1/responses -i \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-4.1",
    "tools": [
        {
            "type": "mcp",
            "server_label": "gitmcp",
            "server_url": "https://gitmcp.io/openai/tiktoken",
            "allowed_tools": ["search_tiktoken_documentation", "fetch_tiktoken_documentation"],
            "require_approval": "never"
        }
    ],
    "input": "how does tiktoken work?"
}'

📖 "The most common scheme is an OAuth access token." — 原文

📖 "To prevent the leakage of sensitive tokens, the Responses API does not store the value you provide in the authorization field." — 原文

📖 "Because of this, you must send the authorization value in every Responses API creation request you make." — 原文

curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
    "model": "gpt-5.6",
    "input": "Create a payment link for $20",
    "tools": [
      {
        "type": "mcp",
        "server_label": "stripe",
        "server_url": "https://mcp.stripe.com",
        "authorization": "$STRIPE_OAUTH_ACCESS_TOKEN"
      }
    ]
  }'

📖 "The Responses API has built-in support for a limited set of connectors to third-party services." — 原文

📖 "We prioritized services that don't have official remote MCP servers. GitHub, for instance, has an official MCP server you can connect to by passing https://api.githubcopilot.com/mcp/ to the server_url field in the MCP tool." — 原文

📖 "The available tools depend on which scopes your OAuth token has available to it." — 原文

curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-5.6",
    "tools": [
      {
        "type": "mcp",
        "server_label": "google_calendar",
        "connector_id": "connector_googlecalendar",
        "authorization": "ya29.A0AS3H6...",
        "require_approval": "never"
      }
    ],
    "input": "What is on my Google Calendar for today?"
  }'

📖 "To work with ChatGPT deep research and company knowledge (and deep research via API), your MCP server should implement two read-only tools: search and fetch, using the compatibility schema in Company knowledge compatibility." — 原文

📖 "In MCP, return this object as structuredContent and include the same value as\na JSON-encoded string in the content array for compatibility." — 原文

📖 "To make a result citable, return its canonical url." — 原文

{
  "structuredContent": {
    "results": [{ "id": "doc-1", "title": "...", "url": "..." }]
  },
  "content": [
    {
      "type": "text",
      "text": "{\"results\":[{\"id\":\"doc-1\",\"title\":\"...\",\"url\":\"...\"}]}"
    }
  ]
}

@mcp.tool(output_schema=SearchOutput.model_json_schema())
async def search(query: str) -> SearchOutput:

📖 "Remote MCP servers carry those same risks, but also have not been verified by OpenAI." — 原文

📖 "Prompt injections are a form of attack where an attacker embeds malicious instructions in content that one of our models is likely to encounter–such as a webpage–with the intention that the instructions override ChatGPT’s intended behavior." — 原文

📖 "Pick official servers hosted by the service providers themselves (e.g. we recommend connecting to the Stripe server hosted by Stripe themselves on mcp.stripe.com, instead of a Stripe MCP server hosted by a third party)." — 原文

📖 "The MCP tool is compatible with Zero Data Retention and Data Residency, but it's important to note that MCP servers are third-party services, and data sent to an MCP server is subject to their data retention and data residency policies." — 原文

# store=true 时，数据经 API 记录 30 天（除非组织启用了 Zero Data Retention）
curl https://api.openai.com/v1/responses -d '{ "store": true, "tools": [ ... ] }'

📖 "Computer use lets a model operate software through the user interface. It can inspect screenshots, return interface actions for your code to execute, or work through a custom harness that mixes visual and programmatic interaction with the UI." — 原文

📖 "Option 3: Use a code-execution harness](#option-3-use-a-code-execution-harness) when you want the model to write and run short scripts in a runtime and move flexibly between visual interaction and programmatic UI interaction, including DOM-based workflows. gpt-5.4 and future models are explicitly trained to work well with this option." — 原文

flowchart TD
    A[要用 Computer use] --> B{已有成熟 harness?}
    B -- 否, 想最快原型 --> C[Option 1: built-in computer 工具
模型返回 click/type/scroll/screenshot]
    B -- 是 Playwright/Selenium/VNC/MCP --> D[Option 2: 暴露为普通工具接口
复用重试与护栏]
    A --> E{需要循环/条件/DOM 检查?}
    E -- 是 --> F[Option 3: code-execution harness
模型写并运行短脚本]

📖 "The model looks at the current UI through a screenshot, returns actions such as clicks, typing, or scrolling, and your harness executes those actions in a browser or computer environment." — 原文

📖 "Later turns can batch actions into the same computer_call. Run them in order before taking the next screenshot." — 原文

{
  "output": [
    {
      "type": "computer_call",
      "call_id": "call_002",
      "actions": [
        { "type": "click", "button": "left", "x": 405, "y": 157 },
        { "type": "type", "text": "penguin" }
      ],
      "status": "completed"
    }
  ]
}

📖 "The apply_patch tool lets GPT-5.1 create, update, and delete files in your codebase using structured diffs. Instead of just suggesting edits, the model emits patch operations that your application applies and then reports back on, enabling iterative, multi-step code editing workflows." — 原文

📖 "When using the apply_patch tool, you don’t provide an input schema; the model knows how to construct operation objects." — 原文

{
  "type": "apply_patch_call_output",
  "call_id": "call_cNWm41dB3RyQcLNOVTIPBWZU",
  "status": "failed",
  "output": "Could not apply patch to lib/foo.py — file not found on disk"
}

📖 "Programmatic Tool Calling lets a model write and run JavaScript that coordinates the tools in a Responses API request. A program can call tools in parallel, use loops and conditions, and keep intermediate results in the hosted runtime. This is useful when a task needs a sequence of related tool calls or needs to process large tool outputs before returning a result." — 原文

📖 "Use Programmatic Tool Calling when a stage has predictable control flow and code can return a smaller structured result. Use direct tool calling when one call is sufficient, each result requires fresh model judgment, or the work requires approval or preservation of citations or native artifacts." — 原文

📖 "OpenAI runs the model-generated JavaScript in the hosted runtime. Your application executes returned client-owned function calls; it does not execute the generated JavaScript." — 原文

{
  "type": "program",
  "id": "prog_123",
  "call_id": "call_prog_123",
  "code": "const [stock, demand] = await Promise.all([tools.get_inventory({ sku: 'sku_123' }), tools.get_demand({ sku: 'sku_123' })]); text(JSON.stringify({ sku: stock.sku, available_units: stock.available_units, requested_units: demand.requested_units, shortage_units: Math.max(demand.requested_units - stock.available_units, 0) }));",
  "fingerprint": "opaque_replay_state"
}

📖 "OpenAI runs each generated program in a fresh, isolated V8 runtime. The runtime supports JavaScript with top-level await, but it does not provide Node.js, package installation, direct network access, a general-purpose filesystem, subprocess execution, a console, or persistent JavaScript state between program executions." — 原文

📖 "Add the programmatic_tool_calling hosted tool to the request. Then set allowed_callers on each eligible tool that the program can invoke." — 原文

{
  "type": "function",
  "name": "get_inventory",
  "description": "Return an object with sku (string) and available_units (number).",
  "parameters": {
    "type": "object",
    "properties": { "sku": { "type": "string" } },
    "required": ["sku"],
    "additionalProperties": false
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "sku": { "type": "string" },
      "available_units": { "type": "number" }
    },
    "required": ["sku", "available_units"],
    "additionalProperties": false
  },
  "allowed_callers": ["programmatic"]
}

📖 "Whether you use a browser or VM, treat screenshots, page text, tool outputs, PDFs, emails, chats, and other third-party content as untrusted input. Only direct instructions from the user count as permission." — 原文

📖 "For Computer use, prefer detail: "original" on screenshot inputs to preserve resolution and improve click accuracy." — 原文

def send_computer_screenshot(response, call_id, screenshot_base64):
    return client.responses.create(
        model="gpt-5.6",
        tools=[{"type": "computer"}],
        previous_response_id=response.id,
        input=[
            {
                "type": "computer_call_output",
                "call_id": call_id,
                "output": {
                    "type": "computer_screenshot",
                    "image_url": f"data:image/png;base64,{screenshot_base64}",
                    "detail": "original",
                },
            }
        ],
    )

📖 "Structured Outputs is a feature that ensures the model will always generate responses that adhere to your supplied JSON Schema, so you don't need to worry about the model omitting a required key, or hallucinating an invalid enum value." — 原文

📖 "Unlike JSON mode, Structured Outputs constrains the shape of the JSON, not only its validity." — 原文

class Step(BaseModel):
    explanation: str
    output: str

class MathReasoning(BaseModel):
    steps: list[Step]
    final_answer: str

📖 "Structured Outputs is the evolution of [JSON mode](#json-mode). While both ensure valid JSON is produced, only Structured Outputs ensure schema adherence." — 原文

📖 "We recommend always using Structured Outputs instead of JSON mode when possible." — 原文

📖 "However, Structured Outputs with response_format: {type: \"json_schema\", ...} is only supported with the gpt-4o-mini, gpt-4o-mini-2024-07-18, and gpt-4o-2024-08-06 model snapshots and later." — 原文

{ "text": { "format": { "type": "json_schema", "strict": true, "schema": "..." } } }

{ "text": { "format": { "type": "json_object" } } }

📖 "Function calling is useful when you are building an application that bridges the models and functionality of your application." — 原文

📖 "Conversely, Structured Outputs via response_format are more suitable when you want to indicate a structured schema for use when the model responds to the user, rather than when the model calls a tool." — 原文

flowchart TD
    A[需要结构化输出] --> B{输出流向?}
    B -->|接工具/函数/数据| C[function calling]
    B -->|直接回复用户| D[response_format / text.format]

📖 "Structured Outputs can be enabled by setting the parameter strict: true in an API call with either a defined response format or function definitions." — 原文

📖 "The new version of the SDK introduces a parse helper to provide your own Pydantic model instead of having to define the JSON schema. We recommend using this method if possible." — 原文

def get_math_solution(question: str):
    completion = client.beta.chat.completions.parse(
        model=MODEL,
        messages=[
            {"role": "system", "content": dedent(math_tutor_prompt)},
            {"role": "user", "content": question},
        ],
        response_format=MathReasoning,
    )
    return completion.choices[0].message

{
  "type": "object",
  "properties": {
    "explanation": {"type": "string"},
    "output": {"type": "string"}
  },
  "required": ["explanation", "output"],
  "additionalProperties": false
}

📖 "Since a refusal does not necessarily follow the schema you have supplied in response_format, the API response will include a new field called refusal to indicate that the model refused to fulfill the request." — 原文

📖 "Since a refusal does not follow the schema you have supplied in response_format, the API has a new field refusal to indicate when the model refused to answer." — 原文

for item in output.content:
    if item.type == "refusal":
        # If the model refuses to respond, you will get a refusal message
        print(item.refusal)
        continue

    if not item.parsed:
        raise Exception("Could not parse response")

    print(item.parsed)

📖 "Structured Outputs is available in our latest large language models, starting with GPT-4o." — 原文

📖 "Structured Outputs is only available with gpt-4o-mini , gpt-4o-2024-08-06, and future models." — 原文

MODEL = "gpt-4o-2024-08-06"

📖 "The model will always try to adhere to the provided schema, which can result in hallucinations if the input is completely unrelated to the schema." — 原文

📖 "Structured Outputs can still contain mistakes. If you see mistakes, try adjusting your instructions, providing examples in the system instructions, or splitting tasks into simpler subtasks." — 原文

📖 "If your application is using user-generated input, make sure your prompt includes instructions on how to handle situations where the input cannot result in a valid response." — 原文

📖 "To prevent your JSON Schema and corresponding types in your programming language from diverging, we strongly recommend using the native Pydantic/zod sdk support." — 原文

📖 "When using JSON mode, you must always instruct the model to produce JSON via some message in the conversation, for example via your system message. If you don't include an explicit instruction to generate JSON, the model may generate an unending stream of whitespace and the request may run continually until it reaches the token limit." — 原文

📖 "JSON mode will not guarantee the output matches any specific schema, only that it is valid and parses without errors." — 原文

{ "text": { "format": { "type": "json_object" } } }

📖 "We're not concerned about enforcing a schema at this step, we just want all of the data to be extracted regardless of type." — 原文

📖 "Not all of the data in the input JSON will fit the schema, so you may need to omit some data or add null values to the output JSON." — 原文

response = client.chat.completions.create(
    model="gpt-4o",
    response_format={ "type": "json_object" },
    messages=[ ... ],
    temperature=0.0,
)

📖 "Agents are applications that plan, call tools, collaborate across specialists, and keep enough state to complete multi-step work." — 原文

📖 "An agent is the core unit of an SDK-based workflow. It packages a model, instructions, and optional runtime behavior such as tools, guardrails, MCP servers, handoffs, and structured outputs." — 原文

flowchart LR
  A[Agent 规格] --> B[model]
  A --> C[instructions]
  A --> D[tools]
  A --> E[handoffs]
  A --> F[guardrails / MCP / outputType]
  A --> G[一次 run 复用同一规格]

📖 "Use the Responses API when you want to own the loop. Use the Agents SDK when you want the SDK to run it." — 原文

📖 "You want the SDK to manage the agent loop and recurring orchestration such as repeated tool calls or branching." — 原文

📖 "Start with one focused agent and one turn. The SDK handles the model call and returns a result object with the final output plus the run history." — 原文

📖 "You should see a concise answer in the terminal. Once that loop works, keep the same shape and add capabilities incrementally rather than starting with a large multi-agent design." — 原文

import { Agent, run } from "@openai/agents";

const agent = new Agent({
  name: "History tutor",
  instructions:
    "You answer history questions clearly and concisely.",
  model: "gpt-5.6",
});

const result = await run(agent, "When did the Roman Empire fall?");
console.log(result.finalOutput);

📖 "Use agent configuration for decisions that are intrinsic to that specialist:" — 原文

📖 "Define the smallest agent that can own a clear task. Add more agents only when you need separate ownership, different instructions, different tool surfaces, or different approval policies." — 原文

import { Agent, tool } from "@openai/agents";
import { z } from "zod";

const getWeather = tool({
  name: "get_weather",
  description: "Return the weather for a given city.",
  parameters: z.object({ city: z.string() }),
  async execute({ city }) {
    return `The weather in ${city} is sunny.`;
  },
});

const agent = new Agent({
  name: "Weather bot",
  instructions: "You are a helpful weather bot.",
  model: "gpt-5.6",
  tools: [getWeather],
});

📖 "Use when downstream code needs typed data rather than free-form prose." — 原文

📖 "Use prompt when you want to reference a stored prompt configuration from the Responses API instead of embedding the entire system prompt in code." — 原文

import asyncio

from pydantic import BaseModel

from agents import Agent, Runner


class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]


agent = Agent(
    name="Calendar extractor",
    instructions="Extract calendar events from text.",
    output_type=CalendarEvent,
)


async def main() -> None:
    result = await Runner.run(
        agent,
        "Dinner with Priya and Sam on Friday.",
    )
    print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())

📖 "The SDK lets you pass application state and dependencies into a run without sending them to the model. Use this for data like authenticated user info, database clients, loggers, and helper functions." — 原文

📖 "If the model needs a fact, put it in instructions, input, retrieval, or a tool. If only your runtime needs it, keep it in local context." — 原文

import { Agent, RunContext, run, tool } from "@openai/agents";
import { z } from "zod";

interface UserInfo {
  name: string;
  uid: number;
}

const fetchUserAge = tool({
  name: "fetch_user_age",
  description: "Return the age of the current user.",
  parameters: z.object({}),
  async execute(_args, runContext?: RunContext<UserInfo>) {
    return `User ${runContext?.context.name} is 47 years old`;
  },
});

const agent = new Agent<UserInfo>({
  name: "Assistant",
  tools: [fetchUserAge],
});

const result = await run(agent, "What is the age of the user?", {
  context: { name: "John", uid: 123 },
});

📖 "A common next step is to split the workflow into specialists and let a router delegate to them with handoffs." — 原文

import { Agent, run } from "@openai/agents";

const historyTutor = new Agent({
  name: "History tutor",
  instructions: "Answer history questions clearly and concisely.",
});

const mathTutor = new Agent({
  name: "Math tutor",
  instructions: "Explain math step by step and include worked examples.",
});

const triageAgent = Agent.create({
  name: "Homework triage",
  instructions: "Route each homework question to the right specialist.",
  handoffs: [historyTutor, mathTutor],
});

const result = await run(
  triageAgent,
  "Who was the first president of the United States?",
);

console.log(result.finalOutput);
console.log(result.lastAgent?.name);

📖 "Split an agent when one specialist shouldn't own the full reply or when separate capabilities are materially different." — 原文

📖 "You want explicit routing in traces rather than a single large prompt." — 原文

📖 "The first capability you add is often a function tool or a hosted OpenAI tool such as web search or file search." — 原文

📖 "Start with static instructions. When the guidance depends on the current user, tenant, or runtime context, switch to a dynamic instructions callback instead of stitching strings together at the call site." — 原文

import asyncio

from agents import Agent, Runner, function_tool


@function_tool
def history_fun_fact() -> str:
    """Return a short history fact."""
    return "Sharks are older than trees."


agent = Agent(
    name="History tutor",
    instructions="Answer history questions clearly. Use history_fun_fact when it helps.",
    tools=[history_fun_fact],
)

📖 "One SDK run is one application-level turn. The runner keeps looping until it reaches a real stopping point:" — 原文

📖 "That loop is the core concept behind the SDK. Tools, handoffs, approvals, and streaming all build on top of it rather than replacing it." — 原文

flowchart TD
  A[Call current agent's model with prepared input] --> B[Inspect the model output]
  B --> C{Tool calls?}
  C -->|yes| D[Execute tools and continue] --> A
  C -->|no| E{Handoff?}
  E -->|yes| F[Switch agents and continue] --> A
  E -->|no| G[Final answer, no more tool work] --> H[Return a result]

📖 "Multi-agent workflows are useful when specialists should own different parts of the job. The first design choice is deciding who owns the final user-facing answer at each branch of the workflow." — 原文

📖 "Handoffs are the clearest fit when a specialist should own the next response rather than merely helping behind the scenes." — 原文

import { Agent, handoff } from "@openai/agents";

const billingAgent = new Agent({ name: "Billing agent" });
const refundAgent = new Agent({ name: "Refund agent" });

const triageAgent = Agent.create({
  name: "Triage agent",
  handoffs: [billingAgent, handoff(refundAgent)],
});

📖 "In most applications, pick one strategy per conversation. Mixing local replay with server-managed state can duplicate context unless you are deliberately reconciling both layers." — 原文

📖 "Sessions are the best default when you want durable memory, resumable approval flows, or storage that your application controls." — 原文

import asyncio

from agents import Agent, Runner, SQLiteSession

agent = Agent(
    name="Tour guide",
    instructions="Answer with compact travel facts.",
)

session = SQLiteSession("conversation_123")


async def main() -> None:
    first_turn = await Runner.run(
        agent,
        "What city is the Golden Gate Bridge in?",
        session=session,
    )
    print(first_turn.final_output)

    second_turn = await Runner.run(
        agent,
        "What state is it in?",
        session=session,
    )
    print(second_turn.final_output)


if __name__ == "__main__":
    asyncio.run(main())

📖 "Multi-agent lets a model spin up and coordinate subagents in parallel, synthesizing their work to provide a final response." — 原文

📖 "Note that adding subagents can increase token usage, and may not be as beneficial for tasks that depend on a single ordered chain of reasoning, require frequent writes to shared mutable state, or are already dominated by one slow external operation." — 原文

from openai import OpenAI

client = OpenAI()


def review_pull_request(diff: str) -> str:
    response = client.beta.responses.create(
        model="gpt-5.6-sol",
        input=(
            "Review the pull-request diff below with three agents: one for "
            "correctness, one for security, and one for missing tests. "
            "Reconcile duplicate or conflicting findings, then return a "
            "prioritized review with file and line references.\n\n"
            f"<diff>\n{diff}\n</diff>"
        ),
        multi_agent={
            "enabled": True,
            "max_concurrent_subagents": 3,
        },
        betas=["responses_multi_agent=v1"],
    )

📖 "When Multi-agent mode is enabled, the Responses API provides six hosted collaboration actions. You may see these as multi_agent_call items. Your application should not execute these or submit outputs for them." — 原文

📖 "Handling developer-defined tool calls works in the same way as without Multi-agent enabled. Any agent in the tree may emit a function_call. Your application must execute the call and submit a matching function_call_output." — 原文

/root
├── /root/researcher
├── /root/reviewer
└── /root/reviewer/tester

📖 "HTTP and WebSocket support the same Multi-agent capabilities, but WebSocket is recommended for tool-heavy or long-running workflows. Its persistent connection lets your application return function outputs as they become available, reducing continuation overhead and allowing agents to spend less time waiting." — 原文

📖 "With HTTP, the response completes once every active agent has either finished or paused to wait for a client-executed function call." — 原文

{
  "type": "response.inject",
  "response_id": "resp_123",
  "input": [
    {
      "type": "function_call_output",
      "call_id": "call_123",
      "output": "{\"temperature\":72}"
    }
  ]
}

📖 "Treat approvals as paused runs, not as new turns. That distinction keeps turn counts, history, and server-managed continuation IDs consistent." — 原文

📖 "If the run pauses for approval, resolve interruptions and resume from state rather than starting a fresh user turn." — 原文

- Wait for the stream to finish before treating the run as settled.
- If the run pauses for approval, resolve `interruptions` and resume from `state` rather than starting a fresh user turn.
- If you cancel a stream mid-turn, resume the unfinished turn from `state` if you want the same turn to continue later.

📖 "When your application receives a multi_agent_call, do not execute it as a function call or send back a result. The Responses API executes the hosted action and returns the corresponding multi_agent_call_output. Preserve both items if your application needs them for replay or tracing." — 原文

📖 "Each item also includes an agent attribute. For an agent_message, agent.agent_name identifies the recipient agent. Use author and recipient to trace the message direction." — 原文

[
  {
    "type": "multi_agent_call",
    "id": "mac_123",
    "call_id": "call_spawn_a",
    "action": "spawn_agent",
    "arguments": "{\"task_name\":\"agent_a\",\"fork_turns\":\"all\",\"message\":\"enc_...\"}",
    "agent": { "agent_name": "/root" }
  },
  {
    "type": "multi_agent_call_output",
    "id": "maco_123",
    "call_id": "call_spawn_a",
    "action": "spawn_agent",
    "output": [
      {
        "type": "output_text",
        "text": "{\"task_name\":\"/root/agent_a\"}",
        "annotations": [],
        "logprobs": []
      }
    ],
    "agent": { "agent_name": "/root" }
  }
]

📖 "max_concurrent_subagents sets the maximum number of subagents that can be active simultaneously across the entire agent tree. It includes all descendants—children, grandchildren, and deeper subagents—but excludes the root agent." — 原文

📖 "When multi_agent.enabled is set to true, automatic server-side compaction is enabled implicitly, even if the request does not configure context_management. Compaction is applied independently to the root agent and each subagent, preserving their separate contexts." — 原文

{
  "multi_agent": {
    "enabled": true,
    "max_concurrent_subagents": 3
  }
}

📖 "Use guardrails for automatic checks and human review for approval decisions. Together, they define when a run should continue, pause, or stop." — 原文

📖 "Pause before side effects like cancellations, edits, shell commands, or sensitive MCP actions" — 原文

flowchart TD
  A[用户请求] --> B{Input guardrail}
  B -- tripwire 触发 --> X[拦截/停止]
  B -- 通过 --> C[主 Agent 运行]
  C --> D{是否敏感动作?}
  D -- 是 --> E[记录 approval interruption, 暂停]
  D -- 否 --> F{Output guardrail}
  E -- approve --> F
  E -- reject --> X
  F -- 通过 --> G[返回最终输出]

📖 "Use input guardrails when you want a fast validation step to run before the expensive or side-effecting part of the workflow starts." — 原文

📖 "Use blocking execution when the cost or risk of starting the main agent is too high. Use parallel guardrails when lower latency matters more than avoiding speculative work." — 原文

const agent = new Agent({
  name: "Customer support",
  instructions: "Help customers with support questions.",
  inputGuardrails: [
    {
      name: "Math homework guardrail",
      runInParallel: false,
      async execute({ input, context }) {
        const result = await run(guardrailAgent, input, { context });
        return {
          outputInfo: result.finalOutput,
          tripwireTriggered: result.finalOutput?.isMathHomework === true,
        };
      },
    },
  ],
});

try {
  await run(agent, "Can you solve 2x + 3 = 11 for me?");
} catch (error) {
  if (error instanceof InputGuardrailTripwireTriggered) {
    console.log("Guardrail blocked the request.");
  }
}

📖 "Approvals are the human-in-the-loop path for tool calls. The model can still decide that an action is needed, but the run pauses until you approve or reject it." — 原文

📖 "You resume the same run from state instead of starting a new user turn." — 原文

📖 "This same interruption pattern applies even when the approving tool lives deeper in the workflow, such as after a handoff or inside a nested call." — 原文

const cancelOrder = tool({
  name: "cancel_order",
  description: "Cancel a customer order.",
  parameters: z.object({ orderId: z.number() }),
  needsApproval: true,
  async execute({ orderId }) {
    return `Cancelled order ${orderId}`;
  },
});

let result = await run(agent, "Cancel order 123.");

if (result.interruptions?.length) {
  const state = result.state;
  for (const interruption of result.interruptions) {
    state.approve(interruption);
  }
  result = await run(agent, state);
}

📖 "Approval flows are the main case where a result is intentionally incomplete." — 原文

📖 "interruptions tells you which pending tool calls need a decision." — 原文

📖 "If the review might take time, serialize state, store it, and resume later. That's still the same run." — 原文

result = await Runner.run(agent, "Cancel order 123.")
if result.interruptions:
    state = result.to_state()
    # 把 state 序列化存起来,等审批决定到达后再从同一个 run 恢复
    for interruption in result.interruptions:
        state.approve(interruption)
    result = await Runner.run(agent, state)

📖 "Input guardrails run only for the first agent in the chain." — 原文

📖 "If you need checks around every custom tool call in a manager-style workflow, don't rely only on agent-level input or output guardrails. Put validation next to the tool that creates the side effect." — 原文

📖 "Tracing is built into the Agents SDK and is enabled by default in the normal server-side SDK path." — 原文

📖 "Every run can emit a structured record of model calls, tool calls, handoffs, guardrails, and custom spans, which you can inspect in the Traces dashboard." — 原文

📖 "If you need less tracing, use the SDK-level or per-run tracing controls rather than removing all observability from the workflow." — 原文

await withTrace("Joke workflow", async () => {
  const first = await run(agent, "Tell me a joke");
  const second = await run(agent, `Rate this joke: ${first.finalOutput}`);
  console.log(first.finalOutput);
  console.log(second.finalOutput);
});

📖 "Use hosted MCP tools when the remote server should run through the model surface." — 原文

📖 "Your runtime owns the connection, approvals, and network boundaries" — 原文

const agent = new Agent({
  name: "MCP assistant",
  instructions: "Use the MCP tools to answer questions.",
  tools: [
    hostedMcpTool({
      serverLabel: "gitmcp",
      serverUrl: "https://gitmcp.io/openai/codex",
    }),
  ],
});

📖 "Streaming doesn't create a separate approval system." — 原文

📖 "If a streamed run pauses, wait for it to settle, inspect interruptions, resolve the approvals, and resume from the same state." — 原文

📖 "Agent Builder is a visual canvas for building multi-step agent workflows." — 原文

📖 "A workflow is a combination of agents, tools, and control-flow logic. A workflow encapsulates all steps and actions involved in handling your tasks or powering your chats, with working code you can deploy when you're ready." — 原文

📖 "Deploy your workflow. Pass the ID into your ChatKit integration, or download the Agents SDK code to deploy your workflow yourself." — 原文

flowchart LR
    A[Design workflow
in Agent Builder] --> B[Publish
object with ID + versioning]
    B --> C{Deploy}
    C -->|Pass workflow ID| D[ChatKit integration]
    C -->|Download SDK code| E[Agents SDK self-host]

📖 "Trace grading is the fastest way to identify workflow-level issues. A trace captures the end-to-end record of model calls, tool calls, guardrails, and handoffs for one run." — 原文

📖 "Once you know what “good” looks like, move from individual traces to repeatable datasets and eval runs. This is the right step when you want to benchmark changes, compare prompts, or run larger-scale evaluations over time." — 原文

1. Open Logs > Traces in the dashboard.
2. Inspect a representative workflow trace (SDK app or Agent Builder workflow).
3. Create a grader and run it against the selected traces.
4. Refine prompts, tool surfaces, routing logic, or guardrails.

📖 "A prompt injection happens when untrusted text or data enters an AI system, and malicious contents in that text or data attempt to override instructions to the AI." — 原文

📖 "It's possible for a model to leak private data in a way that's not intended, without an attacker behind it. For example, a model may send more data to an MCP than the user expected or intended." — 原文

📖 "While guardrails provide better control to limit the information included in context, you don't have full control over what the model chooses to share with connected MCPs." — 原文

📖 "Because developer messages take precedence over user and assistant messages, injecting untrusted input directly into developer messages gives attackers the highest degree of control. Pass untrusted inputs through user messages to limit their influence." — 原文

📖 "By defining structured outputs between nodes (e.g., enums, fixed schemas, required field names), you eliminate freeform channels that attackers can exploit to smuggle instructions or data." — 原文

📖 "When using MCP tools, always enable tool approvals so end users can review and confirm every operation, including reads and writes." — 原文

- Design workflows so untrusted data never directly drives agent behavior.
- Extract only specific structured fields (enums / validated JSON) from external inputs.
- Use guardrails, tool confirmations, and variables passed via user messages to validate inputs.
- 但:Structured outputs and isolation greatly reduce, but don't fully remove, this risk.

📖 "In Agent Builder, insert and connect nodes to create your workflow. Each connection between nodes becomes a typed edge. Click a node to configure its inputs and outputs, observe the data contract between steps, and ensure downstream nodes receive the properties they expect." — 原文

📖 "Here, you can interactively run your workflow, attach sample files, and observe the execution of each node." — 原文

flowchart LR
    Q[接收问题 agent] -->|typed edge: question| R[重新措辞 agent]
    R -->|typed edge: reframed| RT[路由 agent]
    RT -->|typed edge: routed| S[专门 agent → 返回答案]

📖 "When you're happy with your workflow, publish it to create a new major version that acts as a snapshot." — 原文

📖 "You can create new versions or specify an older version in your API calls." — 原文

📖 "Advanced integration: Copy the workflow code and use it anywhere. You can run ChatKit on your own infrastructure and use the Agents SDK to build and customize agent chat experiences." — 原文

📖 "OpenAI’s text embeddings measure the relatedness of text strings." — 原文

📖 "An embedding is a vector (list) of floating point numbers." — 原文

📖 "Small distances suggest high relatedness and large distances suggest low relatedness." — 原文

flowchart LR
  T1["文本 A: delicious beans"] --> E1["向量 A"]
  T2["文本 B: 这些豆子味道很棒"] --> E2["向量 B"]
  T3["文本 C: bad delivery"] --> E3["向量 C"]
  E1 -- 距离小/相关性高 --> E2
  E1 -- 距离大/相关性低 --> E3

📖 "The response contains the embedding vector (list of floating point numbers) along with some additional metadata. You can extract the embedding vector, save it in a vector database, and use for many different use cases." — 原文

from openai import OpenAI
client = OpenAI()

response = client.embeddings.create(
    input="Your text string goes here",
    model="text-embedding-3-small"
)

print(response.data[0].embedding)

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        -0.006929283495992422, -0.005336422007530928, -4.547132266452536e-5,
        -0.024047505110502243
      ]
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 5,
    "total_tokens": 5
  }
}

📖 "By default, the length of the embedding vector is 1536 for text-embedding-3-small or 3072 for text-embedding-3-large." — 原文

📖 "on the MTEB benchmark, a text-embedding-3-large embedding can be shortened to a size of 256 while still outperforming an unshortened text-embedding-ada-002 embedding with a size of 1536." — 原文

📖 "In general, using the dimensions parameter when creating the embedding is the suggested approach." — 原文

from openai import OpenAI
import numpy as np

client = OpenAI()

def normalize_l2(x):
    x = np.array(x)
    if x.ndim == 1:
        norm = np.linalg.norm(x)
        if norm == 0:
            return x
        return x / norm
    else:
        norm = np.linalg.norm(x, 2, axis=1, keepdims=True)
        return np.where(norm == 0, x, x / norm)


response = client.embeddings.create(
    model="text-embedding-3-small", input="Testing 123", encoding_format="float"
)

cut_dim = response.data[0].embedding[:256]
norm_dim = normalize_l2(cut_dim)

print(norm_dim)

📖 "We recommend cosine similarity. The choice of distance function typically doesn't matter much." — 原文

📖 "Cosine similarity can be computed slightly faster using just a dot product" — 原文

📖 "Cosine similarity and Euclidean distance will result in the identical rankings" — 原文

import numpy as np
# 向量已 normalized to length 1，故 cosine == dot product
def cosine_similarity(a, b):
    return np.dot(a, b)

📖 "We can search through all our reviews semantically in a very efficient manner and at very low cost, by embedding our search query, and then finding the most similar reviews." — 原文

📖 "Here we compare the cosine similarity of the embeddings of the query and the documents, and show top_n best matches." — 原文

📖 "To retrieve the most relevant documents we use the cosine similarity between the embedding vectors of the query and each document, and return the highest scored documents." — 原文

from utils.embeddings_utils import get_embedding, cosine_similarity

# search through the reviews for a specific product
def search_reviews(df, product_description, n=3, pprint=True):
    product_embedding = get_embedding(
        product_description,
        model="text-embedding-3-small"
    )
    df["similarity"] = df.embedding.apply(lambda x: cosine_similarity(x, product_embedding))

    results = (
        df.sort_values("similarity", ascending=False)
        .head(n)
        .combined.str.replace("Title: ", "")
        .str.replace("; Content:", ": ")
    )
    if pprint:
        for r in results:
            print(r[:200])
            print()
    return results


results = search_reviews(df, "delicious beans", n=3)

📖 "OpenAI offers two powerful third-generation embedding model (denoted by -3 in the model ID)." — 原文

📖 "Usage is priced per input token." — 原文

| Model                  | ~ Pages per dollar | MTEB   | Max input |
| text-embedding-3-small | 62,500             | 62.3%  | 8192      |
| text-embedding-3-large | 9,615              | 64.6%  | 8192      |
| text-embedding-ada-002 | 12,500             | 61.0%  | 8192      |

📖 "In Python, you can split a string into tokens with OpenAI's tokenizer tiktoken." — 原文

📖 "For third-generation embedding models like text-embedding-3-small, use the cl100k_base encoding." — 原文

import tiktoken

def num_tokens_from_string(string: str, encoding_name: str) -> int:
    """Returns the number of tokens in a text string."""
    encoding = tiktoken.get_encoding(encoding_name)
    num_tokens = len(encoding.encode(string))
    return num_tokens

num_tokens_from_string("tiktoken is great!", "cl100k_base")

📖 "For searching over many vectors quickly, we recommend using a vector database." — 原文

📖 "We can search through these reviews easily. To speed up computation, we can use a special algorithm, aimed at faster search through embeddings." — 原文

📖 "No, the text-embedding-3-large and text-embedding-3-small models lack knowledge of events that occurred after September 2021." — 原文

📖 "Yes, customers own their input and output from our models, including in the case of embeddings." — 原文

- 涉及"2021-09 之后的新事件/新实体"检索 → 语义相关性通常够用，但极端情况可能掉点
- 想公开分享向量数据集       → 允许（数据归客户），但需自查是否违反法律/Terms of Use

📖 "It enables models to retrieve information in a knowledge base of previously uploaded files through semantic and keyword search." — 原文

📖 "This is a hosted tool managed by OpenAI, meaning you don't have to implement code on your end to handle its execution." — 原文

from openai import OpenAI
client = OpenAI()

response = client.responses.create(
    model="gpt-5.6",
    input="What is deep research by OpenAI?",
    tools=[{
        "type": "file_search",
        "vector_store_ids": ["<vector_store_id>"]
    }]
)
print(response)

📖 "When you add a file to a vector store it will be automatically chunked, embedded, and indexed." — 原文

📖 "Vector stores contain vector_store_file objects, which are backed by a file object." — 原文

from openai import OpenAI
client = OpenAI()

vector_store = client.vector_stores.create(        # Create vector store
    name="Support FAQ",
)

client.vector_stores.files.upload_and_poll(        # Upload file
    vector_store_id=vector_store.id,
    file=open("customer_policies.txt", "rb")
)

📖 "Importantly, this includes results with few or no shared keywords, which classical search techniques might miss." — 原文

📖 "Notice how the most relevant result contains none of the words in the search query." — 原文

results = client.vector_stores.search(
    vector_store_id=vector_store.id,
    query="How many woodchucks are allowed per passenger?",
)

📖 "By default, max_chunk_size_tokens is set to 800 and chunk_overlap_tokens is set to 400, meaning every file is indexed by being split up into 800-token chunks, with 400-token overlap between consecutive chunks." — 原文

📖 "chunk_overlap_tokens must be non-negative and should not exceed max_chunk_size_tokens / 2." — 原文

client.vector_stores.file_batches.create_and_poll(
    vector_store_id="vs_123",
    files=[
        {
            "file_id": "file_456",
            "chunking_strategy": {
                "type": "static",
                "max_chunk_size_tokens": 1200,
                "chunk_overlap_tokens": 200
            }
        }
    ]
)

📖 "When ranking_options.hybrid_search is provided you can also tune hybrid_search.embedding_weight (rrf_embedding_weight) and hybrid_search.text_weight (rrf_text_weight) to control how reciprocal rank fusion balances semantic embedding matches vs. sparse keyword matches." — 原文

📖 "They all have different relevancy score that are calculated by our ranker which uses hybrid search." — 原文

for result in search_results.data:
    print(str(len(result.content[0].text)) + ' of character of content from ' + result.filename + ' with a relevant score of ' + str(result.score))
# ... with a relevant score of 0.9813588865322393
# ... with a relevant score of 0.9522476825143714

flowchart LR
    Q[query] --> E[语义 embedding 匹配]
    Q --> K[稀疏关键词匹配]
    E -->|embedding_weight| RRF[Reciprocal Rank Fusion]
    K -->|text_weight| RRF
    RRF --> R[按 score 排序 · score_threshold 过滤]

📖 "Attribute filtering helps narrow down results by applying criteria, such as restricting searches to a specific date range." — 原文

📖 "The dictionary can have at most 16 keys, with a limit of 256 characters each." — 原文

response = client.responses.create(
    model="gpt-5.6",
    input="What is deep research by OpenAI?",
    tools=[{
        "type": "file_search",
        "vector_store_ids": ["<vector_store_id>"],
        "filters": {
            "type": "in",
            "key": "category",
            "value": ["blog", "announcement"]
        }
    }]
)

📖 "This can help reduce both token usage and latency, but may come at the cost of reduced answer quality." — 原文

📖 "While you can see annotations (references to files) in the output text, the file search call will not return search results by default." — 原文

response = client.responses.create(
    model="gpt-5.6",
    input="What is deep research by OpenAI?",
    tools=[{
        "type": "file_search",
        "vector_store_ids": ["<vector_store_id>"],
        "max_num_results": 2
    }],
    include=["file_search_call.results"]
)

📖 "This is where file search — a hosted tool you can use in the Responses API — comes in. It allows you to search your knowledge base and generate an answer based on the retrieved content." — 原文

📖 "By using file search with Responses, you can simplify RAG architecture and leverage this in a single API call using the new Responses API. File storage, embeddings, retrieval all integrated in one tool!" — 原文

query = "What's Deep Research?"
response = client.responses.create(
    input= query,
    model="gpt-4o-mini",
    tools=[{
        "type": "file_search",
        "vector_store_ids": [vector_store_details['id']],
    }]
)
annotations = response.output[1].content[0].annotations
retrieved_files = set([result.filename for result in annotations])
print(f'Files used: {retrieved_files}')

flowchart LR
    subgraph 传统RAG[传统 RAG · 多步]
      P[解析PDF] --> C[切块] --> U[上传存储] --> Emb[跑embedding] --> V[存向量库] --> Ret[检索] --> G1[生成]
    end
    subgraph FS[file search · 单次调用]
      Q2[Responses.create + file_search] --> A2[grounded 答案 + 引用]
    end

📖 "What is key for those information retrieval system is to also measure the relevance & quality of files retrieved for those answers." — 原文

📖 "Recall & Precision are at 1 for this example, and our file ranked first so we're having a MRR and MAP = 1 on this example." — 原文

retrieved_files = [result.filename for result in annotations[:k]]
if expected_filename in retrieved_files:
    rank = retrieved_files.index(expected_filename) + 1
    rr = 1 / rank
    correct = True
else:
    rr = 0
    correct = False

📖 "Rate limits use metrics such as RPM (requests per minute), RPD (requests per day), TPM (tokens per minute), TPD (tokens per day), IPM (images per minute), and audio minutes per minute for some streaming audio models. Rate limits can be hit across any of the options depending on what occurs first." — 原文

📖 "For example, you might send 20 requests with only 100 tokens to the ChatCompletions endpoint and that would fill your limit (if your RPM was 20), even if you didn't send 150k tokens (if your TPM limit was 150k) within those 20 requests." — 原文

# request a bunch of completions in a loop
for _ in range(100):
    client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Hello"}],
        max_tokens=10,
    )

flowchart TD
    A[发起请求] --> B{RPM 已满?}
    B -->|是| E[429 限流]
    B -->|否| C{TPM 已满?}
    C -->|是| E
    C -->|否| D[正常处理]

📖 "One easy way to avoid rate limit errors is to automatically retry requests with a random exponential backoff. Retrying with exponential backoff means performing a short sleep when a rate limit error is hit, then retrying the unsuccessful request. If the request is still unsuccessful, the sleep length is increased and the process is repeated. This continues until the request is successful or until a maximum number of retries is reached." — 原文

📖 "Adding random jitter to the delay helps retries from all hitting at the same time." — 原文

📖 "Note that unsuccessful requests contribute to your per-minute limit, so continuously resending a request won’t work." — 原文

from tenacity import (
    retry,
    stop_after_attempt,
    wait_random_exponential,
)  # for exponential backoff

@retry(wait=wait_random_exponential(min=1, max=60), stop=stop_after_attempt(6))
def completion_with_backoff(**kwargs):
    return client.chat.completions.create(**kwargs)


completion_with_backoff(model="gpt-4o-mini", messages=[{"role": "user", "content": "Once upon a time,"}])

📖 "This error message indicates that you have hit your assigned rate limit for the API. This means that you have submitted too many tokens or requests in a short period of time and have exceeded the number of requests allowed." — 原文

📖 "This error message indicates that you hit your monthly usage limit for the API, or for prepaid credits customers that you've consumed all your credits." — 原文

import openai
from openai import OpenAI
client = OpenAI()

try:
  #Make your OpenAI API request here
  response = client.responses.create(
    model="gpt-5.6",
    input="Hello world"
  )
except openai.APIError as e:
  #Handle API error here, e.g. retry or log
  print(f"OpenAI API returned an API Error: {e}")
  pass
except openai.APIConnectionError as e:
  #Handle connection error here
  print(f"Failed to connect to OpenAI API: {e}")
  pass
except openai.RateLimitError as e:
  #Handle rate limit error (we recommend using exponential backoff)
  print(f"OpenAI API request exceeded rate limit: {e}")
  pass

📖 "In addition to seeing your rate limit on your account page, you can also view important information about your rate limits such as the remaining requests, tokens, and other metadata in the headers of the HTTP response." — 原文

📖 "Project-token headers may be present when a project-scoped token limit applies." — 原文

x-ratelimit-limit-requests           60
x-ratelimit-limit-tokens             150000
x-ratelimit-remaining-requests       59
x-ratelimit-remaining-tokens         149984
x-ratelimit-reset-requests           1s
x-ratelimit-reset-tokens             6m0s

📖 "Your rate limit is calculated as the maximum of max_tokens and the estimated number of tokens based on the character count of your request. Try to set the max_tokens value as close to your expected response size as possible." — 原文

📖 "If you set max_tokens too high, your usage can be overestimated, even if the actual response is much shorter." — 原文

def completions_with_max_tokens(**kwargs):
    return client.chat.completions.create(**kwargs)


completions_with_max_tokens(model="gpt-4o-mini", messages=[{"role": "user", "content": "Once upon a time,"}], max_tokens=100)

📖 "The OpenAI API enforces separate limits for requests per minute/day (RPM/RPD) and tokens per minute (TPM). If you’re hitting RPM limits but still have available TPM capacity, consider batching multiple tasks into each request." — 原文

📖 "If you're hitting the limit on requests per minute but have available capacity on tokens per minute, you can increase your throughput by batching multiple tasks into each request." — 原文

from pydantic import BaseModel

# Define the Pydantic model for the structured output
class StoryResponse(BaseModel):
    stories: list[str]
    story_count: int

📖 "If you encounter rate limit errors on your primary model, one option is to switch to a secondary model. This approach helps keep your application responsive when your primary model is throttled or unavailable." — 原文

📖 "Additionally, keep in mind that some models share rate limits, which may reduce the effectiveness of simply switching models." — 原文

def completions_with_fallback(fallback_model, **kwargs):
    try:
        return client.chat.completions.create(**kwargs)
    except openai.RateLimitError:
        kwargs['model'] = fallback_model
        return client.chat.completions.create(**kwargs)
    
    
completions_with_fallback(fallback_model="gpt-4o", model="gpt-4o-mini", messages=[{"role": "user", "content": "Once upon a time,"}])

📖 "Here, one potential solution is to calculate your rate limit and add a delay equal to its reciprocal (e.g., if your rate limit 20 requests per minute, add a delay of 3–6 seconds to each request). This can help you operate near the rate limit ceiling without hitting it and incurring wasted requests." — 原文

📖 "If you're processing real-time requests from users, backoff and retry is a great strategy to minimize latency while avoiding rate limit errors." — 原文

import time

# Define a function that adds a delay to a Completion API call
def delayed_completion(delay_in_seconds: float = 1, **kwargs):
    """Delay a completion by a specified amount of time."""

    # Sleep for the delay
    time.sleep(delay_in_seconds)

    # Call the Completion API and return the result
    return client.chat.completions.create(**kwargs)


# Calculate the delay based on your rate limit
rate_limit_per_minute = 20
delay = 60.0 / rate_limit_per_minute

📖 "By storing frequently accessed data, you can improve response times without needing to make repeated calls to our API." — 原文

📖 "Avoid exposing the API keys in your code or in public repositories; instead, store them in a secure location." — 原文

[扩容]   水平扩展 + 负载均衡(LB / DNS round-robin);对高频数据加缓存
[密钥]   不写进代码/公开仓库;用环境变量或密钥管理服务注入
[组织]   staging 与 production 拆成独立 project,各设速率与花费上限
[成本]   按 token 数 × 单价框架优化;设 usage 通知阈值
[MLOps]  数据/模型管理、监控、再训练、部署自动化

📖 "Although fine-tuning can feel like the more natural option—training on data is how GPT learned all of its other knowledge, after all—we generally do not recommend it as a way to teach the model knowledge. Fine-tuning is better suited to teaching specialized tasks or styles, and is less reliable for factual recall." — 原文

📖 "In contrast, message inputs are like short-term memory. When you insert knowledge into a message, it's like taking an exam with open notes. With notes in hand, the model is more likely to arrive at correct answers." — 原文

📖 "This notebook demonstrates a two-step Search-Ask method for enabling GPT to answer questions using a library of reference text." — 原文

📖 "Because GPT models are more expensive than embeddings search, a system with a decent volume of queries will have its costs dominated by step 3." — 原文

flowchart LR
  subgraph Prepare[准备阶段 · 每文档一次]
    A[Collect 下载文章] --> B[Chunk 分块]
    B --> C[Embed 生成向量]
    C --> D[Store CSV/向量库]
  end
  subgraph Query[查询阶段 · 每次提问]
    Q[用户问题] --> E[query embedding]
    E --> F[Search 按相关度排序]
    D --> F
    F --> G[Ask 拼接片段送 GPT]
    G --> H[返回答案]
  end

📖 "Embeddings are simple to implement and work especially well with questions, as questions often don't lexically overlap with their answers." — 原文

📖 "Q&A retrieval performance may also be improved with techniques like HyDE, in which questions are first transformed into hypothetical answers before being embedded." — 原文

📖 "Uses distance between query embedding and text embeddings to rank the texts" — 原文

# search function
def strings_ranked_by_relatedness(
    query: str,
    df: pd.DataFrame,
    relatedness_fn=lambda x, y: 1 - spatial.distance.cosine(x, y),
    top_n: int = 100
) -> tuple[list[str], list[float]]:
    """Returns a list of strings and relatednesses, sorted from most related to least."""
    query_embedding_response = client.embeddings.create(
        model=EMBEDDING_MODEL,
        input=query,
    )
    query_embedding = query_embedding_response.data[0].embedding
    strings_and_relatednesses = [
        (row["text"], relatedness_fn(query_embedding, row["embedding"]))
        for i, row in df.iterrows()
    ]
    strings_and_relatednesses.sort(key=lambda x: x[1], reverse=True)
    strings, relatednesses = zip(*strings_and_relatednesses)
    return strings[:top_n], relatednesses[:top_n]

📖 "Because GPT can only read a limited amount of text at once, we'll split each document into chunks short enough to be read." — 原文

📖 "Here, we'll use a simple approach and limit sections to 1,600 tokens each, recursively halving any sections that are too long. To avoid cutting in the middle of useful sentences, we'll split along paragraph boundaries when possible." — 原文

📖 "Longer sections may be worse for retrieval, as they may have more topics muddled together" — 原文

📖 "Return a message for GPT, with relevant source texts pulled from a dataframe." — 原文

def num_tokens(text: str, model: str = GPT_MODELS[0]) -> int:
    """Return the number of tokens in a string."""
    encoding = tiktoken.encoding_for_model(model)
    return len(encoding.encode(text))


def query_message(
    query: str,
    df: pd.DataFrame,
    model: str,
    token_budget: int
) -> str:
    """Return a message for GPT, with relevant source texts pulled from a dataframe."""
    strings, relatednesses = strings_ranked_by_relatedness(query, df)
    introduction = 'Use the below articles on the 2022 Winter Olympics to answer the subsequent question. If the answer cannot be found in the articles, write "I could not find an answer."'
    question = f"\n\nQuestion: {query}"
    message = introduction
    for string in strings:
        next_article = f'\n\nWikipedia article section:\n"""\n{string}\n"""'
        if (
            num_tokens(message + next_article + question, model=model)
            > token_budget
        ):
            break
        else:
            message += next_article
    return message + question

📖 "Embeddings are saved in a CSV file (for large datasets, use a vector database)" — 原文

📖 "(For larger datasets, use a vector database, which will be more performant.)" — 原文

EMBEDDING_MODEL = "text-embedding-3-small"
BATCH_SIZE = 1000  # you can submit up to 2048 embedding inputs per request

embeddings = []
for batch_start in range(0, len(wikipedia_strings), BATCH_SIZE):
    batch_end = batch_start + BATCH_SIZE
    batch = wikipedia_strings[batch_start:batch_end]
    print(f"Batch {batch_start} to {batch_end-1}")
    response = client.embeddings.create(model=EMBEDDING_MODEL, input=batch)
    for i, be in enumerate(response.data):
        assert i == be.index  # double check embeddings are in same order as input
    batch_embeddings = [e.embedding for e in response.data]
    embeddings.extend(batch_embeddings)

df = pd.DataFrame({"text": wikipedia_strings, "embedding": embeddings})

📖 "In case we get any mistakes in the output, we can see whether a mistake is from a lack of relevant source text (i.e., failure of the search step) or a lack of reasoning reliability (i.e., failure of the ask step), you can look at the text GPT was given by setting print_message=True." — 原文

📖 "In general, search-based systems do best on questions that have a simple lookup, and worst on questions that require multiple partial sources to be combined and reasoned about." — 原文

📖 "In this text classification task, we predict the score of a food review (1 to 5) based on the embedding of the review's text." — 原文

📖 "For many text classification tasks, we've seen fine-tuned models do better than embeddings." — 原文

📖 "We can see that the model has learnt to distinguish between the categories decently. 5-star reviews show the best performance overall, and this is not too surprising, since they are the most common in the dataset." — 原文

# split data into train and test
X_train, X_test, y_train, y_test = train_test_split(
    list(df.embedding.values), df.Score, test_size=0.2, random_state=42
)

# train random forest classifier
clf = RandomForestClassifier(n_estimators=100)
clf.fit(X_train, y_train)
preds = clf.predict(X_test)

flowchart LR
    A[原始文本/非结构化数据] --> B[OpenAI embeddings 向量化]
    B --> C[灌入向量库建索引]
    D[用户 query] --> E[同模型向量化]
    E --> F[相似度检索 top_k]
    C --> F
    F --> G[取回最近邻结果]

📖 "A vector database is a database made to store, manage and search embedding vectors." — 原文

📖 "Many of our customers make embeddings solve their problems at small scale but performance and security hold them back from going into production - we see vector databases as a key component in solving that, and in this guide we'll walk through the basics of embedding text data, storing it in a vector database and using it for semantic search." — 原文

EMBEDDING_MODEL = "text-embedding-3-small"

embeddings_url = 'https://cdn.openai.com/API/examples/data/vector_database_wikipedia_articles_embedded.zip'
# The file is ~700 MB so this will take some time
wget.download(embeddings_url)

flowchart TD
    subgraph Pinecone
      P[index: wikipedia-articles] --> P1[namespace: title]
      P --> P2[namespace: content]
    end
    subgraph Weaviate
      W[schema/class: Article] --> W1[property: title + vector]
      W --> W2[property: content]
    end
    subgraph Qdrant
      Q[collection: Articles] --> Q1[named vector: title]
      Q --> Q2[named vector: content]
      Q --> Q3[payload: id/title/url]
    end

📖 "We'll create an index with namespaces for __titles__ and __content__" — 原文

📖 "In Weaviate you create __schemas__ to capture each of the entities you will be searching." — 原文

📖 "Qdrant stores data in __collections__ where each object is described by at least one vector and may contain an additional metadata called __payload__." — 原文

qdrant.recreate_collection(
    collection_name='Articles',
    vectors_config={
        'title': rest.VectorParams(
            distance=rest.Distance.COSINE,
            size=vector_size,
        ),
        'content': rest.VectorParams(
            distance=rest.Distance.COSINE,
            size=vector_size,
        ),
    }
)

📖 "Once we have an index, we can create multiple namespaces, which can make a single index searchable for various use cases." — 原文

📖 "If you want to batch insert to your index in parallel to increase insertion speed then there is a great guide in the Pinecone documentation on batch inserts in parallel." — 原文

pinecone.create_index(name=index_name, dimension=len(article_df['content_vector'][0]))
index = pinecone.Index(index_name=index_name)

for batch_df in df_batcher(article_df):
    index.upsert(vectors=zip(batch_df.vector_id, batch_df.content_vector), namespace='content')

for batch_df in df_batcher(article_df):
    index.upsert(vectors=zip(batch_df.vector_id, batch_df.title_vector), namespace='title')

📖 "In this cookbook, we provide the data with already generated vectors. This is a good approach for scenarios, where your data is already vectorized." — 原文

📖 "Weaviate offers a built-in module text2vec-openai, which takes care of the vectorization for you at:" — 原文

article_schema = {
    "class": "Article",
    "description": "A collection of articles",
    "vectorizer": "text2vec-openai",
    "moduleConfig": {
        "text2vec-openai": {
          "model": "ada",
          "modelVersion": "002",
          "type": "text"
        }
    },
    "properties": [{
        "name": "title",
        "description": "Title of the article",
        "dataType": ["string"]
    },
    {
        "name": "content",
        "description": "Contents of the article",
        "dataType": ["text"],
        "moduleConfig": { "text2vec-openai": { "skip": True } }
    }]
}
client.schema.create_class(article_schema)

📖 "You need to declare the vector size and distance metric for the collection. Distance metric enables vector database to index and search vectors efficiently." — 原文

📖 "Payload is an optional field that allows you to store additional metadata alongside the vectors." — 原文

qdrant.upsert(
    collection_name='Articles',
    points=[
        PointStruct(
            id=k,
            vector={'title': v['title_vector'],
                    'content': v['content_vector']},
            payload={
                'id': v['id'],
                'title': v['title'],
                'url': v['url']
            }
        )
    ]
)

📖 "We may provide an additional parameter vector_name to switch from title to content based search." — 原文

📖 "This allows you to run a vector query with the with_near_text filter, which uses your OPEN_API_KEY." — 原文

def query_qdrant(query, collection_name, vector_name='title', top_k=20):
    embedded_query = openai.embeddings.create(
        input=query,
        model=EMBEDDING_MODEL,
    ).data[0].embedding
    query_results = qdrant.search(
        collection_name=collection_name,
        query_vector=(
            vector_name, embedded_query
        ),
        limit=top_k,
        query_filter=None
    )
    return query_results

nearText = {
    "concepts": [query],
    "distance": 0.7,
}
query_result = (
    client.query
    .get(collection_name, properties)
    .with_near_text(nearText)
    .with_limit(20)
    .do()
)

📖 "The next option we'll look at is Pinecone, a managed vector database which offers a cloud-native option." — 原文

📖 "Another vector database option we'll explore is Weaviate, which offers both a managed, SaaS option, as well as a self-hosted open source option." — 原文

📖 "It offers both on-premise and cloud version, but for the purposes of that example we're going to use the local deployment mode." — 原文

docker compose up -d

qdrant = qdrant_client.QdrantClient(host="localhost", port=6333)
qdrant.get_collections()

📖 "By combining these approaches, and drawing inspiration from re-ranking methods, we identify an approach that sits in the middle." — 原文

📖 "This hybrid approach offers relatively low latency and can be integrated into any existing search endpoint, without requiring the upkeep of a vector database." — 原文

flowchart LR
  U[用户提问] --> G[GPT 生成多条查询]
  G --> S[并行调用 Search API
over-fetch]
  S --> H[生成 hypothetical answer]
  H --> E[对结果 + 假设答案算 embedding]
  E --> R[按语义相似度排序 + 过滤]
  R --> A[top 结果作上下文 → 生成带引用答案]

📖 "A faster approach is embeddings-based search, in which an embedding is computed once for each document and query, and then re-used multiple times to cheaply compute pairwise relevance." — 原文

📖 "Although embeddings-based search is faster, the quality can be worse." — 原文

📖 "Cross-encoders are more accurate than bi-encoders but they don't scale well, so using them to re-order a shortened list returned by semantic search is the ideal use case." — 原文

纯 cross-encoder:   cost ~ D * Q          (精度高, 不 scale)
纯 bi-encoder:      cost ~ D + Q          (快, 精度可能差)
混合 (先 bi 后 cross): (D + Q) * embed + (N * Q) * rerank

📖 "Add a ``logit bias` for the tokens for ` Yes` and ` No`` to decrease the likelihood of any other tokens occurring." — 原文

📖 "Rerank the results by the ``logprobs` keyed on ` Yes``." — 原文

📖 "Make your examples domain-specific - the strength of cross-encoders comes when you tailor them to your domain." — 原文

prompt = '''
You are an Assistant responsible for helping detect whether the retrieved document is relevant to the query. For a given input, you need to output a single token: "Yes" or "No" indicating the retrieved document is relevant to the query.
...
'''
response = openai.chat.completions.create(
    model=OPENAI_MODEL,
    prompt=prompt.format(query=query, document=content),
    temperature=0,
    logprobs=1,
    logit_bias={3363: 1, 1400: 1},
    max_tokens=1,
)

📖 "Drawing inspiration from HyDE (Gao et al.), we first generate a hypothetical ideal answer to rerank our compare our results against." — 原文

📖 "This helps prioritize results that look like good answers, rather than those similar to our question." — 原文

📖 "Note that we can simply calculate the dot product in lieu of doing a full cosine similarity calculation since the OpenAI embeddings are returned normalized in our API." — 原文

Generate a hypothetical answer to the user's question. This answer will be used to rank search results.
Pretend you have all the information you need to answer, but don't use any actual facts. Instead, use placeholders
like NAME did something, or NAME said something at PLACE.

📖 "Now, in order to be as exhaustive as possible, we use the model to generate a list of diverse queries based on this question." — 原文

📖 "Include as many queries as you can think of, including and excluding terms." — 原文

QUERIES_INPUT = f"""
You have access to a search API that returns recent news articles.
Generate an array of search queries that are relevant to this question.
Use a variation of related keywords for the queries, trying to be as general as possible.
Include as many queries as you can think of, including and excluding terms.
...
User question: {USER_QUESTION}
Format: {{"queries": ["query_1", "query_2", "query_3"]}}
"""
queries = json_gpt(QUERIES_INPUT)["queries"]
queries.append(USER_QUESTION)  # 把原问题也加进去

📖 "This notebook shows how to leverage GPT-4o to turn rich PDF documents such as slide decks or exports from web pages into usable content for your RAG application." — 原文

📖 "After converting a PDF file to multiple images, we'll use GPT-4o to analyze the content based on the images." — 原文

📖 "You will be provided with an image of a PDF page or a slide. Your goal is to deliver a detailed and engaging presentation about the content you see, using clear and accessible language suitable for a 101-level audience." — 原文

def get_img_uri(img):
    png_buffer = io.BytesIO()
    img.save(png_buffer, format="PNG")
    png_buffer.seek(0)
    base64_png = base64.b64encode(png_buffer.read()).decode('utf-8')
    data_uri = f"data:image/png;base64,{base64_png}"
    return data_uri

📖 "Before embedding the content, we will chunk it logically by page." — 原文

📖 "That way, each independent chunk can be in context" — 原文

# 原文按页 embedding 的分块思路:把整篇内容按页分隔符切成 chunk,再逐块嵌入
# 优化方向(原文建议):
# - 切成更小的片段
# - 在每块开头拼上 slide 标题 / deck 标题 / 文档描述,让 chunk 自带上下文
chunk = f"{deck_title} — {slide_title}\n{page_text}"

📖 "The last step of the process is to generate outputs in response to input queries, after retrieving content as context to reply." — 原文

📖 "First, you will internally assess whether the content provided is relevant to reply to the input prompt." — 原文

📖 "If the content is not relevant, use your own knowledge to reply or say that you don't know how to respond if your knowledge is not sufficient to answer." — 原文

def search_content(df, input_text, top_k):
    embedded_value = get_embeddings(input_text)
    df["similarity"] = df.embeddings.apply(
        lambda x: cosine_similarity(np.array(x).reshape(1,-1),
                                    np.array(embedded_value).reshape(1,-1)))
    res = df.sort_values('similarity', ascending=False).head(top_k)
    return res

def generate_output(input_prompt, similar_content, threshold=0.5):
    content = similar_content.iloc[0]['content']
    # 相似度高于阈值才追加更多匹配内容作为上下文
    ...

📖 "There is a trade-off between how many potential examples to re-rank vs. processing speed." — 原文

📖 "To get the best of both, one common approach is to use embeddings (or another bi-encoder) to cheaply identify top candidates, and then use GPT (or another cross-encoder) to expensively re-rank those top candidates." — 原文

- 先取 100 篇最相关股票研报 → 按某组客户组合的上下文重排成 top 5/10
- 经典规则搜索取回 top 100/1000 → 按特定用户上下文剪枝
何时换 fine-tuning:文档差异越来越具体、few-shot 覆盖不住,或想降低 text-davinci-003 的逐条延迟

flowchart LR
  IMG[评论图片] -->|Vision 模型描述| DESC[图像情感描述]
  TXT[文字评论] --> MERGE[full_sentiment]
  DESC --> MERGE
  MERGE -->|上传| VS[(向量库 / File Search)]
  Q[自然语言查询] -->|语义检索+过滤| VS --> ANS[更准确回答]

📖 "This example uses OpenAI's built-in vector store and file search capabilities to build a RAG system that can analyse customer experiences from their feedback, which can be both visual and text-based. We create two vector stores for comparisons, one with image understanding and one without." — 原文

📖 "However with image context provided the second RAG system is able to provide a more accurate response." — 原文

def analyze_image_sentiment(image_path: str) -> str:
    """Analyze food delivery image and return sentiment analysis."""
    base64_image = encode_image(image_path)
    response = client.responses.create(
        model="gpt-5",
        reasoning={"effort": "minimal"},
        input=[{
            "role": "user",
            "content": [
                {"type": "input_text",
                 "text": "Analyze this food delivery image. Respond with a brief description and sentiment (positive/negative) in one line."},
                {"type": "input_image",
                 "image_url": f"data:image/jpeg;base64,{base64_image}"},
            ],
        }],
    )
    return response.output_text.strip()

flowchart TD
  P[用户 prompt] -->|LLM 抽实体| J[实体 JSON]
  J -->|模板生成 Cypher| CY[Cypher 查询]
  CY -->|GDS cosine 匹配| G[(Neo4j 图库)]
  G --> R[命中商品]
  R -->|沿共享实体扩展| SIM[相似商品推荐]

📖 "If you have data where relationships between data points are important and you might want to leverage that, then it might be worth considering graph databases instead of traditional relational databases." — 原文

📖 "The querying part of this notebook would work on a relational database as well, the knowledge graph comes in handy when we want to couple the results with similar items that the graph is surfacing." — 原文

query_category = '''
    MATCH (p:Product {id: $product_id})-[:hasCategory]->(c:category)
    MATCH (p)-->(entity)
    WHERE NOT entity:category
    MATCH (n:Product)-[:hasCategory]->(c)
    MATCH (n)-->(commonEntity)
    WHERE commonEntity = entity AND p.id <> n.id
    RETURN DISTINCT n;
'''

📖 "Our approach involves parsing documents into images and utilizing metadata tagging to identify pages containing images, graphics and tables. When a semantic search retrieves such a page, we pass the page image to a vision model instead of relying solely on text." — 原文

📖 "Keep in mind that using the Vision Modality is resource-intensive, leading to increased latency and cost. It is advisable to use Vision Modality only for cases where performance on evaluation benchmarks is unsatisfactory with plain text extraction methods." — 原文

df['Visual_Input_Processed'] = df['PageText'].apply(
    lambda x: 'Y' if 'DESCRIPTION OF THE IMAGE OR CHART' in x or 'TRANSCRIPTION OF THE TABLE' in x else 'N'
)

📖 "Metadata enhances our ability to perform more granular searches, find the text or image associated with the vector, and enables filtering within the vector database." — 原文

📖 "We can analyse our dataset with natural language queries with the help of File Search." — 原文

response = client.responses.create(
    model="gpt-5",
    input=query,
    tools=[{
        "type": "file_search",
        "vector_store_ids": [text_image_vector_store_id],
        "filters": {"type": "eq", "key": "month", "value": "july"}
    }]
)

📖 "Indeed, asking an LLM to generate a Cypher query directly might result in the wrong parameters being used, whether it's the entity type or the relationship type, as is the case above." — 原文

📖 "We will instead use LLMs to decide what to search for, and then generate the corresponding Cypher queries using templates." — 原文

completion = client.chat.completions.create(
    model=model,
    temperature=0,
    response_format={"type": "json_object"},
    messages=[
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": prompt}
    ]
)

📖 "However, the entities extracted might not be an exact match with the data we have, so we will use the GDS cosine similarity function to return products that have relationships with entities similar to what the user is asking." — 原文

📖 "The threshold defines how closely related words should be. Adjust the threshold to return more or less results" — 原文