语义路由

语义路由可以让调用方始终使用同一个模型别名，而 AISIX 会根据请求含义把每次请求转发到不同的上游模型。调用方始终发送相同的 model。AISIX 会读取最新一条用户消息，为其生成向量，并与每个路由上配置的示例语句做相似度比较。随后，AISIX 会把请求转发到最佳匹配路由的目标模型；如果没有匹配项，则转发到默认模型。

在 AISIX 中，语义路由器是一种模型别名，类似路由组和集成模型，AISIX 会通过路由决策解析它。与直接指向某个上游模型不同，语义路由器的 semantic 配置会告诉 AISIX 如何为请求打分，以及每条路由应使用哪个直连模型（direct model）。

当你希望一个入口按主题分流时，可以使用语义路由。例如，把法律问题发送给推理能力更强的模型，把翻译请求发送给成本更低的多语言模型，其它请求走通用默认模型。应用不需要在每次请求时自行选择模型。

请求流程

对于每个请求，AISIX 会使用配置的 embedding model，把最新用户消息与路由示例进行比较，然后分发到一个直连模型。

对于每个发往语义路由器的聊天请求，AISIX 会：

通过配置的 embedding model 对最新用户消息生成向量。
使用余弦相似度，将其与每条路由的示例向量进行打分。
取每条路由中最高的示例得分，并选出超过阈值的最高得分路由。
分发到该路由的目标模型；如果没有任何路由超过阈值，则分发到默认模型。

示例语句只会生成一次向量，并缓存在数据面中。因此稳定状态下，每个请求的额外成本是一轮针对 prompt 的 embedding 调用，以及本地相似度计算。

配置语义路由器

语义路由需要一个支持 embedding 的直连模型，以及一个 semantic router model。请先创建 embedding model 和各个路由的目标模型，再创建引用它们的语义路由器。

完整模型资源结构请参见模型和 Admin API 参考。

Embedding Model

Embedding model 是一个指向兼容 OpenAI /v1/embeddings 端点的直连模型，并带有记录输出维度的 embedding 配置块。它也可以通过 /v1/embeddings 直接调用。

{
  "display_name": "bge-m3",
  "provider": "openai",
  "model_name": "bge-m3",
  "provider_key_id": "<provider key for the embeddings endpoint>",
  "embedding": {
    "dimensions": 1024,
    "normalize": true
  }
}

dimensions 必填，必须与端点输出向量的维度一致。normalize 默认为 true；只有当端点不会返回单位长度向量时，才应设置为 false。

端点必须使用兼容 OpenAI 的 /v1/embeddings 结构，并返回浮点向量。自托管运行器，例如 Text Embeddings Inference、Ollama，以及托管服务提供方都可以使用。

如果要使用 Dashboard 的测试和阈值建议能力，该端点必须能被控制面访问。

Semantic Router

语义路由器是一个带有 semantic 配置块的模型。该配置块会引用 embedding model、列出路由，并指定默认模型。在自托管 Admin API 请求体中，模型引用使用被引用模型的 display_name。语义路由器与直连上游字段、路由组和集成模型互斥；Admin API 会在 schema 校验阶段拒绝无效组合。

{
  "display_name": "prod-chat",
  "semantic": {
    "embedding_model": "bge-m3",
    "default": "gpt-4o",
    "match": {
      "distance_metric": "cosine",
      "aggregation": "max",
      "threshold": 0.75
    },
    "routes": [
      {
        "name": "legal",
        "target": "claude-opus",
        "description": "Contract and legal-risk analysis",
        "examples": [
          "analyze this contract for legal risk",
          "review this NDA for liability exposure",
          "does this indemnity clause create unusual risk"
        ],
        "threshold": 0.8
      },
      {
        "name": "translate",
        "target": "gpt-4o-mini",
        "examples": ["translate this paragraph to French"]
      }
    ]
  }
}

每条路由需要 name、指向直连模型的 target，以及至少一个 examples 条目。description 可选。路由自己的 threshold 会覆盖路由器级别的阈值。Embedding model、默认模型以及每个路由目标模型都必须已经存在。

当示例文本、embedding model 或 embedding 维度发生变化时，AISIX 会自动重新计算路由示例向量。

在 AISIX Cloud 和私有化控制面部署中，Dashboard 的 Models 页面提供 Embedding 和 Semantic Router 配置区域，可以帮助你生成这些配置块。你可以从下拉菜单中选择 embedding model、默认模型和每条路由的目标模型，并为每条路由添加示例语句。

匹配行为

AISIX 只会对最新一条用户消息生成向量。如果该消息包含多个文本部分，会先拼接这些文本。非文本内容会被忽略，system、assistant 和 tool 轮次不会影响路由。
每条路由的得分是请求与该路由全部示例语句之间最高的余弦相似度。
当路由得分达到有效阈值时，路由才会匹配。有效阈值优先使用路由自己的 threshold，否则使用路由器级别的 threshold。如果多条路由匹配，最高得分获胜；如果没有路由匹配，请求会转发到默认模型。

跨语言匹配取决于配置的 embedding model。使用多语言 embedding model 时，prompt 和示例即使用不同语言也可能匹配。相关但不完全相同的文本，其余弦得分通常落在 0.4 到 0.65 区间。请基于自己的示例调优阈值，不要直接假设越高越好。

路由决策可能受对抗性 prompt 影响，因此建议在路由前执行输入安全护栏，并把相似度分数视为仅供运维人员使用的信号。

调优阈值

语义路由器表单提供两个 Dashboard 辅助能力，让阈值调优更具体，而不是靠猜测。二者都会从控制面调用 embedding 端点，因此该端点必须可以被公开访问。

测试路由：输入一个 prompt，查看它会解析到哪条路由，以及每条路由的相似度得分和是否达到阈值。保存前可以用它确认代表性 prompt 是否落在预期路由上。
建议阈值：根据示例集合的几何分布，为每条路由计算推荐阈值：包括每条路由内部示例聚合得多紧，以及不同路由之间相距多远。它不需要真实流量，只依赖已配置示例。可以先把建议值作为起点，再用测试路由继续微调。

调用方可见响应

响应体会报告解析后的上游模型。两个响应头会暴露路由决策：

x-aisix-route：匹配到的路由名称。当请求落到默认模型时，该响应头不存在。
x-aisix-served-by：实际处理该请求的直连模型 display_name。

Embedding 失败行为

如果 embedding 调用报错或超时，路由器会根据 on_embedding_failure 策略处理。可以设置可选的 embedding_timeout_ms，限制路由器等待 embedding 调用的时间。

{
  "semantic": {
    "embedding_timeout_ms": 500,
    "on_embedding_failure": "default"
  }
}

on_embedding_failure 支持以下配置形态：

default：路由到该路由器的默认模型。省略 on_embedding_failure 时默认使用该行为。
fail：以 503 拒绝请求。

显式目标对象：路由到 target 指定的安全模型。

{
  "on_embedding_failure": {
    "target": "safe-model"
  }
}

下一步

当一个请求需要由多个模型组成的候选面板和评审模型共同处理时，请继续阅读集成模型。如果路由决策前需要输入策略检查，请使用安全护栏。

请求流程​

配置语义路由器​

Embedding Model​

Semantic Router​

匹配行为​

调优阈值​

调用方可见响应​

Embedding 失败行为​

下一步​