atlasleong/tcrt5-ft-tcrdb-npu
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

TCRT5 (dkarthikeyan1/tcrt5_ft_tcrdb) · 昇腾 NPU 推理交付

dkarthikeyan1/tcrt5_ft_tcrdb 是一个在 TCRdb 微调得到的 TCRT5 条件生成模型,基于 T5ForConditionalGeneration 架构。本交付将其完整本地权重迁移到华为昇腾 NPU (torch_npu),在物理设备 npu:6(Ascend 910B4-1)上完成了一次端到端条件 T 细胞受体(CDR3β)序列生成推理,并给出完整的运行日志、结构化结果、校验和与截图。

任务清单(manifest.json)将该模型归入粗粒度任务类 protein-sequence-classification; 依据上游模型卡,该模型实际是一个 seq2seq 条件生成模型(给定 pMHC 生成 CDR3β 序列), 本交付按模型卡的真实任务执行。

项目值
模型 IDdkarthikeyan1/tcrt5_ft_tcrdb
上游 Licensecc-by-nc-sa-4.0
固定源码版本f559f8f7f1862d23f863b0d0d3b2f858cdab9705
架构T5ForConditionalGeneration,10 层,d_model 256,16 heads,d_ff 1024,vocab 128
权重精度torch.float32
推理引擎torch_npu 2.9.0(配套 torch==2.9.0+cpu)
执行设备npu:6(Ascend 910B4-1)
权重规模218 个张量 / 41,990,144 个参数 / model.safetensors 167,985,976 B

模型简介

TCRT5 是一个序列到序列(seq2seq)模型,用于给定目标肽-MHC(pMHC)复合物的条件下 条件生成 T 细胞受体(TCR)CDR3β 序列。它基于 T5 架构 以及 Hugging Face 的 T5ForConditionalGeneration 抽象实现,随论文 TCR-TRANSLATE(Nature Machine Intelligence 2025) 发布。

  • 预训练:对 TCRdb 约 1400 万条 TCR 序列做掩码跨度重建(span reconstruction),并配合 IEDB 的约 74 万条肽-伪序列对。
  • 微调:在 VDJdb / IEDB / McPAS 与 MIRA 半合成样本组成的约 33 万条 肽-伪序列 → CDR3β 的平行语料上,使用标准交叉熵损失训练。
  • 输入协议:[PMHC]<肽>[SEP]<MHC-I 伪序列>[EOS];输出为 [TCR]<CDR3β>[EOS]。

本交付直接使用完整的本地预训练检查点(单个 model.safetensors),在昇腾 NPU 上以 fp32 加载并完成束搜索(beam search)条件生成,未使用任何玩具/随机/子集权重。

环境依赖清单

本容器已预装匹配的 torch==2.9.0+cpu 与 torch_npu==2.9.0,不得用普通 PyPI 轮子替换。其它依赖一律从阿里云镜像安装:

export PIP_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/
python3 -m pip install -r requirements.txt

requirements.txt 内容(非 torch 依赖):

包版本说明
transformers4.40.1加载 T5ForConditionalGeneration / T5Tokenizer
sentencepiece0.2.2T5 tokenizer 运行依赖
protobuf7.35.1tokenizer 加载依赖
tokenizers0.19.1分词器加速
safetensors0.8.0权重文件加载
numpy1.26.4测试用例数值工具
Pillow10.4.0仅用于 scripts/render_assets.py 渲染截图

运行环境实测版本:Python 3.11.14、CANN npu-smi 25.5.1、8×Ascend 910B4-1。

