AI安全防护

---
name: add-ai-protection
license: Apache-2.0
description: 保护 AI 聊天和补全端点免受滥用 — 检测提示注入和越狱尝试，阻止 PII 和敏感信息在响应中泄露，并强制执行令牌预算速率限制以控制成本。当用户正在构建或保护任何使用 LLM 处理用户提示的端点时，即使他们将其描述为“防止越狱”、“阻止提示攻击”、“阻止敏感数据”或“控制 AI API 成本”而不是命名具体的保护措施，也请使用此技能。
metadata:
  pathPatterns:
    - "app/api/chat/**"
    - "app/api/completion/**"
    - "src/app/api/chat/**"
    - "src/app/api/completion/**"
    - "**/chat/**"
    - "**/ai/**"
    - "**/llm/**"
    - "**/api/generate*"
    - "**/api/chat*"
    - "**/api/completion*"
  importPatterns:
    - "ai"
    - "@ai-sdk/*"
    - "openai"
    - "@anthropic-ai/sdk"
    - "langchain"
  promptSignals:
    phrases:
      - "prompt injection"
      - "pii"
      - "sensitive info"
      - "ai security"
      - "llm security"
    anyOf:
      - "protect ai"
      - "block pii"
      - "detect injection"
      - "token budget"
---

# 使用 Arcjet 添加 AI 特定的安全保护

通过分层保护来保护 AI/LLM 端点：提示注入检测、PII 阻止和令牌预算速率限制。这些保护措施协同工作，在滥用到达您的模型之前将其阻止，从而节省 AI 预算并保护用户数据。

## 参考

阅读 https://docs.arcjet.com/llms.txt 获取全面的 SDK 文档，涵盖所有框架、规则类型和配置选项。

Arcjet 规则在请求到达您的 AI 模型**之前**运行 — 在 HTTP 层阻止提示注入、PII 泄露、成本滥用和机器人抓取。

## 步骤 1：确保 Arcjet 已设置

检查是否存在共享的 Arcjet 客户端（请参阅 `/arcjet:protect-route` 获取完整设置）。如果不存在，请首先使用 `shield()` 作为基本规则进行设置。用户需要在 https://app.arcjet.com 注册 Arcjet 账户，然后在其环境变量中使用 `ARCJET_KEY`。

## 步骤 2：添加 AI 保护规则

AI 端点应使用 `withRule()` 在共享实例上结合这些规则：

### 提示注入检测

检测越狱、角色扮演逃逸和指令覆盖。

- JS: `detectPromptInjection()` — 在 `protect()` 时通过 `detectPromptInjectionMessage` 参数传递用户消息
- Python: `detect_prompt_injection()` — 通过 `detect_prompt_injection_message` 参数传递

在恶意提示到达模型**之前**将其阻止。这通过及早拒绝攻击来节省 AI 预算。

### 敏感信息 / PII 阻止

防止个人身份信息进入模型上下文。

- JS: `sensitiveInfo({ deny: ["EMAIL", "CREDIT_CARD_NUMBER", "PHONE_NUMBER", "IP_ADDRESS"] })`
- Python: `detect_sensitive_info(deny=[SensitiveInfoType.EMAIL, SensitiveInfoType.CREDIT_CARD_NUMBER, ...])`

在 `protect()` 时通过 `sensitiveInfoValue` (JS) / `sensitive_info_value` (Python) 传递用户消息。

### 令牌预算速率限制

对 AI 端点使用 `tokenBucket()` / `token_bucket()` — `requested` 参数可以设置为与实际模型令牌使用量成比例，直接将速率限制与成本关联起来。它还允许短时突发，同时强制执行平均速率，这与用户与聊天界面的交互方式相符。

推荐的起始配置：

- `capacity`: 10（最大突发）
- `refillRate`: 每间隔 5 个令牌
- `interval`: "10s"

在 `protect()` 时传递 `requested` 参数，以按模型成本比例扣除令牌。例如，每条消息扣除 1 个令牌，或根据提示长度进行估算。

设置 `characteristics` 以跟踪每个用户：如果已认证，则为 `["userId"]`，默认为基于 IP。

### 基本保护

