Gateway with Inference Extension相关组件的配置说明-容器服务 Kubernetes 版 ACK(ACK)-阿里云帮助中心

本文列举了AI推理增强型网关（Gateway with Inference Extension）关联的相关组件核心配置示例及配置项说明

ACKTrafficFilter

ACKTrafficFilter能够为网关路由提供扩展的流量处理选项，如对接阿里云内容安全实现AI内容安全审查。

以下示例通过结合 ACKTrafficFilter 和 HTTPRoute，为网关接入阿里云内容安全服务，实现 AI 内容安全审查的能力，请参考使用Gateway with Inference Extension实现AI内容审查。

apiVersion: inferenceextension.alibabacloud.com/v1alpha1
kind: ACKTrafficFilter
metadata:
  name: aisg
spec:
  aiContentSecurity:
    accessKey: XXXXXX
    secretKey: XXXXXX
    aliyunEndpoint: green-cip-vpc.cn-hangzhou.aliyuncs.com
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: mock-route
spec:
  parentRefs:
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: mock-gateway
    sectionName: llm-gw
  rules:
  - backendRefs:
    - group: inference.networking.x-k8s.io
      kind: InferencePool
      name: mock-pool
    filters:
    - type: ExtensionRef
      extensionRef:
        group: inferenceextension.alibabacloud.com
        kind: ACKTrafficFilter
        name: aisg
    matches:
    - path:
        type: PathPrefix
        value: /

配置项说明

ACKTrafficFilterSpec

字段	类型	必需	描述
aiContentSecurity	AIContentSecurity	否	指定AI内容安全检查的配置
extensionDeploymentOverlay	ExtensionDeploymentOverlay	否	指定插件部署覆盖配置

AIContentSecurity

字段	类型	必需	描述
accessKey	string	否	用于认证的ak
secretKey	string	否	用于认证的sk
aliyunEndpoint	string	否	阿里云内容安全服务的端点地址
checkRequest	boolean	否	是否检查请求内容
checkResponse	boolean	否	是否检查响应内容
requestCheckService	string	否	请求检查的服务名称
responseCheckService	string	否	响应检查的服务名称
requestContentJsonPath	string	否	请求内容的JSON路径
responseContentJsonPath	string	否	响应内容的JSON路径
responseStreamContentJsonPath	string	否	响应流内容的JSON路径
denyMessage	string	否	内容被拒绝时的默认消息
riskLevelBar	string	否	风险等级阈值
timeout	integer	否	超时时间（毫秒）

ExtensionDeploymentOverlay

字段	类型	必需	描述
spec	json.RawMessage	否	插件部署覆盖的原始JSON规范

InferenceTrafficPolicy

InferenceTrafficPolicy用于配置针对指定InferencePool内的推理工作负载进行路由时，Gateway with Inference Extension采用的路由策略，包括推理工作负载的部署形态信息、使用的路由算法及其参数等。

默认情况下，Gateway with Inference Extension将针对InferencePool后端的单机vLLM推理服务，采用基于KVCache利用率与排队请求数的智能路由负载均衡策略进行请求转发，具体内容参考使用Gateway with Inference Extension实现智能路由与流量管理。当推理服务使用其他部署形态、或需要调整Gateway with Inference Extension的路由算法以及相关算法参数时，可使用InferenceTrafficPolicy对智能路由策略进行调整。

示例一：对单机SGLang推理服务配置前缀感知的负载均衡（估算模式）

该策略针对同命名空间下名为 qwen-inference-pool 的InferencePool生效。

apiVersion: inferenceextension.alibabacloud.com/v1alpha1
kind: InferenceTrafficPolicy
metadata:
  name: sglang-prefixcache-policy
spec:
  poolRef:
    name: qwen-inference-pool
  modelServerRuntime: sglang
  profile:
    single:
      trafficPolicy:
        prefixCache:
          mode: estimate

示例二：对单机vLLM推理服务配置前缀感知的负载均衡（跟踪模式）

apiVersion: inferenceextension.alibabacloud.com/v1alpha1
kind: InferenceTrafficPolicy
metadata:
  name: inference-policy
spec:
  poolRef:
    name: qwen-inference-pool
  profile:
    single:
      trafficPolicy:
        prefixCache:
          mode: tracking
          trackingConfig:
            indexerConfig:
              tokenProcessorConfig:
                blockSize: 64
                hashSeed: 42
                model: Qwen/Qwen3-32B
            kvEventsConfig:
              zmqEndpoint: tcp://*:5557
              topicFilter: kv@

示例三：对SGLang PD分离推理服务配置路由

apiVersion: inferenceextension.alibabacloud.com/v1alpha1
kind: InferenceTrafficPolicy
metadata:
  name: inference-policy
spec:
  poolRef:
    name: qwen-inference-pool
  modelServerRuntime: sglang
  profile:
    pd:
      pdRoleLabelName: rolebasedgroup.workloads.x-k8s.io/role
      kvTransfer:
        bootstrapPort: 34000

配置项说明

spec

字段	类型	是否必填	说明
poolRef	PoolObjectReference	是	指定此推理流量策略应用的InferencePool
profile	DeploymentProfile	否	指定后端推理服务的部署形态。可选值为 `single`（单机部署）和 `pd`（PD分离）。您可以在选定的部署形态中配置相应的路由策略。
modelServerRuntime	string	否	指定后端推理服务的模型服务器运行时，可选项`vllm`、`sglang`或`trt-llm`
flowControl	FlowControl	否	指定对后端推理服务的请求控制策略。该配置需要Gateway with Inference Extension组件版本在v1.4.0-apsara.4及以上

