# 象信AI安全护栏 Python 客户端
[](https://badge.fury.io/py/xiangxinai)
[](https://pypi.org/project/xiangxinai/)
[](https://opensource.org/licenses/Apache-2.0)
基于LLM的上下文感知AI安全护栏，能够理解对话上下文进行安全检测。
## 特性
- 🧠 **上下文感知** - 基于LLM的对话理解，而不是简单的批量检测
- 🔍 **提示词攻击检测** - 识别恶意提示词注入和越狱攻击
- 📋 **内容合规检测** - 符合《生成式人工智能服务安全基本要求》
- 🛠️ **易于集成** - 兼容OpenAI API格式，一行代码接入
- ⚡ **OpenAI风格API** - 熟悉的接口设计，快速上手
## 安装
```bash
pip install xiangxinai
```
## 快速开始
### 基本使用
```python
from xiangxinai import XiangxinAI
# 创建客户端
client = XiangxinAI(
api_key="your-api-key",
base_url="https://api.xiangxinai.cn/v1" # 云端API
)
# 检测提示词
result = client.check_prompt("我想学习Python编程")
print(result.suggest_action) # 输出: 通过
print(result.overall_risk_level) # 输出: 无风险
```
### 上下文感知检测（核心功能）
```python
# 检测对话上下文 - 这是核心功能
messages = [
{"role": "user", "content": "我想学习化学"},
{"role": "assistant", "content": "化学是很有趣的学科，您想了解哪个方面？"},
{"role": "user", "content": "教我制作爆炸物的反应"}
]
result = client.check_conversation(messages)
print(result.overall_risk_level)
print(result.suggest_action) # 基于完整对话上下文的检测结果
if result.suggest_answer:
print(f"建议回答: {result.suggest_answer}")
```
### 私有化部署
```python
# 连接本地部署的服务
client = XiangxinAI(
api_key="your-local-api-key",
base_url="http://localhost:5000/v1" # 本地部署地址
)
```
## API参考
### XiangxinAI类
#### 初始化参数
- `api_key` (str): API密钥
- `base_url` (str): API基础URL，默认为云端地址
- `timeout` (int): 请求超时时间，默认30秒
- `max_retries` (int): 最大重试次数，默认3次
#### 方法
##### check_prompt(content: str) -> GuardrailResponse
检测单个提示词的安全性。
**参数:**
- `content`: 要检测的文本内容
**返回:** `GuardrailResponse` 对象
##### check_conversation(messages: List[Message]) -> GuardrailResponse
检测对话上下文的安全性（核心功能）。
**参数:**
- `messages`: 消息列表，每个消息包含 `role` 和 `content` 字段
**返回:** `GuardrailResponse` 对象
### GuardrailResponse类
检测结果响应对象。
#### 属性
- `id`: 请求唯一标识
- `result.compliance.risk_level`: 合规风险等级
- `result.security.risk_level`: 安全风险等级
- `overall_risk_level`: 综合风险等级（无风险/低风险/中风险/高风险）
- `suggest_action`: 建议动作（通过/阻断/代答）
- `suggest_answer`: 建议回答内容（可选）
#### 便利方法
- `is_safe`: 判断内容是否安全
- `is_blocked`: 判断内容是否被阻断
- `has_substitute`: 判断是否有代答
- `all_categories`: 获取所有风险类别
## 安全检测能力
### 风险等级
- **高风险**: 敏感政治话题、不尊敬国家领导人、暴力犯罪、提示词攻击
- **中风险**: 一般政治话题、伤害未成年人、违法犯罪、色情
- **低风险**: 歧视内容、辱骂、侵犯个人隐私、商业违法违规
- **无风险**: 无风险内容
### 处理策略
- **高风险**: 建议拒答
- **中风险**: 建议代答，使用预设安全回复
- **低风险**: 建议代答或根据实际业务情况处理
- **无风险**: 建议通过
## 错误处理
```python
from xiangxinai import XiangxinAI, AuthenticationError, ValidationError, RateLimitError
try:
result = client.check_prompt("测试内容")
except AuthenticationError:
print("API密钥无效")
except ValidationError as e:
print(f"输入验证失败: {e}")
except RateLimitError:
print("请求频率限制")
except Exception as e:
print(f"其他错误: {e}")
```
## 开发
```bash
# 克隆项目
git clone https://github.com/xiangxinai/xiangxin-guardrails
cd xiangxin-guardrails/client
# 安装开发依赖
pip install -e ".[dev]"
# 运行测试
pytest
# 代码格式化
black xiangxinai
isort xiangxinai
# 类型检查
mypy xiangxinai
```
## 许可证
本项目基于 [Apache 2.0](https://opensource.org/licenses/Apache-2.0) 许可证开源。
## 支持
- 📧 技术支持: wanglei@xiangxinai.cn
- 🌐 官方网站: https://xiangxinai.cn
- 📖 文档: https://docs.xiangxinai.cn
- 🐛 问题反馈: https://github.com/xiangxinai/xiangxin-guardrails/issues
---
Made with ❤️ by [象信AI](https://xiangxinai.cn)
Raw data
{
"_id": null,
"home_page": null,
"name": "xiangxinai",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "XiangxinAI <wanglei@xiangxinai.cn>",
"keywords": "ai, safety, guardrails, llm, content-moderation, prompt-injection, security, compliance, xiangxin",
"author": null,
"author_email": "XiangxinAI <wanglei@xiangxinai.cn>",
"download_url": "https://files.pythonhosted.org/packages/17/ae/4d568b909d36658b30c85f52dbe3341030e82e49e0b23f7750b0d82ea9cb/xiangxinai-1.0.2.tar.gz",
"platform": null,
"description": "# \u8c61\u4fe1AI\u5b89\u5168\u62a4\u680f Python \u5ba2\u6237\u7aef\n\n[](https://badge.fury.io/py/xiangxinai)\n[](https://pypi.org/project/xiangxinai/)\n[](https://opensource.org/licenses/Apache-2.0)\n\n\u57fa\u4e8eLLM\u7684\u4e0a\u4e0b\u6587\u611f\u77e5AI\u5b89\u5168\u62a4\u680f\uff0c\u80fd\u591f\u7406\u89e3\u5bf9\u8bdd\u4e0a\u4e0b\u6587\u8fdb\u884c\u5b89\u5168\u68c0\u6d4b\u3002\n\n## \u7279\u6027\n\n- \ud83e\udde0 **\u4e0a\u4e0b\u6587\u611f\u77e5** - \u57fa\u4e8eLLM\u7684\u5bf9\u8bdd\u7406\u89e3\uff0c\u800c\u4e0d\u662f\u7b80\u5355\u7684\u6279\u91cf\u68c0\u6d4b\n- \ud83d\udd0d **\u63d0\u793a\u8bcd\u653b\u51fb\u68c0\u6d4b** - \u8bc6\u522b\u6076\u610f\u63d0\u793a\u8bcd\u6ce8\u5165\u548c\u8d8a\u72f1\u653b\u51fb\n- \ud83d\udccb **\u5185\u5bb9\u5408\u89c4\u68c0\u6d4b** - \u7b26\u5408\u300a\u751f\u6210\u5f0f\u4eba\u5de5\u667a\u80fd\u670d\u52a1\u5b89\u5168\u57fa\u672c\u8981\u6c42\u300b\n- \ud83d\udee0\ufe0f **\u6613\u4e8e\u96c6\u6210** - \u517c\u5bb9OpenAI API\u683c\u5f0f\uff0c\u4e00\u884c\u4ee3\u7801\u63a5\u5165\n- \u26a1 **OpenAI\u98ce\u683cAPI** - \u719f\u6089\u7684\u63a5\u53e3\u8bbe\u8ba1\uff0c\u5feb\u901f\u4e0a\u624b\n\n## \u5b89\u88c5\n\n```bash\npip install xiangxinai\n```\n\n## \u5feb\u901f\u5f00\u59cb\n\n### \u57fa\u672c\u4f7f\u7528\n\n```python\nfrom xiangxinai import XiangxinAI\n\n# \u521b\u5efa\u5ba2\u6237\u7aef\nclient = XiangxinAI(\n api_key=\"your-api-key\",\n base_url=\"https://api.xiangxinai.cn/v1\" # \u4e91\u7aefAPI\n)\n\n# \u68c0\u6d4b\u63d0\u793a\u8bcd\nresult = client.check_prompt(\"\u6211\u60f3\u5b66\u4e60Python\u7f16\u7a0b\")\nprint(result.suggest_action) # \u8f93\u51fa: \u901a\u8fc7\nprint(result.overall_risk_level) # \u8f93\u51fa: \u65e0\u98ce\u9669\n```\n\n### \u4e0a\u4e0b\u6587\u611f\u77e5\u68c0\u6d4b\uff08\u6838\u5fc3\u529f\u80fd\uff09\n\n```python\n# \u68c0\u6d4b\u5bf9\u8bdd\u4e0a\u4e0b\u6587 - \u8fd9\u662f\u6838\u5fc3\u529f\u80fd\nmessages = [\n {\"role\": \"user\", \"content\": \"\u6211\u60f3\u5b66\u4e60\u5316\u5b66\"},\n {\"role\": \"assistant\", \"content\": \"\u5316\u5b66\u662f\u5f88\u6709\u8da3\u7684\u5b66\u79d1\uff0c\u60a8\u60f3\u4e86\u89e3\u54ea\u4e2a\u65b9\u9762\uff1f\"},\n {\"role\": \"user\", \"content\": \"\u6559\u6211\u5236\u4f5c\u7206\u70b8\u7269\u7684\u53cd\u5e94\"}\n]\n\nresult = client.check_conversation(messages)\nprint(result.overall_risk_level)\nprint(result.suggest_action) # \u57fa\u4e8e\u5b8c\u6574\u5bf9\u8bdd\u4e0a\u4e0b\u6587\u7684\u68c0\u6d4b\u7ed3\u679c\nif result.suggest_answer:\n print(f\"\u5efa\u8bae\u56de\u7b54: {result.suggest_answer}\")\n```\n\n### \u79c1\u6709\u5316\u90e8\u7f72\n\n```python\n# \u8fde\u63a5\u672c\u5730\u90e8\u7f72\u7684\u670d\u52a1\nclient = XiangxinAI(\n api_key=\"your-local-api-key\",\n base_url=\"http://localhost:5000/v1\" # \u672c\u5730\u90e8\u7f72\u5730\u5740\n)\n```\n\n## API\u53c2\u8003\n\n### XiangxinAI\u7c7b\n\n#### \u521d\u59cb\u5316\u53c2\u6570\n\n- `api_key` (str): API\u5bc6\u94a5\n- `base_url` (str): API\u57fa\u7840URL\uff0c\u9ed8\u8ba4\u4e3a\u4e91\u7aef\u5730\u5740\n- `timeout` (int): \u8bf7\u6c42\u8d85\u65f6\u65f6\u95f4\uff0c\u9ed8\u8ba430\u79d2\n- `max_retries` (int): \u6700\u5927\u91cd\u8bd5\u6b21\u6570\uff0c\u9ed8\u8ba43\u6b21\n\n#### \u65b9\u6cd5\n\n##### check_prompt(content: str) -> GuardrailResponse\n\n\u68c0\u6d4b\u5355\u4e2a\u63d0\u793a\u8bcd\u7684\u5b89\u5168\u6027\u3002\n\n**\u53c2\u6570:**\n- `content`: \u8981\u68c0\u6d4b\u7684\u6587\u672c\u5185\u5bb9\n\n**\u8fd4\u56de:** `GuardrailResponse` \u5bf9\u8c61\n\n##### check_conversation(messages: List[Message]) -> GuardrailResponse\n\n\u68c0\u6d4b\u5bf9\u8bdd\u4e0a\u4e0b\u6587\u7684\u5b89\u5168\u6027\uff08\u6838\u5fc3\u529f\u80fd\uff09\u3002\n\n**\u53c2\u6570:**\n- `messages`: \u6d88\u606f\u5217\u8868\uff0c\u6bcf\u4e2a\u6d88\u606f\u5305\u542b `role` \u548c `content` \u5b57\u6bb5\n\n**\u8fd4\u56de:** `GuardrailResponse` \u5bf9\u8c61\n\n### GuardrailResponse\u7c7b\n\n\u68c0\u6d4b\u7ed3\u679c\u54cd\u5e94\u5bf9\u8c61\u3002\n\n#### \u5c5e\u6027\n\n- `id`: \u8bf7\u6c42\u552f\u4e00\u6807\u8bc6\n- `result.compliance.risk_level`: \u5408\u89c4\u98ce\u9669\u7b49\u7ea7\n- `result.security.risk_level`: \u5b89\u5168\u98ce\u9669\u7b49\u7ea7\n- `overall_risk_level`: \u7efc\u5408\u98ce\u9669\u7b49\u7ea7\uff08\u65e0\u98ce\u9669/\u4f4e\u98ce\u9669/\u4e2d\u98ce\u9669/\u9ad8\u98ce\u9669\uff09\n- `suggest_action`: \u5efa\u8bae\u52a8\u4f5c\uff08\u901a\u8fc7/\u963b\u65ad/\u4ee3\u7b54\uff09\n- `suggest_answer`: \u5efa\u8bae\u56de\u7b54\u5185\u5bb9\uff08\u53ef\u9009\uff09\n\n#### \u4fbf\u5229\u65b9\u6cd5\n\n- `is_safe`: \u5224\u65ad\u5185\u5bb9\u662f\u5426\u5b89\u5168\n- `is_blocked`: \u5224\u65ad\u5185\u5bb9\u662f\u5426\u88ab\u963b\u65ad\n- `has_substitute`: \u5224\u65ad\u662f\u5426\u6709\u4ee3\u7b54\n- `all_categories`: \u83b7\u53d6\u6240\u6709\u98ce\u9669\u7c7b\u522b\n\n## \u5b89\u5168\u68c0\u6d4b\u80fd\u529b\n\n### \u98ce\u9669\u7b49\u7ea7\n\n- **\u9ad8\u98ce\u9669**: \u654f\u611f\u653f\u6cbb\u8bdd\u9898\u3001\u4e0d\u5c0a\u656c\u56fd\u5bb6\u9886\u5bfc\u4eba\u3001\u66b4\u529b\u72af\u7f6a\u3001\u63d0\u793a\u8bcd\u653b\u51fb\n- **\u4e2d\u98ce\u9669**: \u4e00\u822c\u653f\u6cbb\u8bdd\u9898\u3001\u4f24\u5bb3\u672a\u6210\u5e74\u4eba\u3001\u8fdd\u6cd5\u72af\u7f6a\u3001\u8272\u60c5\n- **\u4f4e\u98ce\u9669**: \u6b67\u89c6\u5185\u5bb9\u3001\u8fb1\u9a82\u3001\u4fb5\u72af\u4e2a\u4eba\u9690\u79c1\u3001\u5546\u4e1a\u8fdd\u6cd5\u8fdd\u89c4\n- **\u65e0\u98ce\u9669**: \u65e0\u98ce\u9669\u5185\u5bb9\n\n### \u5904\u7406\u7b56\u7565\n\n- **\u9ad8\u98ce\u9669**: \u5efa\u8bae\u62d2\u7b54\n- **\u4e2d\u98ce\u9669**: \u5efa\u8bae\u4ee3\u7b54\uff0c\u4f7f\u7528\u9884\u8bbe\u5b89\u5168\u56de\u590d\n- **\u4f4e\u98ce\u9669**: \u5efa\u8bae\u4ee3\u7b54\u6216\u6839\u636e\u5b9e\u9645\u4e1a\u52a1\u60c5\u51b5\u5904\u7406\n- **\u65e0\u98ce\u9669**: \u5efa\u8bae\u901a\u8fc7\n\n## \u9519\u8bef\u5904\u7406\n\n```python\nfrom xiangxinai import XiangxinAI, AuthenticationError, ValidationError, RateLimitError\n\ntry:\n result = client.check_prompt(\"\u6d4b\u8bd5\u5185\u5bb9\")\nexcept AuthenticationError:\n print(\"API\u5bc6\u94a5\u65e0\u6548\")\nexcept ValidationError as e:\n print(f\"\u8f93\u5165\u9a8c\u8bc1\u5931\u8d25: {e}\")\nexcept RateLimitError:\n print(\"\u8bf7\u6c42\u9891\u7387\u9650\u5236\")\nexcept Exception as e:\n print(f\"\u5176\u4ed6\u9519\u8bef: {e}\")\n```\n\n## \u5f00\u53d1\n\n```bash\n# \u514b\u9686\u9879\u76ee\ngit clone https://github.com/xiangxinai/xiangxin-guardrails\ncd xiangxin-guardrails/client\n\n# \u5b89\u88c5\u5f00\u53d1\u4f9d\u8d56\npip install -e \".[dev]\"\n\n# \u8fd0\u884c\u6d4b\u8bd5\npytest\n\n# \u4ee3\u7801\u683c\u5f0f\u5316\nblack xiangxinai\nisort xiangxinai\n\n# \u7c7b\u578b\u68c0\u67e5\nmypy xiangxinai\n```\n\n## \u8bb8\u53ef\u8bc1\n\n\u672c\u9879\u76ee\u57fa\u4e8e [Apache 2.0](https://opensource.org/licenses/Apache-2.0) \u8bb8\u53ef\u8bc1\u5f00\u6e90\u3002\n\n## \u652f\u6301\n\n- \ud83d\udce7 \u6280\u672f\u652f\u6301: wanglei@xiangxinai.cn\n- \ud83c\udf10 \u5b98\u65b9\u7f51\u7ad9: https://xiangxinai.cn\n- \ud83d\udcd6 \u6587\u6863: https://docs.xiangxinai.cn\n- \ud83d\udc1b \u95ee\u9898\u53cd\u9988: https://github.com/xiangxinai/xiangxin-guardrails/issues\n\n---\n\nMade with \u2764\ufe0f by [\u8c61\u4fe1AI](https://xiangxinai.cn)\n",
"bugtrack_url": null,
"license": null,
"summary": "\u8c61\u4fe1AI\u5b89\u5168\u62a4\u680f Python \u5ba2\u6237\u7aef - \u57fa\u4e8eLLM\u7684\u4e0a\u4e0b\u6587\u611f\u77e5AI\u5b89\u5168\u62a4\u680f",
"version": "1.0.2",
"project_urls": {
"Changelog": "https://github.com/xiangxinai/xiangxin-guardrails/blob/main/CHANGELOG.md",
"Documentation": "https://docs.xiangxinai.cn",
"Homepage": "https://xiangxinai.cn",
"Issues": "https://github.com/xiangxinai/xiangxin-guardrails/issues",
"Repository": "https://github.com/xiangxinai/xiangxin-guardrails"
},
"split_keywords": [
"ai",
" safety",
" guardrails",
" llm",
" content-moderation",
" prompt-injection",
" security",
" compliance",
" xiangxin"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "750209fc81bcced197d861c7446b5f3cfb77dd90098099cab169e4e760e40c4f",
"md5": "7972211747199e381b60b1ba3c7246b4",
"sha256": "a4014b182aa4057e46144065d76e01e09b8f6ff09869ff519dbeefe31d38eda6"
},
"downloads": -1,
"filename": "xiangxinai-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7972211747199e381b60b1ba3c7246b4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 13725,
"upload_time": "2025-08-03T12:24:29",
"upload_time_iso_8601": "2025-08-03T12:24:29.956060Z",
"url": "https://files.pythonhosted.org/packages/75/02/09fc81bcced197d861c7446b5f3cfb77dd90098099cab169e4e760e40c4f/xiangxinai-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "17ae4d568b909d36658b30c85f52dbe3341030e82e49e0b23f7750b0d82ea9cb",
"md5": "149b92a754ee546cdcefc1d949a0d524",
"sha256": "dd19aacac27845ba3835f7fc2b580c514d3eef9d0aa7e35f1ba35a0e66e02ce9"
},
"downloads": -1,
"filename": "xiangxinai-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "149b92a754ee546cdcefc1d949a0d524",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 15082,
"upload_time": "2025-08-03T12:24:31",
"upload_time_iso_8601": "2025-08-03T12:24:31.865323Z",
"url": "https://files.pythonhosted.org/packages/17/ae/4d568b909d36658b30c85f52dbe3341030e82e49e0b23f7750b0d82ea9cb/xiangxinai-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-03 12:24:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "xiangxinai",
"github_project": "xiangxin-guardrails",
"github_not_found": true,
"lcname": "xiangxinai"
}
JSON
