合议模型

合议模型让调用方只使用一个模型别名，由 AISIX 请求多个合议成员生成候选响应，再请求评审模型合成最终答案。调用方发送一个请求，并在所请求的别名下收到一个答案。分发与合成都在网关内部完成。

在 AISIX 中，合议模型是一种模型别名，AISIX 通过调用多个直接模型来解析它，与路由组和语义路由器类似。它不直接指向某个上游模型，而是通过 ensemble 配置告诉 AISIX：调用哪些直接模型作为合议成员，以及用哪个直接模型作为评审模型。

合议模型包含两部分：

• 合议成员并发调用，各自生成独立的候选响应。
• 评审模型接收成功的合议成员响应，合成返回给调用方的单一响应。

合议成员和评审模型都必须引用已存在的直接模型。请在这些直接模型上配置服务提供方凭据、上游模型名称、健康行为、冷却行为和子调用限流。

合议成员和评审模型收到的是 Chat Completions 请求，因此它们的服务提供方必须提供 Chat Completions。AISIX Enterprise 和 AISIX Cloud 均不允许不提供 Chat Completions 的模型（例如使用 jina、runwayml 或 typesafe 服务提供方密钥的模型）作为成员或评审模型，也不允许把被合议模型引用的直接模型换到这类密钥上。使用 typesafe 密钥的决策模型应通过 /v1/systemone 和 /v1/decisions 访问。

适用场景与取舍

合议模型用额外的模型调用换取额外的合成步骤。它可以提高某些工作负载的答案质量或一致性，但代价是更高的延迟和开销。

当候选答案的多样性和评审步骤可能有所帮助时，可以使用合议模型：

• 降低单模型的波动并暴露盲区。独立的候选答案为评审模型提供更多可比较的依据。
• 对高难度的推理或研究类提示词做交叉验证。不同模型可能沿不同路径得出答案，另一个候选响应往往能暴露其中的错误。
• 单一服务提供方下的自合议。合议成员可以是同一个直接模型的多次重复，各次使用不同的 temperature 和 seed，这样只有一个服务提供方密钥的团队，无需引入新厂商也能获得答案多样性。

合议模型并不能保证答案更准确。合议成员可能重复同一个错误，共识也可能出错，评审模型也可能选中或引入错误。在生产环境使用合议模型前，请在针对具体任务的评估集上将它与直接模型基线进行比较。评估集应包含有代表性的失败案例，并衡量答案质量、延迟、Token 用量和成本。

合议模型会向每个合议成员各发一个请求，再调用评审模型，因此并不适合所有场景。以下情况请改用其他模型类型：

• 对延迟敏感、以流式优先的链路。首个 Token 到达时间天然偏高，原因见流式与调用方响应一节。
• 使用工具或函数调用的请求。这类请求不受支持，受支持的请求形态见安全护栏与请求约束。
• 高流量、对成本敏感的流量，此时经评估的收益不足以抵消额外开销。
• Chat Completions 以外的端点。合议模型仅支持聊天。

这些情况请改用直接模型或多目标模型。多目标模型每次请求只选一个目标，而合议模型会调用全部合议成员，并综合它们的输出。

请求流程

合议请求从一个模型别名进入。AISIX 把请求并发分发给配置的合议成员，将成功的成员响应交给评审模型，最终只返回评审模型合成的答案。

对于每个聊天请求，AISIX 会执行以下阶段：

1. 分发给合议成员。AISIX 把提示词并发分发给每个合议成员，并套用各成员各自的 temperature 和 seed 覆盖值。
2. 收集成功响应。AISIX 等待合议成员调用完成或超时，保留成功的答案，并检查其数量是否满足 min_responses。否则，请求按失败处理中的行为处理。
3. 合成最终答案。AISIX 用原始请求和已收集的答案构造合成提示词，再以固定的低 temperature 调用评审模型。评审模型的输出在合议模型别名下返回给调用方。

