ailab 服务状态: 检测中…
中文

ailab · v0.3.0

潮来潮去自成期，旧岁回看始自知。

未有明征休妄断，宁将一默胜虚辞。

ailab 是面向传染病监测的开源时间序列引擎。每个预测都必须在滚动回测中打败季节朴素基线；做不到，质量闸门会告诉你为什么不预测。

做一次预测 查看 GitHub

静态展示 · 页面不运行任何模型

服务状态: 检测中…

一个引擎，三种用法

Python 库

序列存储、派生序列、预测、质量闸门、告警信号，都是可直接调用的纯函数。缺失值是 NULL，绝不补 0。

命令行与离线批处理

ailab demo / forecast / gate / alert / export，可在 CI 里定期跑，把结果导出为静态 JSON 与 Parquet。

Docker API

FastAPI + 内嵌 DuckDB，无需 Postgres、Redis。非 root、只读根文件系统；未设置密钥时只读。

从周序列到可信的信号

每条序列都按同样的四步处理。每一步做完都会留下结论和原因，可以逐条核对。

  1. 整理数据

    按周排好，一周一个值。缺的周就记作缺失，不拿 0 去补，免得把“没上报”当成“没病例”。

  2. 质量闸门

    预测之前先体检：历史够不够长、缺得多不多、有没有季节规律，再拿过去的数据试着预测一遍，看准不准。结论只有三种：可以预测、有限制地预测、不预测，每种都写明原因。

  3. 预测

    几种常用方法和“照搬去年同一周”的简单做法比一比，选试算时误差最小的那个；连这个简单做法都比不过，就不预测。结果除了一条线，还给出实际值大概率会落进的范围。

  4. 异常提醒

    某周的数明显高于平常时给出提醒。它只说明“统计上不寻常”，是不是暴发，要由人来判断。

方法：现成库与自研部分

能用成熟库的地方都用成熟库；自研的部分只有成熟库没有覆盖的“决策逻辑”。

需求现成库自研（及原因）
预测模型statsforecast：SeasonalNaive、Naive、MSTL+ETS、AutoTheta、交叉验证无。
预测区间numpy 分位数约 30 行保形风格代码：直接复用已有回测误差，不额外重拟合；按步长、在变换空间内计算，并报告留一窗口覆盖率。
质量闸门statsmodels（STL、ADF/KPSS、HAC）、scipy（Levene）阈值、允许/受限/拒绝的决策逻辑、原因码与三语说明。没有现成工具回答“这条序列该不该预测”。
告警statsmodels GLMEARS C1–C3 与 CUSUM 只是几十行公式；成熟的 R surveillance 需要 R 运行时，所以 Farrington 风格评分基于 GLM 自行封装。
派生序列simpleeval、pandasAST 白名单、类型推断（计数/计数 → 比例）、缺失语义（x/0 为缺失）与血缘记录；禁止 eval。
存储、API、命令行DuckDB、Parquet、FastAPI、pydantic、uvicorn、Typer薄中间件（请求 ID、请求体上限）；无默认口令，未设密钥即只读。

依据与边界

主张实现 / 验证证据适用边界
预测必须在滚动回测中打败季节朴素基线 docs/MODEL_POLICY.md#decision-order-first-match-wins
tests/test_forecast_policy.py
tests/test_gate.py		 回测只说明过去几季的表现；结构突变后需重新评估。
历史太短或缺失太多时拒绝，并给出原因码 docs/MODEL_POLICY.md#reason-codes
tests/test_gate.py		 阈值是可配置的默认值；拒绝表示“这份数据不支持预测”，不代表序列没有价值。
缺失就是缺失，绝不补 0 docs/SERIES_KINDS.md
tests/test_alignment.py
tests/test_derive_kinds.py		 模型内部会对 ≤2 周的短缺口插补，并在 model_input 中披露。
“受限”与“拒绝”分开：缩短步长、放宽区间 docs/MODEL_POLICY.md#limited-mode
tests/test_gate.py		 放宽倍数是经验设定，不是校准保证。

快速开始

镜像发布在 GHCR；也可以用 pip / uv 安装并直接用命令行。

Docker（只读、仅本机）

docker run --rm -p 127.0.0.1:8000:8000 ghcr.io/cnalks/ailab:v0.3.0
# http://127.0.0.1:8000/docs  ·  /health

Python 与命令行

pip install "git+https://github.com/CNalks/ailab@v0.3.0"   # Python 3.12
ailab demo --out out                  # offline batch: static JSON + Parquet
ailab gate us_ilinet_wili --lang zh   # allowed / limited / refused + reasons
ailab forecast us_ilinet_wili --h 8

调用 API

curl -s http://127.0.0.1:8000/api/v1/series/us_ilinet_wili/gate
curl -s "http://127.0.0.1:8000/api/v1/series/us_ilinet_wili/forecast?horizon=8"

容器默认只读（未设置 AILAB_API_KEY 时写入返回 403）。公开暴露前请自行加反向代理与限流。

接口文档

许可与数据来源

代码

ailab 以 Apache-2.0 发布，版权 © CNalks（https://github.com/CNalks）。 github.com/CNalks · Apache-2.0

数据

数据不受代码许可覆盖，遵循各来源条款。原始数值未作修改；预测、判定与告警是我们自己的派生分析，并按来源要求标注。

CDC FluView / ILINet (national, weekly), via Delphi Epidata

US Centers for Disease Control and Prevention (CDC); API by Carnegie Mellon University Delphi Research Group

署名（按许可方要求保留英文原文）
Source: US CDC FluView (ILINet), retrieved through the Delphi Epidata API (Carnegie Mellon University).
声明
Forecasts and alerts shown here are our own statistical analysis of public data. They are not CDC/HHS products, are not endorsed by CDC/HHS, and are not public-health advice. The original data are available free of charge from CDC.
使用的序列
美国全国 ILI 加权比例（wILI，%） · 美国全国 ILI 门诊就诊数

UKHSA data dashboard: influenza testing positivity by week (England)

UK Health Security Agency (UKHSA)

署名（按许可方要求保留英文原文）
Contains public sector information published by the UK Health Security Agency (UKHSA) and licensed under the Open Government Licence v3.0.
声明
Forecasts and alerts shown here are our own statistical analysis of public data. They are not UKHSA products, are not endorsed by UKHSA and are not public-health advice.
使用的序列
英格兰流感检测阳性率（%）

ECDC ERVISS: primary-care sentinel respiratory virus data (weekly), Respiratory_viruses_weekly_data

European Centre for Disease Prevention and Control (ECDC), based on data from reporting countries and/or WHO

署名（按许可方要求保留英文原文）
Dataset provided by ECDC based on data provided by public health authorities, scientific institutes or health care providers in the relevant reporting countries and/or by WHO. Weekly values are unchanged; analysis added by us.
声明
Forecasts, quality gates and alerts shown here are our own statistical analysis (modified/derived material). They are not ECDC products and are not endorsed by ECDC.
使用的序列
欧盟/欧经区流感阳性率，哨点（%） · 马耳他流感检出数，哨点