你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。

使用 Azure OpenAI 响应 API

使用 Azure OpenAI 响应 API 生成有状态的多轮次响应。 它将聊天完成和助手 API 中的功能汇集在一个统一体验中。 使用 多代理业务流程 将独立工作委托给并行子代理,或使用 工具搜索 仅在模型需要它们时才加载工具定义。 响应 API 还支持 computer-use-preview 模型,该模型支持计算机使用。

有关完整的请求和响应参数说明,请参阅 响应 API 参数参考。

先决条件

  • 已部署Azure OpenAI 模型。
  • 身份验证方法:
    • API 密钥(例如 AZURE_OPENAI_API_KEY),或
    • Microsoft Entra ID(建议)。
  • 安装适用于语言的客户端库:
    • Python: pip install openai azure-identity
    • .NET: dotnet add package OpenAI 和 dotnet add package Azure.Identity
    • JavaScript/TypeScript: npm install openai @azure/identity
    • Java:向项目添加 com.openai:openai-java 和 com.azure:azure-identity。
  • 对于 REST 示例,请设置 AZURE_OPENAI_API_KEY (API 密钥流)或 AZURE_OPENAI_AUTH_TOKEN (Microsoft Entra ID 流)。

支持的区域

在运行本文中的示例之前,请确认资源区域是否支持响应 API。 需要 v1 API 才能访问最新功能。 有关详细信息,请参阅 API 版本生命周期。 有关 Foundry 代理服务区域支持,请参阅 区域可用性表。 响应 API 目前在以下区域中可用:

  • australiaeast
  • brazilsouth
  • canadacentral
  • canadaeast
  • centralus
  • eastus
  • eastus2
  • francecentral
  • 德国中西部
  • 意大利北部
  • japaneast
  • japanwest
  • koreacentral
  • northcentralus
  • 挪威东部
  • polandcentral
  • southafricanorth
  • southcentralus
  • 东南亚
  • 南印度
  • 西班牙中部 (spaincentral)
  • swedencentral
  • switzerlandnorth
  • switzerlandwest
  • uaenorth
  • uksouth
  • ukwest
  • westcentralus
  • westeurope
  • westus
  • westus2
  • westus3

支持的模型

响应 API 支持以下模型:

  • gpt-6.2-astra (版本: 2026-11-17)
  • gpt-6.2-sol (版本: 2026-11-17)
  • gpt-6.1-terra (版本: 2026-10-26)
  • gpt-6.1-sol (版本: 2026-09-29)
  • gpt-6-luna (版本: 2026-09-22)
  • gpt-6-sol (版本: 2026-09-22)
  • gpt-6-astra (版本: 2026-09-03)
  • gpt-5.6-sol (版本: 2026-07-09)
  • gpt-5.6-terra (版本: 2026-07-09)
  • gpt-5.6-luna (版本: 2026-07-09)
  • gpt-chat-latest(版本:2026-10-07、2026-06-24、2026-08-06、2026-05-28、2026-05-05)
  • gpt-5.5 (版本: 2026-04-24)
  • gpt-5.4-nano (版本: 2026-03-17)
  • gpt-5.4-mini (版本: 2026-03-17)
  • gpt-5.4-pro (版本:2026-03-05)
  • gpt-5.4 (版本:2026-03-05)
  • gpt-5.3-chat (版本: 2026-03-03)
  • gpt-5.3-codex (版本: 2026-02-24)
  • gpt-5.2-codex (版本: 2026-01-14)
  • gpt-5.2 (版本: 2025-12-11)
  • gpt-5.2-chat (版本: 2025-12-11)
  • gpt-5.2-chat (版本: 2026-02-10)
  • gpt-5.1-codex-max (版本: 2025-12-04)
  • gpt-5.1 (版本: 2025-11-13)
  • gpt-5.1-chat (版本: 2025-11-13)
  • gpt-5.1-codex (版本: 2025-11-13)
  • gpt-5.1-codex-mini (版本: 2025-11-13)
  • gpt-5-pro (版本: 2025-10-06)
  • gpt-5-codex (版本: 2025-09-11)
  • gpt-5 (版本: 2025-08-07)
  • gpt-5-mini (版本: 2025-08-07)
  • gpt-5-nano (版本: 2025-08-07)
  • gpt-5-chat (版本: 2025-08-07)
  • gpt-5-chat (版本: 2025-10-03)
  • gpt-5-codex (版本: 2025-09-15)
  • gpt-4o (版本: 2024-11-20, 2024-08-06, 2024-05-13)
  • gpt-4o-mini (版本: 2024-07-18)
  • computer-use-preview
  • gpt-4.1 (版本: 2025-04-14)
  • gpt-4.1-nano (版本: 2025-04-14)
  • gpt-4.1-mini (版本: 2025-04-14)
  • gpt-image-1 (版本: 2025-04-15)
  • gpt-image-1-mini (版本: 2025-10-06)
  • gpt-image-1.5 (版本: 2025-12-16)
  • gpt-image-2.5-flare (版本: 2026-09-09)
  • gpt-image-2.5-sunburst (版本: 2026-09-09)
  • o1 (版本: 2024-12-17)
  • o3-mini (版本: 2025-01-31)
  • o3 (版本: 2025-04-16)
  • o4-mini (版本: 2025-04-16)

并非每个模型都可用于每个受支持的区域。 请查看 模型页面 以获取模型地区可用性信息。

注意

当前不支持:

  • 通过多轮编辑和流式处理生成图像。

存在以下已知问题:

  • 现在 支持将 PDF 作为输入文件,但目前不支持将文件上传目的设置为 user_data 。
  • 后台模式与流式处理一起使用时的性能问题。 Microsoft正在努力解决此问题。

生成文本响应

