跳到主要内容
版本：3.9.x

使用 AI 重写转换 API 请求

本指南介绍如何使用 ai-request-rewrite，在网关层通过大语言模型转换 API 载荷。与静态正则表达式或模板重写不同，AI 驱动的转换可以理解非结构化输入的意图，并将其规范化为上游可直接使用的格式。

概览​

AI 请求转换会在流量经过 API7 网关时，发起一次专用的大语言模型调用，以重写、丰富或重构载荷。

与传统请求转换相比，当输入含义模糊、格式自由、包含多种语言或语义复杂时，AI 转换尤其适用。

常见用例包括：

  • 格式规范化：把自由文本用户输入转换为结构化 JSON。
  • 语言翻译：把多语言输入转换为上游系统要求的统一目标语言。
  • 数据增强：提取并标准化意图、实体或类别等字段。
  • 旧版 API 适配：把现代客户端载荷转换为旧版上游 API 要求的 Schema。

前置条件​

  • 安装 Docker。

  • 安装 cURL，用于发送请求并验证服务。

  • 拥有一个正在运行的 API7 网关实例。

  • 从控制台获取令牌，并保存到环境变量：

    export API_KEY=your-dashboard-token   # 请替换为你的控制台令牌

  • 将 {gateway_group_id} 替换为网关组 ID。如果正在按照快速入门操作，请使用 default。

  • 如果使用 Admin API 示例，请创建或复用一个服务。如果尚无服务，请按照创建或复用服务操作，然后保存其 ID：

    export SERVICE_ID=your-service-id         # 请替换为你的服务 ID

工作原理​

转换流程如下：

  1. 客户端请求进入网关。
  2. 网关使用 ai-request-rewrite 调用转换模型，并传入你的提示词指令。
  3. 网关接收转换后的内容，并将其注入请求载荷。
  4. 修改后的请求被转发到上游 API。

此插件还支持双向转换：

  • 请求侧转换在调用上游之前发生。
  • 响应侧转换可在数据返回客户端之前应用。

转换模型调用是一项独立的中间件行为，不会取代主要上游服务。

配置 AI 请求重写​

以下路由使用 ai-request-rewrite，并将 OpenAI 作为转换服务提供方。

curl -k "https://localhost:7443/apisix/admin/routes?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  --data-binary @- <<EOF
  {
    "id": "ai-request-transformation",
    "service_id": "$SERVICE_ID",
    "paths": ["/api/intake"],
    "plugins": {
      "ai-request-rewrite": {
        "provider": "openai",
        "auth": {
          "header": {
            "Authorization": "Bearer $OPENAI_API_KEY"
          }
        },
        "options": {
          "model": "gpt-4o"
        },
        "prompt": "transformation instructions here"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "intake-api.internal:8080": 1
      }
    }
  }
EOF

❶ provider 选择转换所用的大语言模型后端，此处为 OpenAI。

❷ auth.header.Authorization 设置调用转换模型所需的凭证。

❸ options.model 设置重写所使用的转换模型。

❹ prompt 包含明确的转换指令。应保持简洁、确定，并以 Schema 为导向。

使用 provider: "openai-compatible" 时，Schema 校验要求必须提供 override.endpoint。

{
  "provider": "openai-compatible",
  "override": {
    "endpoint": "https://your-llm-endpoint.example/v1/chat/completions"
  },
  "auth": {
    "header": {
      "Authorization": "Bearer sk-xxxxxxxx"
    }
  },
  "options": {
    "model": "custom-model"
  },
  "prompt": "transformation instructions here"
}

示例：规范化自由文本输入​

场景：客户端发送非结构化文本，但上游要求严格的 JSON 字段。

curl "http://127.0.0.1:9080/api/intake" \
  -X POST \
  -H "Content-Type: text/plain" \
  --data-raw "Hi, I'm Jane Doe, my email is jane@example.com and I can't log in. Please help me reset my password."

使用如下转换提示词：

Extract name, email, and intent from the following text and return strict JSON with keys: name, email, intent.
If a field is missing, return null.

转发到上游的预期载荷：

{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "intent": "password_reset"
}

示例：转换请求语言​

场景：客户端发送多语言内容，但上游只接受英文载荷。

curl "http://127.0.0.1:9080/api/intake" -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Veuillez annuler mon rendez-vous de mercredi prochain et le reporter à vendredi matin."
  }'

使用如下转换提示词：

Translate the user message to English. Preserve meaning and time references. Return only translated text.

转换后的请求载荷示例：

{
  "message": "Please cancel my appointment for next Wednesday and reschedule it to Friday morning."
}

性能注意事项​

AI 转换会在请求路径中增加一次大语言模型往返调用，因此需要考虑：

  • 延迟：每次转换都会增加模型推理时间，只应在需要语义转换时使用。
  • 成本：转换提示词和输出会在转换服务提供方处消耗额外 Token。
  • 范围控制：仅在需要重写的路由上应用该插件，不要全局启用。
  • 提示词规范：提示词应明确并限制输出格式，以减少重试和结果漂移。
  • 缓存机会：如果输入重复，可以缓存转换结果，同时降低延迟和 Token 开销。

仅当传统的确定性转换（映射、正则表达式、固定模板）不足以满足要求时，才使用 AI 请求转换。

后续步骤​