智能调度

智能调度用于在同一个虚拟模型对应的多个候选模型或多个 provider 之间，按价格、吞吐、延迟和 provider 白名单/黑名单等条件自动选择更合适的调用目标。

概念解释：
虚拟模型：模型广场中展示的模型均为虚拟模型，背后可能有一至多个真实的供应商。
供应商模型/真实模型/候选模型：均指真实的供应商模型，大模型调用真正的请求目标。

当一个虚拟模型背后配置了多个可用候选时，系统会先生成候选集，再根据请求中的智能路由参数过滤和排序，最终选择一个候选发起请求。你可以用它来控制成本、提升响应速度、避开指定 provider，或只允许请求落到某些 provider 上。

使用方式

在请求体中增加 provider 对象，并在其中传入智能路由参数。

{
  "model": "your-virtual-model",
  "messages": [
    {
      "role": "user",
      "content": "你好"
    }
  ],
  "provider": {
    "sort": "price",
    "max_price": {
      "prompt": 0.01,
      "completion": 0.03
    }
  }
}

provider 中的参数不会改变用户请求的模型语义，它们只影响虚拟模型候选集的筛选和排序。

路由流程

智能路由的处理过程可以理解为四步：

根据请求中的 model 找到该虚拟模型下的所有候选。

使用 only、ignore、max_price、preferred_min_throughput、preferred_max_latency 等参数过滤候选集。

使用 sort 对剩余候选排序。

按排序结果选择最终候选并发起请求。

如果过滤条件过严，可能导致没有候选可用，请求将无法完成。因此，强约束参数应谨慎使用。

支持的参数

参数	类型	作用
`max_price`	`object`	限制候选 provider 的最高价格
`preferred_min_throughput`	`number`	限制候选 provider 的最低吞吐
`preferred_max_latency`	`number`	限制候选 provider 的最高延迟
`only`	`string[]`	只允许指定 provider 进入候选集
`ignore`	`string[]`	排除指定 provider
`sort`	`string`	控制最终候选的排序策略

`max_price`

max_price 用于限制单次请求可接受的最高价格。当前支持 prompt 和 completion 两个维度。

{
  "provider": {
    "max_price": {
      "prompt": 0.01,
      "completion": 0.03
    }
  }
}

字段说明：

字段	说明
`prompt`	输入价格上限
`completion`	输出价格上限

匹配规则：

如果设置了 prompt，候选的输入价格必须小于或等于该值。

如果设置了 completion，候选的输出价格必须小于或等于该值。

两个维度都设置时，候选必须同时满足两个条件。

没有设置的维度不参与限制。

价格单位与系统中模型价格配置的单位保持一致。

示例：只使用输入价格不超过 0.01、输出价格不超过 0.03 的候选。

{
  "model": "your-virtual-model",
  "messages": [
    {
      "role": "user",
      "content": "请总结这段内容"
    }
  ],
  "provider": {
    "max_price": {
      "prompt": 0.01,
      "completion": 0.03
    }
  }
}

`preferred_min_throughput`

preferred_min_throughput 用于限制候选 provider 的最低吞吐。只有吞吐大于或等于阈值的候选会被保留。

{
  "provider": {
    "preferred_min_throughput": 50
  }
}

匹配规则：

候选的 throughput 必须大于或等于设置值。

不传该参数时，不限制吞吐。

吞吐单位与系统统计指标保持一致，通常可理解为 tokens/s。

示例：只使用吞吐不低于 50 的候选。

{
  "model": "your-virtual-model",
  "messages": [
    {
      "role": "user",
      "content": "写一段产品介绍"
    }
  ],
  "provider": {
    "preferred_min_throughput": 50,
    "sort": "throughput"
  }
}

这个配置会先过滤掉吞吐低于 50 的候选，再优先选择吞吐更高的候选。

`preferred_max_latency`

preferred_max_latency 用于限制候选 provider 的最高延迟。只有延迟小于或等于阈值的候选会被保留。

{
  "provider": {
    "preferred_max_latency": 3000
  }
}

匹配规则：

候选的 latency 必须小于或等于设置值。