使用响应 API 生成简单的文本响应。 将 YOUR-RESOURCE-NAME 和 MODEL_NAME 替换为您的部署值。

import os
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

# API key authentication
client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
)
response = client.responses.create(
    model="MODEL_NAME",
    input="This is a test."
)
print(response.model_dump_json(indent=2))

# Microsoft Entra ID authentication (recommended)
token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)
client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=token_provider(),
)
response = client.responses.create(
    model="MODEL_NAME",
    input="This is a test."
)
print(response.model_dump_json(indent=2))

示例响应

{
  "id": "resp_67cb32528d6881909eb2859a55e18a85",
  "created_at": 1741369938.0,
  "output_text": "Great! How can I help you today?",
  ...
}

检索响应

从以前的响应 API 调用中按其 ID 检索响应。

import os
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

# API key authentication
client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
)
response = client.responses.retrieve("<response_id>")
print(response.model_dump_json(indent=2))

# Microsoft Entra ID authentication
token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)
client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=token_provider,
)
response = client.responses.retrieve("<response_id>")
print(response.model_dump_json(indent=2))

示例响应

{
  "id": "resp_67cb61fa3a448190bcf2c42d96f0d1a8",
  "output_text": "Hello! How can I assist you today?",
  ...
}

删除响应

默认情况下,响应数据将保留 30 天。 按 ID 删除存储的响应。

import os
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

# API key authentication
client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
)
response = client.responses.delete("<response_id>")
print(response)

# Microsoft Entra ID authentication
token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)
client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=token_provider,
)
response = client.responses.delete("<response_id>")
print(response)

存储的响应数据的加密

当 Responses API 持久保存消息历史记录及相关内容时,服务会对此内容进行静态加密。 有关存储加密的说明,请参阅 Microsoft Foundry 中由 Azure 销售的模型的数据、隐私和安全性。 有关 CMK 覆盖范围和先决条件,请参阅 Microsoft Foundry 中的客户管理的密钥加密。

此加密与你使用 store=false 管理对话状态时返回给应用程序的加密推理项是分开的。

将响应链接在一起

通过将上一次响应 ID 传递给 previous_response_id 来串联处理步骤。

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

first_response = client.responses.create(
    model="MODEL_NAME",
    input="Define catastrophic forgetting."
)

second_response = client.responses.create(
    model="MODEL_NAME",
    previous_response_id=first_response.id,
    input="Explain it for a college freshman."
)

print(second_response.output_text)

手动串联响应

或者,可以在下一个请求中手动转发输出项。

import os
from openai import OpenAI

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  api_key=os.getenv("AZURE_OPENAI_API_KEY")  
)

inputs = [{"type": "message", "role": "user", "content": "Define and explain the concept of catastrophic forgetting?"}] 
  
response = client.responses.create(  
    model="gpt-4o",  # replace with your model deployment name  
    input=inputs  
)  
  
inputs += response.output

inputs.append({"role": "user", "type": "message", "content": "Explain this at a level that could be understood by a college freshman"}) 
               

second_response = client.responses.create(
  model="MODEL_NAME",
    input=inputs
)

print(second_response.model_dump_json(indent=2))

压缩响应

压缩可减少输入上下文,同时保留后续轮次的基本状态。

import os
from openai import OpenAI

