246 lines
8.8 KiB
Markdown
246 lines
8.8 KiB
Markdown
# LLM Guard OpenAPI 对外接口文档
|
||
|
||
## 1. 文档说明
|
||
- 文档版本：v1.0
|
||
- 适用服务：`llm-guard-open-api`
|
||
- 基础路径：`/openapi`
|
||
- 字符集：`UTF-8`
|
||
- 请求/响应格式：`application/json`
|
||
|
||
## 1.1 测试环境信息
|
||
- 接口地址：`http://49.233.48.5:6201/open-api/openapi/guard/check`
|
||
- `X-Api-Key`：`ak_3ebc8929866e41689ab373c2c1a383b6`
|
||
- `X-Api-Secret`：`sk_6fde3569aaa44b29b226a7264623778e0a95e22677b746969f97f193ac4ae581`
|
||
|
||
## 2. 认证方式
|
||
### 2.1 Header 鉴权
|
||
每次请求必须携带以下请求头：
|
||
- `X-Api-Key`
|
||
- `X-Api-Secret`
|
||
|
||
### 2.2 凭证发放与生命周期
|
||
- 凭证来源：`system` 用户管理。
|
||
- 用户新增时：若凭证为空，系统自动生成 `apiKey/apiSecret`。
|
||
- 用户编辑时：默认保持原值不变；仅当凭证字段被设置为空时，重新生成。
|
||
- 服务启动时：会对缺失凭证的用户自动初始化。
|
||
|
||
### 2.3 认证失败返回
|
||
- HTTP 状态：`200`
|
||
- 业务码：`code=401`
|
||
- 示例：
|
||
```json
|
||
{
|
||
"code": 401,
|
||
"msg": "apiSecret 错误"
|
||
}
|
||
```
|
||
|
||
## 3. 检测接口
|
||
### 3.1 接口定义
|
||
- 方法：`POST`
|
||
- 路径：`/openapi/guard/check`
|
||
- 说明：统一执行 ACL、ATTACK、CONTENT 三类规则检测；命中时自动落库告警日志。
|
||
- 兼容性：顶层固定为 `reqData`，`reqData` 内支持原始网关请求体原样提交，不强制重组字段。
|
||
|
||
### 3.2 请求体
|
||
```json
|
||
{
|
||
"sourceIp": "10.0.0.1",
|
||
"path": "/api/llm/chat/completion/V2",
|
||
"method": "POST",
|
||
"interfaceType": "LLM",
|
||
"callerId": "partner-a",
|
||
"reqData": {
|
||
"messages": [
|
||
{
|
||
"role": "user",
|
||
"content": "please union select password and email test_user@demo.com"
|
||
}
|
||
],
|
||
"model": "通义千问2.5-72B",
|
||
"stream": false
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.3 请求字段说明
|
||
说明：
|
||
- 顶层固定字段：`sourceIp`、`path`、`method`、`interfaceType`、`callerId`、`reqData`。
|
||
- `reqData` 内部可直接放三类网关原始入参，不强制重组。
|
||
- 系统会优先使用顶层字段做 ACL 与审计，`reqData` 用于内容检测与原文追溯。
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| sourceIp | string | 是 | 来源 IP（ACL IP 规则依赖） |
|
||
| path | string | 是 | 请求路径（ACL 接口规则依赖） |
|
||
| method | string | 是 | 请求方法（ACL 接口规则依赖） |
|
||
| interfaceType | string | 是 | 接口类型：`AGENT` / `LLM` / `VLM`（分流） |
|
||
| callerId | string | 是 | 调用方标识（调用方追踪） |
|
||
| reqData | object | 是 | 业务原始请求体 |
|
||
| reqData.requestId | string | 否 | 请求唯一标识；为空时系统自动生成 |
|
||
| reqData.traceId | string | 否 | 链路追踪标识；为空时系统自动生成 |
|
||
| reqData.scopeCode | string | 否 | 规则作用域；默认 `GLOBAL` |
|
||
| reqData.stream | boolean | 否 | 是否流式；默认 `false` |
|
||
| reqData.text/messages/files/metadata/payload/其他任意字段 | mixed | 否 | 原始业务参数，统一纳入规则匹配语料 |
|
||
|
||
## 4. 响应体
|
||
### 4.1 成功响应结构
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "来源IP不在白名单；命中攻击特征；命中内容DLP规则",
|
||
"data": {
|
||
"requestId": "req-001",
|
||
"traceId": "trace-001",
|
||
"decision": "BLOCK",
|
||
"alerted": true,
|
||
"rejectCode": 403,
|
||
"rejectAction": "blocked",
|
||
"rejectMsg": "内容不合规",
|
||
"hits": [
|
||
{
|
||
"moduleType": "ACL",
|
||
"eventType": "ACL_IP_WHITELIST",
|
||
"ruleId": null,
|
||
"ruleCode": null,
|
||
"action": "BLOCK",
|
||
"message": "来源IP不在白名单"
|
||
},
|
||
{
|
||
"moduleType": "ATTACK",
|
||
"eventType": "ATTACK_SIGNATURE",
|
||
"ruleId": "sig_multi_1",
|
||
"ruleCode": "ATTACK_SQL_MULTI",
|
||
"action": "ALERT",
|
||
"message": "命中攻击特征"
|
||
},
|
||
{
|
||
"moduleType": "CONTENT",
|
||
"eventType": "CONTENT_DLP",
|
||
"ruleId": "dlp_multi_1",
|
||
"ruleCode": "DLP_EMAIL_MULTI",
|
||
"action": "ALERT",
|
||
"message": "命中内容DLP规则"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.2 响应字段说明
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| code | number | 业务码；`200` 成功，`401` 认证失败 |
|
||
| msg | string | 命中说明汇总（`hits.message` 去重后以 `；` 拼接）；未命中时为“未命中规则，允许通过” |
|
||
| data.requestId | string | 请求 ID |
|
||
| data.traceId | string | 链路 ID |
|
||
| data.decision | string | 最终决策：`ALLOW` / `BLOCK` |
|
||
| data.alerted | boolean | 是否命中任意规则 |
|
||
| data.rejectCode | number | 命中内容合规拦截时返回的拒绝码（来自“拒绝描述配置”） |
|
||
| data.rejectAction | string | 命中内容合规拦截时返回的动作标识 |
|
||
| data.rejectMsg | string | 命中内容合规拦截时返回的提示文案 |
|
||
| data.hits | array | 命中明细列表 |
|
||
| data.hits[].moduleType | string | 模块：`ACL` / `ATTACK` / `CONTENT` |
|
||
| data.hits[].eventType | string | 事件类型 |
|
||
| data.hits[].ruleId | string | 命中的规则/特征 ID |
|
||
| data.hits[].ruleCode | string | 命中的规则编码 |
|
||
| data.hits[].action | string | 命中动作：`ALLOW` / `BLOCK` / `ALERT` / `MASK` / `REPLACE` |
|
||
| data.hits[].message | string | 命中说明 |
|
||
|
||
### 4.3 判定规则（调用方重点）
|
||
- 是否允许放行：看 `data.decision`
|
||
- `ALLOW`：允许通过
|
||
- `BLOCK`：不允许通过
|
||
- 是否触发告警：看 `data.alerted`
|
||
- `true`：已触发告警并写日志
|
||
- `false`：未触发告警
|
||
- 命中明细：看 `data.hits[]`
|
||
- 可用于前端展示、审计留痕、二次策略路由。
|
||
|
||
## 5. 检测范围与执行逻辑
|
||
### 5.1 检测模块
|
||
- ACL：IP 白黑名单、接口封堵、自定义组合规则
|
||
- ATTACK：攻击规则 + 特征签名（如 SQL 注入、越狱等）
|
||
- CONTENT：DLP（邮箱/手机号/证件等）、内容策略、脱敏模板策略
|
||
- 内容审核页面联动：`合规检测范围` 可控制是否执行输入侧内容检测；`词库管理` 会参与内容命中；`拒绝描述配置` 会覆盖拦截文案与返回字段。
|
||
|
||
### 5.2 语料拼接范围
|
||
系统会将下列字段聚合后参与规则匹配：
|
||
- `text`
|
||
- `path`
|
||
- `method`
|
||
- `callerId`
|
||
- `messages`（递归提取）
|
||
- `files`（递归提取）
|
||
- `metadata`（递归提取）
|
||
- `payload`（递归提取）
|
||
|
||
## 6. 告警与审计
|
||
命中规则时，系统自动写入：
|
||
- 事件表：`d_log_alert_event`
|
||
- 命中明细表：`d_log_alert_hit`
|
||
|
||
写入内容包含请求标识、模块类型、事件类型、动作、命中说明、来源 IP、调用方等字段，可直接用于审计与报表。
|
||
|
||
## 7. 三类网关报文适配建议
|
||
### 7.1 智能体接口（AGENT）
|
||
- 建议映射：`text`、`files`、`metadata`。
|
||
- 原始结构可同时放入 `payload` 便于追溯。
|
||
|
||
### 7.2 语义模型接口（LLM）
|
||
- 建议映射：`messages`。
|
||
- 补充模型请求参数到 `metadata/payload`。
|
||
|
||
### 7.3 多模态接口（VLM）
|
||
- 建议映射：`messages`（含文本/图片等多模态内容）。
|
||
- 文件或大对象建议放 `files` 并保留 `payload` 原文。
|
||
|
||
## 8. 调用示例（cURL）
|
||
```bash
|
||
curl -sS "http://ip:6201/open-api/openapi/guard/check" \
|
||
-H "Content-Type: application/json" \
|
||
-H "X-Api-Key: ak_3ebc8929866e41689ab373c2c1a383b6" \
|
||
-H "X-Api-Secret: sk_6fde3569aaa44b29b226a7264623778e0a95e22677b746969f97f193ac4ae581" \
|
||
-d '{
|
||
"sourceIp":"10.0.0.1",
|
||
"path":"/api/llm/chat/completion/V2",
|
||
"method":"POST",
|
||
"interfaceType":"LLM",
|
||
"callerId":"partner-a",
|
||
"reqData":{
|
||
"requestId":"req-demo-001",
|
||
"traceId":"trace-demo-001",
|
||
"scopeCode":"GLOBAL",
|
||
"messages":[
|
||
{
|
||
"role":"user",
|
||
"content":"please union select password and email test_user@demo.com"
|
||
}
|
||
]
|
||
}
|
||
}'
|
||
```
|
||
|
||
## 9. 对接注意事项
|
||
- 顶层必填字段：`sourceIp`、`path`、`method`、`interfaceType`、`callerId`、`reqData`。缺失会返回 `code=400`。
|
||
- 建议调用方保证 `requestId` 全局唯一，方便对账和审计检索。
|
||
- 建议统一使用 `scopeCode=GLOBAL`（或双方约定的租户/场景编码）。
|
||
- 当 `decision=BLOCK` 时，调用方应立即拦截业务请求，不再透传下游。
|
||
- 当 `decision=ALLOW` 且 `alerted=true` 时，建议记录风控告警但允许继续处理。
|
||
|
||
## 10. 建议额外字段
|
||
建议这些字段放在 `reqData` 内（如无对应值可不传）：
|
||
|
||
- 强烈建议：
|
||
- `sourceIp`：用于 ACL 白名单/黑名单判断。
|
||
- `path`：用于接口封堵规则判断。
|
||
- `method`：与 `path` 组合判断 ACL 接口规则。
|
||
- `interfaceType`：标识 `AGENT/LLM/VLM`，便于策略分层与审计。
|
||
- `callerId`：用于区分调用方、追踪告警来源。
|
||
|
||
- 可选增强：
|
||
- `tenantId` / `appId` / `bizCode`：多租户或多应用隔离策略。
|
||
- `reqTimestamp`（毫秒时间戳）：用于请求时序核对。
|
||
- `clientVersion`：便于回溯某版本客户端行为。
|
||
- `channel`（web/app/openapi 等）：便于运营统计与分流。
|