配置提示词模板与提示词装饰器

本文介绍如何使用 ai-prompt-decorator 和 ai-prompt-template 在网关层统一管理提示词策略。平台团队可以集中维护系统指令、模板变量和合规要求，减少不同业务团队各自实现提示词逻辑带来的漂移。

两种模式

API7 AI 网关提供两类常见提示词治理方式：

• 提示词装饰器：使用 ai-prompt-decorator 在每个请求前后追加系统消息或策略提醒。
• 提示词模板：使用 ai-prompt-template 定义带变量的可复用模板。

配置提示词装饰器

以下示例在用户消息之前注入客服助手的系统指令，并在消息末尾追加操作提醒。

Admin API

curl "http://127.0.0.1:7080/apisix/admin/routes?gateway_group_id=default" -X PUT \
  -H "X-API-KEY: $ADMIN_API_KEY" \
  -d '{
  "id": "ai-prompt-decoration",
  "service_id": "'"$SERVICE_ID"'",
  "paths": ["/ai/decorated"],
  "plugins": {
    "ai-proxy": {
      "provider": "openai",
      "auth": { "header": { "Authorization": "Bearer '"$OPENAI_API_KEY"'" } },
      "options": { "model": "gpt-4o" }
    },
    "ai-prompt-decorator": {
      "prepend": [
        {
          "role": "system",
          "content": "You are a customer support assistant. Reply with concise and policy-compliant answers."
        }
      ],
      "append": [
        {
          "role": "system",
          "content": "If the user asks for account actions, ask for a ticket ID before proceeding."
        }
      ]
    }
  }
}'

ADC

adc.yaml

services:
  - name: 提示词装饰服务
    routes:
      - name: ai-prompt-decoration
        uris:
          - /ai/decorated
        plugins:
          ai-proxy:
            provider: openai
            auth:
              header:
                Authorization: Bearer ${OPENAI_API_KEY}
            options:
              model: gpt-4o
          ai-prompt-decorator:
            prepend:
              - role: system
                content: You are a customer support assistant. Reply with concise and policy-compliant answers.
            append:
              - role: system
                content: If the user asks for account actions, ask for a ticket ID before proceeding.

配置提示词模板

模板适合将业务输入转换为统一格式，例如摘要、翻译、分类或信息抽取。模板中的变量由请求参数或插件配置填充。

{
  "ai-prompt-template": {
    "template": [
      {
        "role": "system",
        "content": "你是企业知识库助手，请只基于给定上下文回答。"
      },
      {
        "role": "user",
        "content": "问题：{{question}}\n上下文：{{context}}"
      }
    ]
  }
}

治理建议

• 将强制系统指令放在网关层，减少应用重复实现。
• 对高风险业务保留模板版本、变更人和发布时间。
• 配合提示词防护和内容审核插件，避免模板被用户输入绕过。
• 对模板变量做长度和格式限制，避免超长输入导致成本失控。