分步推理操作流程

  1. 进入交付目录

    cd /work/pipeline/jobs/other40/tcrt5-ft-tcrdb/tcrt5-ft-tcrdb-npu
  2. (可选)创建并激活虚拟环境、安装依赖

    python3 -m venv --system-site-packages \
      /work/pipeline/runtime/venvs-tabular16/tcrt5-ft-tcrdb-npu
    export PIP_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/
    /work/pipeline/runtime/venvs-tabular16/tcrt5-ft-tcrdb-npu/bin/python \
      -m pip install -r requirements.txt

    容器已带匹配的 torch/torch_npu,虚拟环境继承系统包即可,不要重装 torch。

  3. 直接运行推理(含并发 npu-smi 采集)

    ./run_npu_inference.sh npu:6 25 3 3

    该脚本会:

    • 启动 inference.py(真实完整微调检查点,fp32,全模型 to(npu:6));
    • 以精确 Python PID 并发循环采集 npu-smi info;
    • 生成 logs/npu_inference.log、logs/npu_device_call.log、logs/npu_result.json。
  4. 单独运行推理

    /work/pipeline/runtime/venvs-tabular16/tcrt5-ft-tcrdb-npu/bin/python \
      inference.py \
      --model-dir /work/pipeline/models/other40/tcrt5-ft-tcrdb \
      --device npu:6 \
      --max-new-tokens 25 \
      --num-beams 3 \
      --num-return-sequences 3 \
      --output-json logs/npu_result.json

    参数说明:

    • --device npu:6:目标物理 NPU(脚本拒绝非 npu:6,NPU 不可用时非零退出)。
    • --max-new-tokens 25:生成新 token 数上限。
    • --num-beams 3:束搜索宽度;--num-return-sequences 3:返回序列条数。
    • --test-input:可选的 JSON 测试输入文件(含 pmhc 字段),默认使用内嵌的 模型卡示例。
  5. 失败即非零退出

    NPU 初始化、完整权重加载、严格 safetensors 键校验、输入放置、前向/生成或输出校验 任一步失败,脚本以非零退出码终止,绝不静默回退 CPU。

完整测试用例

测试输入为上游模型卡(pinned revision f559f8f7f1862d23f863b0d0d3b2f858cdab9705) 中记录的 pMHC 条件生成示例,按 TCRT5 输入协议逐字使用:

[PMHC]KLGGALQAK[SEP]YFAMYQENVAQTDVDTLYIIYRDYTWAELAYTWY[EOS]
  • 肽:KLGGALQAK(HLA-A*03:01 限制表位);
  • MHC-I 伪序列:YFAMYQENVAQTDVDTLYIIYRDYTWAELAYTWY(NetMHCpan 格式);
  • 输入 token 数:46。

该输入已写入 test_input.json(pmhc 字段),来源与许可信息记录于 test_input.json 与 logs/npu_result.json 的 test_input 字段。推理过程中不依赖 任何网络数据集。

输出结果

一次新鲜端到端推理(PID 3237743,npu:6)的实际结果:

指标值
退出码0
输入 token 数46
生成序列形状(3, 18)(decoder 侧,含 [SOS] 起始 token)
生成 token 形状(3, 17)
Logits 设备/形状npu:6 / (3, 128)
生成 CDR3β 序列CASSLGTGGTDTQYF、CASSPGTGGTDTQYF、CASSLGTGGSYEQYF
模型加载耗时2.67 s
拷贝至 NPU 耗时0.05 s
生成耗时1.01 s
总耗时5.31 s
NPU 显存占用(allocated)192,169,984 B(≈192 MB)
NPU 峰值显存(max allocated)212,346,368 B(≈212 MB)
NPU HBM 总量65,452,113,920 B(≈65.5 GB)

生成的 3 条 CDR3β 序列与模型卡 README 中针对同一 pMHC 示例的示例输出 (CASSLGTGGTDTQYF、CASSPGTGGTDTQYF、CASSLGTGGSYEQYF)完全一致, 证明微调权重与生成路径在昇腾 NPU 上工作正常。束搜索(do_sample=False)输出确定, 可复现。

截图(来自真实日志)

  • Agent 工作流:assets/agent_workflow.png(1440×1800)

  • ModelAgent 实时会话:assets/modelagent_live_session.png(1440×900)

  • NPU 设备调用(并发 npu-smi 采集):assets/npu_device_call.png(1440×900)

  • 模型结果:assets/model_result.png(1440×900)

源版本与权重校验

  • 模型仓库固定版本:f559f8f7f1862d23f863b0d0d3b2f858cdab9705 (本地模型目录 git rev-parse HEAD 一致)。
  • 权重文件为真实 safetensors blob(已校验文件大小与 manifest 声明一致):