只要仍满足 min_responses，个别缓慢或失败的合议成员不会导致整个请求失败。合议成员和评审模型调用都使用其所引用直接模型上配置的重试预算。

成本与延迟

合议模型的成本更高，通常也比直接模型或多目标模型更慢，因为每个请求可能触发多次上游调用。

成本是各子调用之和：

ensemble cost ≈ sum(panel member costs) + judge cost

三个合议成员加一个评审模型，会把提示词处理四次，评审模型还要额外处理所有成员答案。面向调用方的 usage 反映的正是这一真实成本，见用量核算。

延迟主要由最慢的合议成员加上评审模型决定：

ensemble latency ≈ max(panel member latency) + judge latency

由于评审模型必须等合议成员返回后才能开始，首个 Token 到达时间天然偏高——在合成开始前没有任何 Token 可供流式输出。

提示

保持合议成员数量较少（两到四个），选一个响应快的评审模型，并设置 timeout_ms，避免某个卡住的成员拖慢整个请求。

准备工作

开始前，请准备以下资源：

• 至少一个可用作合议成员的直接模型，以及一个可用作评审模型的直接模型。同一个直接模型可以同时担任这两个角色。
• 一个可以调用合议模型别名的调用方 API Key。
• 对于 AISIX Enterprise 或 AISIX Cloud，需要一个已接入网关的环境，以及管理模型和调用方 API Key 的权限。
• 对于开源 AISIX 网关，需要有权访问声明式资源文件和网关进程。

配置合议模型

请先创建直接合议成员模型和评审模型，再创建合议模型。控制面通过模型 ID 引用它们；开源 AISIX 网关则在声明式资源文件中通过 display_name 引用它们。

AISIX Enterprise 或 AISIX Cloud

导出控制面连接信息和直接模型 ID：

# AISIX_CP 是 Admin API 基础 URL；应包含 /api，且末尾不要带斜杠。
# 本地 AISIX Enterprise 快速入门使用 http://localhost:8080/api。
export AISIX_CP="YOUR_AISIX_CONTROL_PLANE_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"
export PANEL_A_MODEL_ID="YOUR_FIRST_PANEL_MODEL_ID"
export PANEL_B_MODEL_ID="YOUR_SECOND_PANEL_MODEL_ID"
export JUDGE_MODEL_ID="YOUR_JUDGE_MODEL_ID"

创建合议模型并记录其 ID：

ENSEMBLE_MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "ensemble",
    "display_name": "research-ensemble",
    "ensemble": {
      "panel": [
        {
          "model_id": "'"$PANEL_A_MODEL_ID"'",
          "temperature": 0.7
        },
        {
          "model_id": "'"$PANEL_B_MODEL_ID"'",
          "temperature": 0.9
        }
      ],
      "judge": {
        "model_id": "'"$JUDGE_MODEL_ID"'"
      },
      "min_responses": 2,
      "timeout_ms": 30000
    }
  }' | jq -r '.model.id')

将 ENSEMBLE_MODEL_ID 添加到调用方 API Key 的 allowed_models 列表。

你也可以在控制台的 Models 页面创建和编辑合议模型。表单提供合议成员选择器、评审模型选择器，以及采样、最少成功响应数和超时设置。

开源 AISIX 网关

将合议模型添加到 models 集合。合议成员和评审模型引用使用直接模型的 display_name：

resources.yaml（合议模型）

models:
  - display_name: research-ensemble
    ensemble:
      panel:
        - model: gpt-4o-panel
          temperature: 0.7
        - model: claude-panel
          temperature: 0.9
      judge:
        model: gpt-4o-judge
      min_responses: 2
      timeout_ms: 30000

完整资源文件还必须包含被引用的直接模型及其服务提供方密钥。将 research-ensemble 添加到调用方密钥的 allowed_models，然后验证并重新加载该文件。

验证合议模型

