使用说明
KPI镜头
一个由人工智能驱动的供应链智能平台，监控8个运营关键绩效指标， 使用一组统计检测器检测异常，并解释根本原因 通过Claude——所有这些都可以通过Streamlit仪表板、FastAPI和MCP服务器访问。
供应链团队花费数小时手动查看KPI仪表板并编写异常报告。
KPI Lens自动化了整个循环：摄取→ 检测→ 解释→ 报告。
一个 docker compose up 为您提供实时异常馈送，LLM生成的根本原因叙述，
一键式Excel/PPT导出，为SteerCo做好准备。
特性
- 8个供应链关键绩效指标 每周跟踪：OTIF、填充率、DFA、库存周转率、DIO、供应商DPPM、交付周期差异、PO周期时间
- 集成异常检测：Z-score+IQR+CUSUM+带加权投票的隔离林探测器
- LLM根本原因分析：Claude为每个异常情况生成叙述性解释和建议行动
- FastAPI后端 具有10多个端点，用于KPI数据、异常管理和LLM聊天
- 流线型仪表板 共5页：指挥中心、KPI深潜、异常日志、LLM分析师、报告
- MCP服务器 用于Claude Desktop集成——通过对话方式查询实时KPI数据
- 自动摄取：带有Pydantic v2验证和APScheduler cron的CSV/Excel文件监视器
- 报告生成：用于SteerCo演示文稿的Excel工作簿和PowerPoint演示文稿
- 80%+测试覆盖率 跨单元和集成测试；CI在Python 3.11+3.12上运行
快速开始
Docker Compose（推荐）
git clone https://github.com/aliivaezii/kpi-lens.git
cd kpi-lens
cp .env.example .env # Add your ANTHROPIC_API_KEY
docker compose up -d api dashboard
# Seed 2 years of synthetic KPI data (first run only)
docker compose run --rm api python scripts/seed_database.py
# Open the dashboard
open http://localhost:8501
本地开发
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env # Add your ANTHROPIC_API_KEY
# Seed the database
python data/seeds/generate_kpis.py
# Start services (three terminals)
uvicorn kpi_lens.api.main:app --reload --port 8000
streamlit run kpi_lens/dashboard/app.py
python -m kpi_lens.mcp_server.server # optional: MCP for Claude Desktop
建筑
┌─────────────────────────────────────────────────────────────┐
│ External Sources (CSV/Excel exports from ERP) │
└──────────────────────────┬──────────────────────────────────┘
│ ingestion/loader.py + validator.py
▼
┌─────────────────────────────────────────────────────────────┐
│ SQLite DB ←── db/repository.py (only DB gateway) │
└──────┬────────────────────────────────────────────────────┬─┘
│ │
▼ ▼
┌─────────────────────┐ ┌──────────────────────────┐
│ anomaly/ensemble │ AnomalyResult │ api/ (FastAPI) │
│ ┣ threshold │ ────────────────► │ dashboard/ (Streamlit) │
│ ┣ zscore/iqr/cusum │ │ mcp_server/ (FastMCP) │
│ ┗ isolation forest │ └──────────────────────────┘
└─────────┬───────────┘
│ async (non-blocking)
▼
┌─────────────────────────────────────────────────────────────┐
│ llm/analyst.py → Claude via Anthropic SDK │
│ Generates narrative + recommended actions per anomaly │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ reporting/ → Excel workbook + PowerPoint deck │
└─────────────────────────────────────────────────────────────┘
KPI参考
| KPI | 单位 | 方向 | 绿色阈值 | 行业基准 |
|---|---|---|---|---|
| OTIF交付率 | % | 越高越好 | 95% | 95.5% |
| 订单完成率 | % | 越高越好 | 97% | 96% |
| 需求预测准确率 | % | 越高越好 | 85% | 80% |
| 库存周转率 | 周转率/年 | 越高越好 | 12 | 10 |
| 未清库存天数 | 天数 | 越低越好 | 30 | 35 |
| 供应商DPPM | ppm | 越低越好 | 500 | 800 |
| 交付周期差异 | 天数 | 越短越好 | 3 | 5 |
| 订单周期时间 | 天 | 越短越好 | 14 | 18 |
API 参考
| 方法 | 端点 | 描述 |
|---|---|---|
| 得到 | /api/health |
健康检查 |
| 得到 | /api/kpis/snapshot |
所有8个KPI的最新值+运行状况 |
| 得到 | /api/kpis/{name}/series |
一个KPI的时间序列数据 |
| 得到 | /api/kpis/{name}/entities |
实体（供应商）明细 |
| 得到 | /api/kpis/{name}/benchmarks |
行业基准百分位数 |
| 得到 | /api/anomalies |
最近使用严重性过滤器的异常 |
| 职位 | /api/anomalies/{id}/acknowledge |
确认异常 |
| 职位 | /api/llm/chat |
与供应链分析师聊天 |
| 职位 | /api/reports/enqueue |
排队提交异常报告 |
交互式文档： http://localhost:8000/api/docs
项目结构
kpi_lens/
├── db/ # repository.py — the only DB gateway; schema.py — ORM models
├── kpis/ # definitions.py — 8 KPI constants; snapshot.py — enrichment
├── anomaly/ # base.py, threshold, statistical, ml, ensemble detectors
├── llm/ # client.py (retry), analyst.py, context_builder.py, prompts.py
├── ingestion/ # loader.py, validator.py (Pydantic v2), scheduler.py (APScheduler)
├── reporting/ # excel_exporter.py, powerpoint.py, pdf_converter.py
├── api/ # FastAPI app + routes (kpis, anomalies, llm, reports, health)
├── dashboard/ # Streamlit app + 5 pages
└── mcp_server/ # FastMCP tools for Claude Desktop
config/ # kpis.yaml, anomaly.yaml, report.yaml (change without redeploy)
scripts/ # seed_database.py, run_anomaly_scan.py
tests/
├── unit/ # 8 test files, 70+ tests, no I/O
└── integration/ # FastAPI test client, in-memory DB, mocked LLM
运行测试
# Unit tests (fast, no infrastructure needed)
pytest tests/unit/ -v --cov=kpi_lens --cov-fail-under=80
# Integration tests (FastAPI + in-memory DB)
pytest tests/integration/ -v
# All tests
pytest tests/ -v --cov=kpi_lens --cov-fail-under=80
种子数据
# Default: 104 weeks (2 years) of synthetic data for all 8 KPIs
python scripts/seed_database.py
# Custom parameters
python scripts/seed_database.py --weeks 52
# Run anomaly detection on seeded data
python scripts/run_anomaly_scan.py
部署
渲染（完整堆栈-API+仪表板）
点击 在渲染上部署 上面或创建一个 Web Service 指向这个回购。
渲染读取 render.yaml 自动。集 ANTHROPIC_API_KEY 在环境中
部署前打开变量面板。
Streamlit社区云（仅仪表板）
- 分叉此回购
- 首选 share.streamlit.io → 新应用程序
- 集 主文件路径:
kpi_lens/dashboard/app.py - 在...之下 高级设置→ 秘密，添加：
ANTHROPIC_API_KEY = "sk-ant-..." DATABASE_URL = "sqlite:///kpi_lens.db" - 部署——Streamlit在第一次运行时为演示数据库添加种子
Docker Compose（自托管）
git clone https://github.com/aliivaezii/kpi-lens.git
cd kpi-lens
cp .env.example .env # add ANTHROPIC_API_KEY
docker compose up -d api dashboard
docker compose run --rm api python scripts/seed_database.py
open http://localhost:8501
数据
该平台配备了一个逼真的 合成数据集 由...生成 data/seeds/generate_kpis.py:
- 104周×8个关键绩效指标×5个供应商实体=4160条周记录
- 具有季节性、趋势性和已知日期故意异常注入的加性模型
- 设计用于锻炼所有四种探测器类型（阈值、Z分数、IQR、CUSUM）
要使用自己的数据，请将CSV放入 data/imports/ 并运行摄取调度器，
或直接POST到 POST /api/ingest格式参考： data/samples/sample_kpi_data.csv.
许可证
麻省理工学院——见 许可证.