client = OpenAI(
  base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

compacted = client.responses.compact(
  model="MODEL_NAME",
  input=[
    {"role": "user", "content": "Create a simple landing page for a dog cafe."},
    {
      "id": "msg_001",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [{"type": "output_text", "text": "..."}],
    },
  ]
)

follow_up = client.responses.create(
  model="MODEL_NAME",
  input=[*compacted.output, {"role": "user", "content": "Add a booking form."}]
)
print(follow_up.output_text)

使用返回的项进行压缩

可以压缩先前请求返回的所有项,例如推理、消息、函数调用等。

curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses/compact \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{
        "model": "MODEL_NAME",
        "input": [
          {
            "role"   : "user",
            "content": "Create a simple landing page for a dog petting café."
          },
          {
            "id": "msg_001",
            "type": "message",
            "status": "completed",
            "content": [
              {
                "type": "output_text",
                "annotations": [],
                "logprobs": [],
                "text": "Below is a single file, ready-to-use landing page for a dog petting café:..."
              }
            ],
            "role": "assistant"
          }
        ]
    }'
# Use the compacted output as input for the next turn.
next_response = client.responses.create(
  model="MODEL_NAME",
  input=[*compacted.output, {"role": "user", "content": "Add opening hours."}],
)
print(next_response.output_text)

使用以前的响应 ID 压缩

还可以使用以前的响应 ID 压缩。

initial_response = client.responses.create(
  model="MODEL_NAME",
  input="What is the size of France?"
)

compacted_response = client.responses.compact(
  model="MODEL_NAME",
  previous_response_id=initial_response.id
)

follow_up_response = client.responses.create(
  model="MODEL_NAME",
  input=[
    *compacted_response.output,
    {"role": "user", "content": "What is the capital?"}
  ]
)
print(follow_up_response.output_text)

服务器端压缩

你还可以通过设置POST /responses 和client.responses.create,直接在响应中使用服务器端压缩(context_management 或compact_threshold)。

  • 当输出令牌计数超过配置的阈值时,响应 API 会自动运行压缩。
  • 在此模式下,无需单独调用 /responses/compact 。
  • 响应包括加密压缩项。
  • 在响应创建请求上设置 store=false 时,服务器端压缩将起作用。

压缩项使用较少的令牌将基本的以前状态和推理推进到下一轮次。 这是不透明的,不应是人类可读的。

如果使用无状态输入数组链接过程,请像往常一样追加输出项。 如果使用 previous_response_id,则每次轮次仅传递新用户消息。 在这两种模式中,压缩项携带下一个窗口所需的上下文。

提示

将输出项追加到以前的输入项后,可以删除最近压缩项之前的项,以保持请求更小并减少长尾延迟。 最新的压缩项包含了继续对话所需的上下文。 如果使用 previous_response_id 串联,请不要手动裁剪。

Flow

  1. 照常调用 responses 。 添加 context_management 并通过 compact_threshold 启用服务器端压缩。
  2. 如果输出超过阈值,服务将触发压缩,在输出流中发出压缩项,并在继续推理之前修剪上下文。
  3. 使用以下模式之一继续聊天:
    1. 无状态输入数组链式处理:将输出项(包括压缩项)添加到下一个输入数组中。
    2. previous_response_id 链接:在每个轮次仅传递新用户消息,并将最新的响应 ID 一并传递下去。

例子

conversation = [
  {
    "type": "message",
    "role": "user",
    "content": "Let's begin a long coding task.",
  }
]

while keep_going:
  response = client.responses.create(
    model="MODEL_NAME",
    input=conversation,
    store=False,
    context_management=[{"type": "compaction", "compact_threshold": 200000}],
  )

  conversation.append(
    {
      "type": "message",
       "role": "user",
      "content": get_next_user_input(),
    }
  )

流媒体

通过设置 stream=true来流式传输响应。 该服务会发布增量事件,您可以订阅这些事件以逐令牌渲染输出。

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

stream = client.responses.create(
    model="MODEL_NAME",
    input="Summarize Azure OpenAI Responses API in one sentence.",
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="")

在流式处理期间,如果错误发生在流中,系统会尝试内部重试以解决错误。 如果请求仍然失败,服务将遇到不可恢复的错误。 在这些情况下,HTTP 响应代码为 200(成功),但流中的错误事件包含有关中流错误的详细信息。

服务器返回以下错误类型:

错误类型 可以翻译为
server_error 返回代码 500
too_many_requests 返回代码 429
forbidden 返回代码 403
user_error 返回代码 400

示例错误事件:

{
  "type": "error",
  "error": {
    "type": "too_many_requests",
    "code": "no_capacity",
    "headers": {
      "skip-error-remapping": "true"
    },
    "message": "The system is currently experiencing high demand and cannot process your request. Your request exceeds the maximum usage size allowed during peak load. For improved capacity reliability, consider switching to Provisioned Throughput.",
    "param": null
  }
}

应用程序应检测这些错误,并优雅地停止或重新启动流传输。 对于流媒体响应失败期间生成的令牌,将不收取费用。

结构化输出

使用结构化输出根据 JSON 架构发出响应。 在 Responses API 请求中,在 text.format 中定义架构。 聊天补全功能改用 response_format 代替。 有关 SDK 和 REST 示例、支持的架构约束和限制,请参阅 结构化输出。

函数调用

响应 API 支持函数调用。

import os
import json
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

response = client.responses.create(
    model="MODEL_NAME",
    tools=[
        {
            "type": "function",
            "name": "get_weather",
            "description": "Get weather for a location",
            "parameters": {
                "type": "object",
                "properties": {"location": {"type": "string"}},
                "required": ["location"],
            },
        }
    ],
    input="What is the weather in San Francisco?",
)

tool_outputs = []
for item in response.output:
    if item.type == "function_call" and item.name == "get_weather":
        args = json.loads(item.arguments)
        weather = {"location": args["location"], "temperature": "70 F"}
        tool_outputs.append(
            {
                "type": "function_call_output",
                "call_id": item.call_id,
                "output": json.dumps(weather),
            }
        )

final_response = client.responses.create(
    model="MODEL_NAME",
    previous_response_id=response.id,
    input=tool_outputs,
)

print(final_response.output_text)

处理防护栏和内容筛选

在部署级别应用防护栏(内容筛选器)。 每个配置的控件评估其支持的内容和干预点:核心伤害筛选器评估输入和输出,用户提示攻击检测评估用户输入,文档攻击检测在启用时评估文档内容。 单独配置护栏。 有关详细信息,请参阅 配置护栏和控制。 本部分介绍如何在调用响应 API 时检测和处理防护措施结果。

Responses API 呈现护栏结果的方式与聊天补全不同。 聊天补全返回的 prompt_filter_results 和 content_filter_results 字段不再使用,响应对象现包含顶层的 content_filters 数组。 每个条目描述一个筛选器结果。

领域 Description
blocked 内容是否被阻止。
source_type 该结果适用于prompt(输入)还是completion(输出)。
content_filter_results 类别结果,例如带有严重程度级别的hate、sexual、violence和self_harm,以及可选类别,如jailbreak、indirect_attack、protected_material_text和protected_material_code。
content_filter_offsets 结果适用的字符偏移量。

注意

该content_filters数组是一个Microsoft Foundry 扩展,该扩展不属于基本 OpenAI 响应架构,因此 SDK 不会为其公开类型化属性。 将其作为原始字段或附加字段读取,如以下示例所示。

检测输入阻塞

当护栏阻止输入时,API 将返回 HTTP 400 错误并显示代码 content_filter。 捕获此错误,以优雅处理被阻断的提示。

import os
from openai import OpenAI, BadRequestError

client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
)

# A blocked prompt raises BadRequestError with the code "content_filter"
try:
    response = client.responses.create(
        model="MODEL_NAME",
        input="This is a test."
    )
    print(response.output_text)
except BadRequestError as error:
    if error.code == "content_filter":
        print("The prompt was blocked by a guardrail.")
    else:
        raise

读取护栏批注

请求成功后,从响应中读取 content_filters 数组,以检查输入和输出的防护措施结果。

