跳到主要内容

常见上游问题

这里记录协议兼容上游的已知差异，以及在 Aidy 里应该如何配置。

MiniMax OpenAI-compatible API​

MiniMax 的 OpenAI-compatible API 使用 Chat Completions 形态。Aidy 侧应按 chat-completions provider 配置：

providers:
  - id: minimax
    name: MiniMax
    protocol: chat-completions
    base_url: https://api.minimax.io/v1
    compat:
      map_developer_role_to_system: true

国内账号或国内网络环境可按 MiniMax 文档改用国内 endpoint：

base_url: https://api.minimaxi.com/v1

如果只想让某个 tenant / upstream 使用这个兼容规则，也可以把 compat 放在对应 upstream 上：

upstreams:
  - id: minimax-main
    provider_id: minimax
    name: MiniMax main
    compat:
      map_developer_role_to_system: true

为什么需要这个配置​

OpenAI Chat Completions 已支持 developer role，但 MiniMax OpenAI-compatible API 的官方示例仍使用 system / user 消息，并且部分客户端（例如 Codex 通过 Responses API 接入时）会在协议转换后生成 developer 消息。

如果上游返回类似下面的错误：

upstream returned status 400: invalid params, invalid role: developer

说明请求已经正确转发到 MiniMax，但出站 Chat Completions 消息里的 developer role 没有被该上游接受。开启 map_developer_role_to_system 后，Aidy 会在发往 chat-completions 上游前把 developer 消息改写为 system 消息。

不要这样配​

不要把 base_url 写成完整 endpoint：

base_url: https://api.minimax.io/v1/chat/completions

Aidy 会自动在 base_url 后拼接 /chat/completions。对 MiniMax 应保留到 /v1：

base_url: https://api.minimax.io/v1