配置提示词装饰器

提示词装饰器让运维人员能够在客户端提示词前后应用可复用的指令。无需让每个客户端重复这些指令，即可统一响应规范、语气、格式或安全要求。

当网关需要添加共享上下文、又不能替换客户端请求体时，提示词装饰器非常有用。应用继续提供任务相关的提示词，APISIX 则在不同请求中一致地应用所配置的指令。

本指南介绍如何将 ai-prompt-decorator 插件用于 OpenAI Chat Completions 和 Responses API 请求。同样的方法也可适配该插件支持的其他请求协议和服务提供方。

前置条件

• 安装 Docker。
• 安装 cURL 以发送验证请求。
• 按照快速入门教程在 Docker 或 Kubernetes 中启动 APISIX 实例。
• 拥有 OpenAI 账户，并能通过 API 访问同时支持两种请求格式的模型。

获取 OpenAI API Key

创建 OpenAI API Key，然后导出 API Key 和模型：

export OPENAI_API_KEY="<your-api-key>"
export OPENAI_MODEL="<your-model-name>"

创建路由

APISIX 根据 messages 字段识别 Chat Completions 请求；根据 input 字段以及以 /v1/responses 结尾的传入 URI 识别 Responses 请求。

Embeddings 格式没有可供前置或追加的提示词角色，因此该插件不会修改 Embeddings 请求。

为两个 OpenAI API 路径创建一个路由。配置提示词装饰器，在客户端提示词之前添加系统指令，并在其后添加用户指令：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
  {
    "id": "ai-prompt-decorator-route",
    "uris": [
      "/v1/chat/completions",
      "/v1/responses"
    ],
    "methods": ["POST"],
    "plugins": {
      "ai-proxy": {
        "provider": "openai",
        "auth": {
          "header": {
            "Authorization": "Bearer $OPENAI_API_KEY"
          }
        },
        "options": {
          "model": "$OPENAI_MODEL"
        }
      },
      "ai-prompt-decorator": {
        "prepend": [
          {
            "role": "system",
            "content": "Answer briefly and conceptually."
          }
        ],
        "append": [
          {
            "role": "user",
            "content": "End the answer with a simple analogy."
          }
        ]
      }
    }
  }
EOF

❶ 配置任意面向客户端的 Chat Completions 路径。APISIX 仅根据 messages 字段识别该格式，并将请求发送到 OpenAI Chat Completions 端点。

❷ 配置面向客户端的 Responses 请求路径。该路径可以有自定义前缀，但必须以 /v1/responses 结尾。APISIX 根据该后缀和 input 字段识别请求格式，并将请求发送到 OpenAI Responses 端点。

❸ 在客户端提示词之前添加系统内容。对于 Responses 请求，插件会将这些内容添加到 instructions。

❹ 在客户端提示词之后添加用户内容。对于 Responses 请求，插件会将这些内容添加到 input。

路由配置包含 OpenAI API Key。启用密钥环数据加密后，APISIX 会在将路由保存到 etcd 之前加密该 Key。生产环境中请配置自定义密钥环。

验证

分别使用两种格式发送请求，验证 APISIX 如何装饰提示词。

发送 Chat Completions 请求

发送包含一条用户消息的请求：

curl -i "http://127.0.0.1:9080/v1/chat/completions" -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is mTLS authentication?"
      }
    ]
  }'

APISIX 按以下消息顺序向上游发送请求：

{
  "messages": [
    {
      "role": "system",
      "content": "Answer briefly and conceptually."
    },
    {
      "role": "user",
      "content": "What is mTLS authentication?"
    },
    {
      "role": "user",
      "content": "End the answer with a simple analogy."
    }
  ]
}

你应该收到 HTTP 200 响应，其中 choices 包含助手消息。

发送 Responses API 请求

使用 Responses API 格式发送相同的提示词：

curl -i "http://127.0.0.1:9080/v1/responses" -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "input": "What is mTLS authentication?"
  }'

APISIX 会按以下形式向上游发送装饰后的字段：

{
  "instructions": "Answer briefly and conceptually.",
  "input": "What is mTLS authentication?\nEnd the answer with a simple analogy."
}

你应该收到 HTTP 200 响应，其中 output 包含带类型的条目。

清理

不再需要该 APISIX 路由时，请将其删除：

curl "http://127.0.0.1:9180/apisix/admin/routes/ai-prompt-decorator-route" -X DELETE \
  -H "X-API-KEY: ${ADMIN_API_KEY}"

从 Shell 中删除 OpenAI 相关值：

unset OPENAI_API_KEY OPENAI_MODEL

下一步

现在，你已经配置 APISIX，使其能够装饰 Chat Completions 和 Responses API 的提示词。

如需为装饰后的提示词添加安全护栏，请在同一路由中配置 ai-prompt-guard。