HarshSharma0007/AegisLogic

🛡️ AegisLogic (PCRA)
持久化认知检索架构

一个**本地优先、零云依赖**的 AI 检索系统，结合了三个并发的数据轨道 —— 时间会话历史（SQLite）、因果图遍历（KuzuDB）和语义向量搜索（Qdrant）—— 通过 **Reciprocal Rank Fusion (RRF)** 进行融合，并由在 Apple Silicon 硬件上本地运行的 **Llama 3.1 8B** 模型提供支持。 专为**网络威胁情报（CTI）**领域而构建 —— 该垂直领域需要对违规时间线有严格的时间感知，需要跨越 MITRE ATT&CK 关系进行多跳因果推理，并且在将威胁行为者归因于恶意软件和缓解措施时具有零幻觉容忍度。 ## 架构概述 ``` ┌─────────────────────────┐ │ User Query Input │ └────────────┬────────────┘ │ ┌────────────▼────────────┐ │ Query Planner / Router │ └────────────┬────────────┘ │ ┌──────────────────────────┼──────────────────────────┐ ▼ ▼ ▼ ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐ │ Hindsight Track │ │ KAG Track │ │ RAG Track │ │ (SQLite History) │ │ (KuzuDB Graph) │ │ (Qdrant Vectors) │ └─────────┬───────────┘ └─────────┬───────────┘ └─────────┬───────────┘ │ │ │ └──────────────────────┬─┘──────────────────────────┘ │ asyncio.gather (parallel) ┌────────▼────────────┐ │ RRF Fusion Engine │ └────────┬────────────┘ │ ┌────────▼────────────┐ │ Context Compression │ └────────┬────────────┘ │ ┌────────▼────────────┐ │ Llama 3.1 (Ollama) │ └────────┬────────────┘ │ ┌────────▼────────────┐ │ Grounded Response │ └─────────────────────┘ ``` ## 你需要安装的内容（在你的 MacBook M4 上） | 组件 | 运行位置 | 安装方式 | 原因 | |-----------|---------------|----------------|-----| | **Docker Desktop** | 主机 (macOS) | [下载](https://www.docker.com/products/docker-desktop/) | 运行 Qdrant + Python 应用容器 | | **Ollama** | 主机 (macOS) | `brew install ollama` | 必须在主机上运行以利用 M4 神经引擎 / GPU 加速 —— Docker 无法访问 Apple 的 ANE | | **Git** | 主机 (macOS) | macOS 预装 | 版本控制 | **其他所有内容都在 Docker 中运行** —— 你无需直接在 Mac 上安装 Python、pip 包、KuzuDB、Qdrant 或 sentence-transformers。 ### 内存预算（16 GB 统一内存） | 子系统 | 分配 | 技术 | |-----------|------------|------------| | macOS 系统 | ~3.50 GB | Apple Silicon 统一内存 | | Ollama LLM | ~4.80 GB | Llama 3.1 8B Q4_K_M（4 位量化） | | KuzuDB 图数据库 | ~200 MB | 进程内列式存储（在 Docker 内） | | Qdrant 向量 | ~150 MB | Docker 容器 | | SQLite 索引 | ~50 MB | 磁盘备份（在 Docker 内） | | Python + LangGraph | ~300 MB | Docker 容器 | | **可用余量** | **~6.97 GB** | 操作系统分页缓冲 | ## 项目结构 ``` PCRA/ ├── src/ # Application source code │ ├── __init__.py │ ├── main.py # CLI entry point — runs the full pipeline │ ├── config.py # Environment config (Ollama, Qdrant, paths) │ ├── state.py # AgentState TypedDict + QueryIntent Pydantic schema │ ├── entity_resolver.py # RapidFuzz fuzzy entity normalization │ ├── graph.py # LangGraph state machine assembly │ ├── workers/ # Async retrieval workers (one per data track) │ │ ├── __init__.py │ │ ├── hindsight.py # Track A — SQLite temporal session history │ │ ├── kag.py # Track B — KuzuDB Cypher graph traversal │ │ └── rag.py # Track C — Qdrant semantic vector search │ └── nodes/ # LangGraph pipeline nodes │ ├── __init__.py │ ├── retrieval.py # Parallel retrieval orchestrator (asyncio.gather) │ ├── fusion.py # Reciprocal Rank Fusion (RRF) scoring │ ├── compression.py # Context compression (regex boilerplate stripping) │ └── generation.py # LLM generation via Ollama (Llama 3.1) ├── data/ # Runtime data stores │ ├── knowledge_base/ # MITRE ATT&CK PDFs and threat intelligence reports for RAG ingestion │ ├── graph_schema/ # KuzuDB schema + seed data │ │ └── seed.cypher # Cypher seed script (threat actors, malware, mitigations) │ └── sessions/ # SQLite DB file (created at runtime) ├── eval/ # Evaluation framework │ ├── evaluation_dataset.json # Cybersecurity test queries (RAGAS harness) │ ├── run_ragas_groq.py # RAGAS evaluation runner (Groq 70B judge) │ ├── debug_relevancy.py # AnswerRelevancy diagnostic probe │ ├── check_noncommittal.py # Noncommittal classifier debug script │ ├── ragas_report_groq.json # Full evaluation results (70B) │ ├── ragas_noncommittal_penalty.md # 📄 Technical write-up: metric design flaw │ └── run_ragas.py # Legacy evaluation runner ├── Dockerfile # Multi-stage Python build (slim, non-root) ├── docker-compose.yml # 2 services: aegis-app + qdrant ├── .dockerignore # Excludes .git, docs, node_modules from build ├── .env.example # Environment variable template ├── .gitignore # Python, Docker, data, IDE exclusions ├── requirements.txt # Pinned Python dependencies ├── report.md # Full system engineering specification └── README.md # ← You are here ``` ## 快速开始 ### 1. 前置条件 ``` # 安装 Ollama（在你的 Mac 主机上运行以实现 M4 GPU 加速） brew install ollama # 拉取量化的 Llama 3.1 模型（约 4.8 GB 下载，一次性） ollama pull llama3.1:8b-instruct-q4_K_M # 验证 Ollama 是否正在运行 ollama list ``` ### 2. 克隆与配置 ``` git clone https://github.com/HarshSharma0007/PCRA.git cd PCRA # 创建你的本地环境 config cp .env.example .env ``` ### 3. 使用 Docker 启动 ``` # 构建并启动所有服务（Qdrant + AegisLogic 应用） docker compose up --build # 或者在 detached 模式下运行 docker compose up --build -d ``` ### 4. 运行查询 ``` # 通过 Docker docker exec -it aegis-app python -m src.main "Which courses of action mitigate the attack pattern used by the Lazarus Group?" # 或者在本地运行（如果你已安装 Python 3.11+） pip install -r requirements.txt python -m src.main "What tools does APT29 use for spearphishing, and are there any recent VCDB incidents involving phishing?" ``` ### 5. 运行评估 ``` docker exec -it aegis-app python -m eval.run_ragas_groq ``` ## 评估亮点 该系统使用 [RAGAS](https://docs.ragas.io/) 框架进行评估，并将 **Llama 3.1 8B**（本地）和 **Llama 3.3 70B**（Groq API）同时作为 LLM 评估器。 | 指标 | 8B 评估器 | 70B 评估器 | 备注 | |--------|----------|-----------|-------| | **Faithfulness** | 0.750 | **1.000** ✅ | 完美的基准依托 —— 零幻觉 | | **Answer Relevancy** | 0.647 | 0.486 ⚠️ | 受到不明确惩罚的影响（见下文） | | **Context Recall** | 0.625 | 0.750 | 随着评估器能力增强而提升 | ### 🔍 关键发现：RAGAS 的“不明确惩罚” 在评估期间，尽管有两个查询具有完美的 Faithfulness，但它们的 Answer Relevancy 得分却正好是 `0.000`。针对源代码级别的调查显示，RAGAS 的 `AnswerRelevancy` 评分器中存在一个**硬编码的二元惩罚**，当 LLM 包含诸如 *"我找不到关于...的具体信息"* 之类的诚实免责声明时，该惩罚会将得分清零。 根本原因被追踪到 RAGAS 源代码中的这一行： ``` score = cosine_sim.mean() * int(not all_noncommittal) ``` ## 研究基础 此架构基于 7 篇经过同行评审的 AI 论文： | # | 论文 | 会议/出版物 | 用于 | |---|-------|-------|----------| | 1 | [用于知识密集型 NLP 任务的 RAG](https://arxiv.org/abs/2005.11401) | NeurIPS 2020 | 核心检索增强生成范式 | | 2 | [Sufficient Context](https://arxiv.org/abs/2411.06037) | ICLR 2025 | 上下文不足时的引导性弃权 | | 3 | [KAG：知识增强生成](https://arxiv.org/abs/2409.13731) | Ant Group 2024 | 基于图的知识增强层 | | 4 | [Speculative RAG](https://arxiv.org/abs/2407.08223) | arXiv 2024 | 并行的起草-验证检索架构 | | 5 | [Agentic RAG 综述](https://arxiv.org/abs/2501.09136) | arXiv 2026 | 多循环智能体执行模式 | | 6 | [Hindsight Memory](https://arxiv.org/abs/2512.12818) | arXiv 2025 | 结构化智能体记忆（保留、回忆、反思） | | 7 | [AgentHER](https://arxiv.org/abs/2603.21357) | arXiv 2026 | 用于轨迹学习的后见经验回放 | ## 技术栈 | 层 | 技术 | 作用 | |-------|-----------|------| | 编排 | LangGraph + asyncio | 状态机 + 并行异步扇出 | | LLM 推理 | Ollama + Llama 3.1 8B Q4_K_M | 在 M4 硬件上进行本地生成 | | 向量存储 | Qdrant (Docker) | 语义相似度搜索 | | 图数据库 | KuzuDB（嵌入式） | 因果/关系路径遍历 | | 关系型存储 | SQLite | 时间会话历史 | | Embeddings | all-MiniLM-L6-v2 | 384 维本地句子嵌入 | | 实体解析 | RapidFuzz | 与规范形式的模糊匹配 | | 评估 | RAGAS | Faithfulness + Context Recall 指标 | | 容器化 | Docker + Docker Compose | 可重现的部署 | ## 已知局限性 - 实体规范化依赖于静态的规范列表（未来：从 KuzuDB 节点自动填充） - RRF 对所有三个轨道同等对待（未来：可学习的轨道权重） - 没有 TLP（Traffic Light Protocol）分类层（建议用于真实的 CTI 部署） - Hindsight Critic 节点已在架构上定义，但尚未作为条件 LangGraph 边缘连接 ## 许可证 MIT

标签：AI风险缓解, LangGraph, 人工智能, 威胁情报, 开发者工具, 本地部署, 检索增强生成, 用户模式Hook绕过, 网络安全, 请求拦截, 逆向工具, 隐私保护