Stage 1 的冻结 CLIP 头让基因嵌入与文本嵌入落到同一 512 维球面上。本指南演示双向检索： 文字 → 细胞群、细胞群 → 描述。底层为 cosine 相似度，可解释、可复现。
训练时，相同细胞的基因表达与文本描述被作为正例拉近；不同细胞或随机配对被推开。 推理时，编码任意一端的查询，与索引库做内积排序——这就是检索。LayerNorm + L2 normalize 已写死，所有相似度都在 [-1, 1]。
下面这台模拟检索器使用了五个真实查询的预计算结果。你可以打字编辑后回车——为了展示稳定性， 每次返回都从 50,000 个 held-out 细胞中选 top-10。
两端都对齐到同一球面，所以方向只决定你写什么作为 query。
绿色横条 = 检索到 top-10；橙色 = 同细胞类型的真值正例（仅供评估对照）。直方图是 50,000 候选的相似度分布。
同一查询，跑在你本机上：
# build the index once python scripts/export_stage2_embeddings.py \ --ckpt save/best_model_stage1_5.pt \ --input data/heldout_50k.h5ad \ --output_dir index/heldout/ # text → gene retrieval python custom_tools/retrieve_text2gene.py \ --index index/heldout/ \ --query "exhausted CD8 T cell, tumor microenvironment, tonsil" \ --topk 10
| --temperature | 0.07 (frozen) · 训练后冻结，建议不动 更小的 τ 会让排名更尖锐但不增加 R@k |
|---|---|
| --topk | 10 默认 · 取值 1–100 |
| --metric | cosine (默认) · dotL2 已 normalize，二者等价 |
| --rerank | off (默认) · 可选 mrl-512→64 二阶段 rerank，仅在 ≥ 1M index 时有意义 |
| --filter | obs.tissue / obs.disease 过滤 在 index 阶段先按元数据子集化，比检索后过滤快 |
不能。Text 塔为 PubMedBERT (英文医学语料)；中文 query 会落入对齐空间外的稀疏区域，R@1 接近随机。请把 query 翻成英文再检索。
top-1 cosine ≥ 0.55 通常对应正确 cell-type；0.40–0.55 之间需要人工审阅；< 0.40 视为「没匹配」。这是 50K 候选的经验门槛，规模不同需重新校准。
把若干细胞的 e_cell 平均后归一化，与一个候选文本短语库做内积；建议候选库提前编码缓存。常见短语库见 custom_tools/text_phrase_bank.json。