版本：Dev

使用 TypeSafe Jev 进行语义路由

语义路由器有两种决策方式。默认情况下，它把请求的向量嵌入与各路由的示例进行比较。使用 TypeSafe jev 决策后端时，AISIX 改为询问 TypeSafe 托管的 jev 决策模型：已配置的路由中哪一条适合该请求。

对于每个请求，AISIX 把请求中最新的用户文本（选取方式参见参与分类的文本）连同每条路由的名称和 description 一起发送给 jev。jev 选出一条路由，并给出它对该选择的置信度。jev 正是在各路由的描述之间进行选择，因此这种方式不需要示例提示词、向量嵌入模型或相似度阈值。

决策之后的行为与基于向量嵌入的路由器相同：由选中路由的目标处理请求，访问日志的 semantic_route 字段标明该路由，没有任何路由处理的请求则发往路由器的默认模型。目标可以是模型组，会话固定可以让会话保持在首个命中的路由上，不再询问 jev。

使用前须知

选择此决策后端前，请考虑以下几点：

网关版本。 jev 路由器需要高于 1.5.0 的 AISIX 网关。1.5.0 及更早版本的网关无法加载这种路由器。它们低于 AISIX Enterprise 和 AISIX Cloud 支持的最低版本 1.6.0，因此控制面在保存时不检查它们，请先将其升级。参见窗口期内控制面会做哪些检查。
每个请求多一次调用。 每个经过路由的请求在分发前都会同步调用一次 TypeSafe 托管 API，会话已固定到某条路由的请求除外。网关需要能够出站访问 TypeSafe，并且请求中最新的用户文本会被发送给 TypeSafe。
语言。 TypeSafe 表示，jev 目前对非英语输入的准确率较低。
计量。 jev 调用不会作为用量或成本记录在 AISIX 中，而是由你的 TypeSafe 账户单独计费。
调试工具。 控制台的测试路由和自动检测阈值工具仅适用于基于向量嵌入的路由器，jev 路由器无法使用。

准备工作

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

一个 TypeSafe API Key。
一个默认目标，以及至少一个路由目标。每个目标可以是直接模型或模型组。
一个可以调用语义路由器别名的调用方 API Key。
对于 AISIX Enterprise 或 AISIX Cloud，需要一个已接入高于 1.5.0 版本网关的环境，以及管理服务提供方密钥、模型和调用方 API Key 的权限。
对于开源 AISIX 网关，需要高于 1.5.0 版本的网关，以及对声明式资源文件的访问权限。
对于 AISIX Enterprise 或 AISIX Cloud 路径，还需要 curl 和 jq。

创建 TypeSafe 服务提供方密钥

jev 调用使用 provider 为 typesafe 的服务提供方密钥进行认证。它的密钥值就是你的 TypeSafe API Key，AISIX 会将其作为 Bearer Token 发送。api_base 为可选字段，默认值为 https://api.typesafe.ai。

同一个密钥还可以用于直接决策模型，调用方通过 /v1/systemone 和 /v1/decisions 访问这类模型。AISIX Enterprise 和 AISIX Cloud 均不允许向量嵌入模型使用它，并且在有语义路由器使用它时拒绝删除它。使用 typesafe 密钥的模型不能作为语义路由器的路由目标、默认目标或失败目标，因为目标会收到 Chat Completions 请求，而 TypeSafe 不提供 Chat Completions。

AISIX Enterprise 或 AISIX Cloud

导出控制面连接信息和你的 TypeSafe API Key：

# 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 TYPESAFE_API_KEY="YOUR_TYPESAFE_API_KEY"

创建服务提供方密钥，允许它在该环境中使用，并记录其 ID：

TYPESAFE_KEY_ID=$(curl -sS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "typesafe",
    "provider": "typesafe",
    "api_key": "'"$TYPESAFE_API_KEY"'",
    "allowed_environments": ["'"$ENV_ID"'"]
  }' | jq -r '.provider_key.id')

在控制台中，请在服务商密钥页面选择 typesafe 服务提供方创建密钥，并允许它在路由器所在的环境中使用。

开源 AISIX 网关

把密钥添加到 provider_keys 集合，并通过环境变量提供密钥值：