导出所配置部署的网关 URL 和调用方 API Key：

# 使用网关源地址，不要附加末尾斜杠或端点路径。
# 本地快速入门使用 http://127.0.0.1:3000。
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"

在 Chat Completions 端点上调用 research-ensemble：

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer $AISIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "research-ensemble",
    "messages": [
      {
        "role": "user",
        "content": "In one sentence, what is an API gateway?"
      }
    ]
  }' \
  | jq '{model, choices: (.choices | length), total_tokens: .usage.total_tokens}'

成功的响应会在合议模型别名下包含一个合成后的答案：

{
  "model": "research-ensemble",
  "choices": 1,
  "total_tokens": 508
}

total_tokens 是合议成员和评审模型调用的合计值。

配置合议行为

每个合议成员都必须引用一个直接模型，并可为该次调用设置 temperature 或 seed。同一个直接模型可以出现多次，从而以不同的采样设置实现自合议。可选的 weight 字段为未来的投票策略预留，目前不起作用。

评审模型必须引用一个直接模型，并可设置自定义 synthesis_prompt。为保证合成稳定，评审模型始终以固定的低 temperature 运行。

min_responses 控制评审模型运行前必须成功的合议成员调用数量。省略时，AISIX 要求的响应数为两个响应与合议成员数量两者中的较小值。控制面会拒绝大于合议成员数量的值；在开源资源文件中，运行时会把更大的值限制为合议成员数量。如果成功数量低于实际最小值，请求会失败，而不会依据过少的证据进行合成。

timeout_ms 是每个合议成员和评审模型调用的可选上游截止时间。它在被引用直接模型自身的超时之外生效。将其设为 0 或省略即可禁用合议级截止时间。

调优

通过调整合议成员数量、各成员采样参数、最少成功响应数以及单次调用超时来调优合议模型。

目标	调整方式
提升答案多样性	使用不同的成员模型，或把各成员的 temperature 拉开差距，例如 0.5、0.7、0.9。
结果可复现	为每个成员设置 seed，并搭配选定的 temperature。
单一服务提供方下的多样性	把同一个 model 以不同的 temperature 和 seed 重复两到三次。
容忍成员失败	多加一两个合议成员，并让 min_responses 低于成员数量，这样个别成员失败不至于让请求失败。
限制尾延迟	把 timeout_ms 设为可接受的单次调用上限；缓慢的成员会被丢弃，只要仍满足 min_responses，流程就继续。
降低成本	缩减合议成员、选更便宜的评审模型。任一调整后都需要重新评估答案质量。

评审合成

评审模型会把原始请求和成功的合议成员答案作为一条消息接收。候选答案以中性标签标注（Answer 1、Answer 2 等），不带合议成员的模型名称，这样运维方选用的服务提供方和模型就不会出现在合成后的响应里。

每个候选答案在送入评审模型前都会被限制长度，因此再大的合议也不会撑爆评审模型的上下文窗口——超长答案会被截断，而不是丢弃。

默认的合成指令要求评审模型：把候选答案当作证据、优先采纳共识、用推理化解矛盾、舍弃缺乏依据的说法，并只返回最终答案。这些是生成指令，并不是对说法正确性的独立检查。响应沿用用户要求的语言和格式，且不会提及背后有多个模型参与。

自定义评审提示词

自定义合成提示词会替换默认指令，同样可以包含 {original_request} 和 {labeled_candidates} 占位符。可以用它给评审模型下达领域特定的评判标准：

{
  "display_name": "code-council",
  "ensemble": {
    "panel": [
      { "model": "model-a" },
      { "model": "model-b" }
    ],
    "judge": {
      "model": "model-a",
      "synthesis_prompt": "You are a senior reviewer. From the candidate solutions, produce one correct, secure, idiomatic answer. Prefer code that compiles and handles edge cases. Output only the final code and a one-line rationale.\n\nRequest:\n{original_request}\n\nCandidates:\n{labeled_candidates}"
    }
  }
}

