# SPCAlertAgent

**Repository Path**: openquality/spc-alert-agent

## Basic Information

- **Project Name**: SPCAlertAgent
- **Description**: 基于 DeepSeek、SPC 与 WM-811K 的晶圆质量趋势预警智能体，支持实时数据接入、规则判异、AI解释、告警闭环与多种部署方式。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-11
- **Last Updated**: 2026-08-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DeepSeek + SPC 质量趋势预警智能体

这是一个可直接运行、可审计的实时质量哨兵，支持使用WM-811K（LSWMD）晶圆图驱动SPC趋势预警和DeepSeek质量分析。

Gitee仓库：<https://gitee.com/openquality/spc-alert-agent>

GitHub仓库：<https://github.com/OpenQuality/spc-alert-agent>

- SPC 规则引擎负责判断数据是否异常。
- DeepSeek负责趋势解释、根因候选和处置建议；无密钥或调用失败时自动使用本地解释器。
- 停机、Hold Lot、修改 Recipe 等高风险操作必须由人工确认。

## 界面预览

### SPC控制图演示

控制图实时输出测量值及中心线（CL）、控制限（UCL/LCL）和规格限（USL/LSL），并用红色标记超规格点、橙色标记超控制限点。右上角可切换不同设备、指标、产品和检测模式的数据流，页面每5秒自动刷新。

![SPC控制图实时趋势与越限点演示](docs/images/spc-control-chart-demo.png)

### 智能告警仪表板

仪表板集中展示告警等级、设备与指标、晶圆模式、SPC规则、近期趋势、分析来源、根因候选和处置建议。

![DeepSeek SPC质量趋势预警仪表板](docs/images/dashboard-overview.png)

### SPC告警分析明细

同一数据流可以同时触发多条SPC规则。系统保留各规则的触发证据，并将相同活动告警合并累计。

![SPC规则告警与AI分析明细](docs/images/alert-details.png)

## SPC智能体流程图

系统在SPC确定性判异后分为两条路径：控制图持续展示全部测量数据、控制限和规格限；异常数据进入DeepSeek解释与质量吹哨流程，最终由人工完成质量闭环。

![DeepSeek SPC晶圆质量趋势预警智能体流程图](docs/images/spc-agent-flow.png)

## 版本状态

| 项目 | 当前状态 |
|---|---|
| 版本 | `0.3.0` |
| 更新日期 | 2026-08-11 |
| 数据集 | WM-811K（LSWMD） |
| SPC规则 | R1～R6 |
| AI分析 | DeepSeek，失败时本地降级 |
| 自动化测试 | 17项全部通过 |
| 当前定位 | WM-811K历史数据实时回放与SPC预警验证 |

> WM-811K没有真实采集时间和设备编号，因此当前属于按顺序模拟实时数据流。生产环境的真正实时运行需要继续对接实际Wafer AOI、MES或主机接口。

## 1. 项目位置

项目位于：

```text
E:\SPCAlertAgent
```

主要目录：

```text
E:\SPCAlertAgent
├─ data\
│  └─ LSWMD.pkl         WM-811K完整晶圆图数据（约2.10GB）
├─ spc_agent\
│  ├─ api.py            HTTP接口与实时仪表板
│  ├─ rules.py          SPC规则引擎
│  ├─ analyzer.py       DeepSeek与本地降级分析器
│  ├─ wm811k.py         LSWMD校验、特征提取和实时回放器
│  ├─ service.py        告警业务及状态流转
│  └─ storage.py        SQLite存储
├─ tests\              17项自动化测试
├─ docs\images\        README界面预览与SPC流程图
├─ deploy\             systemd与Nginx生产部署模板
├─ Dockerfile          容器镜像定义
├─ compose.yaml        Docker Compose部署编排
├─ .env.example        环境变量示例（不含密钥）
├─ pyproject.toml       项目信息
├─ README.md            使用说明
└─ spc_agent.db         运行后生成的 SQLite 数据库
```

