跳到主要内容

Responses API 代理

Responses API 是 OpenAI 面向使用输入/输出项格式而不是 Chat Completions 消息格式的应用提供的响应生成端点。AISIX AI 网关为 Responses API 客户端暴露该路由，同时将调用方认证、模型别名、上游凭证和网关策略保留在网关中。

当应用或工具已经使用 Responses API 时，请使用该路由。当模型的上游自身提供 Responses API 时，AISIX 会把请求转发过去；否则 AISIX 会通过服务提供方适配器转换请求，并向调用方返回 Responses API 结果。

准备工作​

请先准备以下内容：

  • 一个可以处理代理请求的 AISIX 网关。
  • 一个可以访问该模型别名的调用方 API Key。
  • 一个由可处理转换后请求形态的服务提供方支撑的模型别名。

导出网关连接和请求值：

# AISIX_PROXY 末尾不含斜杠，也不包含 /v1 等端点路径。
# 本地快速入门使用 http://127.0.0.1:3000。
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="gpt-4o-prod"

发送 Responses 请求​

通过网关代理发送请求，并在请求体中使用 AISIX 模型别名：

curl -sS -X POST "${AISIX_PROXY}/v1/responses" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${AISIX_MODEL}"'",
    "input": "Say hello from AISIX."
  }'

AISIX 会解析模型别名，并为选中模型选择服务提供方适配器和上游目标。OpenAI 上游模型不会转换 body，而是直接转发到上游 Responses API。其它服务提供方会使用跨服务提供方桥接。

响应体会以 Responses API 格式返回：

{
  "id": "resp_***",
  "object": "response",
  "model": "gpt-4o-prod",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Hello from AISIX."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 5,
    "total_tokens": 17
  }
}

服务提供方行为​

AISIX 通过两种方式处理 Responses 请求：

上游行为
提供 Responses APIAISIX 将请求 model 改写为上游模型 ID，并将请求转发到上游 Responses API。当上游支持时，上游专属 Responses 能力会透传。
不提供AISIX 将受支持 Responses 字段转换为网关聊天格式，通过服务提供方适配器调度，并返回 Responses API 结果。

走哪一条按服务提供方密钥逐个决定。没有协议面声明时，AISIX 对 openai 服务提供方原生转发，对其它服务提供方一律转换。这个默认判断对某些端点在两个方向上都会出错：通过 openai 服务提供方 + 自定义 api_base 接入的 OpenAI 兼容端点可能根本没有 /v1/responses，而其它服务提供方的端点反而可能有。声明该密钥的 API 协议面即可说明属于哪一种，见声明 API 协议面。

桥接路径支持常见的文本、工具调用、工具结果、采样和流式字段。它会把 reasoning.effort 带入规范化聊天请求的 reasoning_effort；支持推理力度控制的服务提供方适配器再将其转换为对应的线上字段。例如，Anthropic 收到的是 output_config.effort。你还可以通过推理力度映射按直连模型重写该值。只属于 OpenAI Responses、且没有服务提供方中立聊天等价语义的能力，不会在桥接路径中转发。

经过转换的请求会忽略以下字段：

  • reasoning 中除 effort 外的成员，例如 summary
  • store
  • previous_response_id
  • web_search、file_search、code_interpreter 等托管工具
  • text、metadata、service_tier 以及其它 OpenAI 专属控制项

策略与用量行为​

输入安全护栏可以在 AISIX 调用服务提供方之前检查请求文本。输出安全护栏可以在非流式响应到达调用方之前检查响应内容。

如果输出安全护栏阻断响应，AISIX 会向调用方返回内容策略错误，并记录该阻断请求以便观测。

对于流式请求，AISIX 会保持 Responses SSE 形态。OpenAI 上游模型可以直接透传上游 SSE；桥接服务提供方时，AISIX 会把服务提供方流式分片编码为 Responses 事件。如果启用了输出安全护栏，AISIX 会先缓冲流内容进行策略检查，再决定返回或阻断。缓冲区中 AISIX 无法解析的帧会被丢弃，而不是未经扫描就放行；如果因此没有任何内容可返回，响应会被以 422 拒绝。参见 AISIX 无法扫描的帧。

对于成功响应，当上游响应包含 Token 用量时，网关会记录用量。流式用量会在 AISIX 从流中收到终止用量信息后发出。

对于 Token 计数方式与 OpenAI 不同的桥接服务提供方，AISIX 会将计数转换为 Responses API 的形式：input_tokens 是完整输入，input_tokens_details.cached_tokens 是其中缓存读取的子集，input_tokens_details.cache_creation_tokens 是缓存写入的子集（仅在上游报告了写入时出现），total_tokens 等于 input_tokens + output_tokens。以 Anthropic 上游为例的完整说明，请参阅 Token 用量——那里用的是 Chat Completions 的字段名，与这里一一对应（prompt_tokens 对应 input_tokens，completion_tokens 对应 output_tokens，prompt_tokens_details 对应 input_tokens_details，completion_tokens_details 对应 output_tokens_details）。有一处形态差异：output_tokens_details.reasoning_tokens 在 Responses 响应中恒存在，包括值为 0 时；而 Chat Completions 会整块省略。

下一步​

你已经了解何时通过 AISIX 使用 Responses API，以及直接转发和桥接时的服务提供方处理差异。旧版 completions 路由请继续阅读文本补全；如果 Responses API 客户端依赖 SSE 行为，请继续阅读流式响应。