resources.yaml（TypeSafe 服务提供方密钥）
provider_keys:
  - display_name: typesafe
    provider: typesafe
    api_key: ${TYPESAFE_API_KEY}

配置 jev 路由器

每条路由都需要 name、一个目标和 description。请把每条描述写成“这条路由处理哪些请求”的说明，因为这是 jev 了解该路由的唯一信息。在这种模式下，路由不接受 examples 和 threshold。

AISIX Enterprise 或 AISIX Cloud

导出各目标模型的 ID。每个目标可以是直接模型，也可以是模型组：

export DEFAULT_MODEL_ID="YOUR_DEFAULT_MODEL_ID"
export BILLING_MODEL_ID="YOUR_BILLING_MODEL_ID"
export CODE_MODEL_ID="YOUR_CODE_MODEL_ID"

创建带有 classifier 块的语义路由器：

SEMANTIC_MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "semantic",
    "display_name": "support-router",
    "semantic": {
      "classifier": {
        "type": "jev",
        "provider_key_id": "'"$TYPESAFE_KEY_ID"'",
        "model": "jev-latest",
        "min_confidence": 0.5,
        "timeout_ms": 3000,
        "on_failure": {"mode": "default"}
      },
      "default_model_id": "'"$DEFAULT_MODEL_ID"'",
      "routes": [
        {
          "name": "billing",
          "target_model_id": "'"$BILLING_MODEL_ID"'",
          "description": "Questions about invoices, payments, refunds, and subscription plans"
        },
        {
          "name": "code",
          "target_model_id": "'"$CODE_MODEL_ID"'",
          "description": "Writing, reviewing, or debugging source code"
        }
      ]
    }
  }' | jq -r '.model.id')

把 SEMANTIC_MODEL_ID 添加到调用方 API Key 的 allowed_models 列表。保存后的配置会自动投射到已接入的网关。

classifier 块支持以下字段：

字段	必填	默认值	说明
`type`	是		决策模型系列。唯一取值为 `jev`。
`provider_key_id`	是		允许在该环境中使用的 `typesafe` 服务提供方密钥的 ID。
`model`	否	`jev-latest`	要调用的 jev 模型。默认值是 TypeSafe 最新稳定正式版本的别名。
`min_confidence`	否	`0.5`	采用选中路由所需的最低置信度，取值范围 `0` 到 `1`。低于该值的选择会把请求发往默认模型。
`timeout_ms`	否	`3000`	jev 调用的超时时间，单位为毫秒，至少为 `1`。
`on_failure`	否	`{"mode": "default"}`	调用失败时的处理方式。参见处理分类器失败。

带有 classifier 的路由器会以 HTTP 400 拒绝仅适用于向量嵌入的字段：路由器上的 embedding_model_id、threshold、embedding_timeout_ms 和 on_embedding_failure，以及路由上的 examples 和 threshold。它还要求每条路由都有非空的 description，最多接受 254 条路由，并要求路由名称唯一。

控制台

在控制台的 Models 页面创建语义路由器，并把 Decision backend 从 Embedding similarity 改为 TypeSafe jev classifier。表单随后会显示以下字段：

TypeSafe provider key：只列出允许在该环境中使用的 typesafe 服务提供方密钥。
Decision model：默认为 jev-latest。
Minimum confidence：默认为 0.5。低于该值的决策会把请求发往默认模型。
Timeout (ms)：默认为 3000。
On classifier failure：可以回退到默认模型、使请求失败，或路由到指定模型。

每条路由都需要填写 Description。路由器列表会为 jev 路由器显示 jev: <model> 标记，例如 jev: jev-latest。

开源 AISIX 网关

把路由器添加到 models 集合。通过 classifier.provider_key 按名称引用 TypeSafe 服务提供方密钥，或通过 classifier.provider_key_id 按 ID 引用。模型引用使用 display_name 值：

resources.yaml（jev 语义路由器）
models:
  - display_name: support-router
    semantic:
      classifier:
        type: jev
        provider_key: typesafe
        model: jev-latest
        min_confidence: 0.5
        timeout_ms: 3000
        on_failure: default
      default: general-chat
      routes:
        - name: billing
          target: billing-chat
          description: Questions about invoices, payments, refunds, and subscription plans
        - name: code
          target: code-chat
          description: Writing, reviewing, or debugging source code