## 2. 已实现功能

- 接收 AOI、MES 或主机上传的测量数据。
- 支持 R1～R6 SPC 判异规则。
- 分别判断控制限和规格限。
- 按设备、产品、Recipe、明场/暗场划分数据流。
- 相同活动告警自动合并并累计发生次数。
- 支持告警确认、调查、恢复、关闭和误报处理。
- 关闭告警时强制填写处置结论。
- 保存完整告警审计记录。
- 根据实际触发证据生成中文解释和处置建议。
- 支持DeepSeek JSON结构化分析、结果校验、超时和安全降级。
- 展示最近测量值、趋势方向、分析来源、置信度和可能原因。
- 输出可切换数据流的SPC控制图，显示测量值、CL/UCL/LCL、USL/LSL及越限点。
- 服务重启后从SQLite恢复最近SPC趋势窗口。
- 支持真实 `LSWMD.pkl` 的完整性校验、内存预检和逐片实时回放。
- 从晶圆图提取良率、缺陷率、中心/中环/边缘缺陷率和缺陷重心。
- 使用 `None` 类晶圆的缺陷率中位数和MAD建立稳健SPC基线。
- 核心服务使用Python和SQLite；WM-811K处理使用NumPy和pandas。
- 提供 HTTP API 和浏览器演示页面。

## 3. 运行环境

要求：

- Windows 10/11或主流Linux发行版。
- Python 3.11或更高版本；也可以使用Docker 24及Docker Compose v2。
- NumPy 1.26或更高版本。
- pandas 2.0或更高版本。

检查 Python 版本：

```powershell
python --version
```

如果 `python` 命令不可用，请安装 Python 3.11 或更高版本，并将其加入系统 `PATH`；使用 Anaconda 时，请先激活相应环境。

建议使用独立虚拟环境安装项目及数据处理依赖。

Windows PowerShell：

```powershell
cd E:\SPCAlertAgent
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .
```

Linux：

```bash
cd /opt/spc-alert-agent
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
```

## 4. 配置DeepSeek

DeepSeek分析是可选功能。未配置API密钥时，SPC规则和本地解释仍可正常运行。

不要将API密钥写入源码、README或提交到Git。仅在启动服务的PowerShell会话中设置：

```powershell
$env:DEEPSEEK_API_KEY = "替换为自己的API密钥"
$env:DEEPSEEK_MODEL = "deepseek-v4-flash"
$env:DEEPSEEK_ENABLED = "true"
```

可选配置：

| 环境变量 | 默认值 | 说明 |
|---|---|---|
| `DEEPSEEK_API_KEY` | 空 | DeepSeek API密钥；为空时使用本地模式 |
| `DEEPSEEK_MODEL` | `deepseek-v4-flash` | 分析模型 |
| `DEEPSEEK_BASE_URL` | `https://api.deepseek.com` | API服务地址 |
| `DEEPSEEK_TIMEOUT` | `12` | 请求超时秒数 |
| `DEEPSEEK_ENABLED` | `auto` | `auto`、`true`或`false` |

模型只负责解释已经由SPC规则确定的告警，不能取消告警，也不能自动执行停机、Hold Lot或修改Recipe。

## 5. 启动服务

### 启动命令

必须先进入项目目录，否则会出现 `No module named 'spc_agent'`：

```powershell
cd E:\SPCAlertAgent
python -m spc_agent.api --host 127.0.0.1 --port 8080
```

启动成功后会显示：

```text
SPC alert agent listening on http://127.0.0.1:8080
```

保持终端窗口运行，然后访问：

```text
http://127.0.0.1:8080/dashboard
```

点击页面中的“注入演示趋势”可以生成演示告警。页面顶部会显示当前为`deepseek`或`local_fallback`模式。

仪表板顶部的“SPC控制图”会每5秒自动刷新。可通过右上角数据流下拉框切换设备、指标、产品和检测模式；橙色点表示越过控制限，红色点表示越过规格限。

