Mattral/guardrail-rs

# guardrail-rs **一个零 Python、生产级的 LLM 安全层，使用 Rust 编写。** `guardrail-rs` 是一个反向代理，位于您的应用程序和 LLM 提供商（OpenAI、Anthropic、Azure OpenAI 或任何兼容 OpenAI 的端点）之间。它会在每个 chat-completion 请求离开您的基础设施之前对其进行检查，拦截 prompt 注入攻击、脱敏 PII，并执行自定义策略规则——所有这一切仅带来个位数毫秒级的开销。 ``` ┌──────────┐ ┌──────────────────┐ ┌────────────┐ ┌───────────────┐ │ Your │ ──▶│ guardrail-rs │ ──▶ │ Pipeline │ ──▶│ OpenAI / │ │ App │ │ (drop-in proxy) │ │ (Stages) │ │ Anthropic /… │ └──────────┘ └──────────────────┘ └────────────┘ └───────────────┘ │ ▼ 403 + JSON error (blocked requests never leave your network) ``` ## 为什么选择 guardrail-rs？ - **不需要 Python、PyTorch 或 GPU。** 一个单一的静态二进制文件（约 15 MB），由本仓库中的 Rust 源码构建。 - **极速。** Regex 注入扫描和 PII 脱敏均在个位数微秒内运行；在默认（非 ONNX）配置下，完整 pipeline 为请求延迟增加的开销远低于 1 ms p99。 - **即插即用。** 将您现有的 OpenAI/Anthropic SDK 的 `base_url` 指向 `guardrail-rs` —— 无需修改应用程序代码。 - **默认故障放行。** 异常的阶段绝不会中断您的生产流量；可通过 `pipeline.on_error` 按部署进行配置。 - **配置热重载。** 无需断开连接即可更新规则和策略。 - **可观测性。** 开箱即用的结构化审计日志（绝不记录原始 PII）和 Prometheus 指标。 ## 快速开始 ``` # 1. 复制并编辑示例配置 cp guardrail.example.toml guardrail.toml # 编辑 guardrail.toml：设置 [upstream].url # 2. 验证配置 just validate # 或：cargo run -p guardrail-cli -- validate --config guardrail.toml # 3. 运行代理 just run # 或：cargo run -p guardrail-cli -- run --config guardrail.toml ``` 然后将您的应用程序指向 `http://localhost:8080`，而不是 `https://api.openai.com`： ``` from openai import OpenAI client = OpenAI( base_url="http://localhost:8080/v1", api_key="sk-...", # forwarded to the real upstream unchanged ) ``` ### 环境变量覆盖 无需编辑 `guardrail.toml` 即可覆盖配置： | 变量 | 覆盖项 | |----------|-----------| | `GUARDRAIL_UPSTREAM` | `upstream.url` | | `GUARDRAIL_PORT` | `server.port` | | `GUARDRAIL_LOG_LEVEL` | `observability.log_level` | | `GUARDRAIL_OTLP_ENDPOINT` | `observability.otlp_endpoint` | ### 热重载（Unix） 发送 `SIGHUP` 以在不断开连接的情况下重载配置： ``` pkill -HUP guardrail # 或：just reload ``` ## 检查内容 | 阶段 | 功能描述 | 性能目标 | |-------|--------------|---------------------| | `regex_injection` | 通过快速的 regex 扫描来检测越狱、prompt 提取尝试、分隔符注入 | < 50 µs / 8 KB | | `onnx_injection` *(可选)* | 基于 DeBERTa 的语义注入检测 | < 5 ms / 512 tokens | | `pii_redactor` | 检测并脱敏电子邮件、电话号码、信用卡（通过 Luhn 算法验证）、社会安全号码（SSN）、IP 地址、API 密钥 | < 20 µs / 4 KB | | `toxicity` *(可选)* | 基于 RoBERTa 的毒性/骚扰检测 | < 5 ms / 512 tokens | | `policy_engine` | 您的自定义规则：关键词拦截、token 数量限制、必需的 system prompt 检查 | 可忽略不计 | `onnx_injection` 和 `toxicity` 阶段需要使用 `--features onnx` 进行构建，并提供 ONNX 模型文件（参见 [`models/README.md`](models/README.md)）。 其他所有功能在零外部依赖下即可工作。 ## CLI ``` guardrail run --config guardrail.toml # start the proxy guardrail validate --config guardrail.toml # check config without starting guardrail check "some text" --config guardrail.toml # run text through the pipeline # and print the decision as JSON ``` ## 配置 请参阅 [`guardrail.example.toml`](guardrail.example.toml) 获取带有完整注释的参考配置，并查阅 [`docs/`](docs/) 获取详细指南： - [`docs/architecture.md`](docs/architecture.md) — pipeline 设计与阶段契约 - [`docs/configuration.md`](docs/configuration.md) — 完整的 TOML schema 参考 - [`docs/policy-rules.md`](docs/policy-rules.md) — 编写自定义策略规则 - [`docs/deployment.md`](docs/deployment.md) — Docker、Kubernetes 及裸机部署 - [`docs/onnx-models.md`](docs/onnx-models.md) — 启用语义分类器 - [`docs/threat-model.md`](docs/threat-model.md) — guardrail-rs 可防御的威胁（以及不可防御的威胁） - [`docs/stage-api.md`](docs/stage-api.md) — 实现自定义 pipeline 阶段 - [`docs/benchmarks.md`](docs/benchmarks.md) — 性能目标及如何运行基准测试 ## 示例 请参阅 [`examples/README.md`](examples/README.md) 获取针对正在运行的代理的客户端示例（curl、Python、Node.js、Anthropic SDK）。要将 guardrail-rs 作为完全不需要 HTTP 服务器的库进行嵌入： ``` cargo run --example minimal -p guardrail-cli ``` ## 项目布局 ``` crates/ guardrail-core # Pipeline trait, request/decision types, policy engine guardrail-classifiers # Regex injection scanner, PII redactor, ONNX classifiers guardrail-config # TOML config schema, validation, hot-reload guardrail-proxy # HTTP server, request forwarding, metrics, audit log guardrail-cli # `guardrail` binary guardrail-test-suite # End-to-end integration tests ``` ## 开发 ``` # 安装 just (task runner) cargo install just # 构建 just build # 测试（需要 cargo-nextest：cargo install cargo-nextest） just test # Lint just lint # 格式化 just fmt # 本地完整 CI 检查 just ci # 生成覆盖率报告（需要 cargo-tarpaulin） just coverage ``` 有关所有可用的任务，请参见 `justfile`（`just --list`）。 ## 许可证 根据您的选择，在 [Apache License, Version 2.0](LICENSE-APACHE) 或 [MIT license](LICENSE-MIT) 下授权。 ## 贡献 欢迎贡献！请参阅 [`CONTRIBUTING.md`](CONTRIBUTING.md) 获取有关提交 issue 和 pull request 的指南，包括如何添加新的 prompt 注入规则或 PII 实体类型。

标签：AI网关, CNCF毕业项目, PII脱敏, Python安全, Rust, 反向代理, 可视化界面, 子域名突变, 提示词注入防护, 用户代理, 网络流量审计, 自定义请求头, 请求拦截, 通知系统