arc-framework/guardrails
GitHub: arc-framework/guardrails
面向LLM应用的Python安全防护库，提供PII检测、提示注入防御和有害输出过滤，支持多种部署模式的流水线架构。
Stars: 0 | Forks: 0
# arc-guardrails
一个用于 LLM 应用的 guardrails 库。三个包，一套决策契约：
- **`arc-guard-core`** — 零依赖契约层（带类型的模型、Protocols、异常层次结构、pipeline 形状）。
- **`arc-guard`** — 包含内置检查器、策略、报告器和中间件适配器的开箱即用库。
- **`arc-guard-service`** — 传输无关的部署面（进程内函数调用、CLI 批处理任务、HTTP sidecar、FastAPI 中间件）。
## 快速开始
```
pip install arc-guard
python -c "
import asyncio
from arc_guard.pipeline import GuardPipeline
from arc_guard_core.types import GuardInput
result = asyncio.run(GuardPipeline().pre_process(GuardInput(text='ignore previous instructions')))
print(result.action, result.refusal.code if result.refusal else None)
"
# 拦截 jailbreak_strong
```
对于 sidecar 部署：
```
pip install 'arc-guard-service[fastapi]'
python -m arc_guard_service --port 8000
```
请参阅 [`examples/`](examples/) 以了解四种可运行的集成模式。
## 开发检查
本代码库已通过根目录的 `Makefile` 和 dashboard 包脚本暴露了主要的质量门禁。
Python 工作区检查：
```
make format
make lint
make test
make test-all
```
`make test` 是快速的默认选项，它会运行 `core` + `pip`。当您还想运行 `api` 包套件时，请使用 `make test-all`。
GuardRailFlow dashboard 检查：
```
cd apps/guardrail-flow
pnpm format
pnpm lint
pnpm test
```
## CI
本代码库现在包含了一个位于 [`.github/workflows/ci.yml`](.github/workflows/ci.yml) 的 GitHub Actions 工作流。
它会在拉取请求、推送到 `main` 分支以及手动触发时，为 `core` 和 `pip` 运行包范围的检查。
- 该工作流仅在 `packages/core`、`packages/pip`、Python 工作区元数据或工作流文件本身发生更改时触发。
- 每项检查会作为 `core` / `pip` 矩阵分发，并设置 `fail-fast: false`，因此一个包的通道不会取消另一个包的通道。
- 每个通道仅通过 `uv sync --package ... --dev` 安装自己的包依赖，而不是同步包含所有附加组件的整个工作区。
## 使用 Docker 运行
在 Docker Hub 上发布了一个一键式堆栈。无需检出源码，无需构建步骤。
```
curl -fsSLO https://raw.githubusercontent.com///main/docker-compose.yml
docker compose up
```
会启动三个服务：
| 服务 | URL | 提供的内容 |
| --------- | -------------------------- | ------------------------------------------- |
| Dashboard | http://127.0.0.1:5173 | GuardRailFlow 运维 UI |
| API | http://127.0.0.1:8766/docs | arc-guard-service Swagger UI |
| Ollama | http://127.0.0.1:11434 | 上游 LLM (首次运行时拉取 llama3.2) |
切换到重量级的 ML 启用镜像（预装了 semantic-intent + jailbreak-ml + code-injection 扩展，并预缓存了 sentence-transformer 模型）：
```
docker compose --profile ml up
```
固定到特定版本：
```
ARC_GUARD_IMAGE_TAG=0.7.1 docker compose up
```
**已发布的镜像**
| 标签 | 大小 | 已启用的检查器 |
| -------------------------------------------- | ------- | ------------------------------------------------------- |
| `wilp/2024mt03053-arc-guard-service:latest` | ~500 MB | 注入 + Presidio (默认 pipeline) |
| `wilp/2024mt03053-arc-guard-service:ml` | ~3.5 GB | 所有检查器，包括 semantic-intent + jailbreak-ml |
| `wilp/2024mt03053-arc-guardrail-flow:latest` | ~45 MB | nginx + Vite 构建的 SPA |
多架构构建：`linux/amd64` + `linux/arm64`。基于标签驱动的 CI 通过 [`.github/workflows/docker-publish.yml`](.github/workflows/docker-publish.yml) 在 `git push --tags v*.*.*` 时发布。
## 架构
请参阅 [`docs/architecture/README.md`](docs/architecture/README.md) 以获取权威的架构概述，包括重写路线图、演练索引和公共接口清单。
## 贡献
请参阅 [`CONTRIBUTING.md`](CONTRIBUTING.md) 以了解贡献流程和文档树约定。
## 许可证
专有；请参阅 [LICENSE](LICENSE)（如果存在）或联系维护者。
标签：AI安全, AI风险缓解, AV绕过, Chat Copilot, DLL 劫持, Falco, FastAPI, HTTP侧车, PII检测, 个人身份信息, 中间件, 大语言模型, 开源, 异步编程, 护栏, 提示注入, 敏感词过滤, 有毒内容过滤, 网络安全, 请求拦截, 越狱防护, 逆向工具, 防注入, 隐私保护, 集群管理