文件字节数SHA256
model.safetensors167,985,9768d702775dfdffa16f77fedef3301672260b9fa2793ce6d6f679d3f09ac61b26b
  • 严格键校验:safetensors 文件含 215 个张量键,全部映射到模型 state_dict (218 个键)且无多余键;decoder.embed_tokens.weight、 encoder.embed_tokens.weight、lm_head.weight 三个键为 T5 权重共享(tied)别名, 与 shared.weight 共享存储,故文件中不单独存储——校验脚本已按共享存储判定为合法。
  • 加载后张量数 218,参数量 41,990,144,与 fp32 权重字节量 41,990,144 × 4 = 167,960,576 B(外加 safetensors header)吻合。
  • 推理未下载任何替代权重;未使用随机初始化或仅配置权重。

兼容性方案

  • 引擎:torch_npu 2.9.0 与容器内 torch==2.9.0+cpu 配套;不引入 CUDA/Triton/ flash-attn/xformers/bitsandbytes,也不替换 torch/torch_npu。
  • 模型加载:T5ForConditionalGeneration.from_pretrained(..., torch_dtype=torch.float32, use_safetensors=True),然后整模型 .to("npu:6"),model.eval()。
  • 分词器:按上游模型卡使用 T5Tokenizer(本地仓库 tokenizer_class 为自定义 TCRT5Tokenizer,但上游文档与用法均以 T5Tokenizer 加载,实测词表映射一致)。
  • 设备放置:所有被神经模型消费的张量(input_ids、attention_mask、KV cache、 decoder 输出序列、logits)均在 npu:6;脚本断言 param_device_set == ["npu:6"] 且 logits_device == "npu:6"。
  • 可复现性:束搜索 do_sample=False + 固定种子,两次运行输出完全一致。

故障排查

问题可能原因处理
torch.npu.is_available() 为 FalseCANN 环境未加载source /usr/local/Ascend/ascend-toolkit/set_env.sh 后重试
assigned device must be npu:6传入了非 npu:6 设备使用 --device npu:6;容器需能看到全部 8 张物理卡
分词器警告 “TCRT5Tokenizer”本地仓库声明自定义 tokenizer 类属预期;按上游用法使用 T5Tokenizer 即可
警告 “sequence already has [EOS]”输入字符串本身以 [EOS] 结尾属预期;4.40.1 不会重复追加
npu-smi info 进程表不显示 PID容器 PID 命名空间隔离属容器限制,见“局限性与说明”;以 ps 捕获与 torch 放置断言为准
OOMNPU 显存不足减小 --max-new-tokens / --num-beams,确认无其它进程占用 npu:6

局限性与说明

  • 容器无法在 npu-smi info 进程表中暴露本容器的 PID:并发 npu-smi info 采集与 ps PID 捕获被保留,logs/npu_device_call.log 记录了 6 次并发采样的时间戳与精确 Python PID(本次运行 3237743)。物理 NPU 6 的 HBM 使用量在推理期间从 3399 MB 升至 峰值 3564 MB,结束后回落,证明设备确实被调用。硬性设备证据以 torch.npu 的 输入/模型/输出张量放置断言、param_device_set == ["npu:6"]、logits 设备与 NPU 显存 统计为准。
  • 推理输出为冒烟测试性质:max_new_tokens=25、num_beams=3、3 条序列,仅执行 完整微调检查点并验证端到端通路;未做大规模基准、精度对齐或超参调优。
  • 上游许可:模型仓库声明 cc-by-nc-sa-4.0(非商业、署名、相同方式共享)。测试 输入取自模型卡示例,随同一许可记录;不构成临床使用建议。
  • 不发布:本交付不执行任何发布动作;由编排方在独立验证、匿名精确提交审计与公共 checkout NPU 复跑后决定是否发布。
  • 交付物不包含权重、缓存、密钥、.pyc/__pycache__、临时文件或其它模型的文本。

测试输入来源与许可

test_input.json 中的 pMHC 字符串逐字取自上游模型卡 README 的 usage 示例(pinned revision f559f8f7f1862d23f863b0d0d3b2f858cdab9705),随模型仓库以 cc-by-nc-sa-4.0 许可分发。推理过程不下载任何网络数据集。


本 README 由 ModelAgent 针对 tcrt5-ft-tcrdb 生成;README.md 与 readme.md 逐字节一致。

适配交付补充

模型简介:见上文模型说明。

环境依赖:torch、torch_npu 与 CANN,详见 requirements.txt。

推理步骤:按运行步骤执行 inference.py,设备必须为 Ascend NPU。

完整测试用例:使用仓库内固定测试输入执行一次完整推理。

输出结果:真实 NPU 输出已记录在 logs/npu_result.json。