该路由器不能设置 embedding_model、embedding_model_id、embedding_timeout_ms、on_embedding_failure 或 match，其路由也不能设置 examples 或 threshold。完整的资源文件还必须包含 typesafe 服务提供方密钥，以及 general-chat、billing-chat 和 code-chat 直接模型。把 support-router 添加到调用方密钥的 allowed_models 中，然后验证并重新加载该文件。

为不属于任何路由的请求配置去向

jev 总是在你配置的路由之间进行选择。AISIX 不会额外添加“以上都不是”选项，因此与所有路由都无关的请求，仍会被发往 jev 认为最接近的路由，除非 jev 的置信度低于 min_confidence。

如果希望无关请求发往特定位置，请自行添加一条兜底路由，并使用类似“The request does not fit any of the other routes”（请求不属于任何其他路由）的描述：

{
  "name": "other",
  "target_model_id": "YOUR_GENERAL_MODEL_ID",
  "description": "The request does not fit any of the other routes"
}

编写描述时：

让每条描述保持具体。写得过于宽泛的描述（例如“一般问题”）会吸收本不属于任何路由的请求。
使用与该路由所处理流量相同的语言编写描述。

处理分类器失败

当 jev 调用失败、超过 timeout_ms，或返回的路由不在配置中时，会应用 on_failure。它的取值与向量嵌入路由器的 on_embedding_failure 相同，默认使用路由器的默认模型。

在 AISIX Enterprise 和 AISIX Cloud 中，on_failure 是一个对象。将 mode 设置为 default 可使用默认模型，设置为 fail 会以 503 拒绝请求，设置为 target 并提供 target_model_id 则使用另一个直接模型或模型组：

{
  "classifier": {
    "type": "jev",
    "provider_key_id": "YOUR_TYPESAFE_KEY_ID",
    "on_failure": {
      "mode": "target",
      "target_model_id": "YOUR_SAFE_MODEL_ID"
    }
  }
}

在开源资源文件中，请使用 default、fail，或一个命名直接模型或模型组的对象：

classifier:
  type: jev
  provider_key: typesafe
  on_failure:
    target: safe-chat

使用 fail 时，返回的 503 携带 error.code semantic_routing_failed，消息中给出路由器名称和原因，例如 classifier_timeout 或 classifier_invalid_response。访问日志行记录 semantic_fallback="decision_failed" 和 error_class="semantic_decision_failed"。各原因的含义参见语义路由失败。

没有可分类用户文本的请求会直接发往默认模型，不调用 jev，除非该请求的会话已固定到某条路由。

验证路由选择

按照验证路由选择中的方式向路由器发送请求。由某条路由处理的请求会在访问日志的 semantic_route 字段中记录该路由的名称；当 proxy.expose_debug_headers 为 true 时，x-aisix-route 响应头也会携带该名称。

请求的访问日志行会在 semantic_route、semantic_score 和 semantic_fallback 中记录决策结果。对于 jev 路由器，semantic_score 是 jev 对其选择的置信度。可以用它来调整 min_confidence：带有 semantic_fallback="low_confidence" 的回退请求会显示未达标的置信度。参见读取语义路由决策。

下一步

语义路由——基于向量嵌入的决策后端，以及两种后端共享的行为。
TypeSafe Jev 安全护栏——通过自定义脚本安全护栏，用同一个决策模型检查请求。
TypeSafe API Reference——该决策模型自身的文档。

使用前须知​

准备工作​

创建 TypeSafe 服务提供方密钥​

AISIX Enterprise 或 AISIX Cloud​

开源 AISIX 网关​

配置 jev 路由器​

AISIX Enterprise 或 AISIX Cloud​

控制台​

开源 AISIX 网关​

为不属于任何路由的请求配置去向​

处理分类器失败​

验证路由选择​

下一步​

使用前须知

准备工作

创建 TypeSafe 服务提供方密钥

AISIX Enterprise 或 AISIX Cloud

开源 AISIX 网关

配置 jev 路由器

AISIX Enterprise 或 AISIX Cloud

控制台

开源 AISIX 网关

为不属于任何路由的请求配置去向

处理分类器失败

验证路由选择

下一步