停止服务时，在运行终端中按 `Ctrl+C`。

## 6. 接入自己的数据

数据接收接口：

```http
POST /api/v1/measurements
Content-Type: application/json
```

PowerShell 示例：

```powershell
$body = @{
    metric_code           = "defect_density"
    value                 = 18.6
    equipment_id          = "AOI-01"
    event_time            = "2026-08-08T14:30:00+08:00"
    product_id            = "PRODUCT-A"
    lot_id                = "LOT-10086"
    wafer_id              = "W12"
    recipe_id             = "RCP-008"
    inspection_mode       = "darkfield"
    unit                  = "count/cm2"
    cl                    = 6.8
    ucl                   = 12.4
    lcl                   = 1.2
    usl                   = 16.0
    lsl                   = 0.0
    sigma                 = 1.87
    control_limit_version = "CL-V3"
} | ConvertTo-Json

Invoke-RestMethod `
    -Method Post `
    -Uri "http://127.0.0.1:8080/api/v1/measurements" `
    -ContentType "application/json" `
    -Body $body
```

提交数据后刷新仪表板。如果数据触发 SPC 规则，页面会显示相应预警。

### 字段说明

| 字段 | 必填 | 说明 |
|---|---|---|
| `metric_code` | 是 | 指标编码，例如 `defect_density` |
| `value` | 是 | 当前测量值 |
| `equipment_id` | 是 | 设备编号 |
| `event_time` | 是 | ISO 8601 格式的测量时间 |
| `product_id` | 否 | 产品编号 |
| `lot_id` | 否 | 批次编号 |
| `wafer_id` | 否 | 晶圆编号 |
| `recipe_id` | 否 | Recipe 编号 |
| `inspection_mode` | 否 | 例如 `brightfield` 或 `darkfield` |
| `unit` | 否 | 指标单位 |
| `cl` | 建议 | 中心线 |
| `ucl`、`lcl` | 建议 | 控制上限、控制下限 |
| `usl`、`lsl` | 建议 | 规格上限、规格下限 |
| `sigma` | 建议 | 标准差，区域和趋势规则使用 |
| `control_limit_version` | 建议 | 控制限版本号 |

## 7. 使用WM-811K（LSWMD）数据

当前数据文件：

```text
E:\SPCAlertAgent\data\LSWMD.pkl
```

文件信息：

```text
大小：2,095,505,977字节（约2.10GB）
SHA-256：1D04FCCB3DD3176B276878B926B20FEAD7E077C5751E4D353EA9741A5E7B5C65
```

该校验值与公开WM-811K文件一致。Pickle文件反序列化时可能执行代码，只能加载来源可信并且校验通过的文件。

### 数据如何进入质量哨兵

系统按以下过程处理每张晶圆图：

```text
LSWMD.pkl
  → 校验SHA-256和可用内存
  → 解析waferMap、lotName、waferIndex和failureType
  → 计算缺陷率、良率、分区缺陷率和缺陷重心
  → 使用None类样本建立稳健控制限
  → 按晶圆顺序调用 /api/v1/measurements
  → SPC判异
  → DeepSeek趋势解释和质量吹哨
```

WM-811K没有真实采集时间和设备编号，因此回放器会生成顺序时间戳，并默认使用设备编号`WM811K-REPLAY-01`。这些字段仅用于仿真实时流，不能当成真实生产时间或设备信息。

### 启动实时回放

先在第一个PowerShell终端启动SPC服务。然后在第二个终端执行：

```powershell
cd E:\SPCAlertAgent

python -m spc_agent.wm811k `
  --source "E:\SPCAlertAgent\data\LSWMD.pkl" `
  --baseline-size 1000 `
  --limit 100 `
  --delay 0.2
```

参数说明：