在注释模式下,已配置的控件可以报告严重性或检测结果,但不会强制执行这些结果。 对应的blocked和filtered值保持false不变。 针对四大核心-危害类别的注释模式,需获得修改后防护栏的批准。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
)
response = client.responses.create(
    model="MODEL_NAME",
    input="This is a test."
)

# content_filters is an Azure extension, so read it from model_extra
content_filters = response.model_extra.get("content_filters", [])
for result in content_filters:
    print(f"Source: {result['source_type']}, Blocked: {result['blocked']}")

若要了解有关护栏类别和严重性级别的详细信息,请参阅 防护栏概述 和 处理批注。

代码解释器

代码解释器工具使模型能够在安全的沙盒环境中编写和执行Python代码。 它支持一系列高级任务,包括:

  • 处理具有不同数据格式和结构的文件
  • 生成包含数据和可视化效果的文件(例如图形)
  • 以迭代方式编写和运行代码来解决问题 — 模型可以调试和重试代码,直到成功
  • 通过启用图像转换(例如裁剪、缩放和旋转)增强受支持模型中的视觉推理(例如 o3、o4-mini)
  • 此工具特别适用于涉及数据分析、数学计算和代码生成的方案。
curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -d '{
        "model": "MODEL_NAME",
        "tools": [
            { "type": "code_interpreter", "container": {"type": "auto"} }
        ],
        "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?"
    }'
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

response = client.responses.create(
    model="MODEL_NAME",
    tools=[{"type": "code_interpreter", "container": {"type": "auto"}}],
    instructions="You are a math tutor. Write and run Python code to solve math problems.",
    input="Solve 3x + 11 = 14."
)

print(response.output_text)

容器

重要

除了与使用 Azure OpenAI 相关的基于令牌的费用之外,代码解释器还有额外的费用。 如果响应 API 在两个不同的线程中同时调用代码解释器,则会创建两个代码解释器会话。 每个会话会产生每分钟的费用,最低费用为 5 分钟。 只要在 20 分钟的空闲超时内访问其容器,会话就保持活动状态。

代码解释器工具需要一个容器,即一个完全沙盒的虚拟机,模型可以在其中执行Python代码。 容器可以包括上传的文件或执行期间生成的文件。

若要创建容器,请在创建新的 Response 对象时在工具配置中指定 "container": { "type": "auto", "file_ids": ["file-1", "file-2"] } 。 这会自动创建新容器或重复使用模型上下文中先前code_interpreter_call的活动容器。 API 输出中的 code_interpreter_call 将包含生成的 container_id。 如果未使用 20 分钟,此容器将过期。

容器不会在项目内按代理或按用户分别隔离。 引用活动容器的请求(包括通过 code_interpreter_call 输入中的项)可以访问该容器的文件和状态。 将容器 ID 和包含它们的输出项视为敏感项,并且不要将其公开给其他用户或工作负荷。

对于多租户或多用户应用程序,请保留每个用户或租户与重复使用的容器和模型上下文之间的受信任关联。 不要在信任边界之间重复使用此状态,并在发送之前针对这些关联验证调用方提供的上下文。 若要分离需要不同信任边界的工作负荷,请使用单独的项目,并查看可跨越项目的继承角色分配。 这些应用程序可保护补充平台身份验证和授权。 它们不能取代这些机制。

以下文件限制适用:

  • 请求最多可以包含 50 个文件 ID。
  • 容器总共可以容纳多达 1,000 个文件,包括代码解释器生成的输入文件和文件。

文件输入和输出

运行代码解释器时,模型可以创建自己的文件。 例如,如果要求它构造绘图或创建 CSV,它会直接在容器上创建这些映像。 它将在其下一条消息的批注中引用这些文件。

模型输入中的任何文件都会自动上传到容器。 无需明确地将其上传到容器。

支持的文件

文件格式 MIME 类型
.c text/x-c
.cs text/x-csharp
.cpp text/x-c++
.csv text/csv
.doc application/msword
.docx application/vnd.openxmlformats-officedocument.wordprocessingml.document
.html text/html
.java text/x-java
.json application/json
.md text/markdown
.pdf application/pdf
.php text/x-php
.pptx application/vnd.openxmlformats-officedocument.presentationml.presentation
.py text/x-python
.py text/x-script.python
.rb text/x-ruby
.tex text/x-tex
.txt text/plain
.css text/css
.js text/JavaScript
.sh application/x-sh
.ts application/TypeScript
.csv application/csv
.jpeg image/jpeg
.jpg image/jpeg
.gif image/gif
.pkl application/octet-stream
.png image/png
.tar application/x-tar
.xlsx application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
.xml application/xml 或“text/xml”
.zip application/zip

列出输入项

获取随响应一起发送的输入项。 这可用于检查完整对话上下文,包括模型添加的任何项(例如函数调用或压缩项)。

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

items = client.responses.input_items.list("<response_id>")
print(items.model_dump_json(indent=2))

示例响应

{
  "object": "list",
  "data": [
    {
      "id": "msg_...",
      "type": "message",
      "role": "user",
      "content": [{"type": "input_text", "text": "This is a test."}]
    }
  ]
}

图像输入

启用视觉的模型可以解释图像以及文本。 它们可以识别对象、形状、颜色和纹理,并读取图像中包含的文本,但受本文后面列出的限制的约束。

可以通过以下任一方式为请求提供图像作为输入:

  • 图像文件的完全限定 URL
  • 经过 Base64 编码的数据 URI
  • 使用文件 API 创建的文件 ID

图像网址

引用一张托管在公开 URL 上的图像。 模型会获取该图像,并将其作为输入内容的一部分。

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

response = client.responses.create(
    model="MODEL_NAME",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "What is in this image?"},
                {"type": "input_image", "image_url": "<image_url>"}
            ]
        }
    ]
)

print(response.output_text)

Base64 编码的图像