不传该参数时，不限制延迟。

延迟单位与系统统计指标保持一致；如果系统使用毫秒统计，则 3000 表示 3000 ms。

示例：只使用延迟不高于 3000 的候选，并优先选择延迟最低的候选。

{
  "model": "your-virtual-model",
  "messages": [
    {
      "role": "user",
      "content": "用户正在等待，请快速回答"
    }
  ],
  "provider": {
    "preferred_max_latency": 3000,
    "sort": "latency"
  }
}

`only`

only 用于指定 provider 白名单。设置后，只有 provider 名称在白名单中的候选会被保留。

{
  "provider": {
    "only": ["openai", "anthropic"]
  }
}

匹配规则：

provider 名称从候选模型名中第一个 / 之前的部分提取。如供应商模型tencent/deepseek/deepseek-v4-pro的 provider 名称为 tencent。

openai/gpt-4o 的 provider 名称是 openai。

openai/azure/gpt-4o 的 provider 名称也是 openai。

only 为空数组时，候选集会变为空。

provider 名称大小写敏感。

示例：只允许请求使用 openai 或 anthropic 的候选。

{
  "model": "your-virtual-model",
  "messages": [
    {
      "role": "user",
      "content": "解释一下量子计算"
    }
  ],
  "provider": {
    "only": ["openai", "anthropic"]
  }
}

适合需要强制限定供应商范围的场景，例如合规、稳定性验证或灰度发布。

`ignore`

ignore 用于指定 provider 黑名单。设置后，provider 名称在黑名单中的候选会被剔除。

{
  "provider": {
    "ignore": ["openai"]
  }
}

匹配规则：

provider 名称同样从候选模型名中第一个 / 之前的部分提取。如供应商模型tencent/deepseek/deepseek-v4-pro的 provider 名称为 tencent。

ignore 为空数组时，不产生过滤效果。

provider 名称大小写敏感。

示例：排除 openai 的候选。

{
  "model": "your-virtual-model",
  "messages": [
    {
      "role": "user",
      "content": "生成一份周报"
    }
  ],
  "provider": {
    "ignore": ["openai"]
  }
}

适合临时避开某个 provider 的场景，例如某个供应商异常、成本超预期或当前任务不希望使用该供应商。

`only` 和 `ignore` 同时使用

当 only 和 ignore 同时存在时，会先应用 only，再应用 ignore。最终候选必须同时满足：

provider 在 only 白名单内。

provider 不在 ignore 黑名单内。

示例：

{
  "provider": {
    "only": ["openai", "anthropic"],
    "ignore": ["openai"]
  }
}

上面的配置会先只保留 openai 和 anthropic，再排除 openai，最终只剩下 anthropic 的候选。

`sort`

sort 用于控制候选集的排序策略。当前支持三个值：

取值	说明
`price`	优先选择价格更低的候选
`throughput`	优先选择吞吐更高的候选
`latency`	优先选择延迟更低的候选

`sort: "price"`

{
  "provider": {
    "sort": "price"
  }
}

按价格升序排序。当前价格排序使用以下公式：

prompt * 3 + completion

该策略适合成本敏感型场景，例如批量摘要、离线生成、低优先级任务。

`sort: "throughput"`

{
  "provider": {
    "sort": "throughput"
  }
}

按吞吐降序排序，吞吐越高越优先。

该策略适合输出内容较长、希望整体生成速度更快的场景，例如长文生成、批量改写、代码生成。

`sort: "latency"`

{
  "provider": {
    "sort": "latency"
  }
}

按延迟升序排序，延迟越低越优先。

该策略适合交互式场景，例如聊天机器人、客服问答、实时辅助。

常见配置示例

预算优先

希望尽量控制调用成本时，可以设置价格上限并按价格排序。

{
  "model": "your-virtual-model",
  "messages": [
    {
      "role": "user",
      "content": "请总结下面的文章"
    }
  ],
  "provider": {
    "max_price": {
      "prompt": 0.01,
      "completion": 0.03
    },
    "sort": "price"
  }
}

这个配置会只保留价格不超过上限的候选，并优先选择综合价格最低的候选。

