跳到主要内容

Guard

Aidy 内置了 Guard 检测能力，可通过 GuardPluginGlobalConfig 与 GuardPluginConfig 配置。

全局配置​

check_service_url​

用于指定 Guard 检测服务的 URL，例如 http://localhost:8080。

备注

检测服务直连检测模型 API，如对应检测 API URL 为 http://localhost:8080/v1/chat/responses，则此处应配置为 http://localhost:8080。

timeout​

检测服务请求超时时间，默认 30s。类型为 google.protobuf.Duration，可使用字符串形式配置，如 "5s"、"1500ms"。

当检测服务响应超时时，将跳过 guard 检测流程

路由配置​

路由配置用于指定特定路由的 Guard 检测配置。请参见 路由配置 的 Guard 节。

输出​

检测结果将与请求/响应日志一同输出，具体请看 日志文档 中的 guard 节。

当检测到违规请求时，路由级别仍只有 block 与 log_only 两种模式，但 CyberGuard 的 action 会细分为以下行为：

  • block_action：拦截模式（intercept）
  • override_action：代答模式（substitute）
  • alert_action：仅记录（log_only）
  • pass_action：通过（pass）

其中 block_action 与 override_action 在 Chat / Embeddings 的响应方式不同；log_only 仍保持“仅记录，不改写响应”的原有行为。

行为 - 拦截模式​

拦截模式对应 CyberGuard 返回 block_action（且路由 mode=block）。

Chat - 请求风险​

当检测到请求存在风险时，直接拦截并返回 HTTP 412 + error JSON（message 来自 CyberGuard，若为空则使用默认提示）：

HTTP/1.1 412 Precondition Failed
Content-Type: application/json

{"error":{"code":null,"message":"[来源于 CyberGuard 返回]您的请求包含不安全内容，无法生成回复","param":null,"type":"security_guard_error"}}

Chat - 响应风险​

  • 非流式：返回 HTTP 512 + error JSON（结构同上）。
  • 流式：在触发风险后插入 refusal chunk（delta.refusal），并以 finish_reason=refusal 结束，随后输出 [DONE]；不会继续转发后续上游内容。

示例（两段 refusal chunk + 完成信号）：

{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini","system_fingerprint":"fp_44709d6fcb","choices":[{"index":0,"delta":{"refusal":"I'm sorry, I cannot assist with that request."},"logprobs":null,"finish_reason":null}]}
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini","system_fingerprint":"fp_44709d6fcb","choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"refusal"}]}

Embeddings - 请求风险​

Embeddings 的拦截逻辑始终返回 HTTP 412 + error JSON（同上）。

行为 - 代答模式​

代答模式对应 CyberGuard 返回 override_action（且路由 mode=block）。Chat 将返回模拟输出（from-security-guard），Embeddings 仍按拦截处理。

Chat - 请求风险​

当请求触发风险时，返回代答内容（HTTP 200），格式与 OpenAI 兼容：

  • 非流式：object=chat.completion，model=from-security-guard
  • 流式：输出 chat.completion.chunk，finish_reason=stop，随后 [DONE]

Chat - 响应风险​

当响应触发风险时，返回代答内容（同上），并终止后续上游内容的转发。

Embeddings - 请求风险​

即便 CyberGuard 返回 override_action，Embeddings 仍按拦截处理，返回 HTTP 412 + error JSON。