KrrishR05/IncidentOS-AI
GitHub: KrrishR05/IncidentOS-AI
一款基于语义记忆的 AI 事件响应系统，通过检索历史故障、提供置信度评分和具体 Runbook 帮助运维团队快速定位和解决问题。
Stars: 0 | Forks: 0
# IncidentOS AI 🚨
一个由 AI 驱动的、基于记忆的事件管理系统，能够从每一个已解决的事件中学习。
基于 **FastAPI**、**Groq (llama-3.3-70b-versatile)**、**Hindsight Cloud memory** 和 **sentence-transformers** 构建。
## 功能说明
| 功能 | 详情 |
|---|---|
| **语义记忆** | 每一个事件都会被向量化（384维，`all-MiniLM-L6-v2`）并存储。Hindsight Cloud 是主要的记忆层；本地 JSON 是离线兜底方案。 |
| **AI 分析** | 当一个新事件到达时，LLM 会以“基于 X 个相似的过往事件，根本原因：……”开场，而不是输出通用内容。 |
| **置信度评分** | 0 个已解决的匹配 = 20%。1 个 = 60%。2 个及以上 = 85%+。 |
| **具体的 Runbook** | 包含精确命令、配置键和阈值的编号步骤，而不是模糊的建议。 |
| **去重** | 标题和描述完全匹配的事件将被拒绝；每个事件只会创建一条记录。 |
| **持久化** | 记忆在服务器重启后依然保留。Hindsight Cloud 会永久存储所有记录及其完整的元数据。 |
| **批量解决** | `bulk_resolve.py` 会根据故障类型对所有未解决的事件进行分类，并通过 `retain_batch()` 一次性将它们全部解决。 |
| **云端同步** | `sync_from_hindsight.py` 使用分页的 `list_memories()` 从 Hindsight 拉取所有内容，同时支持 8 位十六进制 ID 和 `INC0XXXXX` 数据集 ID。 |
## 快速开始
### 1. 克隆并创建虚拟环境
```
git clone https://github.com/KrrishR05/IncidentOS-AI.git
cd IncidentOS-AI
python -m venv venv
# Linux / macOS
source venv/bin/activate
# Windows
venv\Scripts\activate
```
### 2. 安装依赖
**Linux / macOS / Windows (仅限 CPU):**
```
pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install -r requirements.txt
```
**支持 GPU:**
```
pip install -r requirements.txt # torch auto-detects CUDA
```
### 3. 配置环境
在项目根目录创建一个 `.env` 文件：
```
GROQ_API_KEY=gsk_your_groq_api_key_here
HINDSIGHT_API_KEY=hsk_your_hindsight_api_key_here
```
获取你的密钥：
- **Groq**: https://console.groq.com
- **Hindsight**: https://hindsight.vectorize.io
### 4. 运行服务器
```
uvicorn main:app --host 0.0.0.0 --port 8000
```
服务器在 `http://localhost:8000` 启动。在启动时，它会自动从 Hindsight Cloud 同步所有记录。
## API Endpoints
### `POST /incident/new`
提交一个新事件以进行 AI 分析。
```
curl -X POST http://localhost:8000/incident/new \
-H "Content-Type: application/json" \
-d '{"title":"DB connection exhaustion","description":"API latency spiked, database connections maxed out"}'
```
**响应包含：**
- `incident_id` — 唯一 ID（新事件为 8 位十六进制，数据集事件为 `INC0XXXXX`）
- `ai_analysis` — 包含置信度评分和 runbook 的 SRE 风格分析
- `similar_past_incidents` — 语义最相似的前 3 个过往事件
- `suggested_actions` — 4 个具体的、已确定优先级的 runbook 步骤
### `POST /incident/resolve`
将事件标记为已解决，并附带根本原因和缓解措施。
```
curl -X POST http://localhost:8000/incident/resolve \
-H "Content-Type: application/json" \
-d '{
"incident_id": "4e6a6f1b",
"root_cause": "connection pool exhaustion",
"mitigation_steps": "increased pool size, added timeout config, restarted pods"
}'
```
### `GET /incidents/all`
返回内存中的所有事件，以及总数/已解决/未解决的数量统计。
```
curl http://localhost:8000/incidents/all | python3 -m json.tool
```
### `GET /incident/{id}`
根据 ID 获取单个事件。
```
curl http://localhost:8000/incident/4e6a6f1b
```
### `GET /status`
针对后端、Groq LLM 和 Hindsight Cloud 连接状态的健康检查。
```
curl http://localhost:8000/status
```
### `POST /sync`
触发手动云同步（从 Hindsight 拉取最新数据，合并到本地 JSON 中）。
```
curl -X POST http://localhost:8000/sync
```
### `POST /deduplicate`
对本地内存执行语义去重扫描（合并高度相似的事件）。
```
curl -X POST http://localhost:8000/deduplicate
```
## 实用脚本
| 脚本 | 用途 |
|---|---|
| `sync_from_hindsight.py` | 使用分页的 `list_memories()` 将所有记录从 Hindsight Cloud 拉取到本地内存 |
| `check_hindsight.py` | 审计本地内存：显示所有事件、已解决/未解决计数、向量统计信息以及实时的 recall ping |
| `debug_hindsight.py` | 逐步的 Hindsight 诊断——检查原始 recall 响应结构、元数据字段以及对 `retain()` 的支持情况 |
| `bulk_resolve.py` | 将所有未解决的事件按故障类别分类并批量解决；通过 `retain_batch()` 推送到 Hindsight |
```
# 将 Hindsight 中的新记录合并到本地内存
python sync_from_hindsight.py
# 完全替换（清除本地 JSON，完全从 Hindsight 重建）
python sync_from_hindsight.py --replace
# 审计本地内存中的内容 + 实时 cloud check
python check_hindsight.py
# 深度 Hindsight recall 诊断
python debug_hindsight.py
# Dry-run：显示 bulk_resolve 将执行的操作
python bulk_resolve.py
# 实际解析所有未解决的 incident 并推送到 Hindsight
python bulk_resolve.py --commit
```
## 架构
```
HTTP Client
│
▼
FastAPI (main.py)
├── POST /incident/new ──► memory.store_incident()
│ memory.find_similar_incidents() ◄─ Hindsight recall()
│ agent.analyze_incident() ◄─ Groq LLM (llama-3.3-70b)
│ agent.suggest_actions()
│
├── POST /incident/resolve ──► memory.resolve_incident()
│ Hindsight retain() (updated metadata: root_cause, status)
│
├── GET /incident/{id} ──► memory.get_incident_by_id()
├── POST /sync ──► memory.sync_from_hindsight_cloud()
└── POST /deduplicate ──► memory.deduplicate_incidents()
Memory Layer (memory.py)
Primary: Hindsight Cloud — retain() / recall() / list_memories() / retain_batch()
Secondary: incident_memory.json — local JSON fallback, embedding cache, truth store
Embeddings: sentence-transformers/all-MiniLM-L6-v2 (384-dim)
Dedup: Exact ID match + semantic cosine similarity (threshold 0.97)
LLM (agent.py)
Model: llama-3.3-70b-versatile (via Groq API)
Persona: SRE on-call engineer — no filler phrases, confidence-scored output
Prompts: prompts.py
```
## 同步策略
`memory.py` 中的 `sync_from_hindsight_cloud()` 会在服务器启动时和收到 `POST /sync` 请求时运行：
1. **`list_memories()`** — 分页批量拉取所有 Hindsight 条目（最多 4500+）
2. **Recall 扫描** — 执行 30 个宽泛的查询，以呈现被列表遗漏的包含丰富元数据的记录
3. **ID 提取** — 通过正则表达式同时支持 `[0-9a-f]{8}` 十六进制 ID 和 `INC\d+` 数据集 ID
4. **合并** — 已解决状态优先于未解决状态；永远不会用未解决的记录覆盖已解决的记录
5. **去重** — 精确的 ID 匹配会消除重复项；语义扫描会合并高度相似的标题
## 批量解决
`bulk_resolve.py` 会将未解决的事件分类到 13 个故障类别中：
| 类别 | 事件数 |
|---|---|
| 负载均衡器配置错误 | 257 |
| 第三方 API 中断 | 138 |
| 缓存集群故障 | 138 |
| 数据库连接池耗尽 | 81 |
| 部署失败 / 回归 | 73 |
| DNS 解析失败 | 69 |
| CPU 饱和 | 65 |
| 内存泄漏 (OOM) | 63 |
| SSL/TLS 证书过期 | 57 |
| 磁盘空间耗尽 | 32 |
| 数据库性能下降 | 11 |
| 延迟 / 超时 | 1 |
每个类别都会获得一个真实的 `root_cause` + `mitigation_steps`。所有已解决的记录都会以 50 个为一批，通过 `retain_batch()` 推送到 Hindsight。
**当前状态：1,019 / 1,019 个事件已解决 (100%)，全部已同步至 Hindsight。**
## 演示测试序列
```
# 1. 检查内存是否已加载
curl http://localhost:8000/incidents/all | python3 -c \
"import json,sys; d=json.load(sys.stdin); print(f'Total: {d[\"total\"]} Resolved: {d[\"resolved\"]}')"
# 2. 提交具有强历史记录的 incident（置信度 85%+）
curl -X POST http://localhost:8000/incident/new \
-H "Content-Type: application/json" \
-d '{"title":"Database connections rising","description":"DB connections spiking, API latency climbing"}'
# 3. 解析该 incident
curl -X POST http://localhost:8000/incident/resolve \
-H "Content-Type: application/json" \
-d '{"incident_id":"","root_cause":"connection pool exhaustion","mitigation_steps":"increased pool size"}'
# 4. 手动触发 cloud sync
curl -X POST http://localhost:8000/sync
# 5. 检查健康状态
curl http://localhost:8000/status
```
## License
MIT
标签：AI智能体, IT运维, Socks5代理, 事件管理, 凭据扫描, 根因分析, 语义检索, 逆向工具