通过将图像字节编码为 base64 数据 URI 来内联发送图像。 如果映像未托管在公共 URL 上,或者想要避免额外的网络提取,请使用此模式。

import base64
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

with open("path_to_your_image.jpg", "rb") as image_file:
    base64_image = base64.b64encode(image_file.read()).decode("utf-8")

response = client.responses.create(
    model="MODEL_NAME",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "What is in this image?"},
                {"type": "input_image", "image_url": f"data:image/jpeg;base64,{base64_image}"}
            ]
        }
    ]
)

print(response.output_text)

文件标识

使用 purpose="assistants"文件 API 上传图像,然后在请求中引用返回的文件 ID。 如果要在多个请求之间重复使用同一映像,而无需重新发送其字节,此方法非常有用。

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

def create_file(file_path):
    with open(file_path, "rb") as file_content:
        result = client.files.create(
            file=file_content,
            purpose="assistants",
        )
        return result.id

file_id = create_file("path_to_your_image.jpg")

response = client.responses.create(
    model="MODEL_NAME",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "What is in this image?"},
                {"type": "input_image", "file_id": file_id},
            ],
        }
    ],
)

print(response.output_text)

图像输入要求

下表列出了图像输入支持的文件类型。

文件类型 MIME 类型
PNG image/png
JPEG image/jpeg
WebP image/webp
非动画 GIF image/gif

在单个请求中,最多可以包含 50 个图像。 每个单独的图像文件必须低于 512 MB,并且请求中提示及所有图像的总大小也必须低于 512 MB。

映像必须满足以下附加要求:

  • 图像必须与提示相关;该模型不是针对不相关的视觉内容设计的。
  • 图像不应包含违反内容策略的有害或敏感内容。
  • 图像文件无法损坏或不可读。 如果模型无法处理映像,请求将失败。

选择图像详细信息级别

使用 detail 内容部件上的 input_image 属性来控制模型处理图像的方式。 较低的详细信息使用更少的令牌且速度更快,而更详细的详细信息使用更多令牌,但允许模型捕获更精细的功能。

{
  "type": "input_image",
  "image_url": "<image_url>",
  "detail": "high"
}

下表描述了每个详细信息级别。

详细程度 Description
low 模型使用映像的分辨率较低版本。 此选项使用最少的令牌并生成最快的响应,但模型可能会错过精细的详细信息。
high 模型使用映像的更高分辨率版本。 此选项捕获更精细的详细信息,但使用更多令牌并花费更长的时间进行响应。
auto 默认值。 模型根据图像和提示选择适当的详细信息级别。

图像输入限制

已启用视觉的模型具有以下限制:

  • 医学图像:该模型不适合解释专门的医学图像,如CT扫描,不应用于医疗建议。
  • 非英语文本:处理包含非拉丁字母(如日语或朝鲜语)中的文本的图像时,模型可能无法以最佳方式执行。
  • 小文本:放大图像中的文本以提高可读性,但避免裁剪重要详细信息。
  • 旋转:模型可能错误地解释旋转或倒置的文本和图像。
  • 视觉元素:模型可能难以处理颜色或样式(如纯色、虚线或虚线)变化的图形或文本。
  • 空间推理:模型难以执行需要精确空间本地化的任务,例如识别国际象棋位置。
  • 准确性:在某些情况下,模型可能会生成不正确的说明或标题。
  • 图像形状:模型难以处理全景图像和鱼眼图像。
  • 元数据和大小调整:模型不会处理原始文件名或元数据,并且图像在分析之前调整大小,这会影响其原始尺寸。
  • 计数:模型可能会为图像中的对象提供近似计数。
  • CAPTCHA:出于安全原因,系统会阻止提交 CAPTCHA。

文件输入

具有视觉功能的模型支持 PDF 输入。 可以通过以下任一方式提供 PDF 文件:

  • Base64 编码的数据
  • 使用文件 API 创建的文件 ID
  • 外部文件 URL (file_url)

为了帮助模型理解 PDF 内容,模型的上下文包括提取的文本和每页的图像。 当通过关系图或非文本内容传达关键信息时,此功能非常有用。

注意

  • 所有提取的文本和图像都放入模型的上下文中。 请确保了解将 PDF 用作输入的定价和令牌使用含义。
  • 在单个 API 请求中,可以包含多个文件,但每个文件必须小于 50 MB。 请求中所有文件的组合限制为 50 MB。
  • 只有支持文本和图像输入的模型才能接受 PDF 文件作为输入。
  • 目前不支持 purpose 的 user_data。 作为临时解决方法,需要将 assistants目的设置为 。

将 PDF 转换为 Base64 并进行分析

通过将 PDF 字节编码为 base64 数据 URI 来内联发送 PDF。 模型同时接收提取的文本和每个页面的呈现图像。

import base64
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

with open("PDF-FILE-NAME.pdf", "rb") as f:
    base64_string = base64.b64encode(f.read()).decode("utf-8")

response = client.responses.create(
    model="MODEL_NAME",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_file",
                    "filename": "PDF-FILE-NAME.pdf",
                    "file_data": f"data:application/pdf;base64,{base64_string}",
                },
                {"type": "input_text", "text": "Summarize this PDF."},
            ],
        },
    ]
)

print(response.output_text)

上传 PDF 和分析

使用 purpose="assistants" 上传 PDF 文件。 目前不支持 purpose 中的 user_data。

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

file = client.files.create(
    file=open("nucleus_sampling.pdf", "rb"),
    purpose="assistants"
)

response = client.responses.create(
    model="MODEL_NAME",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_file", "file_id": file.id},
                {"type": "input_text", "text": "Summarize this PDF."},
            ],
        },
    ]
)

print(response.output_text)

从外部文件 URL 分析 PDF