如果自定义合成提示词省略了 {original_request} 或 {labeled_candidates}，就收不到对应内容。当评审模型需要原始请求和候选答案时，请把这两个占位符都包含进去。

合议模式

创建出基本的合议模型后，可以按以下常见模式调整合议成员和评审模型的配置。以下示例使用开源资源文件中的直接模型名称；在 AISIX Enterprise 和 AISIX Cloud 中，请改用相应的 model_id 字段和模型 ID。

跨服务提供方合议

从不同服务提供方选取合议成员，并用一个推理能力强的模型作评审模型，以提高候选答案的多样性：

{
  "panel": [
    { "model": "model-a" },
    { "model": "model-b" },
    { "model": "model-c" }
  ],
  "judge": { "model": "model-b" },
  "min_responses": 2
}

单一服务提供方的自合议

在不引入额外厂商的前提下，用不同 temperature 重复同一个模型，从单个模型获得答案多样性：

{
  "panel": [
    { "model": "model-a", "temperature": 0.4, "seed": 1 },
    { "model": "model-a", "temperature": 0.7, "seed": 2 },
    { "model": "model-a", "temperature": 1.0, "seed": 3 }
  ],
  "judge": { "model": "model-a" }
}

成本受限的合议

使用两个合议成员、一个更便宜的评审模型和一个较紧的超时，在限制额外成本的同时评估合议模型：

{
  "panel": [
    { "model": "model-a" },
    { "model": "model-b" }
  ],
  "judge": { "model": "model-b" },
  "min_responses": 1,
  "timeout_ms": 20000
}

运行时行为

AISIX 接受合议请求后，调用方看到的仍是一个模型响应。与直接模型的差异体现在流式、用量核算、遥测、限流和失败处理上。

流式与调用方响应

合议模型接受 stream: true，但合议成员阶段不会流式传输。AISIX 等待合议成员调用完成或超时，检查 min_responses，再只把评审模型的输出流式发给调用方。

在合议成员阶段，连接不发送任何字节，包括 keep-alive 帧。请把客户端读取超时设得足以容纳最慢的合议成员，再加上评审模型发出首个 Token 前的时间。评审模型开始流式输出后，AISIX 会发送 SSE keep-alive 帧来保持连接。通用的流式行为见流式传输。

面向调用方的响应完整保留合议这层抽象。response.model 回显调用方请求的合议模型别名，响应不会暴露合议成员别名、评审模型或上游服务提供方的模型 ID。合议模型和直接模型一样，会出现在 GET /v1/models 列表中。

用量核算

响应的 usage 对象是每次合议成员调用加上评审模型调用的合计。它反映请求的真实成本，因此 prompt_tokens 可能远大于调用方实际发送的 Token 数：每个合议成员都要处理提示词，评审模型则同时处理提示词上下文和成员答案。

在流式请求中，这个合计只会在末尾的 usage 分片里返回，并且仅当调用方设置了 stream_options.include_usage: true 时才会出现；否则流式响应不带 usage，与直接模型完全一致。

子调用遥测

每个子调用都会发出自己的用量事件，因此可以按合议成员和评审模型分别归因成本与延迟。同一个请求的所有事件共享同一个 request ID。

字段	取值
attempt_kind	合议成员为 panel，评审模型调用为 judge。
attempt_index	该成员在合议中的槽位。评审模型最后运行，其 index 等于合议成员数量。调用方放弃的请求中，已返回的子调用改为连续编号，见下文。
attempt_model	该子调用的模型 display_name。
prompt_tokens、completion_tokens	该子调用自身的 Token 计数。

一个三成员的合议模型会产生四个用量事件——三个合议成员事件加一个评审模型事件——此外还有返回给客户端的合计。用这些事件可以看出哪个成员慢、哪个成员贵。

