1 背景随着大模型应用从概念验证走向生产落地，企业面临多模型集成切换成本高、Token消耗与成本难以管控、数据安全合规风险突出等新挑战。传统API网关基于RESTful API和静态请求响应设计，难以适配AI场景下流式传输、Token级计费、语义化缓存等独特需求，因此，企业迫切需要一款面向AI原生场景，同时具备大模型流量治理能力及内容安全治理能力的全新网关产品。 2 方案介绍 AI网关在传统网关的基础上，扩展了LLM多模型灵活路由、模型故障降级、内容安全、Token配额管理、Token限流、Token可观测等大模型领域的能力。 Higress是一款基于Istio和Envoy内核的云原生AI网关，配置变更毫秒级生效且业务无感，在AI长连接及流式处理（SSE）场景下优势明显。 Higress提供丰富的Wasm插件扩展体系，支持Go/Rust/JS多语言开发，通过沙箱隔离实现内存安全与热更新，覆盖AI多模型统一接入、Token流控、智能路由降级及AI可观测等核心能力。同时兼容K8s Ingress/Gateway API标准，可对接Nacos等微服务注册中心，并支持脱离K8s以Docker单机运行，已在业界多个企业及组织实现大规模落地。 3 部署指南本参考实践提供Docker部署及K8S的Helm Charts部署两种部署方式，大家可以按照自身环境以及业务需要选择使用，大规模生产使用更推荐Helm Charts部署的方式。 3.1 环境信息说明本实践中所用到的软件版本如下：组件版本说明 ctr (containerd) v2.1.1 containerd 命令行工具，用于管理容器镜像 OS openEuler 22.03 (LTS-SP4) 操作系统 Kubernetes v1.34.3 K8s 集群服务端版本 Helm v3.21.2 Kubernetes 包管理工具 Docker 26.1.3 用于镜像导入导出及docker容器部署 3.2 Docker部署 Docker部署使用的镜像包如下：组件镜像 Tag 用途 gateway、controller、pilot console、Plugin Server all-in-one 2.2.3 Higress多个组件合一，包括数据面、控制面、控制台等核心部分，同时提供插件服务器能力，用于快速部署及测试 Redis redis-stack-server 7.4.0-v3 (可选组件) 配合4.3.5章节Token配额管理平台使用本小节介绍如何使用自动化脚本完成Higress网关的Docker部署，脚本链接如下：Docker自动化部署Higress脚本链接。该脚本提供 Higress 网关的 Docker 容器化一键部署方案，基于 ascend_deployer 自动化框架实现下载、基础软件安装、服务部署的全流程自动化。支持在线/离线两种部署模式，适用于单机测试、批量部署及离线部署等场景。详细部署步骤如下： 1.克隆代码仓。git clone https://atomgit.com/Ascend/ascend-deployer.git -b appliance_deployer cd ascend-deployer/kadt/higress/docker_deploy chmod +x *.sh 2.下载软件包，按照对应场景使用对应示例及参数。# 默认场景(全量下载，包括Higress、Redis、Token额度平台) ./higress_download.sh --os OpenEuler_22.03LTS-SP4_aarch64 # 跳过Token额度管理平台镜像下载/构建，该组件属于可选组件 ./higress_download.sh --os OpenEuler_22.03LTS-SP4_aarch64 --skip-quota-console # 下载包含docker仓库组件 ./higress_download.sh --os OpenEuler_22.03LTS-SP4_aarch64 --with-registry 执行该命令后会一键下载 Higress 镜像及系统依赖，Redis组件(可选，配合章节4.3.5 Token配额管理平台使用)及其他插件镜像。 3.(离线场景使用) 传输下载包到待部署服务器。将联网服务器的ascend_deployer目录(包含脚本及resources目录)传输到待部署服务器。随后步骤4及步骤5在待部署服务器的ascend_depoler/kadt/higress/docker_deploy执行, 执行前赋予执行脚本的权限。 4.安装基础软件。./install_base_sw.sh 执行该命令后会一键安装操作系统依赖、Docker 引擎等基础软件。 5.一键部署Higress服务，按照对应场景使用对应示例及参数，具体参数使用可参考README。# 默认全量部署Higress服务(包括Higress、Redis、Token额度平台)，使用--skip-quota-console跳过Token额度管理平台部署，同时部署docker registry仓库用于插件镜像推送 ./install_higress.sh --install-registry --skip-quota-console # 仅部署Higress服务及redis组件，部署docker registry仓库用于插件镜像推送 ./install_higress.sh --install higress,redis --install-registry --skip-quota-console # 全量部署Higress服务，使用已有仓库地址用于插件镜像推送，网关HTTP端口选择8081端口(默认为8080) ./install_higress.sh --plugin-registry 192.168.25.58:80/higress --port 8081 --quota-admin-key sk-1234 # 部署Higress服务，Redis组件，Token额度管理平台及docker registry仓库，额度平台端口设为8981 ./install_higress.sh --install higress,redis,quota_admin --install-registry --quota-port 8981 --quota-admin-key sk-1234 执行该命令后会一键安装部署Higress ，通过--install 可选择部署Token额度管理平台（可选，配合章节4.3.5 Token配额管理插件使用），--plugin-registry（用已有仓库，如 Harbor）与 --install-registry（部署本地 docker_registry）二选一，必传其一。部署完成后脚本会打印控制台、Gateway HTTP/HTTPS、Redis、插件镜像的访问地址，浏览器访问 http://{服务器IP}:8001进入 Higress 控制台。初次登录需要初始化管理员账号。说明：脚本暂不支持软件的卸载与重装。 3.3 K8S Helm Charts部署本小节介绍如何使用自动本小节介绍如何使用自动化脚本完成Higress网关的Helm Chart部署，脚本链接如下：Helm Chart自动化部署Higress脚本链接。该脚本使用Helm Chart部署的方式将Higress部署到K8S集群，支持在线/离线两种部署模式，适用于单机测试、批量部署及离线部署等场景。 3.3.1 镜像版本信息 Helm自动化部署使用的镜像包如下：组件镜像 Tag 用途 gateway (Envoy) gateway 2.1.9 请求流量的入口以及请求路由规则生效的载体 controller higress 2.1.9 核心控制器进程，感知 Kubernetes 资源变化并推送给 Envoy pilot pilot 2.1.9 控制面一部分，从Controller获取配置转换为 Envoy 格式，并负责下发 console console 2.1.9 Higress控制台界面，分为前端和后端，后端把前端传入的配置写入K8s Plugin Server plugin-server 2.1.11 插件服务器（用于预置插件部署后直接使用） Redis redis-stack-server 7.4.0-v3 (可选组件) 配合4.3.5章节Token配额管理平台使用 3.3.2 前置条件部署前，需要提前部署好Kubernetes集群并安装Helm，或按照《一体机与小集群算力底座参考实践》2.2章节部署openFuyao集群。 3.3.3 部署步骤 1.克隆代码仓。git clone https://atomgit.com/Ascend/ascend-deployer.git -b appliance_deployer cd ascend-deployer/kadt/higress/helm_chart_deploy chmod +x *.sh 2.下载软件包，按照对应场景使用对应示例及参数。# 默认场景(全量下载，包括Higress、Redis、Token额度平台) ./higress_helm_download.sh --os OpenEuler_22.03LTS-SP4_aarch64 # 跳过Token额度管理平台镜像下载/构建，该组件属于可选组件 ./higress_helm_download.sh --os OpenEuler_22.03LTS-SP4_aarch64 --skip-quota 执行该命令后会一键下载 Higress 镜像，插件镜像，Higress配套的Redis组件镜像(配合部署章节4.3.5的Token配额管理平台使用)，系统依赖及Higress的官方Chart包。 3.(离线场景使用) 传输ascend_deployer目录到待部署服务器。将联网服务器的ascend_deployer目录(包含脚本及resources目录)传输到待部署服务器。随后步骤4在待部署服务器的ascend_depoler/kadt/higress/helm_chart_deploy执行, 执行前赋予执行脚本的权限。 4.一键部署Higress服务，按照对应场景使用对应示例及参数，具体参数使用可参考README。# 单独安装部署Higress，镜像推送到本地私有仓库（跳过Token额度管理平台安装） ./install_higress_helm.sh \ --plugin-registry 192.168.25.58:80/higress \ --skip-quota-console # 安装部署Higress以及Token额度管理平台，镜像推送到本地私有仓库，控制台端口设置为30080, redis端口号为30083，Token额度管理平台端口号为30086 ./install_higress_helm.sh \ --plugin-registry 192.168.25.58:80/higress \ --console-port 30080 \ --redis-port 30083 \ --quota-port 30086 部署完成后脚本会打印控制台、Gateway HTTP/HTTPS、Redis、插件镜像、以及Token额度管理平台的访问地址，浏览器访问 http://{服务器IP}:打印的端口号进入 Higress 控制台。初次登录需要初始化管理员账号。说明：脚本暂不支持软件的卸载与重装。 4 特性使用指导 4.1 功能概览 Higress整体功能分为基础功能以及插件扩展功能两大部分：基础功能包括AI服务提供者、AI路由管理、消费者管理、插件管理等菜单，通过这些菜单，管理员可直观完成多模型供应商的API-KEY配置、路由规则与降级策略设定、消费者认证等操作，大幅降低AI治理的配置门槛与运维复杂度。插件扩展功能包含Higress预置的插件如请求脱敏及本参考实践提供的自定义插件如请求动态限流，模型智能路由增强等，覆盖AI，认证，安全，转换等多种类型, 满足各种AI场景下的独特需求。 4.2 基础功能 4.2.1 AI服务提供者管理 AI服务提供者是Higress控制台中的模型厂商管理模块，运维人员可在此统一录入通义千问、DeepSeek、OpenAI等服务商的API地址和认证凭证。配置完成后，AI路由即可将请求精准转发至对应的大模型服务，实现后端AI资源的集中纳管。配置步骤如下： 1.进入Higress控制台，左侧菜单进入"AI服务提供者管理"，点击创建AI服务提供者。 2.填写对应的大模型供应商，服务名称，协议，凭证等信息。 ●大模型供应商：下拉框选择，Higress预置了主流的大模型供应商如通义千问、DeepSeek、OpenAI等，若使用本地部署的模型则选择"OpenAI/OpenAI兼容服务"。服务名称：自定义，后续在AI路由管理界面配置AI服务提供者时提供下拉框选项。 ●协议：固定选项为openai/v1，是大模型领域的通用协议规范，配置服务url时需要配置后缀为/v1。 ●OpenAI服务类型：分为OpenAI官方服务/自定义服务，使用OpenAI供应商时选择"OpenAI官方服务", 本地部署选择"自定义服务"。 ●自定义OpenAI服务配置方式：分为输入URL/选择服务，选择"输入URL"后填写本地部署的大模型服务URL；选择"选择服务"后下拉框选择对应的K8S集群服务。 3.验证是否配置成功。参考4.2.2AI路由管理小节，若配置目标AI服务能带出对应的AI服务提供者则配置成功。 4.2.2 AI路由管理 AI路由管理是Higress AI网关中用于配置请求如何匹配并转发到不同大模型服务（如通义千问、DeepSeek）的核心功能，支持基于模型名称、域名、路径、请求头、请求参数等规则进行智能路由，并可配置降级策略和模型映射。配置步骤如下： 1.进入Higress控制台，左侧菜单进入"AI路由管理"，点击创建AI路由。 2.填写对应的路由名称，路径，匹配规则，模型匹配规则，目标模型服务(通过4.1.2AI服务提供者管理小节配置AI服务提供者后带出)。 ●名称：AI路由名称，自定义，创建后不能修改。 ●路径：AI路由目前只支持前缀匹配，按照路径的前缀匹配对应的路由规则。 ●请求头：可选前缀匹配/精确匹配/正则匹配，通过请求头的KEY匹配对应的路由规则。 ●请求参数：可选前缀匹配/精确匹配/正则匹配，通过请求参数如路径?后的参数匹配对应的路由规则。 ●模型匹配规则: 可选前缀匹配/精确匹配/正则匹配，通过请求体中的model参数匹配对应的路由规则。 ●目标AI服务：下拉框可选AI服务提供者菜单中配置的AI服务，根据此处填写的目标模型将请求中的model转换后转发到目标AI服务。 ●允许请求本路由的消费者名称列表：消费者在消费者管理中配置后带出，填写后访问该路由需要有对应消费者的凭证。说明：请求头/请求参数/模型匹配规则均可配置多条，Higess按照配置顺序进行匹配，命中则执行对应操作并停止后续匹配。按照上述配置，路由会匹配路径为/v1/chat/completions，且请求体中model为"qwen3-test"的请求，并将model转换成"qwen3"后转发到对应的目标AI服务vllm-qwen3中，若一个请求同时匹配到两个路由规则，则会按照配置的优先级进行匹配，若没有配置，则会按照路由配置的先后顺序进行匹配。 3.验证配置是否生效。进入首页，点击使用方法获取对应的访问请求路径。访问对应的接口，应替换为对应的"IP:端口"格式，替换对应的model，接口返回状态码200且返回llm回复则说明验证成功。 4.验证是否转发到对应的路由。进入控制台左侧菜单"监控面板"->功能菜单(四个方格)-General->Higress Access Logs路径，查看对应的日志信息。可以看到，该请求转发到了上述步骤中配置的vllm-route-test1路由上。 4.2.3 插件管理 Higress网关的插件配置是一个预置了丰富AI增强插件（如缓存、脱敏、负载均衡、RAG等）的可扩展功能模块，用于在不修改业务代码的前提下，为AI请求链路附加智能化处理能力。配置步骤： 1.进入Higress控制台，左侧菜单进入"插件配置"。Higress预置了AI，认证，安全，转换等多种类型多样功能的插件。 2.(可选)添加自定义插件，具体的自定义插件部署可参考4.3章节"插件扩展功能"。填写插件名称，对应的镜像地址，插件执行阶段等信息。 ●镜像地址：插件编译后打包的Wasm镜像存放地址(OCI镜像仓库)。 ●插件执行阶段：控制插件在请求处理链中的生效位置，按需选择阶段（认证 → 鉴权 → 统计 → 默认），同一执行阶段内按照插件执行优先级大小顺序进行执行。 ●插件拉取策略：分为默认/总是拉取/仅本地不存在时拉取，默认模式下，若本地已存在插件，则直接使用缓存，不再重新拉取；仅当本地不存在时，去远端仓库拉取。 3.配置插件。Higress的插件配置分为全局配置或者单路由配置。单路由配置：进入"AI路由管理"界面，选择对应的路由，点击"策略"，在"策略配置"界面选择对应的插件，点击"配置"，打开"开启状态"按钮后配置将会在该路由上生效。全局配置：进入"插件配置"界面，选择对应的插件，点击"配置"，打开"开启状态"按钮后配置将会在所有域名和路由上生效。 4.验证插件生效。以"请求屏蔽"插件为例，为vllm-route-test1路由配置"请求屏蔽"插件并开启，屏蔽请求body为"illegal"，返回状态码为403。配置前请求body带"this is a illegal content"返回正常。插件配置后相同请求返回403Forbidden，验证插件配置成功。 4.2.4 消费者管理消费者管理用于为不同的调用方（应用或租户）创建身份标识并分配认证凭证（如KeyAuth、OAuth2、JWT等），以控制其对后端服务或AI接口的访问权限。配置步骤： 1.在Higress网关页面左侧点击"消费者管理", 进入消费者管理页面, 点击"创建消费者"。 2.填写消费者名称，认证凭证，令牌来源等信息。令牌来源指定网关从请求的哪个位置获取认证凭证： ●Authorization: Bearer ${value}：从HTTP请求头的Authorization字段中提取Bearer令牌（默认方式）。 ●自定义HTTP Header：从自定义的请求头字段中获取令牌。 ●查询参数：从URL的查询字符串（如?token=xxx）中获取令牌。 3.验证消费者是否配置成功。参考4.2.2 AI路由管理小节，验证是否能够在配置"允许请求本路由的消费者名称列表"时候带出。 4.验证消费者鉴权。不使用令牌时验证不通过。使用路由对应的消费者令牌后验证通过。 4.2.5 实践示例本参考实践提供两个场景下对接后端推理服务的示例：GPUStack本地部署推理服务场景，非GPUStack本地部署推理服务场景。非GPUStack本地部署推理服务场景： 1.配置AI服务提供者。 2.配置消费者, 认证令牌为"test"。 3.配置AI路由。选择启用请求认证，允许访问消费者选择刚才创建的消费者"consumer-test"。 4.配置插件。对于刚才配置的AI路由vllm-route-test配置插件"请求屏蔽"，设置开启状态为打开，配置请求体为敏感词的时候进行屏蔽并返回响应403。 5.验证路由转发。请求屏蔽开启后识别到请求体中包含"敏感词"，因此插件生效，响应返回403。请求屏蔽关闭后正常返回，请求转发到AI服务提供者配置的本地部署的后端推理服务。 GPUStack本地部署推理服务场景： Higress和GPUStack在同一个集群中时，由于GPUStack本身也有内置的路由能力，因此需要做好2个系统命名空间和Ingress类型的隔离。以本参考实践为例，独立部署的Higress的命名空间为"higress-system"，IngressClass为"higress-individual"。 GPUStack的命名空间为"gpustack"，内置的higress的IngressClass为"higress"。 1.参考基于GPUStack的模型服务能力增强参考实践安装部署GPUStack并启动后端推理服务，若GPUStack已部署则忽略该步骤。本参考实践使用Helm Chart方式部署GPUStack到K8S集群中，且部署在"gpustack"命名空间中。 2.检查GPUStack的现有配置。查看GPUStack及内置的Higress所在的命名空间：kubectl get namespace kubectl get pods -n gpustack 确认内置网关已启用：kubectl get deployment higress-gateway -n gpustack 查看当前 IngressClass：kubectl get ingressclass 3.(可选) 配置GPUStack内置的网关service类型为ClusterIP。 GPUStack内置的网关service类型默认为LoadBalancer，这会导致两个Higress网关都会对外提供服务，若想保证统一入口(只有独立Higress网关提供对外服务)，则建议执行以下指令更新内置网关service类型为ClusterIP(按照联网/离线场景选择对应指令)：helm upgrade gpustack gpustack-chart/ -n gpustack --set higress-core.gateway.service.type=ClusterIP --reuse-values #此处gpustack-chart为从官方下载到本地的chart包，在离线场景下进行本地chart包更新helm upgrade gpustack oci://registry-1.docker.io/gpustack/gpustack-chart \ -n gpustack \ --set higress-core.gateway.service.type=ClusterIP #联网场景 4.修改单独部署的Higress网关的 IngressClass 名称，确保该名称与GPUStack内置的Higress的IngressClass名称(默认为"higress")不一致。若单独的Higress网关尚未部署，执行以下指令部署的时候指定IngressClass名称：# 添加 Higress 的 Helm 仓库（如果尚未添加） helm repo add higress.io https://higress.io/helm-charts # 安装 Higress，并指定一个独立的 IngressClass 名称，例如 "higress-individual" helm install higress higress.io/higress -n higress-system --create-namespace \ --set global.ingressClass=higress-individual 若已经部署了单独的Higress网关，执行以下指令更新IngressClass名称：# 升级已部署的 Higress 网关，修改其 IngressClass 名称 helm upgrade higress -n higress-system \ --set global.ingressClass=higress-individual \ higress.io/higress 验证新的IngressClass名称已创建：kubectl get ingressclass 5.在单独部署的Higress网关上配置 AI 路由，将流量转发给 GPUStack。以下示例使用的内置网关service类型为ClusterIP，在创建AI服务提供者时选择自定义 OpenAI 服务配置方式为"选择服务"，自定义 OpenAI 服务选择对应的K8S集群中的服务"higress-gateway.gpustack.svc.cluster.local:80"即可。若内置网关service类型为LoadBalancer，在创建AI服务提供者时选择自定义 OpenAI 服务配置方式为"输入URL"，自定义 OpenAI 服务 BaseURL选择GPUStack内置higress对外暴露的IP即可。设置对应的AI服务提供者：设置对应的AI路由： 6.验证Higress成功将流量转发到GPUStack。说明： 1.如果从Docker Hub下载镜像缓慢，可以使用镜像网站quay.io。 2.在GPUStack本地部署推理服务场景中，由于GPUStack机制存在一个已知问题，请求使用的model name请勿与GPUStack后端服务实际的model name一致，否则会报错404。 4.3 插件扩展功能插件扩展功能包含Higress预置的插件如请求脱敏及本参考实践提供的自定义插件如请求动态限流，模型智能路由增强等。对于Higress预置的插件使用，请参考Higress官方文档进行使用：Higress预置插件文档。本参考实践提供的自定义插件（包含请求QoS、请求动态限流、模型智能路由等），默认按照小节3.2或者3.3的自动部署步骤即可直接使用。如用户有其他自定义的插件，请参考如下流程进行编译并推送到仓库，并参考小节4.2.3插件管理完成自定义插件的添加与管理。自定义插件编译与生效流程：插件编译：自定义插件需根据源码进行编译安装，才能在Higress中使用，以下是自定义插件的编译、构建镜像的流程： 1.安装Go环境若自定义插件是用Go语言编写，则编译插件需要安装Go环境：wget https://go.dev/dl/go1.24.4.linux-aarch64.tar.gz tar -C /usr/local -xzf go1.24.4.linux-aarch64.tar.gz export PATH=$PATH:/usr/local/go/bin 2.编译自定义插件执行以下命令，会生成main.wasm文件，也就是自定义插件。cd /path/to/wasm-dir go mod tidy GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared -o main.wasm ./ 3.构建镜像将步骤2中main.wasm文件打包到镜像里，步骤如下：先创建文件DockerfileFROM scratch COPY main.wasm plugin.wasm 然后构建镜像并推送到仓库：docker build -t /your-wasm:1.0.0 -f Dockerfile . docker push /your-wasm:1.0.0 说明： Higress 的预置插件以 OCI 镜像形式存储，使用时需从镜像仓库拉取。在离线或内网环境中，需提前将所需插件镜像下载并推送至本地镜像仓库，然后在 WasmPlugin CRD 中将 url 字段改为本地仓库地址，否则网关将因拉取失败而无法加载插件。若部署并启用了 Higress Plugin Server，则无需此操作——Plugin Server 会内置所有预置插件的镜像，网关可直接从其拉取，章节3部署指南中已包含Plugin Server的启用。 4.3.1 请求脱敏插件 AI 数据脱敏插件（下文简称请求脱敏插件）是 Higress 预置的插件，通过配置灵活的拦截与替换规则，对经过网关的 AI 请求和响应内容进行实时处理，实现敏感词拦截、隐私数据脱敏等功能，确保敏感信息在传输和处理过程中的安全。 4.3.1.1 插件编译安装按照第3章节部署，已默认安装Higress预置插件，可直接配置使用。 4.3.1.2 插件配置使用插件配置界面：针对某个AI路由配置：Higress控制台->左侧菜单AI网关管理->AI路由管理->选中路由后点击策略->AI数据脱敏->设置。全局配置：Higress控制台->左侧菜单插件配置->AI数据脱敏->设置。插件配置说明：配置后打开"开启"按钮保存后即生效。表1 配置说明配置内容对应YAML视图字段取值描述示例示例说明 OpenAI协议拦截 deny_openai true/false，默认为true 是否开启AI请求拦截功能。 true 一般用于拦截请求及返回内容，如用户请求中的messages[""].content，返回内容中的choices[*].message.content，choices[*].message.reasoning字段 JsonPath拦截 deny_jsonpath JsonPath 表达式指定要从请求/响应 JSON 中提取哪个字段内容进行敏感词检测。 $.messages[""].content 提取 messages 数组里某个对象的 content 字段，例如请求体是{"messages":[{"role":"user","content":"你好"}]} 原始Body拦截 deny_raw true/false 是否拦截原始文本 false 系统拦截规则 system_deny true/false，默认值为false 是否开启内置拦截规则。 false 拦截状态码 deny_code 自定义拦截时http状态码 400 AI拦截消息 deny_message 自定义 openai拦截时返回内容提问中包含敏感词，已被屏蔽开启了OpenAI协议拦截后返回的拦截内容非AI拦截消息 deny_raw_message 自定义非openai拦截时返回内容提问中包含敏感词，已被屏蔽拦截返回类型 deny_content_type 自定义非openai拦截时返回content_type头 application/json 自定义敏感词 deny_words 自定义自定义敏感词列表 deny_words: - "暴力" - "色情" - "赌博" - "毒品" 敏感词替换规则 replace_roles 自定义自定义敏感词替换规则，由regex、type、value、restore组成 replace_roles: # 邮箱地址替换 - regex: "%{EMAIL:email}" type: "replace" value: "***@***.***" 规则正则 replace_roles.regex 正则表达式用于敏感词替换的规则正则表达式 %{EMAIL:email} 替换类型 replace_roles.type replace/hash 将敏感词替换成什么样子，一般选项为replace(替换成设置好的替换值)/hash(转换成哈希值) replace 若选择hash则不需要填写替换值字段是否恢复 replace_roles.restore true/false 是否将替换后的敏感词恢复原样后返回展示到前端 true 以敏感词"张三", 替换值"***"为例，两种情况大模型都会看到脱敏后的"***", 若选择恢复，则请求返回结果显示为"张三"，若选择不恢复，则请求返回结果显示为"***" 替换值 replace_roles.value 自定义用于替换敏感词的值 **** 说明： 1.为保障性能，拦截敏感词库的数量和替换规则的数量和建议不超过2000。 2.拦截及替换规则同时开启时，插件会先扫描是否触发拦截，若触发则直接返回，若未触发，则进一步匹配敏感词并按照替换规则进行替换。 3.OpenAI协议拦截/JsonPath拦截/原始Body拦截三个开关均用于拦截与替换， OpenAI协议拦截用于拦截用户的请求及返回内容，JsonPath拦截用于具体Json表达式需要拦截的字段，原始Body拦截会扫描整个请求或响应Body进行拦截，三者覆盖范围依次叠加，按需选择单个或多个拦截开关即可。插件配置示例：以下为脱敏插件yaml视图配置示例：该示例配置了敏感词拦截(敏感词为"炸弹""爆炸"，拦截返回状态码为400)，启用系统拦截库，隐私信息脱敏(手机，电子邮箱，IP信息，身份证号等替换成*号，API令牌替换成哈希值)。system_deny: true deny_openai: true deny_jsonpath: - "$.messages[*].content" deny_raw: true deny_code: 400 deny_message: "提问或回答中包含敏感词，已被屏蔽" deny_raw_message: "{\"errmsg\":\"提问或回答中包含敏感词，已被屏蔽\"}" deny_content_type: "application/json" deny_words: - "炸弹" - "爆炸" replace_roles: - regex: "%{MOBILE}" type: "replace" value: "****" # 手机号 13800138000 -> **** - regex: "%{EMAILLOCALPART}@%{HOSTNAME:domain}" type: "replace" restore: true value: "****@$domain" # 电子邮箱 admin@gmail.com -> ****@gmail.com - regex: "%{IP}" type: "replace" restore: true value: "***.***.***.***" # ip 192.168.0.1 -> ***.***.***.*** - regex: "%{IDCARD}" type: "replace" value: "****" # 身份证号 110000000000000000 -> **** - regex: "sk-[0-9a-zA-Z]*" restore: true type: "hash" # hash sk-12345 -> 9cb495455da32f41567dab1d07f1973d # hash后的值提供给大模型，从大模型返回的数据中会将hash值还原为原始值以下面请求为例：我的手机号是13800138000，身份证是110101199001011234，邮箱是admin@gmail.com，我的IP是192.168.0.1，OpenAI的key是sk-abc123xyz 该请求未触发拦截规则，且匹配到了替换规则，大模型收到的请求会替换成：我的手机号是****，身份证是****，邮箱是****@gmail.com，我的IP是***.***.***.***，OpenAI的key是9cb495455da32f41567dab1d07f1973d 大模型返回的结果为：好的，您的手机号****已记录，邮箱admin@gmail.com已验证，IP192.168.0.1已识别。 4.3.1.3 插件功能验证该配置开启了对 OpenAI 协议请求的拦截功能，对于请求中 messages 数组里每条消息的 content 字段进行检查，当用户消息包含“炸弹”时，请求会被直接拦截，返回错误消息，不会执行任何替换。当用户消息不包含"炸弹"时，请求会继续处理。此时，所有“李四”都会被替换为 ****，再发送给大模型。如果大模型的回答中也包含“李四”，在返回时也会被替换为 ****。基于该配置示例，验证以下三个拦截功能： 1.输入提示词拦截用户输入提示词包含"炸弹"，消息被拦截，返回状态码400以及拦截消息"提问或回答中包含敏感词, 已被屏蔽"。用户消息包含"炸弹"，即使包含需要替代的敏感词"李四"，按照上述说明2，该消息会先扫描拦截的规则，因此该消息仍会被拦截，返回状态码400以及拦截消息"提问或回答中包含敏感词, 已被屏蔽"。 2.输出结果拦截输出结果包含敏感词"炸弹"，消息被拦截，返回拦截消息"提问或回答中包含敏感词, 已被屏蔽"。说明：输出结果拦截时会返回拦截信息，但是不会返回设置的拦截状态码，而是一律返回200。 3.输入替换用户消息不包含需要拦截的敏感词，不会被拦截；用户消息包含"李四"，命中替换规则，且是否恢复为false，传给模型的提示词以及模型返回回答中会将"李四"替换成"****"。注意：在多个插件配合使用的过程中需要注意插件执行的优先级。以请求脱敏插件与model-route插件为例，model-route插件会提取请求中的"model"字段并组装请求头字段"x-higress-llm-model"用于请求与AI路由的匹配，请求脱敏插件的优先级会高于model-route，因此请求脱敏插件会先执行，此时请求头字段未配置，会导致找不到对应的AI路由，请求脱敏插件不生效。解决方案：调高model-route的优先级或调低AI数据脱敏插件的优先级，以及在请求上手动设置请求头字段"x-higress-llm-model"。调高model-route插件的优先级或调低AI数据脱敏插件的优先级：配置路径：控制台菜单->插件配置->右上角三个点(该配置全局生效)。手动设置请求头字段：将请求体中"model"字段的内容设置到请求头"x-higress-llm-model"字段。 4.3.2 请求QoS插件 4.3.2.1 插件介绍本插件能够根据管理员配置的 API Key 精确匹配或正则匹配规则，自动识别用户请求并为其分配对应优先级，然后将该优先级注入请求体中。 4.3.2.2 插件编译安装 1.插件源码链接：链接: 2.按照第3章节部署，已默认安装该自定义插件，可直接配置使用。 4.3.2.3 插件配置使用 1.新增插件网页端点击新增插件，填入以下信息，注意镜像地址替换为实际地址，执行阶段选择认证阶段 2.配置插件在网页端如下图所示配置即可。配置示例:# 精确匹配 exact: - apiKey: "sk-premium-user" priority: 100 - apiKey: "sk-standard-user" priority: 50 # 正则匹配 regex: - apiKey: "^sk-vip-.*$" priority: 80 # 默认优先级（必须配置） default: priority: 10 注：priority值越低优先级越高 4.3.2.4 插件功能验证本插件必须按照4.2.2章节配置AI路由才能正确调用执行以下命令验证插件，注意{ip}和{port}替换为实际的网关的ip与portcurl http://${ip}:${port}/v1/chat/completions \ -H "Authorization: Bearer sk-vip-001" \ -H "Content-Type: application/json" \ -d '{"model":"gpt-4","messages":[{"role":"user","content":"hello"}]}' 可通过抓包或者其他方式看到发往vLLM的请求被添加了对应的priority字段 4.3.3 请求动态限流插件 4.3.3.1 插件介绍动态限流插件给不同优先级的请求设置动态限流门限，高优先级请求可分配更高的吞吐带宽；在模型服务空闲时，各组可跨组借用，超比例使用带宽资源。核心机制： ●配额分组：4 个分组（high_group/medium_group/low_group/default_group），比例之和必须为 100。未匹配到任何规则的 API Key 归入 default_group（默认组）。 ●双层限流：插件支持RPM和TPM两种限流维度，可以使用其中一种或者同时生效。 ●跨组额度借用：系统负载较高时，各组只能用各自的份额，互不抢占；当负载降到下行水线（watermark_low）以下并持续一段时间后，放宽逐组限制，允许各组借用其他组未用完的额度；负载回升到上行水线（watermark_high）以上后恢复分组隔离。 4.3.3.2 插件编译安装 1.插件源码链接：链接: 2.按照第3章节部署，已默认安装该自定义插件，可直接配置使用。 4.3.3.3 插件配置使用 1.新增插件网页端点击新增插件，填入以下信息，注意镜像地址替换为实际地址，执行阶段选择认证阶段 2.配置Redis服务在网页端选择服务来源，创建服务来源，添加实际的Redis服务地址配置的服务名称在下一步配置插件时需增加后缀.static，按图中示例为redis.static 3.配置插件在网页端如下图所示配置即可配置字段 redis（必选）名称数据类型填写要求默认值描述 redis.service_name string 必选 — Redis 服务名（FQDN），支持 .static 后缀和 IP redis.service_port int 可选 6379 Redis 端口 redis.username string 可选 — Redis 用户名 redis.password string 可选 — Redis 密码 redis.timeout int 可选 1000 调用超时，单位 ms redis.database int 可选 0 Redis 数据库编号限流参数名称数据类型填写要求默认值描述 group_ratio object 必选 — 4 个分组的配额比例，范围 [0, 100]，4组总和必须为100 group_ratio.high_group int 必选 — 高份额组 group_ratio.medium_group int 必选 — 中份额组 group_ratio.low_group int 必选 — 低份额组 group_ratio.default_group int 必选 — 默认组 max_tpm int 可选 — 每分钟最大 Token 数（TPM 限制） max_rpm int 可选 — 每分钟最大请求数（RPM 限制） window_seconds int 可选 60 统计窗口，单位秒，最小 1 watermark_high int 可选 80 上行水线百分比，范围 [0, 100]，负载超过此线时恢复分组隔离 watermark_low int 可选 60 下行水线百分比，范围 [0, 100]，负载低于此线时允许跨组借用，必须小于 watermark_high key_prefix string 可选空 Redis key 前缀，仅允许字母、数字、下划线 default_output_tokens int 可选 0 默认预估输出 Token 数（请求未指定 max_tokens 时使用），仅 TPM 启用时生效 zh_token_weight float 可选 0.8 中文字符的 Token 权重，仅 TPM 启用时生效。0.8表示1个中文字符预估为0.8个token en_token_weight float 可选 0.25 英文字符的 Token 权重，仅 TPM 启用时生效。0.25表示1个英文字符预估为0.25个token 注：group_ratio 的 4 个值之和必须为 100。 max_tpm 和 max_rpm 至少配置一项。 api_key_mappings（可选）将 API Key 映射到配额组名（high_group/medium_group/low_group/default_group）。未匹配的 Key 归入 default_group。名称数据类型填写要求默认值描述 api_key_mappings.exact map 可选 — 精确匹配：API Key → 配额组名 api_key_mappings.regex map 可选 — 正则匹配：正则表达式 → 配额组名匹配顺序：先 exact 精确匹配 → 再 regex 正则匹配 → 均未命中则归入 default 组。插件从 Authorization: Bearer 或 X-API-Key 请求头提取 API Key。配置示例：（1）仅 RPM：只限制每分钟请求数redis: service_name: "redis.default.svc.cluster.local" service_port: 6379 group_ratio: high_group: 50 medium_group: 30 low_group: 15 default_group: 5 max_rpm: 600 （2）仅 TPM：只限制每分钟 Token 数，不限请求次数redis: service_name: "redis.default.svc.cluster.local" service_port: 6379 group_ratio: high_group: 50 medium_group: 30 low_group: 15 default_group: 5 max_tpm: 1000000 （3）RPM + TPM：同时限制每分钟请求数和Token数redis: service_name: "redis.default.svc.cluster.local" service_port: 6379 username: "" password: "secret" timeout: 1000 database: 0 # 4 组配额比例，和必须为 100 group_ratio: high_group: 40 medium_group: 30 low_group: 20 default_group: 10 # 每分钟最大 Token 数和请求数 max_tpm: 2000000 max_rpm: 1000 # 统计窗口（秒） window_seconds: 60 # 水位：负载降到 low 以下时允许跨组借用，回升到 high 以上时恢复分组隔离 watermark_high: 80 watermark_low: 60 # Redis key 前缀（多租户隔离） key_prefix: "tenant_a" # 请求未指定 max_tokens 时的默认预估输出 default_output_tokens: 2048 # Token 估算权重（仅 TPM 启用时生效） zh_token_weight: 0.8 en_token_weight: 0.25 # API Key → 配额组映射 api_key_mappings: exact: "sk-premium-tier": "high_group" # 40% 配额 "sk-standard-tier": "medium_group" # 30% 配额 regex: "^sk-pro-.*$": "high_group" # 归入 high_group "^sk-basic-.*$": "low_group" # 归入 low_group 插件在加载配置时对配置字段做校验。若配置了非法值，控制台不会给出提示，仅在网关日志中输出报错，因此配置完成后务必查看日志确认配置已生效，失败时日志输出具体的校验错误信息，按提示修正后重新应用。 Kubernetes 部署：查看网关 Pod 的标准输出kubectl -n higress-system logs All-in-One 容器部署：查看容器内的网关日志文件docker exec -it cat /var/log/higress/gateway.log 4.3.3.4 插件功能验证执行以下命令验证插件，注意{ip}和{port}替换为实际的网关的ip与portcurl http://${ip}:${port}/v1/chat/completions \ -H "Authorization: Bearer sk-vip-001" \ -H "Content-Type: application/json" \ -d '{"model":"gpt-4","messages":[{"role":"user","content":"hello"}]}' 限流效果可通过提高并发观察被拒绝返回429的请求比例，或者通过vllm自带的/metrics接口观察通过的请求数 4.3.4 模型智能路由增强插件在模型智能路由方案中，语义识别和复杂度识别是两种不同的实现方式。语义识别可以对请求进行语义进行分类，实现不同语义的请求走不同的路由；而复杂度识别则是对请求的各个维度进行评估，综合计算一个复杂度，实现不同复杂度类型的请求走不同的路由。 4.3.4.1 语义识别在模型智能路由方案中，语义识别插件可以对请求进行语义进行分类，并给请求打上和类别有关的header头，然后进行重路由，根据header头的信息将请求转发到不同的路由，实现基于语义识别的智能路由。基于此，我们开发了ai-semantic插件。 ai-semantic插件在网关侧对用户请求做意图分类，并把分类结果写入指定的请求header，用于后续按意图路由到不同上游路由/模型。它支持两种分类方式： ●embedding 模型分类：把用户问题与各类别的示例句子（utterances）分别向量化，计算余弦相似度，取相似度最高且达到阈值的类别； ●大模型（LLM）分类：把用户问题与预设类别拼进prompt交给LLM，直接返回类别名。 4.3.4.1.1 插件编译安装 1.插件源码链接：链接。 2.按照第3章节部署，已默认安装该自定义插件，可直接配置使用。 4.3.4.1.2 插件配置使用要将ai-semantic插件配置到higress网关，需要在AI路由管理里新建一个AI路由，并为其配置ai-semantic插件，执行阶段为认证阶段、优先级900（>800即可），并根据分类类别，创建不同的AI路由，用于处理不同的分类结果，这些路由需要配置header校验条件，确保路由处理的请求为对应类别的请求。使用流程如下：具体步骤如下： 1.新增自定义插件使能ai-semantic插件，需要在构建好ai-semantic插件镜像后，在Higress控制台添加该插件，步骤如下：打开Higress控制台“插件配置->添加插件”，新增ai-semantic插件，如下为配置示例（补充插件镜像地址即可）： 2.新建AI服务及higress服务新建AI服务：用Embedding、LLM分类以及各个路由的后端，均需要提供AI服务，可参考4.2.1章《AI服务提供者管理》添加AI服务。配置示例如下，其中qwen25、qwen3为路由后端模型，qwen3embedding、qwen35为分类用的模型：新建embedding模型路由和大模型路由：需新建两条higress的模型路由，供该插件访问embedding或LLM分类模型，如下所示：新建higress服务：需新建一个固定地址的服务（如：semantic-service），服务指向自身网关实例+端口（如127.0.0.1:8080），ai-semantic插件内部需要该服务进行调用，以访问上述新增的路由： 3.配置通用路由通用路由：请求经过的第一个路由，用于对请求prompt的语义进行识别、分类。通用路由用来转发用户的请求，所有的请求都会经过通用路由，ai-semantic插件也是配置在该插件上，通用路由分类完成后，会将请求转发给对应的路由，配置方法如下：打开Higress控制台“AI网关管理->AI路由管理”，新增新建一个AI路由，示例如下（可按实际情况修改目标AI服务）： 4.配置分类路由分类路由：根据通用路由的分类结果将请求转发到不同的路由后端，也就是分类路由。分类路由用于处理用户的请求，将请求转发给模型后端。在语义分类路由场景下，可以为不同的路由配置不同的后端，配置方法如下：打开Higress控制台“AI网关管理->AI路由管理”，新增新建一个AI路由，示例如下（可依据实际情况配置多个类别的路由），为code、analysis、summarize和query场景配置路由：注意：此处目标AI服务中需指定目标模型，将请求中的model字段转换为指定的模型，防止因model名称不匹配导致模型调用失败，示例中code、analysis、summarize和query四个路由的model分别为qwen25、qwen3、qwen3、qwen3。 5.使能ai-semantic插件 ai-semantic插件的功能是根据请求的prompt进行分类，并将分类结果添加到指定的header中，故只需给通用路由配置ai-semantic插件，配置方法如下：打开Higress控制台“AI网关管理->AI路由管理->test-ai-semantic->策略”，点击策略即可为该通用路由配置插件，示例如下：进入插件配置界面后，滑到最底部，选择“自定义->ai-semantic->配置”进行插件的配置：进入ai-semantic配置界面后，将插件设为开启，并配置yaml视图，点击保存，示例如下：如下是其中的yaml示例：embedding: ApiKey: "" Model: "" ServiceName: "semantic-service.static" Threshold: 0.6 Timeout: 10000 Url: "http://127.0.0.1:80/semantic-embedding/v1/embeddings" enabled: true utterances: code: - "写一段Bash代码实现：解析日志并过滤出ERROR行" - "这个异常是什么意思：ModuleNotFoundError: No module named 'xxx'" analysis: - "把工作流自动化拆成可执行步骤" - "把准备一次技术面试拆成可执行步骤" summarize: - "给我一个三点总结：今天我们讨论了三件事：第一是项目排期，第二是接口改动，第三是上线风险。总体结论是先做最小可用版本。" - "帮我总结一下：这篇文章主要讲了如何用缓存减少数据库压力，并给出了失效策略与建议。" query: - "成都这周末适合出门吗？" - "深圳明天会下雨吗？" llm: ApiKey: "" Model: "" ServiceName: "semantic-service.static" Timeout: 10000 Url: "http://127.0.0.1:80/semantic-llm/v1/chat/completions" enabled: true prompt: |- 你是一个智能类别识别助手，负责根据用户提出的问题和预设的类别，确定问题属于哪个预设的类别，并给出相应的类别。用户提出的问题为:'%s'，预设的类别为'%s'，你需要直接返回一种具体类别。 modelToHeader: "higress-llm-model" scene: category: "code|analysis|summarize|query" fallback_category: "Not Match" 其中semantic-service.static为步骤2新建的higress服务，可在Higress控制台“服务列表->服务名称（FQDN）”查看，Url字段则为步骤2新建的higress服务。在通用路由进行分类并改写header后，会进行重路由，需要根据分类结果匹配到不同的分类路由，故要为分类路由分别配置不同的请求头匹配规则，配置方法如下：上面的ai-semantic插件配置中会将分类结果写入higress-llm-model这个header里，故在每个分类路由需要配置对应的higress-llm-model字段匹配规则，示例如下（分别编辑test-ai-semantic-code、test-ai-semantic-analysis、test-ai-semantic-summarize和test-ai-semantic-query路由）： 4.3.4.1.3 插件功能验证配置好ai-semantic插件和对应的路由后，即可进行调用测试，示例如下（模型最终被路由到了code类别，其后端模型是qwen25）：执行命令示例：curl http://110.21.1.25:13002/v1/chat/completions \ -H 'Content-Type: application/json' \ -d '{ "model": "deepseek_v4_flash", "messages": [ {"role": "user", "content": "给我一个脚本：读取一个JSON文件并统计字段出现次数"} ] }' 也可以查看debug日志确认具体信息，方式如下：curl localhost:15000/logging?wasm=debug -X POST cat /var/log/higress/gateway.log 得到的日志示例如下： 4.3.4.2 复杂度识别在模型智能路由方案中，复杂度识别插件可以对请求进行复杂度计算和分类，并给请求打上和类别有关的header头，然后进行重路由，根据header头的信息将请求转发到不同的路由，实现基于复杂度识别的智能路由。通过识别请求的复杂度，将不同复杂度的请求路由到匹配的模型：简单请求使用轻量模型，复杂请求使用更强模型，使模型选择更加合理，同时降低调用成本。基于此，我们开发了ai-complexity插件。 ai-complexity插件在网关侧对用户请求做复杂度分类，并把分类结果写入指定的请求header，用于后续按复杂度路由到不同上游路由/模型。它支持八个维度的复杂度计算： ●推理：配置项为reasoning_keywords，根据命中推理关键词数量计算得分； ●代码：配置项为code_keywords，支持追加关键词，根据命中代码关键词数量计算得分； ●技术：配置项为technicalTerms_keywords，支持追加关键词，根据命中技术关键词数量计算得分； ●上下文长度：配置项为token_count_threshold，设置simple与complex两个长度分界点，共分为三个长度区间，根据输入token长度所处区间计算得分； ●工具调用：配置项为toolCalls，根据tool_call调用数量计算得分； ●简单场景：配置项为simpleIndicators_keywords，支持追加关键词，根据是否命中简单关键词计算得分； ●分步：仅可配置权重，根据命中分步结构计算得分； ●问号：仅可配置权重，根据命中问号数量计算得分；根据复杂度得分，请求将被分为四档：SIMPLE、MEDIUM、COMPLEX、REASONING。 4.3.4.2.1 插件编译安装 1.插件源码链接：链接。 2.按照第3章节部署，已默认安装该自定义插件，可直接配置使用。 4.3.4.2.2 插件配置使用要将ai-complexity插件配置到higress网关，需要在AI路由管理里新建一个AI路由，并为其配置ai-complexity插件，执行阶段为认证阶段、优先级900（>800即可），并根据分类类别，创建不同的AI路由，用于处理不同的分类结果，这些路由需要配置header校验条件，确保路由处理的请求为对应类别的请求。使用流程如下：具体步骤如下： 1.新增自定义插件使能ai-complexity插件，需要在构建好ai-complexity插件镜像后，在Higress控制台添加该插件，步骤如下：打开Higress控制台“插件配置->添加插件”，新增ai-complexity插件，如下为配置示例（补充插件镜像地址即可）： 2.新建AI服务不同复杂度的请求会被转发到不同的路由，各个路由的后端，均需要提供AI服务，可参考4.2.1章《AI服务提供者管理》添加AI服务。如下基于AICoding场景，配置三个AI服务，分别为GLM5.2（REASONING档）、deepseek_v4_flash（COMPLEX档）、qwen3.5-27b（MEDIUM、SIMPLE档），具体的模型可按实际场景自行配置： 3.配置通用路由通用路由：请求经过的第一个路由，用于对请求prompt的复杂度进行识别、分类。通用路由用来转发用户的请求，所有的请求都会经过通用路由，ai-complexity插件也是配置在该插件上，通用路由分类完成后，会将请求转发给对应的路由，配置方法如下：打开Higress控制台“AI网关管理->AI路由管理”，新增新建一个AI路由，示例如下（可按实际情况修改目标AI服务）： 4.配置分类路由分类路由：根据通用路由的分类结果将请求转发到不同的路由后端，也就是分类路由。分类路由用于处理用户的请求，将请求转发给模型后端。在复杂度识别路由场景下，可以为不同的路由配置不同的后端，配置方法如下：打开Higress控制台“AI网关管理->AI路由管理”，新增新建一个AI路由，示例如下（可依据实际情况配置多个类别的路由），为REASONING档、COMPLEX档、MEDIUM档和SIMPLE档配置路由：注意：此处目标AI服务中需指定目标模型，将请求中的model字段转换为指定的模型，防止因model名称不匹配导致模型调用失败，示例中REASONING档、COMPLEX档、MEDIUM档和SIMPLE档四个路由的model分别为GLM5.2、deepseek_v4_flash、qwen3.5-27b、qwen3.5-27b。 5.使能ai-complexity插件 ai-complexity插件的功能是根据请求的prompt进行分类，并将分类结果添加到指定的header中，故只需给通用路由配置ai-complexity插件，配置方法如下：打开Higress控制台“AI网关管理->AI路由管理->test-ai-complexity->策略”，点击策略即可为该通用路由配置插件，示例如下：进入插件配置界面后，滑到最底部，选择“自定义->ai-complexity->配置”进行插件的配置：进入ai-complexity配置界面后，将插件设为开启，并配置yaml视图，点击保存，示例如下：如下是其中的yaml示例：modelToHeader: "higress-complexity" fallback_tier: "MEDIUM" complexity_tier_boundaries: simple_medium: 0.10 medium_complex: 0.25 complex_reasoning: 0.45 dimension_weights: reasoningMarkers: 0.30 codePresence: 0.15 technicalTerms: 0.15 simpleIndicators: 0.10 toolCalls: 0.10 tokenCount: 0.10 multiStepPatterns: 0.05 questionComplexity: 0.05 在通用路由进行分类并改写header后，会进行重路由，需要根据分类结果匹配到不同的分类路由，故要为分类路由分别配置不同的请求头匹配规则，配置方法如下：上面的ai-complexity插件配置中会将分类结果写入higress-complexity这个header里，故在每个分类路由需要配置对应的higress-complexity字段匹配规则，示例如下（分别编辑test-ai-complexity-reasoning、test-ai-complexity-complex、test-ai-complexity-medium和test-ai-complexity-simple路由）： 4.3.4.2.3 插件功能验证配置好ai-complexity插件和对应的路由后，即可进行调用测试，示例如下（基于AICoding场景，测试不同复杂度的请求对应的路由）：示例以opencode为基础进行开发，涉及代码开发的设计、开发、文档写作等各个阶段，如下是该示例下不同步骤的输入：步骤一：你做为一个资深的代码专家，现在需要你设计一个记账软件，并详细分析其架构和实施可行性；步骤二：把这个方案写入设计文档；步骤三：按照这个方案的的要求开发吧；步骤四：写下readme吧；通过查看higress网关info日志确认具体信息，方式如下：curl localhost:15000/logging?wasm=info -X POST cat /var/log/higress/gateway.log 得到的日志示例如下：可以看到，不同类型的任务被路由到了不同档位的模型。 4.3.5 Token配额管理插件大模型服务通过Higress AI网关统一对外提供访问接口。随着用户规模增长，为了合理分配资源，防止滥用或恶意消耗资源，管理方需对每名用户的token使用额度进行管理控制。 4.3.5.1 方案介绍本方案基于Higress网关的插件能力，搭建配套的Token额度管理平台实现对消费者的Token配额管理，平台由前端管理界面与后台额度管理服务组成。管理员登录平台后，可实时查看各消费者的余额与额度管理模式，支持修改初始额度、追加当前可用额度、批量编辑与批量重置；所有余额变化均记录操作流水，每月/每日自动重置额度，记录完整重置日志，全程可审计。 Token额度管理平台需具备以下三个核心能力： 1.余额可查：实时掌握每个消费者的剩余可用 Token 额度； 2.超额可拦：额度耗尽时在网关层直接拒绝请求，避免产生超额调用； 3.额度可续：支持按月、按天、固定总量三种额度控制模式，同时提供管理员手动控制额度的能力。所有操作全程留痕、可审计。本额度管理服务围绕这套额度管控机制构建开发，各组件关系图如下： 4.3.5.2 平台部署参考章节3.2 Docker部署的操作步骤完成Token额度管理平台的自动化部署。 4.3.5.3 平台使用 4.3.5.3.1 准备工作 Token额度管理平台完成部署后，需要在Higress Console界面（默认http://<网关地址>:8001）完成以下配置。 1.配置Redis访问来源点击Higress Console的左侧菜单 "服务来源 -> 创建服务来源"：配置项值类型固定地址（Static IP）名称固定为 local-redis.static 服务地址 Redis 的可达地址，如 127.0.0.1:6379（与网关同机）或 :6379 注意：创建后该来源的服务端口为 80（映射到填的 6379）。后文的 ai-quota 插件配置中 service_name 填 local-redis.static、service_port 填 80——填成 6379 会导致插件初始化 Redis 失败（日志报 bad argument）。 2.配置服务来源点击Higress Console的左侧菜单“服务来源 -> 创建服务来源”：配置项值类型固定地址（Static IP）名称固定为 quota-admin-web 服务地址平台 8081 的可达地址：与网关同机填 127.0.0.1:8081；容器部署填宿主机 IP:8081 3.配置域名与证书平台流量中携带管理员凭证（Basic认证的用户名密码以Base64明文编码传输），且接口涉及额度等敏感数据，故必须采用HTTPS通信，保证传输过程加密。点击左侧菜单“域名管理 -> 创建域名”，按实际情况选择证书来源： ●有正式域名：填写域名并上传对应的CA签发证书，开启HTTPS，将两条管理平台路由关联到该域名。生产环境推荐此方式； ●自建域名（内网/无正式域名）：在内网DNS或各访问端hosts中配置一个内部域名指向网关地址，证书使用自签名证书（可用OpenSSL自行签发，内网可统一分发根证书使各终端信任），开启HTTPS并关联路由。 ●临时测试：可选择网关自带的 default 自签证书快速开启 HTTPS。浏览器会提示"不受信任"，确认继续访问即可，加密功能不受影响。此方式仅用于部署验证，不得用于正式运行。域名配置完成后，请在访问端（浏览器侧）修改本地hosts文件，添加如下映射：xxx.xxx.241.25 higress.local 无论选择哪种方式，HTTPS 都必须开启。区别仅在于证书的信任级别：CA 证书 > 自签名证书（分发根证书）> default 自签证书（仅临时）。配置完成后，应使用 https://<域名>: 访问平台，并确认浏览器地址栏为加密连接。 4.创建路由点击Higress Console的左侧菜单“路由管理 -> 创建路由”，创建两条路由。路由名称匹配路径目标服务域名（可选）用途 quota-admin-web /（前缀匹配） quota-admin-web 按需，没有可不选前端页面 quota-admin-web-api /admin-api（前缀匹配） quota-admin-web 按需，没有可不选后端 API 接下来，给路由 quota-admin-web-api 配置basic认证，点击对应路由的“策略 -> Basic 认证”：点击开启状态按钮，并按下表配置调用方列表。配置完成后保存退出。名称访问凭证 admin admin:sk-1234（格式为用户名:密码；登录额度平台时用户名填 admin、密码填 sk-1234，演示凭证请按需修改） 5.创建消费者点击Higress Console的左侧菜单“消费者管理 -> 创建消费者”，请按下表进行管理员创建：消费者名称认证方式 key值令牌来源用途 quota-admin Key Auth sk-1234 Authorization: Bearer ${value} ai-quota 管理接口管理员 consumer1 Key Auth sk-01 Authorization: Bearer ${value} 业务消费者（示例） consumer2 Key Auth sk-02 Authorization: Bearer ${value} 业务消费者（示例） consumer3 Key Auth sk-03 Authorization: Bearer ${value} 业务消费者（示例） 6.创建 quota-admin 管理路由并配置插件平台后端通过 ai-quota 插件的管理接口（/quota）查询和调整余额，该接口由网关在路由层直接响应，需要一条专用路由承载。 Console界面点击“路由管理 -> 创建路由”，参考下表进行配置：配置项注意路由名称 quota-admin 匹配路径 /v1/chat/completions/quota（前缀匹配）目标服务任选有效服务（如 llm 服务来源），请求会被插件拦截，不会真到上游域名不绑定然后给该路由配置两个插件：（1）策略 -> Key认证：开启。配置项注意 API Key 来源字段删除默认的 apikey，只保留 Authorization；访问凭证填完整值 Bearer sk-1234（必须含 Bearer 前缀）（2）策略 -> AI 配额管理：开启。配置如下：配置项注意 Quota Redis key 前缀固定 chat_quota，不建议修改。与平台侧配置保持一致，否则平台与网关看到的余额会不一致管理身份Consumer 固定 quota-admin 管理请求路径默认 /quota Redis 服务来源固定 local-redis.static Redis 服务端口固定 80 7.AI路由配置ai-quota 请确保所有AI路由均已配置key-auth、ai-quota插件插件。 Console界面找到对应AI路由，点击"策略 → Key 认证"：开启。配置项注意 API Key 来源字段删除默认的 apikey，只保留 Authorization；调用方 consumer1 / consumer2 / consumer3（示例）访问凭证完整值 Bearer sk-01 / Bearer sk-02 / Bearer sk-03（必须含 Bearer 前缀）说明： AI 路由不开 Key 认证，导致 ai-quota 插件拿不到 x-mse-consumer 身份，业务请求时会出现401 "No Key Authentication information found" 点击“策略 -> AI配额管理”，参考下表进行配置：配置项注意 Quota Redis key 前缀固定 chat_quota，不建议修改。与平台侧配置保持一致，否则平台与网关看到的余额会不一致管理身份Consumer 固定 quota-admin 管理请求路径默认 /quota Redis 服务来源固定 local-redis.static Redis 服务端口固定 80 4.3.5.3.2 环境配置 1.登录界面浏览器访问额度管理平台入口（示例：http://higress.local:32692/，实际以你配置的网关gateway域名/端口为准），输入 basic-auth 里配置的管理员账号密码（示例：admin / sk-1234）。 2.打开"环境配置" 点击界面右上角「环境配置」按钮，弹窗分两个分区： ●Redis 连接：填 Redis 的 IP、Port（可选 Redis用户、密码）。填完点 [测试连接] 验证，确认 [连接正常] 后再点 [保存并连接]。 ●Higress Console：填 Higress Console 地址、管理员用户、密码。点 [测试连接] 应显示 [连接正常]。 3.确认状态保存后看弹窗顶部是否显示：Redis 正常、ai-quota 正常、Console 已配置。说明：ai-quota 是否正常，取决于后端服务配置的QUOTA_ADMIN_KEY是否正确。 4.3.5.3.3 功能验证请按以下顺序逐项完成功能验证： 1.消费者列表打开「消费者与额度」页，应看到完整的消费者名单，可对比Higress Console的消费者管理页。 2.配置三种模式消费者 + 余额联动编辑消费者（单个或批量），分别设置：消费者模式初始额度剩余可用额度 A 按月 60000000 60000000（首次配置直接初始化） B 按天 1200000 1200000 C 固定 500000 500000 再次编辑消费者 A，观察余额联动： 1）初始额度改为 65000000（即增加 5000000）：余额 = 60000000 +（65000000 − 60000000）= 65000000。保存后提示"余额 +5,000,000 → 65,000,000"，Redis 中余额同步为该值。 2）追加剩余可用额度 −1000000（即手动扣减 1000000）：余额 = 65000000 − 1000000 = 64000000。 3）初始额度改为 100（减少 64999900）：余额 = 64000000 +（100 − 65000000）= 64000000 − 64999900 = −63999900，结果为负，按规则归零，余额 = 0。说明：余额联动规则：编辑消费者（单个或批量）时，"初始额度"的修改会自动联动当前余额，规则为：新余额 = 当前余额 +（新初始额度 − 旧初始额度），若结果为负数则归零。 3.余额扣减验证（真实请求）# 用消费者A的 key 发起一次AI请求（路由按你的环境；模型用 DeepSeek Api/本地 vLLM 服务均可） curl -i http://<网关地址>/v1/chat/completions \ -H "Authorization: Bearer <消费者A的key>" \ -H "Content-Type: application/json" \ -d '{"model":"deepseek-chat","messages":[{"role":"user","content":"你好"}]}' ●响应 200 且末尾有 usage（total_tokens 即本次用量）。 ●Redis查余额，对比确认额度：redis-cli GET chat_quota:<消费者A> ●界面点「刷新」，用户A的剩余额度列同步变小。 ●验证拦截：把余额调到0，下一次请求返回 Request denied by ai quota check。 ●注意流式请求（stream:true）必须带 "stream_options":{"include_usage":true}，否则上游不返回 usage、不扣费。 4.手动操作与审计 ●编辑弹窗"追加剩余可用额度"填正/负数 → 余额增减，流水页出现「增减」记录。 ●勾选同模式消费者 → 「批量重置」→ 余额全部回到各自初始额度，流水「重置」记录。 ●操作流水页可看到全部 action 类型（重置/增减/改标准值/余额调整/初始化）与操作前后余额。 5.月/日自动重置验证（可选，验证调度器）临时把 cron 调到 2 分钟后触发： ●Docker 部署：环境变量无法热改，需重建容器（其余启动参数保持不变）：docker stop token-quota-console && docker rm token-quota-console docker run -d --name token-quota-console --network host \ -e RESET_CRON='*/2 * * * *' \ -e DAILY_RESET_CRON='*/2 * * * *' \ <其余原有 -e 参数与挂载保持不变> \ token-quota-console:<镜像tag> ●helm/k8s 部署：通过 Deployment 环境变量注入，自动触发 Pod 重启：kubectl set env deployment/token-quota-console -n higress-system \ RESET_CRON='*/2 * * * *' \ DAILY_RESET_CRON='*/2 * * * *' 到期重置后观察以下现象： ●后端服务日志开始打印 [reset] 日志 ●Redis中额度管理模式为按月、按天额度的消费者余额恢复到初始额度 ●Redis中 quota-admin:resetlog:list 出现对应 mode 的重置记录验证完成后务必还原（否则重置记录会持续打印）： ●Docker：再次重建容器，去掉两个 -e RESET_CRON/DAILY_RESET_CRON 参数； ●helm/k8s：删除前面设置的两个环境变量，恢复默认值：每月 1 号 00:05 / 每天 00:05）。kubectl set env deployment/token-quota-console -n higress-system RESETCRON- DAILYRESET_CRON-