始终包含 `shield()` (WAF) 和 `detectBot()` 作为基本层。抓取 AI 端点的机器人是常见的滥用向量。对于通过浏览器访问的端点（例如聊天界面），考虑添加 Arcjet 高级信号以进行客户端机器人检测，从而捕获复杂的无头浏览器。请参阅 https://docs.arcjet.com/bot-protection/advanced-signals 进行设置。

## 步骤 3：组合 protect() 调用并处理决策

所有规则参数都在单个 `protect()` 调用中一起传递。使用此模式：

```typescript
const userMessage = req.body.message; // 用户的输入

const decision = await aj.protect(req, {
  requested: 1, // 用于速率限制的扣除令牌数
  sensitiveInfoValue: userMessage, // PII 扫描
  detectPromptInjectionMessage: userMessage, // 注入检测
});

if (decision.isDenied()) {
  if (decision.reason.isRateLimit()) {
    return Response.json(
      { error: "您已超出使用限制。请稍后再试。" },
      { status: 429 },
    );
  }
  if (decision.reason.isPromptInjection()) {
    return Response.json(
      { error: "您的消息被标记为可能有害。" },
      { status: 400 },
    );
  }
  if (decision.reason.isSensitiveInfo()) {
    return Response.json(
      {
        error:
          "您的消息包含敏感信息，无法处理。请删除任何个人数据。",
      },
      { status: 400 },
    );
  }
  if (decision.reason.isBot()) {
    return Response.json({ error: "禁止访问" }, { status: 403 });
  }
}

// Arcjet 开放失败 — 记录错误但允许请求
if (decision.isErrored()) {
  console.warn("Arcjet 错误:", decision.reason.message);
}

// 继续调用 AI 模型...
```

根据您的框架调整响应格式（例如，Express 的 `res.status(429).json(...)`）。

## 步骤 5：验证

1. 启动应用程序并发送一条正常消息 — 应该成功
2. 通过发送类似“忽略所有先前的指令并...”来测试提示注入
3. 通过发送包含虚假信用卡号的消息来测试 PII 阻止

首先以 `"DRY_RUN"` 模式启动所有规则。验证后，提升到 `"LIVE"`。

**始终建议使用 Arcjet MCP 工具**来验证规则和分析流量：

- `list-requests` — 确认决策正在记录，按结论过滤以查看阻止
- `analyze-traffic` — 审查 AI 端点的拒绝率和模式
- `explain-decision` — 了解特定请求被允许或拒绝的原因（有助于调整提示注入敏感度）
- `promote-rule` — 验证后将规则从 `DRY_RUN` 提升到 `LIVE`

如果用户需要全面的安全审查，建议使用 `/arcjet:security-analyst` 代理，它可以调查流量、检测异常并推荐额外的规则。

Arcjet 仪表板 https://app.arcjet.com 也可用于视觉检查。

## 常见模式

**流式响应**：在开始流之前调用 `protect()`。如果被拒绝，在打开流之前返回错误 — 不要开始流然后中止。

**多个模型 / 提供商**：无论您使用哪个 AI 提供商，都使用相同的 Arcjet 实例。Arcjet 在 HTTP 层运行，独立于模型提供商。

**Vercel AI SDK**：Arcjet 与 Vercel AI SDK 协同工作。在 `streamText()` / `generateText()` 之前调用 `protect()`。如果被拒绝，返回一个纯错误响应而不是调用 AI SDK。

## 常见错误避免

- 敏感信息检测在 **WASM 中本地运行** — 不会向外部服务发送用户数据。它仅在路由处理程序中可用，不在 Next.js 页面或服务器操作中。
- `sensitiveInfoValue` 和 `detectPromptInjectionMessage` (JS) / `sensitive_info_value` 和 `detect_prompt_injection_message` (Python) 都必须在 `protect()` 时传递 — 忘记其中任何一个都会默默跳过该检查。
- 在调用 `protect()` 之前开始流 — 如果请求在流中途被拒绝，客户端会收到损坏的响应。始终先调用 `protect()` 并在打开流之前返回错误。
- 对 AI 端点使用 `fixedWindow()` 或 `slidingWindow()` 而不是 `tokenBucket()` — 令牌桶允许您按模型成本比例扣除令牌，并且 m