llm-guard-server/doc/open-api-interface.md

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
• 示例：

{
  "code": 401,
  "msg": "apiSecret 错误"
}

3. 检测接口

3.1 接口定义

• 方法：POST
• 路径：/openapi/guard/check
• 说明：统一执行 ACL、ATTACK、CONTENT 三类规则检测；命中时自动落库告警日志。
• 兼容性：顶层固定为 reqData，reqData 内支持原始网关请求体原样提交，不强制重组字段。

3.2 请求体

{
  "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 成功响应结构

{
  "code": 200,
  "msg": "来源IP不在白名单；命中攻击特征；命中内容DLP规则",
  "data": {
    "requestId": "req-001",
    "traceId": "trace-001",
    "decision": "BLOCK",
    "alerted": true,
    "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.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）

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 等）：便于运营统计与分流。