使用 input_file 内容项的 file_url 属性引用托管在可公开访问 URL 上的 PDF。 无需先下载、编码或上传文件。

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

response = client.responses.create(
    model="MODEL_NAME",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Analyze the letter and provide a summary of the key points.",
                },
                {
                    "type": "input_file",
                    "file_url": "https://www.berkshirehathaway.com/letters/2024ltr.pdf",
                },
            ],
        },
    ]
)

print(response.output_text)

使用远程 MCP 服务器

可以通过将其连接到远程模型上下文协议 (MCP) 服务器上托管的工具来扩展模型的功能。 这些服务器由开发人员和组织维护,并公开可由 MCP 兼容的客户端(例如响应 API)访问的工具。

模型上下文协议 (MCP)是一个开放标准,用于定义应用程序如何向大型语言模型(LLM)提供工具和上下文数据。 它支持将外部工具与模型工作流的一致、可缩放集成。

以下示例演示如何使用远程 MCP 服务器查询有关Azure REST API 存储库的信息。 模型实时检索存储库内容并基于其进行推理。

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

response = client.responses.create(
    model="MODEL_NAME",
    tools=[
        {
            "type": "mcp",
            "server_label": "github",
            "server_url": "https://contoso.com/Azure/azure-rest-api-specs",
            "require_approval": "never"
        }
    ],
    input="What transport protocols are supported in the 2025-03-26 version of the MCP spec?"
)

print(response.output_text)

MCP 工具仅适用于响应 API,并且适用于所有较新的模型(gpt-4o、gpt-4.1 和推理模型)。 使用 MCP 工具时,只需为导入工具定义或进行工具调用时使用的令牌付费,无需额外付费。

批准

默认情况下,在与远程 MCP 服务器共享任何数据之前,响应 API 需要显式批准。 此审批步骤有助于确保透明度,并让你控制外部发送的信息。

建议查看与远程 MCP 服务器共享的所有数据,并选择性地记录这些数据以进行审核。

当需要审批时,模型在响应输出中返回一个 mcp_approval_request 项。 此对象包含挂起请求的详细信息,并允许在继续操作之前检查或修改数据。

{
  "id": "mcpr_682bd9cd428c8198b170dc6b549d66fc016e86a03f4cc828",
  "type": "mcp_approval_request",
  "arguments": {},
  "name": "fetch_azure_rest_api_docs",
  "server_label": "github"
}

若要继续进行远程 MCP 调用,必须通过创建包含mcp_approval_response项的新响应对象来响应审批请求。 此对象确认了允许模型将指定数据发送到远程 MCP 服务器的意图。

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

response = client.responses.create(
    model="MODEL_NAME",
    tools=[
        {
            "type": "mcp",
            "server_label": "github",
            "server_url": "https://contoso.com/Azure/azure-rest-api-specs",
            "require_approval": "never"
        }
    ],
    previous_response_id="<previous_response_id>",
    input=[
        {
            "type": "mcp_approval_response",
            "approve": True,
            "approval_request_id": "<approval_request_id>"
        }
    ]
)

print(response.output_text)

认证

重要

  • 响应 API 中的 MCP 客户端需要 TLS 1.2 或更高版本。
  • 目前不支持双向 TLS(mTLS)。
  • 目前,Azure 服务标记 不支持 MCP 客户端流量。

与GitHub MCP 服务器不同,大多数远程 MCP 服务器都需要身份验证。 响应 API 中的 MCP 工具支持自定义标头,允许你使用所需的身份验证方案安全地连接到这些服务器。

可以直接在请求中指定标头,例如 API 密钥、OAuth 访问令牌或其他凭据。 最常用的标头是 Authorization 标头。

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

response = client.responses.create(
    model="MODEL_NAME",
    input="What is this repo in 100 words?",
    tools=[
        {
            "type": "mcp",
            "server_label": "github",
            "server_url": "https://contoso.com/Azure/azure-rest-api-specs",
            "headers": {"Authorization": "Bearer $YOUR_MCP_TOKEN"}
        }
    ]
)

print(response.output_text)

后台任务

后台模式可让你借助 o3 和 o1-pro 等推理模型,以异步方式运行长时间运行的任务。 对于可能需要几分钟才能完成的复杂任务(例如 Codex 或 Deep Research 样式代理)非常有用。 当使用 "background": true 发送请求时,任务将异步处理,您需要轮询其状态。

启动后台任务

在请求中设置 background=true 以将任务加入队列。 该服务会立即返回响应 ID 和 queued 状态 — 使用该 ID 轮询、流式传输或取消任务。

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

response = client.responses.create(
    model="MODEL_NAME",
    input="Write me a very long story.",
    background=True
)

print(response.status)

轮询完成状态

当状态为 queued 或 in_progress 时,继续轮询。 响应到达终端状态后,即可进行检索。

from time import sleep

while response.status in {"queued", "in_progress"}:
    print(f"Current status: {response.status}")
    sleep(2)
    response = client.responses.retrieve(response.id)

print(f"Final status: {response.status}\nOutput:\n{response.output_text}")

取消后台任务

使用 cancel 端点取消正在进行中的后台任务。 取消是幂等的 - 后续调用返回最终响应对象。

response = client.responses.cancel("<response_id>")
print(response.status)

若要流式传输后台响应,请将 background 和 stream 均设置为 true。 这种模式可让你在连接中断后继续进行流式传输。 通过每个事件中的 sequence_number 跟踪你的位置。

stream = client.responses.create(
    model="MODEL_NAME",
    input="Write me a very long story.",
    background=True,
    stream=True,
)

cursor = None
for event in stream:
    print(event)
    cursor = event["sequence_number"]

后台响应当前比同步响应具有更高的首个令牌时间。 正在改进,以减少这种差距。

