跳到主要内容

Protocols

文档导航​

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

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

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

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

1. 三种协议一览​

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

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

2. Base URL 规则​

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

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

2.1 配 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。

2.2 配客户端接入 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。

3. 每种协议各自说明​

chat-completions​

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

open-responses​

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

claude-messages​

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

4. Compat 规则​

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

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

当前实现里，chat-completions 和 claude-messages 都会读取并使用 compat。open-responses 当前仍不消费这些选项。

chat-completions 支持的 compat​

request_path​

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

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

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

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 请求头转发。

compat 示例​

chat-completions​

providers:
  - name: openai-compatible
    protocol: chat-completions
    base_url: https://your-openai-compatible.example.com
    compat:
      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"

5. 协议转换说明​

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

这意味着：

  • 客户端请求 /v1/chat/completions，可以转发到 open-responses 或 claude-messages
  • 客户端请求 /v1/responses，也可以转发到 chat-completions
  • 客户端请求 /v1/messages，也可以转发到其他两种协议

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