# 使用 TypeSafe Jev 进行语义路由

[语义路由器](https://docs.apiseven.com/ai-gateway/routing/semantic-routing.md)有两种决策方式。默认情况下，它把请求的向量嵌入与各路由的示例进行比较。使用 TypeSafe jev 决策后端时，AISIX 改为询问 [TypeSafe](https://docs.typesafe.ai) 托管的 jev 决策模型：已配置的路由中哪一条适合该请求。

对于每个请求，AISIX 把请求中最新的用户文本（选取方式参见[参与分类的文本](https://docs.apiseven.com/ai-gateway/routing/semantic-routing.md#what-the-router-classifies)）连同每条路由的名称和 `description` 一起发送给 jev。jev 选出一条路由，并给出它对该选择的置信度。jev 正是在各路由的描述之间进行选择，因此这种方式不需要示例提示词、向量嵌入模型或相似度阈值。

决策之后的行为与基于向量嵌入的路由器相同：由选中路由的目标处理请求，访问日志的 `semantic_route` 字段标明该路由，没有任何路由处理的请求则发往路由器的默认模型。目标可以是[模型组](https://docs.apiseven.com/ai-gateway/routing/semantic-routing.md#route-to-a-model-group)，[会话固定](https://docs.apiseven.com/ai-gateway/routing/semantic-routing.md#pin-a-session-to-its-route)可以让会话保持在首个命中的路由上，不再询问 jev。

## 使用前须知[​](#before-you-use-it "使用前须知的直接链接")

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

* **每个请求多一次调用。** 每个经过路由的请求在分发前都会同步调用一次 TypeSafe 托管 API，会话已固定到某条路由的请求除外。网关需要能够出站访问 TypeSafe，并且请求中最新的用户文本会被发送给 TypeSafe。
* **语言。** TypeSafe 表示，jev 目前对非英语输入的准确率较低。
* **计量。** 在 AISIX Enterprise 和 AISIX Cloud 中，每次 jev 调用都会记录为请求的一次[内部调用](https://docs.apiseven.com/ai-gateway/cloud/model-pricing.md#bill-the-gateways-internal-model-calls)，按路由器引用的决策模型的价格计费。你的 TypeSafe 账户同样会对该调用计费。开源 AISIX 网关会记录该调用，但不计算费用。
* **调试工具。** 控制台的**测试路由**和**自动检测阈值**工具仅适用于基于向量嵌入的路由器，jev 路由器无法使用。

## 准备工作[​](#prerequisites "准备工作的直接链接")

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

* 一个 TypeSafe API Key。
* 对于 AISIX Enterprise 或 AISIX Cloud，如果决策调用需要计费，请为决策模型[设置价格](https://docs.apiseven.com/ai-gateway/endpoints/decision-models.md#pricing)。
* 一个默认目标，以及至少一个路由目标。每个目标可以是[直接模型](https://docs.apiseven.com/ai-gateway/models/model-aliases.md#create-a-direct-model)或[模型组](https://docs.apiseven.com/ai-gateway/routing/semantic-routing.md#route-to-a-model-group)。
* 一个可以调用语义路由器别名的[调用方 API Key](https://docs.apiseven.com/ai-gateway/traffic-controls/caller-api-keys.md)。
* 对于 AISIX Enterprise 或 AISIX Cloud，需要一个已接入网关的环境，以及管理服务提供方密钥、模型和调用方 API Key 的权限。
* 对于开源 AISIX 网关，需要一个运行中的网关，以及对声明式资源文件的访问权限。
* 对于 AISIX Enterprise 或 AISIX Cloud 路径，还需要 `curl` 和 `jq`。

## 创建 TypeSafe 服务提供方密钥和决策模型[​](#create-a-typesafe-provider-key-and-decision-model "创建 TypeSafe 服务提供方密钥和决策模型的直接链接")

jev 调用使用 `provider` 为 `typesafe` 的[服务提供方密钥](https://docs.apiseven.com/ai-gateway/models/provider-keys.md)进行认证。它的密钥值就是你的 TypeSafe API Key，AISIX 会将其作为 Bearer Token 发送。`api_base` 为可选字段，默认值为 `https://api.typesafe.ai`。

同一个密钥还可以用于直接[决策模型](https://docs.apiseven.com/ai-gateway/endpoints/decision-models.md)，调用方通过 `/v1/systemone` 和 `/v1/decisions` 访问这类模型。在 AISIX Enterprise 和 AISIX Cloud 中，AISIX Cloud Admin API 不允许将该密钥用作向量嵌入模型的服务提供方密钥。如果仍有模型或语义路由器使用该密钥，API 也会拒绝删除它。使用 `typesafe` 密钥的模型不能作为语义路由器的路由目标、默认目标或失败目标，因为目标会收到 Chat Completions 请求，而 TypeSafe 不提供 Chat Completions。

### AISIX Enterprise 或 AISIX Cloud[​](#aisix-enterprise-or-aisix-cloud "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')
```

在 AISIX Enterprise 和 AISIX Cloud 中，路由器不直接调用该密钥，而是引用该密钥上的一个直接模型，即决策模型，并按 `/v1/systemone` 请求调用该模型的方式调用它。创建决策模型并记录其 ID：

```
JEV_MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \

  -H "Authorization: Bearer $AISIX_TOKEN" \

  -H "Content-Type: application/json" \

  -d '{

    "display_name": "jev",

    "model_name": "jev-latest",

    "provider_key_id": "'"$TYPESAFE_KEY_ID"'"

  }' | jq -r '.model.id')
```

`jev-latest` 是 TypeSafe 最新稳定正式版本的别名。决策模型的价格就是路由器决策调用的价格，设置方法见[决策模型](https://docs.apiseven.com/ai-gateway/endpoints/decision-models.md#pricing)。路由器的决策调用不要求把该模型加入调用方 API Key 的允许模型。

在控制台中，请在**服务商密钥**页面选择 `typesafe` 服务提供方创建密钥，并允许它在路由器所在的环境中使用；然后在**模型**页面上基于该密钥创建一个直接模型。

### 开源 AISIX 网关[​](#aisix-oss "开源 AISIX 网关的直接链接")

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

resources.yaml（TypeSafe 服务提供方密钥）

```
provider_keys:

  - id: 52cfff8d-2e5f-44fc-bb08-dfdfd9519c49

    display_name: typesafe

    provider: typesafe

    api_key: ${TYPESAFE_API_KEY}
```

## 配置 jev 路由器[​](#configure-a-jev-router "配置 jev 路由器的直接链接")

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

### AISIX Enterprise 或 AISIX Cloud[​](#aisix-enterprise-or-aisix-cloud-1 "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",

        "model_id": "'"$JEV_MODEL_ID"'",

        "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`。                                                                                                                                                                |
| `model_id`       | 是   |                       | 决策模型的 ID：同一环境中的直接模型，其服务提供方密钥的服务提供方为 `typesafe`，且不是通配别名。决策调用使用它的 `model_name`，以及其服务提供方密钥的 API Key、`api_base`、请求覆盖项和请求头。 |
| `min_confidence` | 否   | `0.5`                 | 采用选中路由所需的最低置信度，取值范围 `0` 到 `1`。低于该值的选择会把请求发往默认模型。                                                                                                         |
| `timeout_ms`     | 否   | `3000`                | jev 调用的超时时间，单位为毫秒，至少为 `1`。                                                                                                                                                    |
| `on_failure`     | 否   | `{"mode": "default"}` | 调用失败时的处理方式。参见[处理分类器失败](#handle-classifier-failures)。                                                                                                                       |

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

### 控制台[​](#dashboard "控制台的直接链接")

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

* **决策模型**：只列出该环境中使用 TypeSafe 服务提供方密钥的直接模型。所选模型没有价格时，表单会给出提示，并链接到 **模型定价** 页面。
* **最低置信度**：默认为 `0.5`。低于该值的决策会把请求发往默认模型。
* **超时（毫秒）**：默认为 `3000`。
* **分类器失败时**：可以回退到默认模型、使请求失败，或路由到指定模型。

每条路由都需要填写 **描述**。路由器列表会为 jev 路由器显示 `jev：` 加决策模型名称的标记，例如 `jev：jev`。

### 开源 AISIX 网关[​](#aisix-oss-1 "开源 AISIX 网关的直接链接")

把 jev 决策模型对应的直接模型和路由器添加到 `models` 集合。分类器通过 `classifier.model_id` 按 `id` 引用决策模型，并使用该模型的服务提供方密钥和 `model_name` 发起决策调用，与 AISIX Enterprise 和 AISIX Cloud 中一致。路由目标和默认模型使用 `display_name` 值：

resources.yaml（jev 语义路由器）

```
models:

  - id: 6b4b2655-1c76-4fc6-af0b-7be0547f227c

    display_name: jev

    provider: typesafe

    model_name: jev-latest

    provider_key_id: 52cfff8d-2e5f-44fc-bb08-dfdfd9519c49

  - id: 0067f34d-5ffb-43ad-826f-ebfc506b3609

    display_name: support-router

    semantic:

      classifier:

        type: jev

        model_id: 6b4b2655-1c76-4fc6-af0b-7be0547f227c

        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
```

设置 `model_id` 后，不再读取分类器的 `provider_key_id` 和 `model`。网关在请求到达路由器时检查被引用的模型是否为 `typesafe` 服务提供方密钥上的直接模型，加载文件时不做该检查。解析不到这样的模型时，决策调用会失败，并应用 `on_failure`。

未设置 `model_id` 的分类器可以改用 `classifier.provider_key_id` 按 `id` 引用 TypeSafe 服务提供方密钥，并用 `classifier.model` 指定 jev 模型，默认为 `jev-latest`。

该路由器不能设置 `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` 中，然后验证并重新加载该文件。

`aisix export` 按 etcd 中的存储原样写出分类器，包括 `model_id` 以及旁边的 `provider_key_id` 和 `model`（如果有）。如果 `model_id` 指向的模型不在导出结果中，它会被报告为悬空引用。

## 引用决策模型[​](#reference-the-decision-model "引用决策模型的直接链接")

在 AISIX Enterprise 和 AISIX Cloud 中，分类器通过 `model_id` 引用决策模型。保留这个引用会带来以下影响：

* 有路由器的分类器在使用某个决策模型时，该模型不能删除，删除会返回 `409` `MODEL_IN_USE` 并指出该路由器。请先把路由器的分类器改为指向其他模型，或删除该路由器。
* 有路由器的分类器在使用某个决策模型时，该模型不能改用服务提供方不是 `typesafe` 的密钥，也不能改名为通配别名。修改它的服务提供方密钥或 `model_name`，会作用于所有使用它的路由器。

在 `model_id` 出现之前保存的路由器，其分类器直接指定 TypeSafe 服务提供方密钥和 jev 模型，读取时显示为 `classifier.provider_key_id` 和 `classifier.model`。这类路由器会继续路由，但其决策调用不计费。控制台的编辑表单会显示提示：**此路由的分类器直接指定了 TypeSafe 服务商密钥和模型，这种配置已无法保存，其决策调用也不计费。请在下方选择决策模型后再保存修改。**

对这类路由器的每次写入都会以 `400` 拒绝，直到同一次写入设置了 `classifier.model_id`，只修改名称、路由或阈值的写入也一样。错误消息会说明分类器直接指定了服务提供方密钥和模型，已无法保存。要转换路由器，请在它的 TypeSafe 服务提供方密钥上创建一个 `model_name` 相同的决策模型，然后发送路由器完整的 `semantic` 块，其中设置 `classifier.model_id`，且不带 `provider_key_id` 和 `model`。在控制台中，打开路由器的编辑表单，选择 **决策模型** 后保存即可。

控制面仍会把决策模型的服务提供方密钥和模型名称写在 `model_id` 旁边下发给网关。早于 1.11.0 的网关只读取这两项，因此会用同一个密钥调用同一个模型，但不会上报决策调用以供计费。

## 为不属于任何路由的请求配置去向[​](#route-requests-that-fit-no-route "为不属于任何路由的请求配置去向的直接链接")

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"

}
```

编写描述时：

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

## 处理分类器失败[​](#handle-classifier-failures "处理分类器失败的直接链接")

当 jev 调用失败、超过 `timeout_ms`，或返回的路由不在配置中时，会应用 `on_failure`。网关无法把分类器的 `model_id` 解析为 `typesafe` 服务提供方密钥上的直接模型时，同样会应用 `on_failure`。它的取值与向量嵌入路由器的 `on_embedding_failure` 相同，默认使用路由器的默认模型。

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

```
{

  "classifier": {

    "type": "jev",

    "model_id": "YOUR_DECISION_MODEL_ID",

    "on_failure": {

      "mode": "target",

      "target_model_id": "YOUR_SAFE_MODEL_ID"

    }

  }

}
```

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

```
classifier:

  type: jev

  provider_key_id: 52cfff8d-2e5f-44fc-bb08-dfdfd9519c49

  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"`。各原因的含义参见[语义路由失败](https://docs.apiseven.com/ai-gateway/reference/headers-and-error-codes.md#semantic-routing-failures)。

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

## 验证路由选择[​](#verify-route-selection "验证路由选择的直接链接")

按照[验证路由选择](https://docs.apiseven.com/ai-gateway/routing/semantic-routing.md#verify-route-selection)中的方式向路由器发送请求。由某条路由处理的请求会在访问日志的 `semantic_route` 字段中记录该路由的名称；当 [`proxy.expose_debug_headers`](https://docs.apiseven.com/ai-gateway/reference/configuration-files.md#expose-debug-response-headers) 为 `true` 时，`x-aisix-route` 响应头也会携带该名称。

请求的访问日志行会在 `semantic_route`、`semantic_score` 和 `semantic_fallback` 中记录决策结果。对于 jev 路由器，`semantic_score` 是 jev 对其选择的置信度。可以用它来调整 `min_confidence`：带有 `semantic_fallback="low_confidence"` 的回退请求会显示未达标的置信度。参见[读取语义路由决策](https://docs.apiseven.com/ai-gateway/observability/access-logs-and-request-correlation.md#read-the-semantic-routing-decision)。

## 下一步[​](#next-steps "下一步的直接链接")

* [语义路由](https://docs.apiseven.com/ai-gateway/routing/semantic-routing.md)——基于向量嵌入的决策后端，以及两种后端共享的行为。
* [TypeSafe Jev 安全护栏](https://docs.apiseven.com/ai-gateway/traffic-controls/guardrails/typesafe-jev.md)——通过自定义脚本安全护栏，用同一个决策模型检查请求。
* [TypeSafe API Reference](https://docs.typesafe.ai/api)——该决策模型自身的文档。
