跳到主要内容

Protocols

Aidy 当前支持四种上游协议：

  • chat-completions
  • open-responses
  • claude-messages
  • bedrock-runtime

这里的 protocol 不是独立资源，而是 Provider.protocol 字段。

  • 想看 provider / upstream / protocol 的职责边界，请看 Upstream / Provider / Protocol
  • 这篇文档只回答三件事：
    • 每种协议对应什么请求路径
    • base_url 应该怎么配
    • compat 当前哪些协议真的会生效

四种协议一览​

protocol入站路径出站路径base_url 配置规则
chat-completions/v1/chat/completions/chat/completionsbase_url 需要带 /v1
open-responses/v1/responses/responsesbase_url 需要带 /v1
claude-messages/v1/messages/v1/messagesbase_url 不要带 /v1
bedrock-runtime无直接入站路径/model/{modelId}/converse 或 /model/{modelId}/converse-streambase_url 不要带 /v1，应为区域 Bedrock Runtime origin

上表里的“入站路径”是 Aidy 对外暴露的实际路径；“出站路径”是 Aidy 转发到上游时拼接的目标路径。

Base URL 规则​

base_url 最容易混淆，因为不同协议所使用的 base url 不完全相同

  1. Aidy 所配置的 <prefix> 均不含 /v1
  2. 有的协议在配置 Base URL 时需要带 /v1、有的不需要

配 Provider / Upstream 时​

这是 Management API / seed / 数据库里的 provider.base_url 或 upstream.base_url。

chat-completions​

应配置成带 /v1 的标准 OpenAI Base URL，例如：

  • https://api.openai.com/v1
  • https://your-openai-compatible.example.com/v1

Aidy 会在这个 base_url 后面继续拼 /chat/completions。

open-responses​

规则和 chat-completions 一样，也应配置成带 /v1 的版本，例如：

  • https://api.openai.com/v1
  • https://your-openai-compatible.example.com/v1

Aidy 会在这个 base_url 后面继续拼 /responses。

claude-messages​

这里要特别注意：base_url 不要带 /v1，例如：

  • https://api.anthropic.com
  • https://your-claude-compatible.example.com

Aidy 会在这个 base_url 后面继续拼 /v1/messages。

如果把 claude-messages 的 base_url 错配成带 /v1 的版本，例如 https://api.anthropic.com/v1，最终请求路径会变成 /v1/v1/messages。

bedrock-runtime​

bedrock-runtime 是仅出站 upstream 协议，不提供独立入站路径。客户端仍请求 Aidy 的 /v1/chat/completions、/v1/responses 或 /v1/messages，Aidy 会把请求转换为 Bedrock Runtime Converse API。

base_url 应配置为区域 Bedrock Runtime origin，例如：

  • https://bedrock-runtime.us-east-1.amazonaws.com

Aidy 会根据 resolved upstream model 拼接：

  • 非流式：/model/{modelId}/converse
  • 流式：/model/{modelId}/converse-stream

配客户端接入 Aidy 时​

这里说的是“你的 AI 客户端如何配置 Aidy 的 Base URL”。

Aidy 实际对外暴露的路径始终是：

  • <aidy-base>/<prefix>/v1/chat/completions
  • <aidy-base>/<prefix>/v1/responses
  • <aidy-base>/<prefix>/v1/messages

但不同客户端对“Base URL”的定义不同：

  • OpenAI 风格客户端通常把 Base URL 理解为请求前缀，自己只再拼 /chat/completions 或 /responses
  • Claude 风格客户端通常把 Base URL 理解为域名或前缀，自己再拼 /v1/messages

但是，有部分客户端对于 Base URL 是否带 /v1 的理解不同，因此建议在遇到问题时手动增删 /v1 来测试。

备注

对 Aidy 来说，真正收到的请求路径仍然必须是带 /v1 的版本。
如果实际入站请求缺少 /v1 前缀，Aidy 会返回 462。

每种协议各自说明​

chat-completions​

  • 入站子路径：/chat/completions
  • 上游请求路径：/chat/completions
  • 典型上游：OpenAI 兼容接口
  • base_url：应配置为带 /v1 的版本
  • 可通过 compat.chat_request_path 覆盖出站 path

open-responses​

  • 入站子路径：/responses
  • 上游请求路径：/responses
  • 典型上游：OpenAI Responses API 兼容接口
  • base_url：应配置为带 /v1 的版本

claude-messages​

  • 入站子路径：/messages
  • 上游请求路径：/v1/messages
  • 典型上游：Anthropic Messages API 兼容接口
  • base_url：应配置为不带 /v1 的版本

