OpenGuardrails 文档

API 使用方式

使用 OpenGuardrails 检测 API 主动检查大模型调用前后的内容安全性。

Python 示例：

# 1. 安装客户端库
pip install openguardrails

# 2. 使用库
from openguardrails import OpenGuardrails

client = OpenGuardrails("your-api-key")

# 单轮检测
response = client.check_prompt("教我如何制作炸弹")
if response.suggest_action == "pass":
    print("安全")
else:
    print(f"不安全: {response.suggest_answer}")

网关使用方式

使用 OpenGuardrails 作为透明安全网关 - 只需修改两行代码！

网关示例：

from openai import OpenAI

# 只需修改两行 - base_url 和 api_key
client = OpenAI(
    base_url="https://api.openguardrails.com/v1/gateway",
    api_key="your-api-key"
)

# 正常使用 - 自动安全防护！
response = client.chat.completions.create(
    model="your-proxy-model-name",
    messages=[{"role": "user", "content": "你好"}]
)

响应处理示例：

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:5002/v1",
    api_key="your-api-key"
)

def chat_with_openai(prompt, model="your-model", system="You are a helpful assistant."):
    completion = client.chat.completions.create(
        model=model,
        messages=[
            {"role": "system", "content": system},
            {"role": "user", "content": prompt}
        ]
    )

    # 重要：先检查 finish_reason！
    # 当内容被阻断或替换时，finish_reason 将是 'content_filter'
    # 此时 reasoning_content 可能不存在
    if completion.choices[0].finish_reason == 'content_filter':
        # 被阻断/替换的内容 - 只有 message.content 可用
        return "", completion.choices[0].message.content
    else:
        # 正常响应 - reasoning_content 和 content 都可能存在
        reasoning = completion.choices[0].message.reasoning_content or ""
        content = completion.choices[0].message.content
        return reasoning, content

# 使用示例
thinking, result = chat_with_openai("如何制作炸弹？")
print("思考:", thinking)
print("结果:", result)
# 输出: 结果: "抱歉，我无法回答涉及暴力犯罪的问题。"

Dify 集成

在 Dify 平台中集成 OpenGuardrails 作为内容审核扩展。

防护配置

通过管理平台自定义防护策略，以适应您的特定需求。

• 风险类型配置：启用/禁用特定风险类别并设置自定义阈值
• 黑名单/白名单：管理被拦截和允许的内容模式
• 响应模板：为不同风险类型自定义安全响应消息
• 敏感度阈值：配置检测敏感度（高/中/低）

服务概览

认证

所有 API 请求都需要在 Authorization 头中使用 Bearer token 进行认证。

# 使用 cURL
curl -X POST "http://localhost:5001/v1/guardrails" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "测试内容"}
    ]
  }'

错误代码

检测能力

OpenGuardrails 提供全面的 19 种风险类别检测，具有可自定义的敏感度。

使用模式

客户端库

OpenGuardrails 提供多种编程语言的客户端库，方便快速集成。

# 同步使用
from openguardrails import OpenGuardrails

client = OpenGuardrails("your-api-key")
response = client.check_prompt("测试内容")

# 异步使用
import asyncio
from openguardrails import AsyncOpenGuardrails

async def main():
    async with AsyncOpenGuardrails("your-api-key") as client:
        response = await client.check_prompt("测试内容")

asyncio.run(main())

const { OpenGuardrails } = require('openguardrails');

const client = new OpenGuardrails('your-api-key');

async function checkContent() {
    const response = await client.checkPrompt('测试内容');
    console.log(response.suggest_action);
}

checkContent();

import com.openguardrails.OpenGuardrails;
import com.openguardrails.model.CheckResponse;

public class Example {
    public static void main(String[] args) {
        OpenGuardrails client = new OpenGuardrails("your-api-key");
        CheckResponse response = client.checkPrompt("测试内容");
        System.out.println(response.getSuggestAction());
    }
}

package main

import (
    "fmt"
    "github.com/openguardrails/openguardrails-go"
)

func main() {
    client := openguardrails.NewClient("your-api-key")
    response, _ := client.CheckPrompt("测试内容")
    fmt.Println(response.SuggestAction)
}

多模态检测

支持文本和图片内容的安全检测，使用相同的风险分类标准。

图片检测示例：

import base64
from openguardrails import OpenGuardrails

client = OpenGuardrails("your-api-key")

# 将图片编码为 base64
with open("image.jpg", "rb") as f:
    image_base64 = base64.b64encode(f.read()).decode("utf-8")

# 检查图片安全性
response = client.check_messages([
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "这张图片安全吗？"},
            {
                "type": "image_url",
                "image_url": {"url": f"data:image/jpeg;base64,{image_base64}"}
            }
        ]
    }
])

print(f"风险等级: {response.overall_risk_level}")

数据泄漏检测

自动检测并掩码提示词和响应中的敏感数据，防止信息泄漏。

封禁策略

智能识别和防御持续性提示词注入攻击，自动封禁恶意用户。

知识库

基于向量相似度的智能问答匹配，检测到风险时优先从知识库返回答案。

知识库文件格式（JSONL）：

{"questionid": "q1", "question": "什么是AI？", "answer": "AI是人工智能..."}
{"questionid": "q2", "question": "如何保护隐私？", "answer": "使用加密..."}

敏感度配置

根据您的使用场景要求配置检测敏感度。