kgateway项目中的Prompt Enrichment功能配置问题解析

背景介绍

在kgateway项目v2.0.0-main版本中，AI网关功能提供了Prompt Enrichment（提示词增强）这一重要特性。该功能允许开发者在请求到达AI模型前，对提示词进行预处理和增强，例如在用户输入前添加系统指令。这一功能对于规范AI模型输出格式、提升响应质量非常有用。

问题现象

在Kubernetes v1.31环境中配置kgateway时，发现Prompt Enrichment功能未能按预期工作。具体表现为：虽然配置了预处理系统提示词（要求将非结构化文本解析为CSV格式），但AI模型返回的仍然是原始格式的响应，而非预期的CSV格式数据。

配置分析

典型的Prompt Enrichment配置包括三个核心资源：

1. Backend资源：定义AI后端服务，如OpenAI

apiVersion: gateway.kgateway.dev/v1alpha1
kind: Backend
metadata:
  name: openai
spec:
  type: AI
  ai:
    llm:
      provider:
        openai:
          authToken:
            kind: SecretRef
            secretRef:
              name: openai

2. HTTPRoute资源：定义路由规则

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: openai
spec:
  parentRefs:
  - name: ai-gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /openai
    backendRefs:
    - name: openai
      group: gateway.kgateway.dev
      kind: Backend

3. RoutePolicy资源：定义提示词增强策略

apiVersion: gateway.kgateway.dev/v1alpha1
kind: RoutePolicy
metadata:
  name: openai
spec:
  ai:
    promptEnrichment:
      prepend:
      - role: SYSTEM
        content: "Parse the unstructured text into CSV format and respond only with the CSV data."

问题根源

经过深入排查，发现问题出在HTTPRoute资源的配置方式上。正确的做法是将ExtensionRef过滤器作为backendRef的子元素，而不是与backendRef并列。错误的配置会导致过滤器不被执行，从而Prompt Enrichment功能失效。

正确配置示例：

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: openai
spec:
  parentRefs:
  - name: ai-gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /openai
    backendRefs:
    - name: openai
      group: gateway.kgateway.dev
      kind: Backend
      filters:  # 过滤器必须作为backendRef的子元素
      - type: ExtensionRef
        extensionRef:
          group: gateway.kgateway.dev
          kind: RoutePolicy
          name: openai

技术要点

1. 过滤器位置：在kgateway中，ExtensionRef过滤器必须嵌套在backendRef内部，这是与标准Kubernetes Gateway API的一个关键区别点。

2. 版本兼容性：无论是使用gateway.networking.k8s.io/v1beta1还是v1版本的API，这一规则都适用，版本差异不会影响功能行为。

3. 应用顺序：资源创建顺序（先创建RoutePolicy还是先创建HTTPRoute）不会影响功能，但必须确保所有引用关系正确无误。

最佳实践

1. 始终验证ExtensionRef过滤器的位置是否正确嵌套
2. 使用kubectl describe检查资源状态，确认所有引用关系已正确建立
3. 在复杂配置场景下，建议分步创建资源并验证每步功能
4. 启用网关访问日志，有助于调试请求处理流程

总结

kgateway的Prompt Enrichment功能为AI应用提供了强大的提示词预处理能力，但需要特别注意过滤器的正确配置位置。通过本文的分析，开发者可以避免常见的配置陷阱，确保AI网关按预期工作。这一经验也提醒我们，在使用扩展API时，必须仔细阅读特定实现的文档要求，不能完全依赖标准API的使用习惯。