速度优先

希望优先获得更快的生成速度时，可以限制最低吞吐并按吞吐排序。

{
  "model": "your-virtual-model",
  "messages": [
    {
      "role": "user",
      "content": "生成一份详细的技术方案"
    }
  ],
  "provider": {
    "preferred_min_throughput": 80,
    "sort": "throughput"
  }
}

低延迟优先

希望减少首包等待或整体响应等待时，可以限制最高延迟并按延迟排序。

{
  "model": "your-virtual-model",
  "messages": [
    {
      "role": "user",
      "content": "用一句话回答：什么是向量数据库？"
    }
  ],
  "provider": {
    "preferred_max_latency": 1500,
    "sort": "latency"
  }
}

成本和性能同时控制

希望在成本可控的前提下获得较好的性能时，可以组合使用价格、吞吐和延迟限制。

{
  "model": "your-virtual-model",
  "messages": [
    {
      "role": "user",
      "content": "把这段内容改写成更正式的表达"
    }
  ],
  "provider": {
    "max_price": {
      "prompt": 0.02,
      "completion": 0.05
    },
    "preferred_min_throughput": 50,
    "preferred_max_latency": 3000,
    "sort": "price"
  }
}

这个配置表示：

只使用价格不超过上限的候选。

只使用吞吐不低于 50 的候选。

只使用延迟不高于 3000 的候选。

在剩余候选中优先选择价格最低的候选。

只允许指定 provider

{
  "model": "your-virtual-model",
  "messages": [
    {
      "role": "user",
      "content": "分析这段客服对话"
    }
  ],
  "provider": {
    "only": ["anthropic", "openai"],
    "sort": "latency"
  }
}

这个配置会只在 anthropic 和 openai 的候选中选择，并优先选择延迟最低的候选。

排除指定 provider

{
  "model": "your-virtual-model",
  "messages": [
    {
      "role": "user",
      "content": "生成一段营销文案"
    }
  ],
  "provider": {
    "ignore": ["openai"],
    "sort": "price"
  }
}

这个配置会排除 openai 的候选，并在剩余候选中优先选择价格最低的候选。

最佳实践

成本敏感任务优先使用 max_price + sort: "price"。

交互式任务优先使用 preferred_max_latency + sort: "latency"。

长文本生成任务优先使用 preferred_min_throughput + sort: "throughput"。

合规或供应商限定场景使用 only。

临时避开异常供应商使用 ignore。

不确定 provider 状态时，避免设置过多强过滤条件，以免候选集为空。

如果只是想表达倾向，优先使用 sort；如果必须强制限制，才使用 only、ignore 或阈值过滤。

注意事项

provider参数作用于候选集，不是直接指定某一个具体模型。

only、ignore 基于 provider 名称匹配，provider 名称取候选模型名第一个 / 之前的部分。如供应商模型tencent/deepseek/deepseek-v4-pro的 provider 名称为 tencent。

only 和 ignore 均大小写敏感。

only: [] 会导致候选集为空。

ignore: [] 不会产生效果。

max_price、preferred_min_throughput、preferred_max_latency 都是过滤条件，设置过严可能导致没有可用候选。

sort 只对过滤后的候选排序，不会恢复已被过滤掉的候选。

使用方式#

路由流程#

支持的参数#

max_price#

preferred_min_throughput#

preferred_max_latency#

only#

ignore#

only 和 ignore 同时使用#

sort#

sort: "price"#

sort: "throughput"#

sort: "latency"#

常见配置示例#

预算优先#

速度优先#

低延迟优先#

成本和性能同时控制#

只允许指定 provider#

排除指定 provider#

最佳实践#

注意事项#

使用方式

路由流程

支持的参数

`max_price`

`preferred_min_throughput`

`preferred_max_latency`

`only`

`ignore`

`only` 和 `ignore` 同时使用

`sort`

`sort: "price"`

`sort: "throughput"`

`sort: "latency"`

常见配置示例

预算优先

速度优先

低延迟优先

成本和性能同时控制

只允许指定 provider

排除指定 provider

最佳实践

注意事项