请求失败时，例如回答的合议成员不足、评审模型失败或输出安全护栏拦截了回答，合议成员和评审模型的事件之后会跟一条位于下一个 attempt_index 的最终事件，其 attempt_kind 为空。

调用方中途断开时，已经返回的每个合议成员和评审模型调用仍会发出自己的事件。这些事件从该请求的下一个 attempt_index 起连续编号，之后是 499 事件。它们的 Token 会像完成的请求一样，计入面向调用方各作用域的 Token 限流。遥测细节见指标与用量事件和可观测性导出器。

限流

限流作用于两个层面：

• 调用方 API Key 和合议模型别名上的限流对面向调用方的请求生效一次。在 AISIX Enterprise 和 AISIX Cloud 中，适用的团队和成员限流也只生效一次。在这些作用域中，一个合议请求计为一个请求。
• 模型级限流作用于每个被引用的合议成员和评审模型。超出自身模型限流的合议成员会成为失败的子调用，并在计算 min_responses 时被丢弃；只要其他成员作答足够，请求仍然成功。超出自身模型限流的评审模型则会以 429 让请求失败。

请在合议模型别名上设置限流以控制面向调用方的请求，并在底层直接模型上设置限流以控制各个子调用。资源关联限制的配置详情请参阅 API Key 与模型限流，团队、成员或条件配额的配置详情请参阅限流策略。

安全护栏与请求约束

适用的输出安全护栏作用于合成后的答案，也就是评审模型的输出，而不是每个合议成员的响应。因此，面向调用方的结果反映的是对应用最终收到答案所做的检查。安全护栏配置见安全护栏。

附加到某个合议成员、或附加到评审模型上的安全护栏，都不会在合议请求上运行。安全护栏的作用范围由调用方寻址的模型决定，这里就是合议模型本身，因此要筛查经由合议模型进入的流量，请把安全护栏附加到合议模型上。参见安全护栏作用范围由调用方寻址的模型决定。

合议模型还有以下请求形态约束：

• 仅支持聊天。合议模型只在 /v1/chat/completions 上受支持；其他任何端点都会以 400 拒绝合议模型，并指明该模型及仅支持聊天的约束。
• 不支持工具。携带非空 tools 数组，或携带强制调用的 tool_choice 的请求会被以 400 拒绝——把一次强制的工具调用广播给多个合议成员，会产生调用方无法调和的相互冲突的工具调用。空的 tools: []，或 tool_choice 取值为 none、auto，视为没有工具并被接受。
• 仅限直接模型。在 AISIX Enterprise 和 AISIX Cloud 中，合议成员和评审模型必须是同一环境中的直接模型；在开源资源文件中，它们必须是同一文件中的直接模型。合议模型不能嵌套，也不能使用路由、语义或合议目标。
• 由配置驱动。没有按请求覆盖合议成员的方式，调用方只能通过模型名称选择合议模型。

失败处理

条件	行为	客户端状态码
一个或多个合议成员缓慢或失败，但仍满足 min_responses	合成基于已到达的答案继续，失败的成员被丢弃。	200
成功的合议成员响应少于 min_responses	请求失败——AISIX 拒绝基于过少的依据勉强合成。	502
某个合议成员超出自身模型限流	视为失败的子调用，在计算 min_responses 时被丢弃。	其他成员作答足够则 200，否则 502
评审模型调用在完成其配置的重试后仍失败	请求失败。评审模型的配置或凭证错误（4xx）会被保留，上游 5xx 归并为 502。	4xx / 502
评审模型超出自身模型限流	请求失败。	429
请求包含工具，或指向非聊天端点	在分发之前即被拒绝。	400

下一步

继续阅读代理错误与重试了解面向调用方的失败。对于 AISIX Enterprise 或 AISIX Cloud，请通过用量报告查看子调用用量。如果合议子调用遥测需要离开 AISIX，请使用可观测性导出器。