LucaGroup/LucaCell-v1.0-step6.4M

LucaCell-v1.0

细胞基础模型：基因（LucaOne 核酸序列向量）+ 表达量分箱 → 40 层 Transformer 编码器。

主干	40 层 / 40 heads / hidden 2560 / FFN 10240 / RoPE / pre-LN
参数量	≈ 3.15 B（bf16 ≈ 6.3 GB）
基因表征	LucaGroup/LucaOne-step60M，float32，核酸右截断 10240，mean(last_hidden[:, 1:-1, :]) → 2560 维
细胞长度	1200 基因 + [E_CLS] + [E_SEP] = 1202
表达词表	6 特殊 token + 50 分箱 = 56
预训练任务	express_token_mask（MLM，mlm_probability = 0.5，80/10/10）
预测目标	[E_NON]（基因不表达）+ 全部表达分箱
关闭项	express_sorted embedding、gene_type embedding、nucleotide token encoder
Checkpoint dtype	bf16

表达值编码规范（务必遵守）

基因状态	写什么	id
不表达 / 零计数	"[E_NON]"	5
表达（50 档分箱，1-indexed）	"1" … "50"	6 … 55

⚠️ 不要用 "0" 表示不表达或最低档 —— 它不在词表里，会被映射成 [E_UNK]， 该位置将不参与 MLM、不进 loss，且输入一个几乎未训练的 embedding，且不报错。

• qcut_bins / feature_ids 列必须一一对应；非表达基因放在 zero_freature_ids 列 （collator 会自动把它们的表达值置为 [E_NON]）。
• 上手前先跑：python tools/check_bin_labels.py --model_dir <repo> --data_file <your.csv>， 「未命中词表比例」必须为 0。
• tokenizer 默认 unknown_bin_policy="error"，遇到未知标签直接抛异常（可改成 "warn"）。

dtype 规则

场景	模型	权重加载	计算精度	输出 dtype	关键参数
推理 / 抽 embedding	LucaCell	float32	bfloat16	float32(自动 cast)	--use_bf16
	LucaOne	float32	float32	float32	—
继续预训练	LucaCell	float32(master weights)	bfloat16(AMP)	—	torch_dtype=torch.float32 + --bf16
	LucaOne	float32	—	float32	离线冻结,不参与梯度更新

安装

pip install torch==2.5.1 torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu121
pip install -r requirements.txt

Meta 数据:

gene_positions.txt: the sorted index of all seqs.
express_vocab.txt: the vocab of the gene expression bins.

数据格式(gene 序列fasta文件 + 细胞CSV文件)

binned_logcpm.test.fa: fasta for seq embedding binned_logcpm.test.csv: the cell data, one record one cell, including: sample_id,sample_type,seq_ids(list), expression_bins

1) 用 LucaOne 预计算基因向量（Only Once）

python lucaone_embedding.py \
      --gene_fasta ./test_data/binned_logcpm.test.fa \
      --emb_dir ../emb/seq/mean_vector \
      --max_len 10240 \
      --pooling_type mean \
      --overwrite \
      --gpu_id 0 

2) cell embedding

python lucacell_embedding.py \
     --model_name_or_path LucaGroup/LucaCell-v1.0-step6.4M \
     --input_file ./test_data/binned_logcpm.test.csv \
     --max_gene_len 1202 \
     --save_path ../emb/cell/ \
     --gene_emb_dirs ../emb/seq/mean_vector \
     --embedding_type matrix  \
     --overwrite \
     --use_bf16 \
     --add_special_tokens \
     --attn_impl sdpa \
     --gpu_id 0