# llm-api-guard

**Repository Path**: xiashaoyan/llm-api-guard

## Basic Information

- **Project Name**: llm-api-guard
- **Description**: LLM API 网关防护层：当前轮次执法、历史上下文隔离与可选远程 Judge
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-27
- **Last Updated**: 2026-07-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LLM API Guard

[![CI](https://github.com/ShaoyanXia/llm-api-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/ShaoyanXia/llm-api-guard/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/ShaoyanXia/llm-api-guard)](https://github.com/ShaoyanXia/llm-api-guard/releases)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Go](https://img.shields.io/badge/Go-1.22%2B-00ADD8.svg)](go.mod)

面向 OpenAI 兼容网关的轻量级请求防火墙。部署在客户端与 NewAPI、One API、LiteLLM 等模型网关之间，拦截提示词窃取、模型蒸馏、模型提取、越狱、密钥外传和滥用自动化请求，并隔离已经污染的历史对话。

**v0.2.0 的核心变化：强制封禁规则与语义复核规则彻底分离。** 精确关键词可以无条件阻断；需要理解上下文的规则可交给 OpenAI 兼容聊天模型、OpenAI Moderation 或 Llama Guard 复核。

- GitHub：[ShaoyanXia/llm-api-guard](https://github.com/ShaoyanXia/llm-api-guard)
- Gitee：[xiashaoyan/llm-api-guard](https://gitee.com/xiashaoyan/llm-api-guard)
- 当前版本：`v0.2.0`

![LLM API Guard 管理页面](docs/assets/management-console.png)

## 为什么需要它

许多网关会对整个 `messages` 数组执行关键词过滤。用户只要在某一轮误触一次规则，客户端后续每次请求都会重新携带该历史消息，导致所有正常追问持续失败。

LLM API Guard 只让最新的 `user` 消息决定当前请求是否阻断。历史违规消息可以替换为安全占位文本后继续转发，不会让一次误触永久污染整个会话。

```mermaid
flowchart LR
    Client["客户端 / OpenAI SDK"] --> Guard["LLM API Guard"]
    Guard --> Parse["提取最新 user 消息"]
    Parse --> Hard["强制封禁规则"]
    Parse --> Review["本地复核触发规则"]
    Review --> Judge["可选远程 Judge"]
    Hard -->|命中| Block["403 policy_violation"]
    Judge -->|block 且达到阈值| Block
    Parse --> History["隔离历史违规 user 消息"]
    History --> Upstream["NewAPI / One API / LiteLLM"]
    Review -->|允许| Upstream
```

## 三分钟启动

```bash
git clone https://github.com/ShaoyanXia/llm-api-guard.git
cd llm-api-guard
cp config.example.json config.json

export LLM_GUARD_ADMIN_TOKEN="$(openssl rand -hex 32)"
go run . -config ./config.json
```

```bash
curl http://127.0.0.1:8320/health
# {"status":"ok","version":"0.2.0"}
```

客户端原来访问 `http://127.0.0.1:8317/v1/chat/completions`，接入后改为 `http://127.0.0.1:8320/v1/chat/completions`。路径、查询参数、`Authorization` 和流式响应会继续透传。

## 两类本地规则

| 配置 | 用途 | 命中后的行为 |
|---|---|---|
| `block_keywords` | 必须禁止出现的精确词语 | `block`、置信度 `1.0`，不调用 Judge，不受阈值影响 |
| `block_regex_rules` | 必须禁止的结构化模式 | 与强制关键词相同 |
| `keywords` | 需要语义判断的触发词 | 标记为 `suspicious`，启用 Judge 时交给 Judge 复核 |
| `regex_rules` | 需要语义判断的模式 | 与复核关键词相同 |

升级自 v0.1.x 时，原有 `keywords` 和 `regex_rules` 仍保持复核触发语义，不会突然变成强制封禁。

## Judge 提供方

| `judge_provider` | 接口 | 适用场景 |
|---|---|---|
| `openai_chat` | `/v1/chat/completions` | 提示词泄露、蒸馏、模型提取、越狱等语义风险 |
| `openai_moderation` | `/v1/moderations` | 暴力、仇恨、自残、色情等通用内容安全 |
| `llama_guard` | `/v1/chat/completions` | 自托管或私有化内容安全分类 |

- `review_matches`：默认。只有本地复核规则命中时才调用 Judge，延迟最低。
- `all_current`：每条最新用户消息都调用 Judge，覆盖面更大，但每次请求都会增加远程分类延迟。

Judge 超时、网络失败或输出不可解析时默认 fail-open，并将错误写入事件记录，避免分类服务故障中断全部模型业务。

## 网关接入

- [NewAPI 示例](examples/new-api/)
- [One API 示例](examples/one-api/)
- [LiteLLM Proxy 示例](examples/litellm/)
- [网关链路与通用检查](docs/08-integrations.md)

## 可复现评估

```bash
go run . -config ./config.json -evaluate ./testdata/policy-cases.jsonl
```

输出包含混淆矩阵、准确率、精确率、召回率、平均延迟、P95 延迟和逐条结果。启用远程 Judge 后，报告会包含真实网络耗时和分类错误。

2026-07-27 本地规则回归基线：32 条中英样本，18 条风险、14 条正常，准确率/精确率/召回率均为 100%，平均约 `0.08ms`，P95 约 `0.50ms`。该语料用于防止项目自身回归，不代表真实生产流量的通用准确率或合规认证。详见 [评估方法](docs/09-evaluation.md)。

## 主要能力

- 只让最新 `user` 消息决定当前请求是否阻断。
- 历史违规消息替换或仅审计，正常追问可以继续。
- 强制封禁规则与 Judge 复核规则独立配置。
- OpenAI Chat、OpenAI Moderation、Llama Guard 三种 Judge。
- Judge 可按本地命中调用，也可检查每条当前消息。
- HMAC-SHA256 短期违规指纹，不持久化被拦截原文。
- `observe` 与 `block` 两种运行模式。
- OpenAI `messages` 与 Gemini `contents/parts` 上下文结构。
- 内置管理、统计、事件分页和配置页面。
- 单 Go 二进制，可配 systemd、Caddy、Nginx 或 Docker。

## 文档

- [五分钟快速开始](docs/00-quickstart.md)
- [完整配置手册](docs/01-configuration.md)
- [系统架构与数据链路](docs/02-architecture-dataflow.md)
- [拦截策略与业务细节](docs/03-policy-business.md)
- [生产部署与升级回滚](docs/04-deployment.md)
- [运维、事件与容量规划](docs/05-operations.md)
- [安全边界与隐私](docs/06-security.md)
- [常见问题与排障](docs/07-troubleshooting.md)
- [网关接入](docs/08-integrations.md)
- [评估方法与基线](docs/09-evaluation.md)

## 安全边界

LLM API Guard 是降低误用与误拦的请求过滤层，不是完整的内容合规、身份认证、限流、配额、账单、DLP、恶意文件扫描或人工审核系统。远程 Judge 和本地规则都可能误报或漏报，生产环境必须先使用 `observe` 模式测量真实流量，再逐步启用阻断。

事件预览可能包含敏感业务文本，应限制管理页访问、文件权限和保留周期。完整说明见 [SECURITY.md](SECURITY.md)。

## License

Apache License 2.0。