| 参数 | 默认值 | 说明 |
|---|---|---|
| `--source` | `E:\SPCAlertAgent\data\LSWMD.pkl` | Pickle数据文件 |
| `--baseline-size` | `1000` | 用于建立控制限的`None`类样本数 |
| `--limit` | `100` | 本次回放晶圆数；`0`代表全部 |
| `--start` | `0` | 跳过前N个有效样本 |
| `--delay` | `0.1` | 每片晶圆的回放间隔秒数 |
| `--equipment-id` | `WM811K-REPLAY-01` | 仿真设备编号 |
| `--include-unlabeled` | 关闭 | 是否包含未标注晶圆 |
| `--dry-run` | 关闭 | 只预览，不上传到SPC服务 |

建议先使用`--limit 100`验证，再逐步扩大。DeepSeek开启时，触发告警会产生API调用和相应费用。

### 内存保护

`LSWMD.pkl`必须整体反序列化。回放器在加载前要求约6GB可用内存；内存不足时会主动停止，避免系统失去响应。

当前机器检查时可用内存约2.7～4GB，因此未强行加载完整数据集。关闭大型程序、浏览器和多余开发工具，确保可用内存达到要求后再运行。`--allow-low-memory`可以绕过检查，但可能导致系统卡死，不建议使用。

## 8. SPC 规则

| 规则 | 判断条件 | 默认级别 |
|---|---|---|
| R1 | 单点超过 UCL 或低于 LCL | 严重 |
| R2 | 连续 3 点中有 2 点超过中心线同侧 2σ | 严重 |
| R3 | 连续 5 点中有 4 点超过中心线同侧 1σ | 一般 |
| R4 | 连续 8 点位于中心线同一侧 | 一般 |
| R5 | 连续 6 点持续上升或下降 | 一般 |
| R6 | 测量值超过 USL 或低于 LSL | 紧急 |

## 9. 告警状态

正常告警闭环：

```text
new → acknowledged → investigating → recovered → closed
```

告警也可以在确认后标记为 `false_positive`（误报）。关闭告警或标记误报时必须填写处置结论。

状态更新请求示例：

```http
POST /api/v1/alerts/{alert_id}/transition
Content-Type: application/json
```

```json
{
  "status": "acknowledged",
  "actor": "operator-01",
  "resolution": ""
}
```

## 10. API 列表

| 方法 | 路径 | 用途 |
|---|---|---|
| GET | `/health` | 服务健康检查 |
| GET | `/dashboard` | 浏览器仪表板 |
| GET | `/api/v1/system/status` | 查询DeepSeek模式、模型和规则状态 |
| GET | `/api/v1/streams` | 查询已经接入的测量数据流 |
| GET | `/api/v1/control-chart?stream_key=...` | 输出控制图点位、控制限、规格限和越限标记 |
| GET | `/api/v1/trends?stream_key=...` | 查询指定数据流的最近测量值 |
| POST | `/api/v1/measurements` | 上报数据并执行 SPC 判异 |
| GET | `/api/v1/alerts` | 查询告警，支持 `status` 和 `limit` 参数 |
| GET | `/api/v1/alerts/{id}` | 查询单个告警 |
| GET | `/api/v1/alerts/{id}/audit` | 查询告警审计记录 |
| POST | `/api/v1/alerts/{id}/transition` | 更新告警状态 |

## 11. 运行测试

```powershell
cd E:\SPCAlertAgent
python -m unittest discover -s tests -v
```

预期结果：

```text
Ran 17 tests
OK
```

## 12. 部署指南

### 12.1 部署前检查

1. 服务器时间和时区必须正确，生产环境建议统一使用NTP。
2. 不要把真实的`DEEPSEEK_API_KEY`、`.env`、SQLite数据库或`LSWMD.pkl`提交到Git。
3. 生产服务必须使用独立数据库目录，并为该目录配置定期备份。
4. 只在可信网络直接暴露8080端口；跨网络访问时应在前面部署HTTPS反向代理、身份认证和访问控制。
5. WM-811K只用于离线验证或回放，不需要放入API服务容器。生产测量数据应由AOI、MES或主机调用接口上传。