限制

  • 后台模式需要 store=true。 不支持无状态请求。
  • 仅当原始请求包含 stream=true时,您才能重新开始流式传输。
  • 若要取消同步响应,请直接终止连接。

从特定点恢复流式传输

如果流式连接中断,您可以通过在响应中传递 stream=true 以及 starting_after=<sequence_number> 上的 GET,从已知事件处恢复。 服务会重播该序列号之后发布的事件。

curl -N -X GET "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses/<response_id>?stream=true&starting_after=42" \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY"

加密推理

在无状态模式下store=false将推理模型与 Responses API 一起使用时,应用程序会为每个后续请求提供上下文。 以前的消息提供对话历史记录,但它们不包含模型的内部推理。 加密的推理项允许将兼容的推理上下文传递到后续请求中,而无需将推理作为可读文本公开给应用程序。

为何使用加密推理?

当应用程序管理聊天状态并需要继续执行多轮推理工作流时,请使用加密推理。 例如,用户可能会提出后续问题,或者模型可能会调用工具,然后在收到其结果后继续。

仅传递之前的消息,并不会传递上一轮中模型的推理上下文。 加密的推理项会延续该上下文,同时对您的应用程序保持其内容不可见。

使用方法

  1. 设置 store=false。 若要显式请求加密推理,请将reasoning.encrypted_content添加到include参数中,如以下示例所示。
  2. 按原始顺序保留所有返回的输出项,包括具有 encrypted_content 属性的推理项。
  3. 在下一次调用中,将这些项目与其他相关对话项一起包含在 input 中,并继续设置 store=false。 不要将 previous_response_id 用于未存储的响应。

无状态响应默认返回加密的内容;该 include 参数仍受支持,以保持兼容性。 重播项使兼容的推理可用,但模型使用的推理取决于其支持的推理上下文模式。 有关详细信息,请参阅跨调用保留推理。

在无状态模式下,加密的推理项将返回到应用程序。 应用程序负责安全地保留它,并在后续请求中将其传回。 选择满足安全性和生命周期要求的应用程序端存储位置。

以下示例使用 API 密钥身份验证。 Python示例使用 OpenAI 客户端库。 其他示例直接调用响应 REST 终结点,并将完整的输出项保留为 JSON。

安装适用于你的语言的依赖项:

  • Python:使用 pip install --upgrade openai 安装客户端。
  • C#:使用 .NET 8 或更高版本的控制台应用程序。 不需要任何其他软件包。
  • JavaScript:使用 Node.js 18 或更高版本,并将每个示例另存为 .mjs 文件。 不需要任何其他软件包。
  • Java:使用 JDK 17 或更高版本并添加 Maven 依赖项com.fasterxml.jackson.core:jackson-databind:2.22.4。 保存每个示例,其中包含其选项卡中所示的文件名。
  • REST:使用 PowerShell 7 或更高版本运行 PowerShell 示例。

为每个语言设置以下环境变量:

  • AZURE_OPENAI_ENDPOINT:资源终结点,例如 https://YOUR-RESOURCE-NAME.openai.azure.com。
  • AZURE_OPENAI_API_KEY:您的 API 密钥。
  • AZURE_OPENAI_DEPLOYMENT:支持的推理模型部署的名称。

这两个示例都检查加密的推理项,如果未返回任何内容,则引发错误。 使用可为示例请求生成推理项的部署配置和推理配置。

继续无状态对话

此示例将返回项保存在由应用程序管理的列表中,并将其传递到后续请求中。

import os

from openai import BadRequestError, OpenAI

client = OpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    base_url=f"{os.environ['AZURE_OPENAI_ENDPOINT'].rstrip('/')}/openai/v1/",
)
deployment = os.environ["AZURE_OPENAI_DEPLOYMENT"]

# Application-managed state. This example keeps it in memory.
conversation = [
    {"role": "user", "content": "Explain the trade-offs of this design."}
]


def add_response_items(response):
    items = [item.model_dump(exclude_none=True) for item in response.output]

    if not any(
        item.get("type") == "reasoning" and item.get("encrypted_content")
        for item in items
    ):
        raise RuntimeError(
            "No encrypted reasoning item was returned. Check the deployment "
            "and the request's include parameter."
        )

    # Preserve the returned items, including encrypted reasoning.
    conversation.extend(items)


try:
    first = client.responses.create(
        model=deployment,
        input=conversation,
        store=False,
        include=["reasoning.encrypted_content"],
    )
    add_response_items(first)
    print("First answer:", first.output_text)

    conversation.append({
        "role": "user",
        "content": "Which trade-off matters most for reliability?",
    })

    second = client.responses.create(
        model=deployment,
        input=conversation,
        store=False,
        include=["reasoning.encrypted_content"],
    )
    add_response_items(second)
    print("Follow-up answer:", second.output_text)

except BadRequestError as exc:
    # Inspect the service error before deciding whether to restart.
    print(f"Request rejected: {exc}")
    raise

该示例打印第一个答案和后续答案。 它保留所有输出项,包括加密推理,而不是仅保留可读答案。

此 conversation 列表是此示例的应用程序保留这些项目的位置。 它保存在内存中,进程重启后不会保留。 以后需要恢复运行的应用程序必须选择并保护自己的存储。

在工具调用后继续

此示例保留推理内容和函数调用项,执行示例函数,并使用匹配的 call_id 发送其结果。

import json
import os

from openai import BadRequestError, OpenAI

client = OpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    base_url=f"{os.environ['AZURE_OPENAI_ENDPOINT'].rstrip('/')}/openai/v1/",
)
deployment = os.environ["AZURE_OPENAI_DEPLOYMENT"]

