kevinmeix1/sherlockml

# SherlockML SherlockML 是一个确定性的、离线优先的笔记本电脑演示，用于展示多 agent ML 可靠性调查。它将合成的欺诈模型事件转化为可审计的工程案例：agent 收集证据、辩论相互冲突的原因、推荐处理方案、运行恢复实验，并生成案例报告。 它故意被设计为**不是聊天机器人**。主要的交互方式是一个调查控制室：选择一个事件，并观察一个受约束、可重复的工作流如何产生证据和建议。 ## 问题所在 机器学习系统可能会悄无声息地发生故障。当数据分布发生偏移、特征转换发生改变，或新的训练配置导致质量倒退时，模型可能仍在继续提供预测服务。当警报到达人类手中时，证据可能已经分散在指标、数据样本、代码和部署信号中。 ## 解决方案：SherlockML 方法 SherlockML 针对合成数据上演示了该事件响应循环的精简版本： 1. 从健康的欺诈模型基线开始。 2. 触发确定性事件：数据漂移、特征流水线 bug 或模型回归场景。 3. 通过 LangGraph supervisor 编排专家 agent。 4. 收集证据、对嫌疑对象进行排序，并记录一次“作战室”(War Room) 讨论。 5. 对合成的流水线契约应用受控修复，并保留可审查的 diff/配置产出物。 6. 根据显式的验证关卡比较基线和候选结果。 7. 保存恢复报告和产出物以供审查。 该演示从不使用客户数据、不调用托管模型、不部署模型，也不对远程仓库执行操作。其受控的本地流水线契约修复以 diff 产出物的形式展示。它被设计为在面试或黑客马拉松环境中可以安全地进行检查、重复和讨论。 ## 演示内容 | 领域 | 评委可以看到的内容 | | --- | --- | | 模型健康状况 | 基线欺诈模型评分、事件严重程度和证据时间线 | | 事件模拟器 | 可重现的合成漂移、流水线 bug 和回归场景 | | 多 Agent 大脑 | 侦探、统计学家、基础设施、主持人、医生、工程师和实验等角色 | | 作战室 (War Room) | 存储的、与证据关联的辩论，而不是不透明的单一答案 | | 恢复 | 受控的本地流水线契约修复、diff、候选实验、关卡和报告 | | 仪表盘 | 由 FastAPI API 支持的 Streamlit 控制室 | 确切的指标值是根据所选的合成场景和 seed 生成的。它们是**演示观察结果**，而不是关于已部署欺诈模型的声明。 ## 架构 ``` flowchart TD U["Engineer or judge"] --> UI["Streamlit Control Room :8502"] UI --> API["FastAPI Investigation API :8788"] API --> SIM["Deterministic Incident Simulator"] SIM --> SUP{"LangGraph Supervisor"} SUP --> DET["Detective\ncollect evidence"] SUP --> STAT["Statistician\nmeasure drift and data health"] SUP --> INFRA["Infra\ninspect latency and service signals"] DET --> WAR["War Room Moderator\nrecord disagreement and consensus"] STAT --> WAR INFRA --> WAR WAR --> DOC["Doctor\nwrite diagnosis and treatment"] DOC --> ENG["Engineer\nprepare bounded remediation"] ENG --> EXP["Experiment Agent\ntrain and compare candidate"] EXP --> VAL{"Validation gates"} VAL --> REP["Recovery report and local artifacts"] VAL -. "not approved" .-> WAR ``` 请参阅[架构指南](docs/ARCHITECTURE.md)了解数据流、agent 职责和安全边界。 ## 快速开始 要求：Python 3.10+ 和一个虚拟环境。Docker 是可选的。 ``` cd /Users/kaiwenmei/Desktop/SherlockML python3 -m venv .venv source .venv/bin/activate make install ``` 在单独的终端中，运行 API 和控制室： ``` make run-api make run-ui ``` 在 打开 Streamlit 仪表盘。API 可在 访问，当服务器运行时，交互式 API 文档位于 。 在演示前验证项目： ``` make check ``` ### 本地 API 快速参考 | 方法 | 路径 | 目的 | | --- | --- | --- | | GET | /health | 检查本地服务是否存活。 | | GET | /api/incidents | 列出确定性的演示场景。 | | POST | /api/incidents/{incident_type}/investigate | 运行一次有边界的调查。 | | POST | /api/reset | 恢复合成的流水线契约基线。 | 支持的事件类型包括 data_drift、pipeline_bug 和 model_regression。 仪表盘还接受易于理解的 feature_pipeline_bug 别名。这些仅是本地演示操作。 ## 演示：五个步骤 1. 打开仪表盘并建立健康的基线。 2. 触发诸如 **Data Drift** 的场景。 3. 选择 **Investigate Incident** 并观察证据时间线和作战室逐渐填充。 4. 检查提议的补救措施和候选实验比较。 5. 阅读审批决定和生成的恢复报告。 [演示脚本](docs/DEMO_SCRIPT.md) 包含面向评委的简明叙述和一次恢复演练。 ## 项目布局 ``` SherlockML/ ├── agents/ # Specialist investigation roles and LangGraph orchestration ├── api/ # FastAPI application and investigation interface ├── dashboard/ # Streamlit control room ├── ml/ # Training, evaluation, prediction, and drift utilities ├── simulator/ # Deterministic synthetic incident generators ├── experiments/ # Optional scratch space; runtime records live under artifacts/ ├── models/ # Generated local model artifacts ├── artifacts/ # Case reports and evidence snapshots ├── runtime/ # Ephemeral local state ├── tests/ # Deterministic test suite └── docs/ # Architecture, runbook, study material, and demo guidance ``` ## 使用 Docker 运行（可选） 默认的 Compose 命令仅运行 API： ``` docker compose up --build ``` 仪表盘位于一个显式配置文件之后，以便评委可以仅在需要时选择它： ``` docker compose --profile dashboard up --build ``` 这是本地容器打包，不是生产部署。Compose 将生成的产出物写入本地的 `artifacts/` 和 `runtime/` 文件夹。 ## 诚实界定范围的可选集成 - **MLflow：** 仅限本地 SQLite 支持的实验跟踪。笔记本电脑演示不使用 MLflow 服务器或远程产出物存储；便携式案例产出物仍然是规范的演示证据，并在跟踪不可用时作为后备。 - **Git：** 受控的本地修复始终会生成 diff 证据。可以启用可选的本地提交，但演示绝不需要凭据、推送分支或声称部署修复。 - **Docker：** 用于 FastAPI 服务和仪表盘的可选可重现打包。它不是 Kubernetes、CI/CD 或生产运行时。 [实现矩阵](docs/IMPLEMENTATION_MATRIX.md) 区分了可在本地运行的内容与可选及仅限设计路径的内容。 ## 学习和面试用途 SherlockML 有意设计得足够紧凑，以便能够端到端地理解。从 [学习指南](docs/STUDY_GUIDE.md) 开始，然后使用 [操作手册](docs/RUNBOOK.md) 排练正常路径和故障/恢复演练。 ## 安全性和可重现性 - 所有输入数据均为生成的合成类欺诈数据。 - 固定的 seed 使默认场景可重复。 - 除非操作员明确选择其他路径，否则产出物将保留在笔记本电脑上。 - 修复仅应用于合成的本地流水线契约。验证决定是供审查的工程建议，而不是生产发布。 ## 许可和范围 本仓库是一个技术演示和面试学习项目。它不是欺诈决策系统、生产监控平台，也不能替代安全、合规、模型风险或人工审批流程。

标签：Apex, Kubernetes, LangGraph, MLOps, 可靠性测试, 大模型智能体, 机器学习, 模块化设计, 自动化修复, 请求拦截, 逆向工具