bedrock-runtime​

  • 入站子路径：不支持直接作为入站协议
  • 上游请求路径：/model/{modelId}/converse 或 /model/{modelId}/converse-stream
  • 典型上游：AWS Bedrock Runtime Converse API
  • base_url：应配置为区域 Bedrock Runtime origin，不带 /v1
  • 鉴权：使用当前 upstream api key 作为 Authorization: Bearer <key>
  • 流式响应：只解析 Bedrock ConverseStream 的 AWS event stream wire format，不支持 text/event-stream fallback

Compat 规则​

compat 字段是 Aidy 用来配置协议兼容性的。即使是同一协议，不同的上游可能也有不同的配置需求，这通常包括两方面：

  • 供应商本身支持或不支持某些协议本身的功能
  • 配置时期望启用或禁用某些协议本身的功能

当前实现里，chat-completions 和 claude-messages 都会读取并使用 compat。open-responses 与 bedrock-runtime 当前仍不消费这些选项，但保留独立 compat message 作为后续扩展合约。

chat-completions 支持的 compat​

chat_request_path​

  • 类型：string
  • 作用：覆盖发往上游的请求 path
  • 默认值：/chat/completions
  • 约束：
    1. 必须是以 / 开头的非空 path
    2. 不支持绝对 URL
    3. 不支持把 query string 写进这个字段

这个配置只影响 Aidy 转发到上游时的目标 path，不会改变 Aidy 自己对外暴露的入站路径；客户端仍然请求 /v1/chat/completions。

请勿把 chat_request_path 配成 /v1/chat/completions 这类自带版本前缀的值；否则最终会变成 /v1/v1/chat/completions。

always_include_usage​

  • 类型：boolean
  • 默认值：true
  • 作用：为流式 chat-completions 上游请求自动添加 stream_options.include_usage = true

当配置为 true 或未配置时，Aidy 会在协议转换和同协议透传时都自动补上 usage option。配置为 false 时，同协议透传保持原始请求不变；但其它协议转换到 chat-completions 时仍会自动补上该 option。

map_developer_role_to_system​

  • 类型：boolean
  • 默认值：false
  • 作用：把转发给上游的 developer role 改写为 system role

OpenAI Chat Completions 已支持 developer role，因此默认会原样转发。只有遇到不支持 developer role 的兼容上游时，才需要把这个选项配置为 true。

map_message_roles​

  • 类型：Record<string, string>
  • 默认值：未配置
  • 作用：按映射表改写发往上游的 Chat Completions messages[].role

例如 {"developer":"user"} 会把所有出站 developer 消息改写为 user。

map_developer_role_to_system 是历史兼容字段，新配置优先使用 map_message_roles。

claude-messages 支持的 compat​

anthropic_version​

  • 类型：string
  • 作用：覆盖发往上游的 anthropic-version 请求头
  • 默认值：2023-06-01
  • 优先级：
    1. compat.anthropic_version
    2. 入站请求头 anthropic-version
    3. 默认值 2023-06-01

anthropic_beta​

  • 类型：string 或 string[]
  • 作用：设置一个或多个 anthropic-beta 请求头
  • 优先级：
    1. compat.anthropic_beta
    2. 入站请求头 anthropic-beta

如果 compat.anthropic_beta 是数组，Aidy 会把每个元素都作为独立的 anthropic-beta 请求头转发。

bedrock-runtime 的 compat​

第一版没有可配置字段。后续如果要支持 IAM/SigV4 或 Bedrock 特有开关，会在这个 message 下扩展。

compat 示例​

chat-completions​

providers:
  - name: openai-compatible
    protocol: chat-completions
    base_url: https://your-openai-compatible.example.com
    compat:
      chat_request_path: /v1/chat/completions

claude-messages​

providers:
  - name: anthropic
    protocol: claude-messages
    base_url: https://api.anthropic.com
    compat:
      anthropic_version: "2023-06-01"
      anthropic_beta:
        - "tools-2024-05-16"
        - "prompt-caching-2024-07-31"

bedrock-runtime​

providers:
  - name: bedrock
    protocol: bedrock-runtime
    base_url: https://bedrock-runtime.us-east-1.amazonaws.com

协议转换说明​

在 chat 主链路里，Aidy 当前是先把入站请求解析成统一 IR，再按目标 provider.protocol 组装出站请求。

这意味着：

  • 客户端请求 /v1/chat/completions，可以转发到 open-responses、claude-messages 或 bedrock-runtime
  • 客户端请求 /v1/responses，也可以转发到 chat-completions、claude-messages 或 bedrock-runtime
  • 客户端请求 /v1/messages，也可以转发到 chat-completions、open-responses 或 bedrock-runtime

具体职责边界与运行时解析流程，请看：