### 12.2 Windows本机部署

```powershell
git clone https://gitee.com/openquality/spc-alert-agent.git E:\SPCAlertAgent
cd E:\SPCAlertAgent
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .

$env:SPC_HOST = "0.0.0.0"
$env:SPC_PORT = "8080"
$env:SPC_DB = "E:\SPCAlertAgent\runtime\spc_agent.db"
$env:DEEPSEEK_API_KEY = "替换为自己的API密钥"
$env:DEEPSEEK_ENABLED = "true"

New-Item -ItemType Directory -Force E:\SPCAlertAgent\runtime | Out-Null
python -m spc_agent.api
```

验证：

```powershell
Invoke-RestMethod http://127.0.0.1:8080/health
```

若需要开机长期运行，可使用Windows任务计划程序：触发器选择“计算机启动时”，程序填写`E:\SPCAlertAgent\.venv\Scripts\python.exe`，参数填写`-m spc_agent.api`，起始位置填写`E:\SPCAlertAgent`。API密钥应配置在运行账号的安全环境或凭据系统中，不要写进任务参数。

### 12.3 Docker Compose部署（推荐）

```bash
git clone https://gitee.com/openquality/spc-alert-agent.git spc-alert-agent
cd spc-alert-agent
mkdir -p runtime

# 可选：只在当前终端设置，不要提交真实密钥
export DEEPSEEK_API_KEY="替换为自己的API密钥"
export DEEPSEEK_ENABLED="true"

docker compose up -d --build
docker compose ps
curl http://127.0.0.1:8080/health
```

常用维护命令：

```bash
docker compose logs -f --tail=200
docker compose restart
docker compose down
```

SQLite数据保存在宿主机`runtime/spc_agent.db`，重新构建容器不会丢失。修改对外端口时设置`SPC_PUBLISH_PORT`，例如`SPC_PUBLISH_PORT=18080 docker compose up -d`。

### 12.4 Linux systemd部署

以下命令以Debian/Ubuntu为例，执行前请按公司规范调整账号、目录和防火墙：

```bash
sudo useradd --system --home /opt/spc-alert-agent --shell /usr/sbin/nologin spc-agent
sudo mkdir -p /opt/spc-alert-agent /var/lib/spc-alert-agent
sudo chown -R spc-agent:spc-agent /opt/spc-alert-agent /var/lib/spc-alert-agent

sudo -u spc-agent git clone https://gitee.com/openquality/spc-alert-agent.git /opt/spc-alert-agent
sudo -u spc-agent python3.11 -m venv /opt/spc-alert-agent/.venv
sudo -u spc-agent /opt/spc-alert-agent/.venv/bin/python -m pip install -e /opt/spc-alert-agent

sudo cp /opt/spc-alert-agent/deploy/spc-alert-agent.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now spc-alert-agent
sudo systemctl status spc-alert-agent
curl http://127.0.0.1:8080/health
```

DeepSeek配置写入`/etc/spc-alert-agent.env`，并限制读取权限：

```bash
sudo install -m 600 /dev/null /etc/spc-alert-agent.env
sudoedit /etc/spc-alert-agent.env
sudo systemctl restart spc-alert-agent
```

文件内容示例：

```dotenv
DEEPSEEK_API_KEY=替换为自己的API密钥
DEEPSEEK_MODEL=deepseek-v4-flash
DEEPSEEK_ENABLED=true
```

查看日志：

```bash
journalctl -u spc-alert-agent -f -n 200
```

### 12.5 Nginx与HTTPS

复制`deploy/nginx-spc-alert-agent.conf`到Nginx站点目录，替换其中的`spc.example.com`，启用配置并申请HTTPS证书。生产环境建议只让服务监听`127.0.0.1:8080`，由Nginx对外提供443端口。

