# SentinelAI
SentinelAI 位于您的应用程序和 AI 模型之间，实时分析每一个 prompt 和响应。它能检测捏造的声明、数字不一致、实体混淆、prompt 注入以及对抗性输入——然后返回一个**信任评分**、一个**可解释的决策**，以及一个可选的**修正后的响应**，您可以直接提供服务。
- [产品愿景](#product-vision)
- [快速开始](#quick-start)
- [工作原理](#how-it-works)
- [检测能力](#detection-capabilities)
- [理解结果](#understanding-results)
- [SDK 参考](#sdk-reference)
- [API 端点](#api-endpoints)
- [仪表板](#dashboard)
- [架构](#architecture)
- [工作区与团队](#workspaces--teams)
- [集成模式](#integration-patterns)
- [配置](#configuration)
- [部署](#deployment)
- [测试](#testing)
- [已知局限性](#known-limitations)
- [路线图](#roadmap)
- [商业背景](#business-context)
- [安全](#security)
- [支持](#support)
## 产品愿景
SentinelAI 是一个提供 AI 风险全景的统一平台——为**工程师**、**安全分析师**、**合规专员**和**高管**提供针对其角色定制的视图，以查看同一份受信任的数据。它将安全检测、可解释的调查和合规审计连接在一个单一的工作流中。
**目标 ICP：** 正在生产环境中推出基于 LLM 功能的中型 SaaS 公司（50-500名员工）的 AI/ML 工程师。Python SDK (`pip install sentinelai-sdk`) 专为零阻力采用而设计。
**与 Langfuse、Arize、WhyLabs、Guardrails AI 的主要区别：** 具有代理式推理层的可解释、轻量级、实时风险评分——而不仅仅是被动日志记录或黑盒评分。
## 快速开始
### 1. 注册并创建组织
前往 [sentinelaihq.com](https://sentinelaihq.com) 并使用 GitHub 或 Google 登录。系统会提示您创建一个组织——这是您的团队工作区，您可以在其中管理 API 密钥、邀请成员并查看风险日志。
### 2. 获取您的 API 密钥
导航至组织仪表板中的 **API Keys**。创建一个新密钥并将其复制。
### 3. 安装 SDK
```
pip install sentinelai-sdk
```
### 4. 分析您的首次交互
```
from sentinelai import SentinelAIClient
client = SentinelAIClient(
base_url="https://sentinel-ai-dml3.onrender.com",
api_key="sk_your_api_key_here"
)
result = client.verify(
prompt="What was Apple's revenue in 2025?",
response="Apple reported $395 billion in revenue for fiscal year 2025."
)
print(result.score) # 0-100 trust score
print(result.status) # "trusted", "needs_review", or "hallucinated"
print(result.corrected) # corrected version if hallucinations found
```
## 工作原理
### 请求流
```
flowchart LR
User[User] --> Prompt[Prompt]
Prompt --> App[Your App]
App --> AI[AI Model]
AI --> Response[Response]
Response --> SentinelAI[SentinelAI]
App -.->|Verify in parallel| SentinelAI
SentinelAI --> Decision{Decision}
Decision -->|Trusted| User
Decision -->|Corrected Response| User
Decision -->|Block| App
style SentinelAI fill:#2B42F5,color:#fff
style Decision fill:#f59e0b,color:#fff
```
### 代理式检测流水线
```
flowchart TD
Client[Client Application] --> API[SentinelAI API]
subgraph SignalDetection[Signal Detection Layer]
direction LR
PAD[Prompt Anomaly Detector] --> SR[Signal Registry]
ORS[Output Risk Scorer] --> SR
end
subgraph Reasoning[Agentic Reasoning Layer]
RR[Risk Reasoner Agent]
end
subgraph Policy[Policy & Action Layer]
PE[Policy Engine] --> AE[Action Executor]
end
API --> PAD
API --> ORS
SR --> RR
RR --> PE
AE --> RL[(Risk Logs)]
AE --> AL[(Action Logs)]
classDef layer fill:#e8edff,stroke:#2B42F5,stroke-width:2px
class SignalDetection,Reasoning,Policy layer
```
| 层级 | 组件 | 职责 |
|-------|-----------|----------------|
| **信号检测** | Prompt 异常检测器 | 通过 embedding 相似度检测 prompt 注入、越狱和对抗性输入 |
| **信号检测** | 输出风险评分器 | 对模型输出的幻觉、捏造、数值漂移进行评分 |
| **代理式推理** | 风险推理代理 | 汇总信号，解决冲突，生成可解释的风险决策 |
| **策略与行动** | 策略引擎 | 应用工作区阈值（允许 / 警告 / 阻止 / 升级） |
| **策略与行动** | 行动执行器 | 执行决策并写入不可变的审计追踪 |
## 检测能力
每次交互都会经过六个并行检测器：
| 检测器 | 捕获内容 |
|----------|----------------|
| **无支持声明** | 没有提供上下文支持的事实陈述 |
| **捏造引用** | 引用了不存在的论文、案例或统计数据 |
| **数值漂移** | 与原始材料不一致的数字或数量 |
| **实体混淆** | 将两个相似的人物、地点或产品混为一谈 |
| **上下文矛盾** | 响应与 prompt 或对话历史相矛盾 |
| **过度自信标记** | 对无法验证的声明使用绝对肯定的语言 |
此外，还包含通过 embedding 相似度进行的 **prompt 异常检测**（分布偏移检测），以及用于高风险内容模式的**基于规则的输出启发式检测**。
每个检测器并行运行。Risk Reasoner Agent 将结果汇总为统一的 **0–100 信任评分**，并提供针对每个信号的可解释性。
### 多轮对话追踪
```
sequenceDiagram
participant User
participant App as Your App
participant S as SentinelAI
participant AI as AI Model
User->>App: Turn 1: "What is Q1 revenue?"
App->>AI: prompt
AI-->>App: "Q1 revenue was $12.4B"
App->>S: verify(turn1)
S-->>App: score: 0, status: trusted
App-->>User: "Q1 revenue was $12.4B"
User->>App: Turn 2: "How does that compare to last year?"
App->>AI: prompt + history
AI-->>App: "That's up 22% from $10.2B"
App->>S: verify(turn1 + turn2)
S-->>App: context-aware score
App-->>User: verified response
```
```
from sentinelai import ConversationTracker
tracker = ConversationTracker(client, session_id="conv_001")
result = tracker.analyze_turn(
prompt="User message",
response="AI response"
)
# 自动包含先前的对话轮次以实现上下文感知检测
```
## 理解结果
### 评分区间
```
flowchart LR
Score[Risk Score 0-100] -->|0-24| Trusted[Trusted ✅]
Score -->|25-59| Review[Needs Review ⚠️]
Score -->|60-100| Hallucinated[Hallucinated 🚫]
Trusted --> Serve[Serve as-is]
Review --> Correct[Auto-correct or flag]
Review --> Human[Human review]
Hallucinated --> Block[Block response]
Hallucinated --> ServeCorrected[Serve corrected version]
style Trusted fill:#22c55e,color:#fff
style Review fill:#f59e0b,color:#fff
style Hallucinated fill:#ef4444,color:#fff
```
| 区间 | 分数 | 处理方式 |
|------|-------|------------|
| **受信任** | 0–24 | 未发现问题。按原样提供响应。 |
| **需审查** | 25–59 | 存在轻微隐患。标记供人工审查，或自动更正低风险的片段。 |
| **幻觉** | 60–100 | 高置信度捏造。阻止响应或提供修正后的版本。 |
### 更正
当分数达到 25 分及以上时，响应将包含一个 `corrected` 字段——这是一个重写后的版本，其中被标记的声明已被删除或修正：
```
if result.status == "hallucinated":
return result.corrected # serve the fix, not the flaw
```
### 可解释性
每个决策都包含针对每个标记的人类可读解释——token 级别的归因分析，展示了 prompt 或响应的哪些部分导致了风险评分的增加。这是与黑盒评分系统的关键区别。
## SDK 参考
### Python SDK
**安装：**
```
pip install sentinelai-sdk
```
**SentinelAIClient：**
```
from sentinelai import SentinelAIClient
client = SentinelAIClient(
base_url="https://sentinel-ai-dml3.onrender.com",
api_key="sk_...",
source="my-app", # optional: identifier for your application
timeout=10, # optional: request timeout in seconds
max_retries=3 # optional: retry on transient errors
)
```
**方法：**
| 方法 | 描述 |
|--------|-------------|
| `client.verify(prompt, response)` | 单次验证。返回 `score`、`status`、`corrected`、`claims`。 |
| `client.analyze(prompt, response, user_id?, session_id?)` | 包含风险决策和审计日志的完整分析。返回 `decision`（"allow" / "warn" / "block" / "escalate"）以及 `corrected_response`。 |
| `client.health_check()` | 检查后端连通性。 |
```
# verify — 快速检查
result = client.verify(
prompt="What is the capital of France?",
response="The capital of France is Paris."
)
print(result.score) # 0
print(result.status) # "trusted"
# analyze — 带 audit logging 的生产流程
result = client.analyze(
prompt="User message",
response="AI response",
user_id="user_123",
session_id="session_456"
)
if result["decision"] == "block":
return safe_fallback()
elif result["decision"] == "warn":
log_for_review(result)
return result["corrected_response"]
```
### TypeScript SDK
```
import { SentinelAIClient } from "sentinelai-sdk";
const client = new SentinelAIClient({
apiKey: "sk_...",
baseURL: "https://sentinel-ai-dml3.onrender.com"
});
const result = await client.verify({
prompt: userMessage,
response: llmResponse,
});
if (result.status === "hallucinated") {
return result.corrected;
}
```
## API 端点
基础 URL：`https://sentinel-ai-dml3.onrender.com/api`
| 端点 | 方法 | 描述 |
|----------|--------|-------------|
| `/analyze` | POST | 包含审计日志的完整风险分析 |
| `/analyze/external` | POST | 针对外部/现有日志的分析 |
| `/logs` | GET | 列出风险日志（支持分页、过滤） |
| `/logs/{id}` | GET | 带有解释的风险日志详情 |
| `/health` | GET | 后端健康检查 |
| `/settings` | GET/PUT | 工作区风险阈值和配置 |
| `/settings/history` | GET | 设置变更的版本历史 |
| `/baselines` | GET/PUT | 用于漂移检测的基线配置 |
交互式 API 文档：[sentinel-ai-dml3.onrender.com/api/docs](https://sentinel-ai-dml3.onrender.com/api/docs)
## 仪表板
[sentinelaihq.com](https://sentinelaihq.com) 上的 Web 仪表板提供了一个企业级 AI 风险监控界面，为工程师、安全分析师、合规专员和高管提供角色自适应视图。
### 核心模块
| 模块 | 描述 |
|--------|-------------|
| **Dashboard** | AI 风险健康评分（0–100）、按严重程度划分的活动警报、主要风险、7天趋势图、近期已解决事件 |
| **Risk Events** | 核心分诊界面——可过滤的事件列表、带有风险细分和 token 级别解释的事件详情、快捷操作（阻止、升级、忽略）、证据导出 |
| **Investigations** | 深度分析工作区，包含事件时间轴、相似事件面板、根因分析、token 热力图、证据包生成（JSON + 签名清单） |
| **Models** | 模型注册表，包含各模型的风险监控、基线阈值、漂移历史、防护栏规则和审计日志 |
| **Analytics** | 风险趋势（7天/30天/90天）、模型间对比、团队指标、合规报告 |
| **Audit Logs** | 防篡改、不可变的所有配置变更日志，带有哈希链验证 |
| **Policies** | 防护栏规则引擎——IF/THEN 规则构建器，支持针对历史数据的试运行测试，以及效能指标 (TP/FP) |
| **API Usage** | 请求量、速率限制状态、主要消费者、成本估算 |
| **Team** | 基于角色的访问控制——邀请成员、管理角色（Viewer、Developer、Admin、Owner） |
| **Settings** | 工作区配置、集成（Slack、PagerDuty、webhooks）、SSO/SAML、账单、API 密钥管理 |
### 角色自适应视图
```
flowchart TD
subgraph Personas[Personas]
Maya[Maya - AI Engineer]
Priya[Priya - Security Analyst]
David[David - Compliance Officer]
Marcus[Marcus - CTO/VP Eng]
end
subgraph Views[Default Dashboard View]
V1[Alert feed + model list]
V2[Alert inbox + kill-chain]
V3[Compliance score + checklist]
V4[Health score + trends]
end
Maya --> V1
Priya --> V2
David --> V3
Marcus --> V4
classDef persona fill:#e8edff,stroke:#2B42F5
classDef view fill:#f0fdf4,stroke:#22c55e
class Maya,Priya,David,Marcus persona
class V1,V2,V3,V4 view
```
### 设计系统
该仪表板遵循受 CrowdStrike × Linear × Datadog × Stripe 启发的权威、高信息密度的设计语言。关键元素包括：
- **主品牌色：** `#2B42F5`，采用 Inter (UI) 和 JetBrains Mono (数据) 字体
- **4px 基础间距系统**，确保跨组件的节奏一致
- **严重性颜色**（红/琥珀/蓝/绿）配有图标 + 文本标签——绝不单独依赖颜色
- **渐进式披露**——优先展示核心信息，按需显示详情
- 完整规范见 `Docs/design-system.md`
## 架构
### 生产环境技术栈
```
flowchart LR
subgraph Clients
SDK[Python SDK]
TSSDK[TypeScript SDK]
UI[Next.js Dashboard]
end
subgraph Backend[FastAPI Backend - Render]
API[API Layer]
Detectors[Detector Pipeline]
Reasoner[Risk Reasoner]
Engine[Policy Engine]
end
subgraph Storage
DB[(PostgreSQL)]
AL2[(Audit Logs)]
end
SDK --> API
TSSDK --> API
UI --> API
API --> Detectors
Detectors --> Reasoner
Reasoner --> Engine
Engine --> DB
Engine --> AL2
style Backend fill:#e8edff,stroke:#2B42F5,stroke-width:2px
style Storage fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
```
**后端：** Python (FastAPI)，使用 PostgreSQL 持久化、模块化检测器流水线和代理式推理层。
**前端：** Next.js 15 App Router、TypeScript (严格模式)、Tailwind CSS v4、Zustand (客户端状态)、TanStack Query (服务端状态)、Observable Plot + Recharts (可视化)，部署在 Vercel 上并使用 Clerk 身份验证。
**SDK：** 在 PyPI 上发布的 Python 软件包 (`pip install sentinelai-sdk`)，TypeScript SDK 正在开发中。
### 生产级 Docker 技术栈
对于自托管部署，后端以 Docker Compose 技术栈运行：
```
graph TD
subgraph Host[Machine - Ports :443 :3000]
subgraph Network[Docker Bridge Network]
Nginx[Nginx :443]
FastAPI[FastAPI :8000]
DB[(PostgreSQL 15 :5432)]
Mailpit[Mailpit :8025]
Prometheus[Prometheus :9090]
Grafana[Grafana :3000]
end
end
Nginx -->|reverse proxy| FastAPI
FastAPI -->|persistence| DB
FastAPI -->|email testing| Mailpit
Prometheus -->|scrape /metrics| FastAPI
Grafana -->|query| Prometheus
classDef infra fill:#f3e8ff,stroke:#9333ea
class Nginx,DB,Mailpit,Prometheus,Grafana infra
```
| 服务 | 角色 |
|---------|------|
| **Nginx** | 反向代理、SSL 终止、速率限制 |
| **FastAPI (Uvicorn)** | 应用服务器 |
| **PostgreSQL 15** | 主数据库 |
| **Mailpit** | 电子邮件测试 (SMTP :1025, WebUI :8025) |
| **Prometheus** | 指标采集 (抓取 `/metrics`) |
| **Grafana** | 仪表板和可视化 |
所有服务均在专用的 Docker 桥接网络上运行。只有 Nginx 向宿主机暴露端口。
## 工作区与团队
组织可以拥有多个独立设置、API 密钥和风险日志的工作区——这对于分离开发、测试和生产环境非常有用。
### 角色
| 角色 | 权限 |
|------|-------------|
| **Viewer** | 仅查看日志和仪表板 |
| **Developer** | 查看日志、运行分析、管理 API 密钥 |
| **Admin** | 完整的工作区管理权限，邀请成员 |
| **Owner** | 所有权限 + 账单和删除工作区权限 |
## 集成模式
```
flowchart TD
subgraph Blocking[Blocking Mode]
B1[User Request] --> B2[Your App] --> B3[AI Model]
B3 --> B4[SentinelAI Verify]
B4 -->|Pass| B5[Response to User]
B4 -->|Fail| B6[Corrected / Fallback]
end
subgraph Monitoring[Monitoring Mode]
M1[User Request] --> M2[Your App] --> M3[AI Model]
M3 --> M4[User]
M3 -.->|Async Log| M5[SentinelAI Analyze]
M5 -->|Escalate| M6[Notify Team]
end
subgraph Async[Async Mode]
A1[High-Volume App] --> A2[SentinelAI]
A2 -->|Webhook| A3[Your Callback]
end
```
### 阻断模式
在响应发送给用户之前验证每一个响应。阻断或修正不安全的响应。
```
response = get_llm_response(prompt)
result = client.verify(prompt, response)
return result.corrected if result.corrected else response
```
### 监控模式
记录所有交互以供分析，但不会进行阻断。稍后审查被标记的响应。
```
result = client.analyze(prompt, response, user_id=user.id)
if result["decision"] == "escalate":
notify_team(result)
```
### 异步模式
为高吞吐量应用程序提供即发即忘的验证。通过 webhook 回调异步处理结果。
### 自托管模式
在您自己的基础设施上部署后端。没有任何客户数据会离开您的网络。说明请参见 `Docs/operations/DEPLOYMENT_GUIDE.md`。
## 配置
### 风险阈值
在仪表板的 **Settings** 下或通过 API 为每个工作区配置阈值：
```
flowchart LR
Score[Risk Score] -->|0-24| Allow[Allow ✅]
Score -->|25-59| Warn[Warn ⚠️]
Score -->|60-84| Block[Block 🚫]
Score -->|85-100| Escalate[Escalate 🔔]
style Allow fill:#22c55e,color:#fff
style Warn fill:#f59e0b,color:#fff
style Block fill:#ef4444,color:#fff
style Escalate fill:#dc2626,color:#fff
```
| 阈值 | 描述 | 默认值 |
|-----------|-------------|---------|
| 允许最大值 | 无需审查允许的最大分数 | 24 |
| 警告最小值 | 触发审查标记的最低分数 | 25 |
| 阻止最小值 | 触发阻止的最低分数 | 60 |
| 升级最小值 | 通知管理员的最低分数 | 85 |
设置带有完整的版本历史记录——每一次更改都会记录在不可变的审计追踪中。
### 基线
为分布偏移检测配置基线配置文件。当 prompt embedding 明显偏离基线时（例如，>2σ），系统会标记异常。
## 部署
### 生产环境 URL
| 组件 | URL |
|-----------|-----|
| 仪表板 | [sentinelaihq.com](https://sentinelaihq.com) |
| API | [sentinel-ai-dml3render.com](https://sentinel-ai-dml3.onrender.com) |
| API 文档 | [sentinel-ai-dml3.onrender.com/api/docs](https://sentinel-ai-dml3.onrender.com/api/docs) |
### 本地开发
```
# Backend
cd Backend
cp .env.example .env
pip install -r requirements.txt
uvicorn main:app --reload --port 8001
# Frontend
cd Frontend
npm install
npm run dev
```
### Docker (自托管)
```
cd Backend
docker compose up
```
这将启动 API、PostgreSQL、Nginx、Mailpit、Prometheus 和 Grafana。完整的部署指南、操作手册和事件响应程序请参见 `Docs/operations/`。
### CI/CD
通过 GitHub Actions 进行自动化测试和部署。测试配置和覆盖率要求请参见 `Docs/TESTING.md`。
## 测试
后端测试套件涵盖：
- **单元测试：** 检测器逻辑、评分算法、策略引擎
- **集成测试：** API 端点、数据库交互、完整的分析流水线
- **测试夹具：** 针对每个检测类别的 prompt 和响应示例
```
cd Backend
pytest --cov=. --cov-report=term-missing
```
详细的测试计划请参见 `Docs/TESTING.md` 和 `Docs/PHASE1_TEST_GUIDE.md`。
## 已知局限性
| 类别 | 局限性 |
|----------|------------|
| **检测** | 基于规则的启发式方法可能会产生误报 |
| **检测** | 新型的 prompt 模式可能会绕过异常检测 |
| **检测** | 风险评分较为粗略，不具备概率性 |
| **系统** | 阈值需要手动调整（MVP 中无自动校准） |
| **系统** | 监控会给请求带来轻微延迟（约 100–300ms） |
| **系统** | MVP 不会根据反馈自动学习 |
| **安全** | SentinelAI 无法阻止滥用，只能进行标记 |
| **安全** | 检测到风险并不代表判断绝对正确 |
完整文档请参见 `Docs/FAILURE_MODES.md`。
## 路线图
```
gantt
title SentinelAI Roadmap
dateFormat YYYY-MM
axisFormat %Y Q%q
section Short-term
Prompt drift detection :2025-10, 2026-01
Structured logging :2025-10, 2026-01
Alerting mechanisms :2025-11, 2026-02
section Mid-term
Feedback-driven calibration :2026-01, 2026-06
Model-specific monitoring :2026-02, 2026-06
CI pipeline integration :2026-03, 2026-07
Plagiarism detection :2026-03, 2026-08
section Long-term
Automated red-teaming :2026-07, 2027-01
Adaptive threshold learning :2026-07, 2027-03
Compliance reporting :2026-09, 2027-06
```
### 短期
- 改进 prompt 漂移检测
- 结构化日志和过滤
- 基础警报机制
### 中期
- 反馈驱动的风险校准
- 特定于模型的监控配置文件
- CI/评估流水线集成
- 抄袭和幻觉检测模块
### 长期
- 自动化红队挂钩
- 自适应阈值学习（自动基线化）
- 组织级安全仪表板
- 完整的合规报告（欧盟 AI 法案、SOC 2、ISO 42001）
更多细节请参见 `Docs/ROADMAP.md` 和 `Docs/FUTURE_SCOPE_OF_MVP.md`。
## 商业背景
### 竞争格局
| 工具 | Sentinel 填补的空白 |
|------|--------------------|
| **Langfuse** | 侧重于追踪/可观测性；缺乏实时风险评分或干预机制 |
| **Arize AI** | 强大但笨重/昂贵；对中型团队来说是大材小用 |
| **WhyLabs** | 数据漂移检测；非针对 LLM 输出，可解释性较弱 |
| **Guardrails AI** | 输入/输出验证，但严重依赖规则；缺乏统一的风险评分或代理层 |
SentinelAI 的定位：**可解释、轻量级、实时的风险评分，配以只需 3 行代码即可运行的 Python SDK**——而不仅仅是被动日志记录。
### 商业模式
- **免费版：** 自托管、开源、社区支持
- **专业版：** 托管云、仪表板、警报、设置历史
- **企业版：** SLA、SSO、审计日志、自定义数据保留、合规报告
### 当前阶段
具备核心检测流水线、FastAPI 后端、Python SDK（在 PyPI 上）和 React 仪表板的可用 MVP。部署在 Render + Vercel 上。正在寻找首批设计合作伙伴和开源早期采用者。
### 公司价值观
- **可解释性优先**——每个信号都应易于理解，而不仅仅是一个分数
- **设计轻量**——3 行 SDK 集成，无供应商锁定
- **工程师同理心**——由经历过切肤之痛的工程师打造
- **对局限性坦诚**——我们标记风险，但不保证安全
- **默认开放**——开源核心作为建立信任的机制
## 安全
- 通过 Clerk 进行身份验证（生产模式，`pk_live_*`），支持 GitHub 和 Google OAuth
- 每个工作区实行基于角色的访问控制（Viewer、Developer、Admin、Owner）
- SDK 请求使用 API 密钥验证（`sk_*` 密钥）
- 所有分析结果均记录在完整的、不可变的审计追踪中
- 通过哈希链验证审计日志的完整性
- 自托管模式下不存储任何客户数据
- 在生产部署中通过 Nginx 进行 SSL 终止
## 支持
- **仪表板：** [sentinelaihq.com](https://sentinelaihq.com)
- **GitHub Issues：** 错误报告和功能请求
- **电子邮件：** `support@sentinelai.dev`
*SentinelAI —— 让 AI 系统默认具备可观测性与安全性。*