YuchenShen/FoMo-0D — Ascend NPU 适配推理

FoMo-0D 是一个零样本表格离群点检测 prior-fitted network（PFN，MIT 许可）。 本仓库在 Ascend 910 NPU（torch_npu） 上完成适配，提供统一 inference.py （CLI 单次推理 + FastAPI 服务），实测推理通过。

1. 模型与硬件

• 模型：YuchenShen/FoMo-0D（线性编码器 + 4 层 Transformer encoder， emsize=256 / nhead=4 / nhid=512 / num_R=500 路由 + 标准 2 类解码头）
• 输入：(train_x, test_x) 上下文帧，输出 (num_test, 1, 2) 两类 logits
• 参数量：4,886,786
• 权重来源：HuggingFace YuchenShen/FoMo-0D（经 hf-mirror.com 镜像下载）
• 模型类代码：官方仓 github.com/A-Chicharito-S/FoMo-0D 固定 commit 34d4339e318d96ac744850188a547b62387a718c，随本仓 vendored 于 src/ （fomo_hub.py + pfns 包），导入前逐文件 SHA-256 校验（fail-closed）。
• 设备：npu:0（Ascend910，torch_npu 2.9.0.post1，PyTorch 2.9.0）

2. 环境依赖

pip install -r requirements.txt

依赖：torch、torch_npu、safetensors、huggingface_hub、einops、 numpy、fastapi、uvicorn、python-multipart。

3. 权重缓存

首次启动会自动从镜像下载权重到本地缓存目录：

./model_weights/YuchenShen__FoMo-0D/
├── config.json
├── model.safetensors
└── README.md

启动时优先加载本地缓存（命中即跳过下载），未命中才走 HF_ENDPOINT=https://hf-mirror.com 下载。

4. 输入契约（表格离群点检测）

模型是 PFN：给定一组上下文（正常/inlier）表格 train_x，对查询点 test_x 逐点输出「正常 / 离群」两类 logits 与离群概率。

CLI 用 --text（JSON），FastAPI POST /predict 收相同 JSON：

{
  "train_x": [
    [0.51, 0.48, 0.50],
    [0.49, 0.52, 0.47]
  ],
  "test_x": [
    [0.50, 0.50, 0.51],
    [0.05, 0.04, 0.06]
  ]
}

• train_x / test_x：二维数值数组（行 = 样本，列 = 特征），float。
• 特征数 d：d < 100 时自动缩放并零填充到 100；d > 100 时确定性截取前 100 列（模型特征预算为 100）。
• 上下文总量约束：train_x + test_x <= 5000 行（模型训练 seq_len=5000）。
• 预处理：默认按列 z-score 归一化（基于 train 上下文统计，无 test 泄漏）， 可用 --preprocess none 跳过。
• 输出：每行 {logits, probabilities, outlier_score, prediction}， outlier_score 为类别 1（离群）概率，>= 0.5 判为 outlier。

5. 用法

5.1 CLI 单次推理

python3 inference.py --text '{"train_x": [[0.5,0.5]], "test_x": [[0.05,0.06]]}'
# 或从文件读取
python3 inference.py --text @demo_input.json --device npu:0

stdout 输出一行 JSON（模型、设备、逐点结果、耗时等）。

5.2 FastAPI 服务

python3 inference.py --serve --port 8011
# 或
uvicorn inference:app --host 0.0.0.0 --port 8011

接口：

• GET /health → 服务状态
• POST /predict → body 为上述 JSON，返回推理结果 JSON

curl -X POST http://127.0.0.1:8011/predict \
  -H "Content-Type: application/json" \
  -d '{"train_x": [[0.5,0.5]], "test_x": [[0.05,0.06]]}'

6. 实测结果

CLI 与 FastAPI 均在 npu:0 实测通过：

• 64 个上下文样本 + 4 个查询点，10 维特征（自动填充到 100）
• 2 个近邻点判为 inlier（outlier_score ≈ 0.01），2 个远离聚类点判为 outlier（outlier_score = 1.0）
• 设备字段：device=npu:0、model_device=npu:0，NPU 名 Ascend910_9362
• 单次前向约 150 ms

7. 证据截图

• assets/agent_workflow.png — 环境部署、依赖、任务启动总日志
• assets/npu_device_call.png — CLI 推理成功 stdout（含 NPU 信息与结果）
• assets/model_result.png — FastAPI curl POST /predict 真实 HTTP 响应

8. 目录结构

├── inference.py          # 统一推理入口（CLI + FastAPI）
├── src/                  # vendored 官方模型类代码（fomo_hub.py + pfns/）
├── requirements.txt
├── model_weights/        # 权重缓存（自动下载，不入库）
├── assets/               # 证据截图
└── logs/                 # 运行日志

9. 说明

• 全部设备调用仅面向 npu:0（Ascend），无任何其它设备后端。
• src/ 为官方模型类代码逐字节拷贝（SHA-256 校验），inference.py 在导入前 注入 torch.nn.modules.transformer.Optional 兼容 shim（torch>=2.6 移除）。