```bash
sudo cp deploy/nginx-spc-alert-agent.conf /etc/nginx/sites-available/spc-alert-agent
sudo ln -s /etc/nginx/sites-available/spc-alert-agent /etc/nginx/sites-enabled/spc-alert-agent
sudo nginx -t
sudo systemctl reload nginx
```

Nginx模板只提供反向代理。上线前还必须按企业要求增加TLS证书、统一身份认证、IP白名单或VPN，不应把当前无登录保护的仪表板直接暴露到互联网。

### 12.6 数据集部署与回放

`data/LSWMD.pkl`约2.10GB，已被`.gitignore`和`.dockerignore`排除，不会上传到GitHub、Gitee或API服务镜像。需要回放时，由使用者单独获取可信数据文件，校验SHA-256后放入项目`data`目录，再按第7节运行回放命令。

### 12.7 备份、升级与回滚

停止写入后备份SQLite数据库，避免复制过程中产生不一致文件：

```bash
sudo systemctl stop spc-alert-agent
sudo cp /var/lib/spc-alert-agent/spc_agent.db /var/backups/spc_agent-$(date +%F-%H%M%S).db
sudo systemctl start spc-alert-agent
```

升级前先备份数据库并记录当前提交号，然后拉取、测试、安装和重启：

```bash
cd /opt/spc-alert-agent
git rev-parse HEAD
git pull --ff-only
.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python -m pip install -e .
sudo systemctl restart spc-alert-agent
curl http://127.0.0.1:8080/health
```

若验证失败，切回升级前记录的Git提交、恢复对应数据库备份并重启服务。生产变更应通过审批和维护窗口执行。

### 12.8 上线验收清单

- `/health`返回`status: ok`，仪表板可访问。
- `/api/v1/system/status`显示预期模型和分析模式。
- 使用一条正常数据和一组越限数据验证入库、告警、审计和状态闭环。
- 重启服务后历史告警与趋势窗口仍可查询。
- DeepSeek不可用时能够自动降级，且日志和响应不泄露API密钥。
- 数据库备份能够恢复；主机磁盘、内存、端口、日志和服务状态已接入监控。

## 13. 常见问题

### 页面显示`local_fallback`

说明未设置API密钥，或者DeepSeek调用失败。先检查环境变量：

```powershell
if ($env:DEEPSEEK_API_KEY) { "API密钥已设置" } else { "API密钥未设置" }
```

设置环境变量后需要重启服务。系统不会把API密钥写入数据库或告警内容。

### `No module named 'spc_agent'`

原因是没有进入项目目录。执行：

```powershell
cd E:\SPCAlertAgent
python -m spc_agent.api --host 127.0.0.1 --port 8080
```

### 浏览器显示“无法访问此站点”

确认启动服务的终端仍然打开，然后检查：

```powershell
Invoke-RestMethod http://127.0.0.1:8080/health
```

如果终端已关闭，需要重新启动服务。

### 8080 端口被占用

改用 8081：

```powershell
cd E:\SPCAlertAgent
python -m spc_agent.api --host 127.0.0.1 --port 8081
```

然后访问：

```text
http://127.0.0.1:8081/dashboard
```

### Git 提示 `dubious ownership`

```powershell
git config --global --add safe.directory "E:/SPCAlertAgent"
```

### WM-811K提示可用内存不足

这是安全保护，不是文件错误。关闭其他占用内存的程序后重试。不要在可用内存低于6GB时使用`--allow-low-memory`强行加载2.1GB Pickle。

## 14. 生产接入前需要完善

1. 将控制限迁移到经过审批、带版本的配置表或数据库。
2. 接入企业身份认证、角色权限、HTTPS 和操作审计。
3. 根据客户标准确认 Western Electric 或 Nelson 规则。
4. 增加 MES、AOI、主机协议适配器及断线重试机制。
5. 接入设备记录、Recipe 变更、维护记录和 SOP 知识库。
6. 使用真实历史数据进行影子运行，评估误报率和漏报率。
7. 大模型只用于解释、归因和建议，不得绕过规则引擎执行高风险动作。