NitheshK4/Semantic-DebtMapper

# Semantic Debt Mapper (SDM) [](https://github.com/NitheshK4/Semantic-DebtMapper/actions/workflows/ci.yml) [](https://fastapi.tiangolo.com) [](https://react.dev) [](https://www.docker.com) **在遗留的 AI 语义假设导致下游决策发生静默失败之前，精准定位它们。** ### 什么是 Semantic Debt？ **Semantic debt（语义债务）** 代表了 schema 元素的*活跃语义*（修订后的策略、prompt 变更、更新后的标签定义）与*遗留校准*之间的隐藏不匹配，而下游业务逻辑、机器学习模型或人工干预阈值最初是基于这些遗留校准配置的。 SDM 是一个生产级的 AI 可靠性与治理平台，它通过接入您的 pipeline、模型和干预日志，来映射、标记并修复这些语义不一致问题。 ## 🏗️ 系统架构与数据流 SDM 将数据定义、分类模型、覆盖规则和 human-in-the-loop 决策链接到一个统一的依赖模型中： ``` graph TD %% Styling classDef source fill:#1e1b4b,stroke:#4f46e5,stroke-width:1px,color:#e0e7ff; classDef ingest fill:#18181b,stroke:#3f3f46,stroke-width:1px,color:#f4f4f5; classDef engine fill:#0c4a6e,stroke:#0284c7,stroke-width:1px,color:#e0f2fe; classDef detector fill:#1c1917,stroke:#d97706,stroke-width:1px,color:#fffbeb; classDef output fill:#064e3b,stroke:#059669,stroke-width:1px,color:#ecfdf5; %% Nodes A1["Label Definitions & Schemas"]:::source A2["Model Inferences & Predictions"]:::source A3["Business Rules & Thresholds"]:::source A4["Reviewer Overrides & Logs"]:::source B["Ingestion Engine (FastAPI)"]:::ingest C1["Semantic Lineage Builder"]:::engine C2["Scoring & Trend Engine"]:::engine subgraph Detectors ["Semantic Debt Detectors"] D1["Class Meaning Drift (CMD)"]:::detector D2["Embedding Space Fracture (ESF)"]:::detector D3["Rule-Model Conflict (RMC)"]:::detector D4["Human-Model Divergence (HMD)"]:::detector D5["Ghost Feature Misalignment (GFM)"]:::detector end E1["Interactive Lineage Graph"]:::output E2["Action Center & Remediation"]:::output E3["PDF Audit Reports"]:::output %% Connections A1 & A2 & A3 & A4 --> B B --> C1 & C2 C1 & C2 --> Detectors D1 & D2 & D3 & D4 & D5 --> E1 & E2 & E3 ``` ### 技术栈 * **后端：** Python FastAPI, SQLAlchemy ORM, SQLite（本地开发）/ PostgreSQL（使用 `pgvector` 的生产环境）。 * **检测器：** 基于 NumPy 的向量相似度计算、统计漂移分析和边界覆盖检测。 * **前端：** React 19, TypeScript, Vite, Vanilla CSS 自定义样式, React Flow（交互式血缘图），Recharts（趋势和数据分析）。 * **测试：** Pytest（数据接入、API endpoint 和检测器启发式算法）。 ## 🔍 核心检测器 SDM 使用 5 个专门的、确定性的检测器持续审计 ML pipeline： | 检测器 | 目标风险 | 机制 | 触发阈值 | | :--- | :--- | :--- | :--- | | **1. Class Meaning Drift (CMD)** | 发生偏移的 schema 定义包含了过时的遗留数据引用。 | 计算连续定义版本的 vector embedding 之间的 Cosine Similarity，并衡量审核者的 override 增量。 | 相似度 $< 0.92$ & override 增加 $> 10\%$ | | **2. Embedding Space Fracture (ESF)** | 更新后的模型 query vector 读取了遗留的 index。 | 将部署的模型几何结构与 vector DB 中的 index 版本 metadata 进行比较。 | Embedding 维度不匹配 / 标签差异 | | **3. Rule-Model Conflict (RMC)** | 基于遗留模型校准的陈旧规则/override 作用于新的分数分布上。 | 扫描指向旧模型标签的活跃规则，并衡量决策边界处的 override 率。 | 阈值范围内的 override 率 $> 20\%$ | | **4. Human-Model Divergence (HMD)** | 特定群体中的系统性预测失败。 | 同类群组分组比较对照全局 override 率；通过 NLP 提取失败模式。 | override 率 $> 20\%$ & 与基线的差值 $> 15\%$ | | **5. Ghost Feature Misalignment (GFM)** | 规则引用了陈旧或已删除的 schema 属性。 | 将活跃规则表达式的 AST/regex 模式与历史及当前模型特征进行扫描比对。 | 活跃规则使用了非活跃/重命名的特征 | ## 🛠️ 配置与安全 API endpoint 需要通过 `X-API-Key` HTTP header 传递 API Key。 ### 环境设置 在根目录下创建一个 `.env` 文件（或使用 `.env.example` 模板）： #### 后端 (`backend/.env`) ``` DATABASE_URL=sqlite:///./sdm.db API_KEY=your-secure-backend-api-key ``` #### 前端 (`frontend/.env`) ``` VITE_API_URL=http://localhost:8005/api/v1 VITE_API_KEY=your-secure-backend-api-key ``` ## 🚀 快速开始 ### 方式 1：使用 Docker Compose 运行（推荐） 启动 PostgreSQL、Redis、FastAPI 后端、Vite dev server 和 worker 容器： ``` docker compose up --build ``` * **Dashboard 界面：** `http://localhost:5173` * **API 文档 (Swagger)：** `http://localhost:8005/docs` ### 方式 2：在本地运行（开发模式） #### 1. 启动后端 API ``` cd backend python3 -m venv venv source venv/bin/activate pip install -r requirements.txt # 运行 migrations/setup export API_KEY=dev-key-123 export DATABASE_URL=sqlite:///./sdm.db python3 -m uvicorn app.main:app --port 8005 --reload ``` #### 2. 启动前端应用 ``` cd frontend npm install npm run dev ``` ## 🧪 验证与测试 ### 运行 Python 测试 我们维护了全面的单元测试和集成测试覆盖率： ``` cd backend export API_KEY=dev-key-123 export DATABASE_URL=sqlite:///./sdm.db PYTHONPATH=. pytest tests/ ``` ### 运行前端质量审计 验证 TypeScript 编译和 ESLint 合规性： ``` cd frontend npm run lint npm run build ``` ## 📈 交互式演示（Demo 数据集） 要直观查看 semantic debt： 1. 启动两个服务器。 2. 转到侧边栏的 **Ingestion Center**。 3. 点击 **"Load Support Ticket Demo"**。这将接入一个注入了 semantic drift（CMD, ESF, RMC, HMD, GFM）的模拟数据集。 4. 导航到 **Overview**、**Findings** 和 **Lineage Graph** 页面，检查计算出的指标并追踪语义失败。

标签：AI治理, AV绕过, Docker, FastAPI, React, Syscalls, 代码质量分析, 安全防御评估, 技术债务, 搜索引擎查询, 数据可靠性, 测试用例, 请求拦截, 逆向工具