GPN-Star 远程工具安装与运行技能用于在 Linux、Python 3.12.3、CUDA GPU（驱动 580 或更新，对应 CUDA 13.0 固定栈）环境下部署一个提供单核苷酸变异效应评分的 ToolUniverse 远程工具。该工具基于多物种比对的窗口进行打分，每个分数为掩码位置上 logit(alt) - logit(ref)，并对正向与反向互补窗口取平均；它是比对窗口上的语言模型，而不是裸 DNA 上的模型。比对存储是输入而非权重，本验证未下载真实 hg38 100-way 存储（42 GB 压缩包，解压约 64 GB），仅使用工具包自带的 0.14 MiB 稀疏示例存储（染色体 1、2、3、5 上的八个窗口）及同形状合成存储。任何其他位置会以“the alignment holds no data”拒绝。验证覆盖了四次连续相同请求、混合批次形状序列，以及窗口/批次/单变异/拒绝序列，同一请求五次返回字节一致的 scores_sha256。峰值显存从 2 个变异时的 1.01 GiB 升至 8192 列上限（批次 64 × 窗口 128）时的 5.79 GiB，声明的预算为 7.72 GiB。CUDA 图杠杆默认关闭。公开出版、跨用户隔离、并发、恢复及对完整存储的评分科学有效性尚未测试，应保持私有部署。
使用前需满足前置条件：在 ToolUniverse 仓库根目录运行；需要 CUDA GPU；提供方数据、权重、比对存储、缓存和凭据应放在 Git 之外；仅绑定回环地址，非回环绑定需要 TOOLUNIVERSE_API_TOKEN 且不得放入参数或结果。下载大依赖前先运行标准库契约检查：python scripts/remote_validation/setup_skill_preflight.py --implementation gpnstar。导出提供方资源后可加 --check-provider-env；服务器启动后加 --live 验证 MCP 工具集；共享前加 --check-connect-prereqs 仅报告密钥是否设置。
创建两个环境：MCP 服务器运行于 ToolUniverse 环境，模型运行于独立环境（Python 3.13、torch 2.13.0、transformers 5.15.0），二者不能互相导入。先用 python3 -m venv .venvs/gpnstar 创建并安装依赖，再以 uv venv --seed --managed-python --python 3.13 ~/gpnstar-venv 创建模型解释器，通过 tu remote setup --only environment 按锁文件填充。随后设置 TOOLUNIVERSE_GPNSTAR_PYTHON 和 HF_HOME，运行 tu remote setup gpnstar，该命令读取 provider.toml 并执行 preflight、environment、kit、weights、smoke 五步；smoke 步骤会加载模型、发送八个示例变异请求、断言输出非空 scores 和 ids，并将实测峰值 VRAM 记录到 ~/.cache/tooluniverse/measured/gpnstar.json。步骤可用 --only 单独运行。
凭据、数据和权重：HF_HOME 指向包含检查点快照的 Hugging Face 缓存（hub/models--songlab--gpn-star-hg38-v100-200m/snapshots/<commit>/，0.8 GB），tu remote setup gpnstar --only weights 会从上游仓库按固定版本下载并校验九个文件的 sha256 和大小。请求时不获取任何内容。比对存储需用户自备；未设置时读取工具包稀疏示例；真实使用需将 TOOLUNIVERSE_GPNSTAR_MSA_ROOT 指向包含 <n_species>/all.zarr 的目录，例如 <root>/100/all.zarr，每个染色体一个数组。ref 必须与比对中的人类碱基一致，不匹配会被拒绝而非评分。TOOLUNIVERSE_GPNSTAR_GRAPHS 默认关闭。
授权与共享：安装依赖并安装固定版本的 relay SDK 后，每台机器登录一次（tu remote login，或使用受保护的 0600 文件导入），然后 tu remote share gpnstar 即可私有共享。登录默认请求短期设备码并在浏览器批准，无需复制粘贴密钥；无头机器可加 --no-browser。共享命令会执行环境和平台预检、启动或复用回环端点、验证发现，并保持中继前台运行直至 Ctrl-C。可使用 tu remote check 做就绪检查，tu remote run 仅本地运行。
本地启动与验证：运行 python -m tooluniverse.remote.gpnstar.gpnstar_tool，端点 http://127.0.0.1:8057/mcp。使用 FastMCP 客户端列出工具，确认包含 run_gpnstar_vep。重启后首个请求需付出解释器、导入和 0.8 GB 检查点读取成本（约 15-35 秒），后续请求不再付出，这是常驻设计的原因。可使用 tuplatform-connect 中继（尚未发布到 PyPI，需安装已审核的公开 wheel 并固定 SHA-256），并通过 tu doctor 和 tu serve 进行共享。浏览器设备授权为首选；CI 或迁移时仅通过受保护环境提供 TOOLUNIVERSE_SERVICE_KEY，或使用 tu remote login --manual-key。
示例请求：run_gpnstar_vep 接受 variants 列表（chrom、pos、ref、alt）、window_size 和 batch_size。验证主机使用示例存储时成功返回 n_variants 4、四个 ids、scores [2.88394, -0.08641, -3.10446, 0.36191]，以及 scores_sha256、window_size、batch_size、levers_applied、levers_declined（["graph"]）和 peak_reserved_gib。同一批变异通过工具包自身 GPNSTAR_OPT=exact 和 stock gpn star vep 产生字节一致的 parquet，且 scores_sha256 匹配。分数按（变异，批次形状）可复现；不同 batch_size 可能移动最后几位数字。
工具会明确拒绝而非猜测的情况包括：ref 与比对不一致；存储无数据的位置；batch_size × window_size 超过 8192 列（限制峰值内存）；variants × window_size 超过 524,288（限制单次调用时长）；超过 2048 个变异；奇数或越界窗口；indel 和模糊代码。单个变异按两个副本的批次评分，回复中会注明 single_variant_sent_twice。
GPU 与并发调优：使用一个 worker，常驻 worker 按设计一次服务一个请求，第二个进行中请求会在锁上排队而非加倍峰值显存。在卡上共置其他任务前，读取提供方清单中的 vram_budget_gb 和实测文件。峰值跟随 batch_size × window_size，而非变异数量。建议先测冷启动，再测至少四次连续相同请求、混合形状序列（小、小、大、小），然后分别改变 window_size 和 batch_size；再测并行级别 1、2、4、8，仅在内存允许时测 16；记录成功/错误、p50/p95、峰值 RAM/VRAM、利用率、排队、取消清理和恢复；仅在单飞初始化和可恢复的 OOM/超时行为被证明后才增加 worker。
故障排查：每一步 tu remote setup 都会指出问题并附带修复方法，退出码 3 表示拒绝，1 表示失败。worker 日志位于 ~/.cache/tooluniverse/remote-logs/gpnstar-resident.log。出现“Reference allele mismatch ... genome has '-'”表示比对在该位置没有数据，可能是稀疏示例存储或位置超出存储；“[gpnstar-opt] NOT ACTIVE at start”表示工具包拒绝该栈；模型半部分导入/执行失败可重跑 --only environment；权重偏离固定值时会保留文件供检查，需手动删除后重跑 --only weights。TF32 相关环境变量会被移除。401/403 需配置匹配的 TOOLUNIVERSE_API_TOKEN 或优先使用回环加中继。用 Ctrl-C 停止服务器/中继，并可用 tuplatform-service uninstall --name validation-gpnstar 卸载。worker 可能有空闲超时（300 秒）和孤儿看门狗。撤销临时密钥后，仅删除 .venvs/gpnstar、~/gpnstar-venv 和提供方缓存目录（~/.gpnstar），切勿使用宽泛递归目标。仅使用实现 README 链接的上游官方文档。