本指南展示在不微调的情况下，使用 Stage 1.5 检查点对任意 scRNA-seq AnnData 文件进行细胞身份嵌入与零样本类型注释。
所有步骤都使用仓库中的 inference.py，无需重写脚本。
LingoCell 期望接收一份标准的 .h5ad，行 = 细胞，列 = 基因。
基因名采用 GRCh38 HGNC 符号；可以是原始计数 (raw)、归一化后 (normalized)、log1p 之任意状态——
推理脚本会用启发式检测自动接上预处理流水线。
| obj | AnnDatascanpy ≥ 1.9 |
|---|---|
| X | (n_cells, n_genes) · sparse 或 denseint32 counts 或 float32 normalized |
| var_names | HGNC gene symbols 未匹配的基因将被零填充；匹配率建议 ≥ 60% |
| obs (optional) | cell_type, tissue, donor仅用于评估，不参与推理 |
| varm (optional) | pos_encoding, chr_encoding提供则启用，缺失自动跳过 |
| 不允许 | 含 NaN / Inf 的 X · 基因数 < 200 · cell count > 200K（请分批） |
下面的演示在浏览器里模拟实际推理过程：选取一个公开数据集 → 预处理 →
调用 Stage 1.5 → 得到 e_cell 与类型概率。返回的数据是从真实运行结果中截取的样本。
三份不同尺度的公开数据，挑一个就好。生产环境下你也可以用 --input your.h5ad 上传任意文件。
实时显示推理进度，每个阶段对应仓库 inference.py 的真实函数调用。
推理完成后右侧的数据张量与左侧的 UMAP 可视化会同步更新。下表展示按 cosine 相似度匹配到的 top-5 细胞类型。
| type | prob | n_cells |
|---|
# Stage 1.5 zero-shot inference python scripts/inference.py \ --ckpt save/best_model_stage1_5.pt \ --input "data/HCA_colon_health.h5ad" \ --output_dir "out/colon/" \ --batch_size 64 \ --fp16
下表是 inference.py 暴露给用户的真实参数，按对结果影响从大到小排列。
如果只是想拿到 embedding，默认设置就够了。
| --gene_mode | nonzero (默认) · 每细胞随机采样非零基因到 1200；fixed 使用 1200-HVG 列表，便于跨细胞对比改成 fixed 会让 UMAP 的局部结构略微变紧 |
|---|---|
| --n_bins | 51 (默认) · 与训练严格一致，不要改 如要改请同步重新训练 Stage 1 |
| --data_state | raw · normalized · log1p，对应数据起点。默认 raw + 启发式检测；如果你的 X 已 log1p，请显式传入避免重复 log |
| --batch_size | 64 (default) · 单 GPU；fp16 模式下 H100 可到 256 大 batch 不影响数值结果 |
| --topk | 5 · 输出概率最高的前 k 个细胞类型 取值 1–10 |
| --save_attn | false · 是否一并保存基因注意力矩阵 单细胞 ~ 8 MB，慎开 |
使用 scripts/gene_utils.py:map_to_hgnc() 进行别名映射；匹配率低于 60% 时脚本会给出警告并列出未匹配的前 100 个基因。匹配率高于 60% 一般不影响 top-1 结果。
这是预期行为。e_cell 仍然是有效嵌入；你可以用最近邻取 ground-truth 标签做评估，或者把这些细胞加入 fine-tune 数据。Stage 1.5 词表见 cell_type_code_mapping.json。
常见原因：① X 已被你 normalize 但 --data_state 仍是 raw；② 基因匹配率过低；③ 细胞中位 UMI < 500，建议先做 Stage 1.5 推理而不是 Stage 1。
能，但 1 万细胞约需 15 分钟。--device cpu --fp32。建议仅用于小型测试。