PoolObjectReference

字段	类型	是否必填	说明
group	string	否	引用对象的组，默认为`inference.networking.x-k8s.io`
kind	string	否	引用对象的类型，默认为`InferencePool`
name	string	是	引用对象的名称

DeploymentProfile

字段	类型	是否必填	说明
single	SingleProfile	否	单机部署的配置
pd	PDProfile	否	PD分离部署的配置

SingleProfile

字段	类型	是否必填	说明
trafficPolicy	TrafficPolicy	否	独立部署的负载均衡路由策略，默认采用基于KVCache利用率与排队请求数的智能路由负载均衡策略。
burstLimitPerServer	BurstLimit	否	每个后端服务器的突发请求软限制，超过限制时会降低对应服务器的负载均衡权重

PDProfile

字段	类型	是否必填	说明
trafficPolicy	TrafficPolicy	否	PD分离部署的路由策略声明
prefillPolicyRef	string	否	预填充请求的路由策略名称引用
decodePolicyRef	string	否	解码请求的路由策略名称引用
pdRoleLabelName	string	是	用于区分PD角色的Pod标签名称，PD角色应为`prefill`或`decode`
pdThreshold	int	否	PD的阈值，当前缀缓存显示解码服务器已缓存超过阈值的prompt token时，将跳过PD。默认启用PD分离。
kvTransfer	KVTransfer	否	PD分离中KVCache传输的相关配置，需要根据实际部署中KVCache传输的方式确定。
burstLimitPerServer	BurstLimit	否	每个后端服务器的突发请求软限制，超过限制时会降低对应服务器的负载均衡权重

KVTransfer

字段	类型	是否必填	说明
protocol	string	否	KVCache传输协议，可以是`nixlv2`或`sglang`。默认将基于modelServerRuntime确定PD分离KVCache传输协议。
bootstrapPort	int	否	KVCache传输时使用的bootstrap端口号，仅适用于sglang PD分离。

TrafficPolicy

字段	类型	是否必填	说明
simple	string	否	简单路由策略。可选值只有DEFAULT，使用DEFAULT时，将采用基于KVCache利用率与排队请求数的智能路由负载均衡策略。
prefixCache	PrefixCachePolicy	否	前缀感知的负载均衡路由策略。

PrefixCachePolicy

字段	类型	是否必填	说明
mode	string	是	前缀缓存策略模式，可以是`estimate`（估算模式）或`tracking`（跟踪模式）。有关估算模式，可参考使用估算模式的前缀缓存感知路由能力，有关跟踪模式，可参考使用精准模式的前缀缓存感知路由能力
estimateConfig	EstimateConfig	否	启用估算模式时的配置
trackingConfig	TrackingConfig	否	启用跟踪模式时的配置

EstimateConfig

字段	类型	是否必填	说明
hashBlockSize	int32	是	估算模式记录请求前缀哈希时使用的哈希块的大小
maxPrefixBlocksToMatch	int32	是	估算模式匹配请求前缀时可匹配的最大前缀块数
lruCapacityPerServer	int32	是	每个服务器的LRU容量

TrackingConfig

字段	类型	是否必填	说明
indexerConfig	IndexerConfig	是	跟踪模式中使用的KVCache索引器的配置
kvEventsConfig	KVEventsConfig	否	跟踪模式中使用的KV事件接收器的配置

IndexerConfig

字段	类型	是否必填	说明
tokenProcessorConfig	TokenProcessorConfig	是	令牌处理器的配置
kvBlockIndexConfig	KvBlockIndexConfig	否	KV块索引的配置

TokenProcessorConfig

字段	类型	是否必填	说明
blockSize	int32	是	每个前缀缓存块的大小，需要与vLLM的block-size启动参数保持一致。
hashSeed	int32	是	哈希种子，需要与vLLM的PYTHONHASHSEED环境变量保持一致
model	string	是	实际在引擎中运行的模型在ModelScope中的官方名称

KvBlockIndexConfig

字段	类型	是否必填	说明
size	int64	否	索引中缓存的KVCache块索引的最大个数
podCacheSize	int32	否	为每个Pod缓存的KVCache块索引的最大个数

KVEventsConfig

字段	类型	是否必填	说明
zmqEndpoint	string	否	要监听的ZMQ地址（例如："tcp://*:5557"）
topicFilter	string	否	ZMQ订阅过滤器（例如："kv."）
concurrency	int	否	并行运行的工作线程数

BurstLimit

字段	类型	是否必填	说明
interval	metav1.Duration	是	检查突发限制的时间间隔
threshold	int32	是	突发限制的阈值

FlowControl

字段	类型	是否必填	说明
enableQueueing	bool	是	是否在检测到推理服务过载时，对后续推理请求启用排队机制
saturationDetector	SaturationDetector	否	后端推理服务过载检测配置

SaturationDetector

字段	类型	是否必填	说明
queueDepthThreshold	int	否	用于判断后端推理服务是否过载的平均等待请求数阈值
kvCacheUtilThreshold	int	否	用于判断后端推理服务是否过载的kv-cache使用率阈值
metricsStalenessThreshold	metav1.Duration	否	后端服务指标数据保持有效的最长时间。若距上次指标成功更新的时间间隔超过此阈值，网关将认为该指标已失效。