使用 TypeSafe Jev 进行语义路由

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

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

决策之后的行为与基于向量嵌入的路由器相同：由选中路由的直接模型处理请求，x-aisix-route 标明该路由，没有任何路由处理的请求则发往路由器的默认模型。

使用前须知

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

• 网关版本。 jev 路由器需要高于 1.5.0 的 AISIX 网关。1.5.0 及更早版本的网关无法加载这种路由器。只要环境中还注册着这样的网关，AISIX Cloud 就会以 HTTP 422 和错误码 DP_INCOMPATIBLE 拒绝保存 jev 路由器。参见窗口期内控制面会做哪些检查。
• 每个请求多一次调用。 每个经过路由的请求在分发前都会同步调用一次 TypeSafe 托管 API。网关需要能够出站访问 TypeSafe，并且最新的用户消息会被发送给 TypeSafe。
• 语言。 TypeSafe 表示，jev 目前对非英语输入的准确率较低。
• 计量。 jev 调用不会作为用量或成本记录在 AISIX 中，而是由你的 TypeSafe 账户单独计费。
• 调试工具。 控制台的测试路由和自动检测阈值工具仅适用于基于向量嵌入的路由器，jev 路由器无法使用。

准备工作

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

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

创建 TypeSafe 服务提供方密钥

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

typesafe 服务提供方密钥只用于语义路由器决策调用的认证。AISIX Cloud 不允许直接模型或向量嵌入模型使用它，并且在有语义路由器使用它时拒绝删除它。

AISIX Cloud

导出 AISIX Cloud 连接信息和你的 TypeSafe API Key：

# AISIX_CP 是 Admin API 基础 URL；应包含 /api，且末尾不要带斜杠。
# 本地部署快速入门使用 http://localhost:8080/api。
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_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 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 模型。
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 条路由，并要求路由名称唯一。

AISIX Cloud 控制台

在控制台的模型页面创建语义路由器，并把决策方式从嵌入相似度改为 TypeSafe jev 分类器。表单随后会显示以下字段：

• TypeSafe 服务商密钥：只列出允许在该环境中使用的 typesafe 服务提供方密钥。
• 决策模型：默认为 jev-latest。
• 最低置信度：默认为 0.5。低于该值的决策会把请求发往默认模型。
• 超时（毫秒）：默认为 3000。
• 分类器失败时：可以回退到默认模型、使请求失败，或路由到指定模型。

每条路由都需要填写描述。路由器列表会为 jev 路由器显示 jev：<模型> 标记，例如 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 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_kind="semantic_decision_failed"。各原因的含义参见语义路由失败。

如果请求的最新用户消息不含文本，它会直接发往默认模型，不调用 jev。

验证路由选择

按照验证路由选择中的方式向路由器发送请求。由某条路由处理的请求会携带 x-aisix-route，其值为该路由的名称。

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

下一步

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