stihia-ai/stihia-sdk-python
GitHub: stihia-ai/stihia-sdk-python
面向 AI 系统的实时威胁检测 Python SDK，提供提示注入识别、敏感数据检测和流式 LLM 输入输出护栏能力。
Stars: 0 | Forks: 0
# Stihia SDK for Python
[](https://stihia.ai)
[](https://github.com/stihia-ai/stihia-sdk-python/actions/workflows/ci.yml)
[](https://pypi.org/project/stihia/)
[](https://pypi.org/project/stihia/)
[](LICENSE)
用于 AI 系统的 Stihia 实时威胁检测 API 的 Python SDK。
## 安装
```
pip install stihia
```
## 配置
该 SDK 需要一个 Stihia API 密钥进行身份验证。您可以通过两种方式提供它：
### 选项 1：直接参数（推荐用于显式控制）
```
from stihia import StihiaClient
client = StihiaClient(
api_key="sk_...",
project_key="my-app",
user_key="user-123",
process_key="chat",
)
```
### 选项 2：环境变量（推荐用于安全目的）
设置 `STIHIA_API_KEY` 环境变量：
```
export STIHIA_API_KEY="sk_..."
```
然后在不传递 API 密钥的情况下初始化客户端：
```
from stihia import StihiaClient
client = StihiaClient(
project_key="my-app",
user_key="user-123",
process_key="chat",
)
```
**优先级**：如果您同时提供了这两种方式，显式的 `api_key` 参数将优先于环境变量。
## 快速开始
```
from stihia import StihiaClient
# 初始化 client
client = StihiaClient(
api_key="sk-...",
project_key="my-app",
user_key="user-123",
process_key="chat",
)
# 非阻塞监控
client.sense_background(
messages=[{"role": "user", "content": "Hello, world!"}],
sensor="default",
run_key="session-123",
)
# 阻塞调用 (等待结果)
result = client.sense(
messages=[{"role": "user", "content": "Hello, world!"}],
sensor="default",
run_key="session-123",
)
print(result.payload.sense_result.aggregated_signal.payload.severity)
```
## 执行模式
### 后台（非阻塞）
不增加延迟的即发即弃调用：
```
client.sense_background(
messages=messages,
sensor="prompt-injection",
run_key="session-123",
on_complete=lambda op: print(f"Completed: {op.uid}"),
on_error=lambda e: print(f"Error: {e}"),
)
```
### 同步阻塞
等待 API 响应：
```
result = client.sense(
messages=messages,
sensor="prompt-injection",
run_key="session-123",
)
```
### 异步阻塞
用于异步上下文：
```
result = await client.asense(
messages=messages,
sensor="prompt-injection",
run_key="session-123",
)
```
## Stihia 上下文
使用 `StihiaContext` 为感知操作界定 `thread_key`、`run_key` 和 `process_key` 的作用域。一个上下文等于一个线程中的一次运行。
```
from stihia import StihiaClient, StihiaContext
client = StihiaClient(
api_key="sk-...",
project_key="my-app",
user_key="user-123",
)
# 如果省略，将自动生成 thread_key；如果省略，将自动生成 run_key
with StihiaContext(process_key="my-workflow", thread_key="conv-123") as ctx:
client.sense(
messages=[{"role": "user", "content": "First message"}],
sensor="prompt-injection",
)
client.sense(
messages=[{"role": "assistant", "content": "Response"}],
sensor="sensitive-data",
)
```
### 自定义键
提供您自己的 `run_key`：
```
with StihiaContext(process_key="my-process", thread_key="conv-123", run_key="custom-trace-id") as ctx:
client.sense(messages=messages, sensor="...")
```
### 异步支持
可与异步代码无缝协作：
```
async with StihiaContext(process_key="async-workflow", thread_key="conv-123") as ctx:
await client.asense(messages=messages, sensor="...")
```
## SenseGuard
`SenseGuard` 使用并发的输入/输出防护机制封装了一个异步 LLM 流。
`input_sensor` 和 `output_sensor` 都是可选的（默认为 `None`）。当
传感器为 `None` 时，将完全跳过相应的 API 调用。这
支持 输入+输出、仅输入、仅输出 或 直通（仅后置处理器）配置。
当设置了 `input_sensor` 时，输入检查将与流并发运行，
但在生成第一个数据块之前完成（门控第一个数据块）。当
`input_sensor` 为 `None` 时，数据块将立即流出，没有输入门控。
### 基本用法
```
from stihia import StihiaClient
from stihia.guard import SenseGuard
client = StihiaClient(api_key="sk-...", project_key="my-app", user_key="u1")
# 输入 + 输出 guardrails
guard = SenseGuard(
client,
messages=[{"role": "user", "content": user_input}],
input_sensor="default-input",
output_sensor="default-output",
output_check_interval=5.0,
project_key="my-app",
user_key="u1",
)
chunks = []
async for chunk in guard.shield(llm.astream(prompt)):
chunks.append(chunk)
if guard.triggered:
print("Threat source:", "input" if guard.input_triggered else "output")
```
### 仅输出（无输入门控）
```
guard = SenseGuard(
client,
messages=[{"role": "user", "content": user_input}],
output_sensor="toxic-content",
output_check_interval=3.0,
project_key="my-app",
user_key="u1",
)
async for chunk in guard.shield(llm.astream(prompt)):
print(chunk, end="") # chunks flow immediately — no input gate
```
### 直通（仅后置处理器）
```
from stihia import strip_markdown_images
guard = SenseGuard(
client,
messages=[{"role": "user", "content": user_input}],
post_processors=[strip_markdown_images],
project_key="my-app",
user_key="u1",
)
async for chunk in guard.shield(llm.astream(prompt)):
print(chunk, end="") # no API calls, only post-processing
```
### 仅最终输出检查
将 `output_check_interval` 设置为 `None`，以跳过周期性的流中检查，仅
运行最终的流后检查。这减少了 API 调用，避免了流中
中断，同时仍然验证完整的输出。
```
guard = SenseGuard(
client,
messages=[{"role": "user", "content": user_input}],
input_sensor="default-input",
output_sensor="default-output",
output_check_interval=None, # final check only
project_key="my-app",
user_key="u1",
)
async for chunk in guard.shield(llm.astream(prompt)):
print(chunk, end="") # all chunks delivered without interruption
if guard.output_triggered:
print("\nOutput flagged after completion")
```
### 后置处理器
SenseGuard 支持 `post_processors`——即在将每个数据块
生成给调用者之前对其进行转换的可调用对象。传感器始终看到未修改的输出。
内置的 `strip_markdown_images` 处理器会将 `` 转换为
`[alt](url)`，以防止通过自动获取的图像
URL 进行间接提示注入。它使用 `@text_processor` 装饰，因此它适用于普通的
字符串和兼容 OpenAI 的流式数据块：
```
from stihia import SenseGuard, strip_markdown_images
guard = SenseGuard(
client,
messages=messages,
input_sensor="default-input",
post_processors=[strip_markdown_images],
# ...
)
async for chunk in guard.shield(llm_stream):
print(chunk) # markdown images replaced with plain links
```
使用 `@text_processor` 装饰器从简单的 `str -> str` 函数
创建您自己的支持数据块的
处理器：
```
from stihia import text_processor
@text_processor
def redact_emails(text: str) -> str:
"""Replace email addresses with [REDACTED]."""
import re
return re.sub(r"\S+@\S+", "[REDACTED]", text)
guard = SenseGuard(
client,
messages=messages,
input_sensor="default-input",
post_processors=[redact_emails],
# ...
)
```
该装饰器提升了函数，使其：
- `str` 输入被直接传递给函数
- 兼容 OpenAI 的数据块对象将提取 `choices[0].delta.content`，
进行转换并重新写入
- 任何其他内容将原样传递
## 传感器类型
- `default` - 标准威胁检测（提示注入 + PII）
- `default-input` - 针对输入的综合威胁检测
- `default-output` - 针对输出的综合威胁检测
- `default-input-think` - 带有附加推理的针对输入的综合威胁检测
## 开发
有关完整的开发设置和指南，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
```
git clone https://github.com/stihia-ai/stihia-sdk-python.git
cd stihia-sdk-python
uv sync --all-extras
uv run pytest
```
## 安全
若要报告安全漏洞，请参阅 [SECURITY.md](SECURITY.md)。**请勿为了安全报告而开启公开的 issue。**
## 贡献
我们欢迎各种贡献！在提交 pull request 之前，请阅读 [贡献指南](CONTRIBUTING.md) 和我们的 [行为准则](CODE_OF_CONDUCT.md)。
## 许可证
本项目根据 [Apache License 2.0](LICENSE) 授权。
标签：AI安全, AMSI绕过, API客户端, API集成, Chat Copilot, Python SDK, Stihia, 人工智能, 可观测性, 大模型安全, 威胁检测, 安全防护, 密钥泄露防护, 开源, 异步处理, 数据监控, 机器学习安全, 用户模式Hook绕过, 网络安全, 计算机取证, 软件开发包, 逆向工具, 隐私保护, 零日漏洞检测, 风控系统