tools = [{
    "type": "function",
    "name": "get_order_status",
    "description": "Look up the status of an example order.",
    "parameters": {
        "type": "object",
        "properties": {
            "order_id": {"type": "string"}
        },
        "required": ["order_id"],
        "additionalProperties": False,
    },
}]


def get_order_status(order_id):
    # Replace this example with your own trusted data source.
    if order_id == "A123":
        return {"order_id": order_id, "status": "Shipped"}
    return {"order_id": order_id, "status": "Not found"}


conversation = [{
    "role": "user",
    "content": "What is the status of order A123?",
}]


def create_response():
    return client.responses.create(
        model=deployment,
        input=conversation,
        tools=tools,
        store=False,
        include=["reasoning.encrypted_content"],
    )


try:
    # Bound the number of tool rounds.
    for _ in range(3):
        response = create_response()
        items = [item.model_dump(exclude_none=True) for item in response.output]

        if not any(
            item.get("type") == "reasoning" and item.get("encrypted_content")
            for item in items
        ):
            raise RuntimeError("No encrypted reasoning item was returned.")

        # Preserve returned items in order, including reasoning and tool calls.
        conversation.extend(items)

        calls = [
            item for item in response.output
            if item.type == "function_call"
        ]
        if not calls:
            print(response.output_text)
            break

        for call in calls:
            if call.name != "get_order_status":
                raise ValueError(f"Unexpected tool: {call.name}")

            arguments = json.loads(call.arguments)
            result = get_order_status(arguments["order_id"])

            conversation.append({
                "type": "function_call_output",
                "call_id": call.call_id,
                "output": json.dumps(result),
            })
    else:
        raise RuntimeError("The tool-call limit was reached.")

except BadRequestError as exc:
    print(f"Request rejected: {exc}")
    raise

该示例在处理示例订单状态后打印模型的最终答案。 该函数使用示例数据,而不是实时订单系统。 该循环将响应请求数限制为 3,如果模型继续请求工具,则引发错误。

保持加密的推理项不变;不要尝试读取或修改其加密的内容。 有关函数定义和工具结果格式,请参阅 函数调用。

路由注意事项

如果通过 Azure API 管理 进行路由,请先在所有已配置的后端中验证加密推理重播功能,再依赖它。 如果服务返回 invalid_encrypted_content,请在决定是否重启会话之前检查错误和资源路由。

数据保护注意事项

加密的推理项在请求之间携带不透明的推理上下文。 它们不描述服务如何加密存储的数据、哪些密钥保护存储的提示或聊天状态,或者应用程序必须存储返回的项的位置。

设置 store=false 并不能一概保证每个服务过程中的零保留期。 有关服务端存储和滥用监视详细信息,请参阅 Azure OpenAI 的数据、隐私和安全性。

图像生成

响应 API 支持将图像生成作为对话和多步骤工作流的一部分。 它支持上下文中的图像输入和输出,并包括用于生成和编辑图像的内置工具。

与独立映像 API 相比,响应 API 提供两个优势:

  • 流式处理:在生成过程中显示部分图像输出以提高感知延迟。
  • 灵活的输入:除了原始图像字节外,还接受图像文件 ID 作为输入。

注意

响应 API 中的图像生成工具受 gpt-image-1系列模型支持,可以从一组兼容的聊天和推理模型调用它。 有关支持的业务流程模型的当前列表,请参阅本文后面的 “支持的模型 ”部分。

图像生成工具目前不支持流式处理模式。 若要流式传输部分图像,请直接在响应 API 外部调用 图像生成 API 。

使用响应 API 通过 GPT 图像模型生成对话图像体验。

import base64
import os
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=token_provider,
    default_headers={
        "x-ms-oai-image-generation-deployment": os.getenv("IMAGE_MODEL_NAME"),
        "api_version": "preview",
    },
)

response = client.responses.create(
    model="MODEL_NAME",
    input="Generate an image of a gray tabby cat hugging an otter with an orange scarf.",
    tools=[{"type": "image_generation"}],
)

image_data = [
    output.result
    for output in response.output
    if output.type == "image_generation_call"
]

if image_data:
    with open("otter.png", "wb") as f:
        f.write(base64.b64decode(image_data[0]))

推理模型

有关如何将推理模型与响应 API 配合使用的示例,请参阅 推理模型指南。

计算机使用

Playwright 的计算使用已迁移至专用计算使用模型指南。

故障 排除

为什么我的 API 会话以预防措施结束?

使用 Astra 模型时,为了确保代理正确解释并按照说明进行操作,我们有一个系统在响应 API 中停止会话(如果检测到代理可能未正确解释指令),例如传输敏感数据、访问敏感数据或进行破坏性更改。 如果你的会话已结束,这并不一定意味着代理出错了,而只是说明值得审查代理的操作,以确保它正确理解并遵循了你的指示。

此系统监视哪些 API 请求?

上述同一系统在响应 API 中异步监视对 Astra 的请求。 此特定监视系统不会扫描聊天完成 API。 建议对代理用例使用响应 API,以达到最高性能和安全性。

如何检测此系统已在 API 中结束会话?

当安全系统检测到代理可能以重要方式错误地解释指令时,API 将返回安全注释代码不对齐强制。 在这种情况下,无法恢复给定会话。

如果检测到此类情况,我的应用程序该怎么办?

你可能想要考虑设置一些系统,以使某人能够查看代理在此类对话中执行的操作,例如,通过向最终用户提供 UI 进行评审。 在 API 中出于此原因停止对话后,将无法恢复对话。

解决常见 API 错误

使用以下指南解决常见的 API 错误:

  • 401/403:如果使用 Microsoft Entra ID,请验证是否针对 https://ai.azure.com/.default 确定了令牌范围。 如果使用 API 密钥,请确认你使用的是资源的正确密钥。
  • 404:确认 model 与部署名称匹配。