docs(model-card): improve discovery and inference usage

.gitignore

@@ -0,0 +1,7 @@
+var/
+output/
+.playwright-cli/
+.cache/
+__pycache__/
+*.py[cod]
+.DS_Store

README.md

@@ -2,49 +2,161 @@
 language:
   - en
   - zh
+library_name: pytorch
 tags:
   - scientific-perception
   - multimodal
   - projector
+  - chemistry
+  - biology
+  - materials-science
+  - time-series
+thumbnail: https://huggingface.co/internlm/Sage-SciPerception/resolve/main/assets/branding/sage-sciprojector-hero-titled.png
 ---
 
-<p align="center">
-  <img src="assets/branding/sage-sciprojector-hero-titled.png" alt="Sage Sci Perception: a young scholar explores scientific representations." width="100%">
-</p>
-
 <h1 align="center">Sage-SciPerception</h1>
-<p align="center"><strong>Sage Sci Perception · 书生·元征</strong></p>
-<p align="center">Scientific perception for language models.</p>
-
-<p align="center"><strong>English</strong> · <a href="README_zh.md">简体中文</a></p>
+<p align="center"><strong>Scientific perception for language models · 书生·元征</strong></p>
+<p align="center">Connect crystals, spectra, biological sequences, and biosignals to language models through trained projectors.</p>
+<p align="center"><strong>Continuously expanding scientific modalities, tasks, and language model support.</strong></p>
 
 <p align="center">
+  <a href="#released-projectors">Get weights</a> ·
+  <a href="#inference">Inference</a> ·
   <a href="https://github.com/InternLM/Sage-SciPerception">GitHub</a> ·
-  <a href="#framework">Framework</a> ·
-  <a href="#results">Results</a>
+  <a href="https://huggingface.co/internlm/Sage-SciPerception/blob/main/README_zh.md">简体中文</a>
 </p>
 
-## Introduction
+<p align="center">
+  <img src="assets/branding/sage-sciprojector-hero-titled.png" alt="Sage Sci Perception: a young scholar explores scientific representations." width="640">
+</p>
+
+Sage Sci Perception maps scientific representations into a language model's input space, enabling natural-language analysis and structured scientific answers. Use it to explore interfaces between your scientific workflow and a language model: material property prediction, biomolecular sequence labeling, spectral structure identification, and signal classification.
+
+Projectors are organized by modality, task, and language-model version. Start with the available checkpoints below, or use the [inference guide](#inference) to connect projected scientific inputs to a serving workflow. Each checkpoint records its matching language model and input representation in `config.json`.
+
+## Released projectors
+
+Open a task to browse its files, or download its weights and configuration directly. Additional modalities, tasks, and compatible language-model versions will be added as the project develops.
+
+| Benchmark / task | Metric ↑ | Score | Projector |
+|---|---|---:|---|
+| [JARVIS-DFT](https://huggingface.co/internlm/Sage-SciPerception/tree/main/projectors/glm-5.3-flash/cif/jarvis)<br>Formation energy | MAD/MAE | **15.03** | [Weights](https://huggingface.co/internlm/Sage-SciPerception/resolve/main/projectors/glm-5.3-flash/cif/jarvis/projector.safetensors?download=true) · [config](https://huggingface.co/internlm/Sage-SciPerception/blob/main/projectors/glm-5.3-flash/cif/jarvis/config.json) |
+| [MPBind](https://huggingface.co/internlm/Sage-SciPerception/tree/main/projectors/glm-5.3-flash/protein-seq/mpbind)<br>PPI interface sites | Per-protein F1 (%) | **61.12** | [Weights](https://huggingface.co/internlm/Sage-SciPerception/resolve/main/projectors/glm-5.3-flash/protein-seq/mpbind/projector.safetensors?download=true) · [config](https://huggingface.co/internlm/Sage-SciPerception/blob/main/projectors/glm-5.3-flash/protein-seq/mpbind/config.json) |
+| [QM9S](https://huggingface.co/internlm/Sage-SciPerception/tree/main/projectors/glm-5.3-flash/spectra/qm9s)<br>Molecular structure identification | Acc@1 (%) | **49.75** | [Weights](https://huggingface.co/internlm/Sage-SciPerception/resolve/main/projectors/glm-5.3-flash/spectra/qm9s/projector.safetensors?download=true) · [config](https://huggingface.co/internlm/Sage-SciPerception/blob/main/projectors/glm-5.3-flash/spectra/qm9s/config.json) |
+| [SciTS PHU01](https://huggingface.co/internlm/Sage-SciPerception/tree/main/projectors/glm-5.3-flash/ecg/phu01)<br>ECG classification | Macro-F1 (%) | **71.53** | [Weights](https://huggingface.co/internlm/Sage-SciPerception/resolve/main/projectors/glm-5.3-flash/ecg/phu01/projector.safetensors?download=true) · [config](https://huggingface.co/internlm/Sage-SciPerception/blob/main/projectors/glm-5.3-flash/ecg/phu01/config.json) |
+| [GUE splice](https://huggingface.co/internlm/Sage-SciPerception/tree/main/projectors/glm-5.3-flash/dna/splice)<br>Splice-site classification | MCC (%) | **87.87** | [Weights](https://huggingface.co/internlm/Sage-SciPerception/resolve/main/projectors/glm-5.3-flash/dna/splice/projector.safetensors?download=true) · [config](https://huggingface.co/internlm/Sage-SciPerception/blob/main/projectors/glm-5.3-flash/dna/splice/config.json) |
+| [SciTS NEU06](https://huggingface.co/internlm/Sage-SciPerception/tree/main/projectors/glm-5.3-flash/eeg/neu06)<br>Sleep staging | Macro-F1 (%) | **72.01** | [Weights](https://huggingface.co/internlm/Sage-SciPerception/resolve/main/projectors/glm-5.3-flash/eeg/neu06/projector.safetensors?download=true) · [config](https://huggingface.co/internlm/Sage-SciPerception/blob/main/projectors/glm-5.3-flash/eeg/neu06/config.json) |
+| [BEACON ncRNA](https://huggingface.co/internlm/Sage-SciPerception/tree/main/projectors/glm-5.3-flash/rna/ncrna)<br>RNA family classification | Accuracy (%) | **97.35** | [Weights](https://huggingface.co/internlm/Sage-SciPerception/resolve/main/projectors/glm-5.3-flash/rna/ncrna/projector.safetensors?download=true) · [config](https://huggingface.co/internlm/Sage-SciPerception/blob/main/projectors/glm-5.3-flash/rna/ncrna/config.json) |
+| [SimXRD OL](https://huggingface.co/internlm/Sage-SciPerception/tree/main/projectors/glm-5.3-flash/xrd/simxrd)<br>Crystal-system classification | Accuracy (%) | **63.60** | [Weights](https://huggingface.co/internlm/Sage-SciPerception/resolve/main/projectors/glm-5.3-flash/xrd/simxrd/projector.safetensors?download=true) · [config](https://huggingface.co/internlm/Sage-SciPerception/blob/main/projectors/glm-5.3-flash/xrd/simxrd/config.json) |
+| [ATOM3D PSR](https://huggingface.co/internlm/Sage-SciPerception/tree/main/projectors/glm-5.3-flash/protein-struct/psr)<br>Protein structure ranking | Spearman (%) | **35.36** | [Weights](https://huggingface.co/internlm/Sage-SciPerception/resolve/main/projectors/glm-5.3-flash/protein-struct/psr/projector.safetensors?download=true) · [config](https://huggingface.co/internlm/Sage-SciPerception/blob/main/projectors/glm-5.3-flash/protein-struct/psr/config.json) |
+
+Scores come from generated answers using each task's selected checkpoint. Metrics differ across rows; **MAD/MAE is a ratio where higher is better**, rather than an error to minimize. MPBind uses the assembly-1 reconstructed evaluation set and mean per-protein F1; PSR uses mean Spearman. Each projector is trained for its respective task.
+
+## Inference
+
+Our serving path inserts the projected scientific vectors into the language model's **full templated prompt embeddings**, then sends them to vLLM through `prompt_embeds` at `/v1/completions`. Text tokens use the matching language model's input embedding table; the scientific span uses the projector output. Scientific feature extraction and projection run in the client, while the language-model service generates the answer.
+
+### 1. Prepare the weights and scientific inputs
+
+The complete [crystal client example](https://huggingface.co/internlm/Sage-SciPerception/blob/main/examples/vllm_cif.py) implements feature projection, native chat-template rendering, text embedding lookup, scientific-span insertion, and the HTTP request. Download it with the loader modules and matching projector:
+
+```bash
+python -m pip install torch safetensors huggingface_hub
+python -m pip install --upgrade transformers
+hf download internlm/Sage-SciPerception \
+  examples/vllm_cif.py load_projector.py modeling_projector.py \
+  projectors/glm-5.3-flash/cif/jarvis/config.json \
+  projectors/glm-5.3-flash/cif/jarvis/projector.safetensors \
+  --local-dir ./sage-sciperception
+cd sage-sciperception
+```
 
-Sage Sci Perception (书生·元征) connects scientific encoders to a language model through trainable projectors. It maps molecular graphs, spectra, crystal structures, protein and nucleic-acid sequences, and scientific signals into the language model's input space, enabling natural-language analysis and structured scientific answers.
+Prepare `cif_features.pt` as a PyTorch tensor of shape `[num_atoms, 64]`: the real CHGNet 0.3.0 atom states specified by `cif/jarvis/config.json`, in atom order. The local language-model directory must match the exact revision recorded in the checkpoint's `config.json`. The client reads its tokenizer, configuration, and sharded safetensors input embedding table without loading the full language model.
 
-Projectors are organized by language backbone, modality, and task, and used with their corresponding scientific encoders and configurations.
+### 2. Start the vLLM server
+
+In your inference environment, start a compatible vLLM server with `--enable-prompt-embeds`. Choose tensor parallelism for the selected model and your hardware; the command below shows an eight-way deployment example.
+
+```bash
+vllm serve /path/to/matching-base-model \
+  --served-model-name sage-sciperception \
+  --enable-prompt-embeds \
+  --tensor-parallel-size 8 \
+  --generation-config vllm \
+  --max-model-len 8192 \
+  --host 127.0.0.1 --port 8000
+```
+
+### 3. Generate an answer
+
+Once the server is ready, run the client from the `sage-sciperception` directory prepared in step 1:
+
+```bash
+python examples/vllm_cif.py \
+  --component ./projectors/glm-5.3-flash/cif/jarvis \
+  --base-model /path/to/matching-base-model \
+  --features /path/to/cif_features.pt \
+  --api-base http://127.0.0.1:8000/v1 \
+  --model sage-sciperception
+```
+
+The transport core below is an excerpt from the client. `prompt_embeds` already includes the native system, user, and assistant-generation prefixes, with the projector vectors inserted in the scientific span:
+
+```python
+buffer = io.BytesIO()
+torch.save(prompt_embeds.cpu().contiguous(), buffer)
+body = {
+    "model": "sage-sciperception",
+    "prompt_embeds": base64.b64encode(buffer.getvalue()).decode("ascii"),
+    "max_tokens": 4096,
+    "temperature": 0,
+}
+request = urllib.request.Request(
+    "http://127.0.0.1:8000/v1/completions",
+    data=json.dumps(body).encode("utf-8"),
+    headers={"Content-Type": "application/json"},
+)
+```
+
+The Completions endpoint consumes the assembled embeddings directly. Keep the checkpoint's system prompt, template options, and scientific input representation when preparing a request. The [component index](https://huggingface.co/internlm/Sage-SciPerception/blob/main/projectors/glm-5.3-flash/README.md#scientific-inputs) describes the currently available inputs; the crystal example uses its own task's format. See the [vLLM prompt embedding documentation](https://docs.vllm.ai/en/v0.32.0/features/prompt_embeds/) for the serving interface.
+
+Scientific encoder weights and preprocessing runners are separate dependencies. Task-adapted scientific models for DNA, MPBind, and ncRNA are not yet included here. This inference example starts from prepared scientific features.
+
+### Optional: check projector loading on CPU
+
+From the same downloaded directory, you can verify the projector's parameter count and output dimension on CPU without starting the language-model service:
+
+```python
+from load_projector import load_projector
+
+projector, config = load_projector(
+    "projectors/glm-5.3-flash/cif/jarvis", device="cpu"
+)
+print(config["task"])
+print(sum(p.numel() for p in projector.parameters()))
+print(config["output_dim"])
+```
+
+Expected output:
+
+```text
+cif/jarvis
+4314304
+4096
+```
+
+To load another task, download its matching weights and configuration from the [component index](https://huggingface.co/internlm/Sage-SciPerception/blob/main/projectors/glm-5.3-flash/README.md). Forward inputs vary by task; consult its scientific input description when preparing predictions.
 
 ## Framework
 
 <p align="center">
-  <img src="assets/framework.gif" alt="Scientific inputs pass through scientific encoders and trainable projectors into a language model." width="100%">
+  <img src="assets/framework.gif" alt="Scientific inputs pass through scientific representations and trainable projectors into a language model." width="100%">
 </p>
 
-## Results
+A task-specific projector maps scientific features to the language model's embedding dimension. During the language-mapping stage, the scientific models and language model stay frozen while the projector is trained. Some tasks use scientific models that were adapted to their task beforehand, or combine encoder states with scientific readouts.
+
+## Feedback and next steps
 
-Selected results from task-specific checkpoints, evaluated on generated answers.
+For integration questions, missing assets, or examples you would like to see, [open a GitHub issue](https://github.com/InternLM/Sage-SciPerception/issues/new). Include the task, your scientific input format, and the step you want to run. You can also use the [Hugging Face community tab](https://huggingface.co/internlm/Sage-SciPerception/discussions) for release questions, or follow [InternLM](https://huggingface.co/internlm) for updates.
 
-| Benchmark | Task | Metric ↑ | Score |
-|---|---|---|---:|
-| QM9S | Joint-spectrum structure identification | Acc@1 (%) | **49.75** |
-| JARVIS-DFT | Formation-energy prediction | MAD/MAE | **15.03** |
-| MPBind, assembly-1 reconstruction | PPI interface sites | Mean per-protein F1 (%) | **61.12** |
-| SciTS PHU01 | ECG classification | Macro-F1 (%) | **71.53** |
-| SciTS NEU06 | Sleep staging | Macro-F1 (%) | **72.01** |
-| BEACON ncRNA | RNA family classification | Accuracy (%) | **97.35** |
+License metadata has not yet been specified for this release.

README_zh.md

@@ -1,40 +1,146 @@
-<p align="center">
-  <img src="assets/branding/sage-sciprojector-hero-zh.png" alt="书生·元征：书生探索科学表征。" width="100%">
-</p>
-
 <h1 align="center">书生·元征</h1>
-<p align="center"><strong>Sage Sci Perception</strong></p>
-<p align="center">让大模型感知科学数据。</p>
-
-<p align="center"><a href="README.md">English</a> · <strong>简体中文</strong></p>
+<p align="center"><strong>Sage Sci Perception · 让大模型感知科学数据。</strong></p>
+<p align="center">通过投影模块，将晶体、谱图、生物序列与生理信号接入语言模型。</p>
+<p align="center"><strong>持续扩展科学模态、任务与语言模型支持。</strong></p>
 
 <p align="center">
+  <a href="#已发布权重">下载权重</a> ·
+  <a href="#推理使用">推理使用</a> ·
   <a href="https://github.com/InternLM/Sage-SciPerception">GitHub</a> ·
-  <a href="#整体框架">整体框架</a> ·
-  <a href="#评测结果">评测结果</a>
+  <a href="https://huggingface.co/internlm/Sage-SciPerception">English</a>
 </p>
 
-## 简介
+<p align="center">
+  <img src="assets/branding/sage-sciprojector-hero-zh.png" alt="书生·元征：书生探索科学表征。" width="640">
+</p>
+
+书生·元征（Sage Sci Perception）将科学表征映射到语言模型的输入空间，使其能够生成自然语言分析和结构化科学答案。你可以用它探索科学工作流与语言模型的连接，包括材料性质预测、生物序列标注、谱图结构识别与信号分类。
+
+projector 按模态、任务与语言模型版本组织。你可以从下表下载已有权重，也可以参考[推理使用说明](#推理使用)，将科学输入接入推理服务。各权重的 `config.json` 记录了对应语言模型和科学输入表示。
+
+## 已发布权重
+
+点击任务名称查看配套文件，或直接下载权重和配置。后续将持续增加科学模态、任务与适配的语言模型版本。
+
+| 榜单 / 任务 | 指标 ↑ | 得分 | 下载 |
+|---|---|---:|---|
+| [JARVIS-DFT](https://huggingface.co/internlm/Sage-SciPerception/tree/main/projectors/glm-5.3-flash/cif/jarvis)<br>形成能预测 | MAD/MAE | **15.03** | [权重](https://huggingface.co/internlm/Sage-SciPerception/resolve/main/projectors/glm-5.3-flash/cif/jarvis/projector.safetensors?download=true) · [config](https://huggingface.co/internlm/Sage-SciPerception/blob/main/projectors/glm-5.3-flash/cif/jarvis/config.json) |
+| [MPBind](https://huggingface.co/internlm/Sage-SciPerception/tree/main/projectors/glm-5.3-flash/protein-seq/mpbind)<br>PPI 界面位点 | 逐蛋白 F1（%） | **61.12** | [权重](https://huggingface.co/internlm/Sage-SciPerception/resolve/main/projectors/glm-5.3-flash/protein-seq/mpbind/projector.safetensors?download=true) · [config](https://huggingface.co/internlm/Sage-SciPerception/blob/main/projectors/glm-5.3-flash/protein-seq/mpbind/config.json) |
+| [QM9S](https://huggingface.co/internlm/Sage-SciPerception/tree/main/projectors/glm-5.3-flash/spectra/qm9s)<br>分子结构识别 | Acc@1（%） | **49.75** | [权重](https://huggingface.co/internlm/Sage-SciPerception/resolve/main/projectors/glm-5.3-flash/spectra/qm9s/projector.safetensors?download=true) · [config](https://huggingface.co/internlm/Sage-SciPerception/blob/main/projectors/glm-5.3-flash/spectra/qm9s/config.json) |
+| [SciTS PHU01](https://huggingface.co/internlm/Sage-SciPerception/tree/main/projectors/glm-5.3-flash/ecg/phu01)<br>心电分类 | 宏平均 F1（%） | **71.53** | [权重](https://huggingface.co/internlm/Sage-SciPerception/resolve/main/projectors/glm-5.3-flash/ecg/phu01/projector.safetensors?download=true) · [config](https://huggingface.co/internlm/Sage-SciPerception/blob/main/projectors/glm-5.3-flash/ecg/phu01/config.json) |
+| [GUE splice](https://huggingface.co/internlm/Sage-SciPerception/tree/main/projectors/glm-5.3-flash/dna/splice)<br>剪接位点分类 | MCC（%） | **87.87** | [权重](https://huggingface.co/internlm/Sage-SciPerception/resolve/main/projectors/glm-5.3-flash/dna/splice/projector.safetensors?download=true) · [config](https://huggingface.co/internlm/Sage-SciPerception/blob/main/projectors/glm-5.3-flash/dna/splice/config.json) |
+| [SciTS NEU06](https://huggingface.co/internlm/Sage-SciPerception/tree/main/projectors/glm-5.3-flash/eeg/neu06)<br>睡眠分期 | 宏平均 F1（%） | **72.01** | [权重](https://huggingface.co/internlm/Sage-SciPerception/resolve/main/projectors/glm-5.3-flash/eeg/neu06/projector.safetensors?download=true) · [config](https://huggingface.co/internlm/Sage-SciPerception/blob/main/projectors/glm-5.3-flash/eeg/neu06/config.json) |
+| [BEACON ncRNA](https://huggingface.co/internlm/Sage-SciPerception/tree/main/projectors/glm-5.3-flash/rna/ncrna)<br>RNA 家族分类 | 准确率（%） | **97.35** | [权重](https://huggingface.co/internlm/Sage-SciPerception/resolve/main/projectors/glm-5.3-flash/rna/ncrna/projector.safetensors?download=true) · [config](https://huggingface.co/internlm/Sage-SciPerception/blob/main/projectors/glm-5.3-flash/rna/ncrna/config.json) |
+| [SimXRD OL](https://huggingface.co/internlm/Sage-SciPerception/tree/main/projectors/glm-5.3-flash/xrd/simxrd)<br>晶系分类 | 准确率（%） | **63.60** | [权重](https://huggingface.co/internlm/Sage-SciPerception/resolve/main/projectors/glm-5.3-flash/xrd/simxrd/projector.safetensors?download=true) · [config](https://huggingface.co/internlm/Sage-SciPerception/blob/main/projectors/glm-5.3-flash/xrd/simxrd/config.json) |
+| [ATOM3D PSR](https://huggingface.co/internlm/Sage-SciPerception/tree/main/projectors/glm-5.3-flash/protein-struct/psr)<br>蛋白质结构排序 | Spearman（%） | **35.36** | [权重](https://huggingface.co/internlm/Sage-SciPerception/resolve/main/projectors/glm-5.3-flash/protein-struct/psr/projector.safetensors?download=true) · [config](https://huggingface.co/internlm/Sage-SciPerception/blob/main/projectors/glm-5.3-flash/protein-struct/psr/config.json) |
+
+得分来自各任务选定 checkpoint 的生成答案，不同任务的指标不能直接比较。**MAD/MAE 是越高越好的比值**，不是需要最小化的误差。MPBind 使用 assembly-1 重建评测集及逐蛋白平均 F1；PSR 使用平均 Spearman。各模块分别针对对应任务训练。
+
+## 推理使用
+
+我们的服务路线是：将 projector 输出的科学向量插入语言模型的**完整聊天提示词嵌入**，再通过 `prompt_embeds` 发给 vLLM 的 `/v1/completions`。文本位置使用对应语言模型的输入嵌入表，科学载荷位置使用 projector 的输出。科学特征提取与投影在客户端完成，语言模型服务负责生成答案。
+
+### 1. 准备权重与科学输入
+
+完整的[晶体客户端示例](https://huggingface.co/internlm/Sage-SciPerception/blob/main/examples/vllm_cif.py)包含特征投影、原生 chat template 渲染、文本嵌入读取、科学载荷替换及 HTTP 请求。先下载示例、加载模块和对应任务权重：
+
+```bash
+python -m pip install torch safetensors huggingface_hub
+python -m pip install --upgrade transformers
+hf download internlm/Sage-SciPerception \
+  examples/vllm_cif.py load_projector.py modeling_projector.py \
+  projectors/glm-5.3-flash/cif/jarvis/config.json \
+  projectors/glm-5.3-flash/cif/jarvis/projector.safetensors \
+  --local-dir ./sage-sciperception
+cd sage-sciperception
+```
 
-书生·元征（Sage Sci Perception）通过可训练的投影模块，将科学编码器接入语言模型。分子图、谱图、晶体结构、蛋白质与核酸序列以及科学信号被映射到语言模型的输入空间，使其能够生成自然语言分析和结构化科学答案。
+准备 `cif_features.pt`：这是形状为 `[num_atoms, 64]` 的 PyTorch 张量，内容为 `cif/jarvis/config.json` 指定的真实 CHGNet 0.3.0 原子状态，保持原子顺序。本地语言模型目录应与权重 `config.json` 记录的精确版本一致。客户端从该目录读取 tokenizer、配置和分片 safetensors 中的输入嵌入表，无需加载完整语言模型。
 
-投影模块按语言模型底座、模态和任务组织，与对应的科学编码器及配置配套使用。
+### 2. 启动 vLLM 服务
+
+在推理服务环境中，启动支持 `--enable-prompt-embeds` 的 vLLM 服务。张量并行度根据所选模型与设备选择；以下命令以八路并行为例。
+
+```bash
+vllm serve /path/to/matching-base-model \
+  --served-model-name sage-sciperception \
+  --enable-prompt-embeds \
+  --tensor-parallel-size 8 \
+  --generation-config vllm \
+  --max-model-len 8192 \
+  --host 127.0.0.1 --port 8000
+```
+
+### 3. 生成答案
+
+服务就绪后，在步骤 1 准备的 `sage-sciperception` 目录中运行客户端：
+
+```bash
+python examples/vllm_cif.py \
+  --component ./projectors/glm-5.3-flash/cif/jarvis \
+  --base-model /path/to/matching-base-model \
+  --features /path/to/cif_features.pt \
+  --api-base http://127.0.0.1:8000/v1 \
+  --model sage-sciperception
+```
+
+下面是客户端中的传输代码摘录。此时 `prompt_embeds` 已包含原生 system、user 以及 assistant 生成前缀，并在科学载荷位置插入了 projector 向量：
+
+```python
+buffer = io.BytesIO()
+torch.save(prompt_embeds.cpu().contiguous(), buffer)
+body = {
+    "model": "sage-sciperception",
+    "prompt_embeds": base64.b64encode(buffer.getvalue()).decode("ascii"),
+    "max_tokens": 4096,
+    "temperature": 0,
+}
+request = urllib.request.Request(
+    "http://127.0.0.1:8000/v1/completions",
+    data=json.dumps(body).encode("utf-8"),
+    headers={"Content-Type": "application/json"},
+)
+```
+
+Completions 接口直接消费组装后的完整嵌入。构造请求时沿用 checkpoint 的 system prompt、模板参数及科学输入表示。[组件索引](https://huggingface.co/internlm/Sage-SciPerception/blob/main/projectors/glm-5.3-flash/README.md#scientific-inputs)列出了当前可用输入；晶体示例使用该任务自己的输入格式。服务接口见 [vLLM prompt embeddings 文档](https://docs.vllm.ai/en/v0.32.0/features/prompt_embeds/)。
+
+科学编码器权重和预处理运行脚本是��立依赖。其中 DNA、MPBind 和 ncRNA 所需的任务适配科学模型尚未在此发布。上述推理示例从已准备好的真实科学特征开始。
+
+### 可选：在 CPU 上检查 projector 加载
+
+在同一下载目录中，可以用 CPU 检查 projector 的参数量与输出维度，无需启动语言模型服务：
+
+```python
+from load_projector import load_projector
+
+projector, config = load_projector(
+    "projectors/glm-5.3-flash/cif/jarvis", device="cpu"
+)
+print(config["task"])
+print(sum(p.numel() for p in projector.parameters()))
+print(config["output_dim"])
+```
+
+预期输出：
+
+```text
+cif/jarvis
+4314304
+4096
+```
+
+加载其他任务时，请从[组件索引](https://huggingface.co/internlm/Sage-SciPerception/blob/main/projectors/glm-5.3-flash/README.md)下载对应权重和配置。各任务前向所需的输入不同，准备预测时请查看其科学输入说明。
 
 ## 整体框架
 
 <p align="center">
-  <img src="assets/framework.gif" alt="科学输入经科学编码器与可训练投影模块，接入语言模型。" width="100%">
+  <img src="assets/framework.gif" alt="科学输入经科学表征与可训练投影模块，接入语言模型。" width="100%">
 </p>
 
-## 评测结果
+任务专用 projector 将科学特征映射到语言模型的嵌入维度。在语言映射训练阶段，科学模型和语言模型保持冻结，只训练 projector。部分任务会先对科学模型进行任务适配，或将编码器状态与科学直接读出结合。
+
+## 反馈与后续
 
-以下为各任务独立 checkpoint 的部分评测结果，按生成答案判分。
+如果你正在接入自己的科学流程、缺少配套文件，或希望看到具体示例，可以[提交 GitHub issue](https://github.com/InternLM/Sage-SciPerception/issues/new)，附上任务、科学输入格式和想运行的步骤。发布相关问题也可以在 [HF 社区页](https://huggingface.co/internlm/Sage-SciPerception/discussions)讨论；关注 [InternLM](https://huggingface.co/internlm) 可接收后续更新。
 
-| 榜单 | 任务 | 指标 ↑ | 得分 |
-|---|---|---|---:|
-| QM9S | 三谱联合分子结构识别 | Acc@1（%） | **49.75** |
-| JARVIS-DFT | 形成能预测 | MAD/MAE | **15.03** |
-| MPBind，assembly-1 重建集 | PPI 界面位点预测 | 逐蛋白平均 F1（%） | **61.12** |
-| SciTS PHU01 | 心电分类 | 宏平均 F1（%） | **71.53** |
-| SciTS NEU06 | 睡眠分期 | 宏平均 F1（%） | **72.01** |
-| BEACON ncRNA | RNA 家族分类 | 准确率（%） | **97.35** |
+本次发布尚未指定许可证元数据。

examples/vllm_cif.py

@@ -0,0 +1,101 @@
+"""Send a crystal projector's scientific embeddings to a matching vLLM server.
+
+Input: a CPU-loadable tensor [num_atoms, 64] containing the CHGNet atom states
+specified by the cif/jarvis checkpoint. The language-model directory supplies
+its tokenizer, config, and sharded safetensors input embedding table.
+"""
+import argparse
+import base64
+import io
+import json
+from pathlib import Path
+import sys
+import urllib.request
+
+import torch
+from safetensors import safe_open
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from load_projector import load_projector
+
+MARKER = "￰SAGE_PAYLOAD￱"
+
+
+def build_prompt_embeds(projector, config, features, tokenizer, base_model, question):
+    """Use the checkpoint's native template and replace its scientific span."""
+    with torch.inference_mode():
+        scientific = projector(features.float(), torch.arange(len(features)))
+    spec = config["prompt"]
+    name = spec["names"][0][0]
+    messages = [
+        {"role": "system", "content": spec["system"]},
+        {"role": "user", "content": f"{name}:\n{MARKER}\n\nQuestion: {question}"},
+    ]
+    prompt = tokenizer.apply_chat_template(
+        messages, tokenize=False, add_generation_prompt=True, **spec["template_kwargs"]
+    )
+    before, after = prompt.split(MARKER)
+    prefix_ids = tokenizer(before, add_special_tokens=False)["input_ids"]
+    suffix_ids = tokenizer(after, add_special_tokens=False)["input_ids"]
+
+    # Text rows must come from the exact embedding table used by the server.
+    weight_map = json.loads((base_model / "model.safetensors.index.json").read_text())["weight_map"]
+    key = next(name for name in weight_map if name.endswith("embed_tokens.weight"))
+    with safe_open(base_model / weight_map[key], framework="pt", device="cpu") as weights:
+        table = weights.get_slice(key)
+        rows = {index: table[index:index + 1] for index in set(prefix_ids + suffix_ids)}
+    prefix = torch.cat([rows[index] for index in prefix_ids])
+    suffix = torch.cat([rows[index] for index in suffix_ids])
+    return torch.cat([prefix, scientific.to(prefix), suffix]).contiguous()
+
+
+def complete(api_base, model, prompt_embeds, stop_token_ids, max_tokens):
+    """Completions receives the full templated sequence, including text rows."""
+    buffer = io.BytesIO()
+    torch.save(prompt_embeds.cpu().contiguous(), buffer)
+    body = {
+        "model": model,
+        "prompt_embeds": base64.b64encode(buffer.getvalue()).decode("ascii"),
+        "max_tokens": max_tokens,
+        "temperature": 0,
+        "stop_token_ids": stop_token_ids,
+        "skip_special_tokens": False,
+    }
+    request = urllib.request.Request(
+        api_base.rstrip("/") + "/completions",
+        data=json.dumps(body).encode("utf-8"),
+        headers={"Content-Type": "application/json"},
+    )
+    with urllib.request.urlopen(request, timeout=600) as response:
+        return json.load(response)["choices"][0]["text"]
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--component", type=Path, required=True)
+    parser.add_argument("--base-model", type=Path, required=True)
+    parser.add_argument("--features", type=Path, required=True)
+    parser.add_argument("--question", default="Predict the formation energy per atom in eV/atom.")
+    parser.add_argument("--api-base", default="http://127.0.0.1:8000/v1")
+    parser.add_argument("--model", default="sage-sciperception")
+    parser.add_argument("--max-tokens", type=int, default=4096)
+    args = parser.parse_args()
+
+    projector, config = load_projector(args.component, device="cpu")
+    if config["task"] != "cif/jarvis":
+        parser.error("This example uses the cif/jarvis input format and unnumbered crystal prompt.")
+    features = torch.load(args.features, map_location="cpu", weights_only=True)
+    from transformers import AutoTokenizer
+    tokenizer = AutoTokenizer.from_pretrained(args.base_model, local_files_only=True)
+    prompt_embeds = build_prompt_embeds(
+        projector, config, features, tokenizer, args.base_model, args.question
+    )
+    language_config = json.loads((args.base_model / "config.json").read_text())
+    text_config = language_config.get("text_config", language_config)
+    eos = text_config["eos_token_id"]
+    stop_ids = eos if isinstance(eos, list) else [eos]
+    print(complete(args.api_base, args.model, prompt_embeds, stop_ids, args.max_tokens))
+
+
+if __name__ == "__main__":
+    main()

projectors/glm-5.3-flash/README.md

@@ -1,29 +1,49 @@
-# GLM-5.3-Flash projectors
+# Projector index
 
-This release contains nine task-specific projectors for `zai-org/GLM-5.3-Flash-BF16`.
+Available checkpoints are organized by modality, task, and language-model version. Scientific modalities, tasks, and language-model support will continue to expand. See the [English model card](https://huggingface.co/internlm/Sage-SciPerception#inference) or [中文模型卡](https://huggingface.co/internlm/Sage-SciPerception/blob/main/README_zh.md#推理使用) for inference setup, a vLLM client example, and an optional CPU loading check.
 
-| Modality / task | Training step | Weights and configuration |
-|---|---:|---|
-| cif/jarvis | 2822 | [download](cif/jarvis/) |
-| protein-seq/mpbind | 100 | [download](protein-seq/mpbind/) |
-| spectra/qm9s | 8037 | [download](spectra/qm9s/) |
-| ecg/phu01 | 1068 | [download](ecg/phu01/) |
-| dna/splice | 50 | [download](dna/splice/) |
-| eeg/neu06 | 4688 | [download](eeg/neu06/) |
-| rna/ncrna | 200 | [download](rna/ncrna/) |
-| xrd/simxrd | 500 | [download](xrd/simxrd/) |
-| protein-struct/psr | 200 | [download](protein-struct/psr/) |
+Each task directory contains `projector.safetensors` and `config.json`. The configuration declares the architecture, output dimension, scientific inputs, prompt, backbone revision, and training step. Scientific encoder weights and the language backbone are separate dependencies.
 
-## Loading a projector
+| Task directory | Training step | Weights | Configuration |
+|---|---:|---|---|
+| `cif/jarvis` | 2822 | [Weights](https://huggingface.co/internlm/Sage-SciPerception/resolve/main/projectors/glm-5.3-flash/cif/jarvis/projector.safetensors?download=true) | [config.json](https://huggingface.co/internlm/Sage-SciPerception/blob/main/projectors/glm-5.3-flash/cif/jarvis/config.json) |
+| `protein-seq/mpbind` | 100 | [Weights](https://huggingface.co/internlm/Sage-SciPerception/resolve/main/projectors/glm-5.3-flash/protein-seq/mpbind/projector.safetensors?download=true) | [config.json](https://huggingface.co/internlm/Sage-SciPerception/blob/main/projectors/glm-5.3-flash/protein-seq/mpbind/config.json) |
+| `spectra/qm9s` | 8037 | [Weights](https://huggingface.co/internlm/Sage-SciPerception/resolve/main/projectors/glm-5.3-flash/spectra/qm9s/projector.safetensors?download=true) | [config.json](https://huggingface.co/internlm/Sage-SciPerception/blob/main/projectors/glm-5.3-flash/spectra/qm9s/config.json) |
+| `ecg/phu01` | 1068 | [Weights](https://huggingface.co/internlm/Sage-SciPerception/resolve/main/projectors/glm-5.3-flash/ecg/phu01/projector.safetensors?download=true) | [config.json](https://huggingface.co/internlm/Sage-SciPerception/blob/main/projectors/glm-5.3-flash/ecg/phu01/config.json) |
+| `dna/splice` | 50 | [Weights](https://huggingface.co/internlm/Sage-SciPerception/resolve/main/projectors/glm-5.3-flash/dna/splice/projector.safetensors?download=true) | [config.json](https://huggingface.co/internlm/Sage-SciPerception/blob/main/projectors/glm-5.3-flash/dna/splice/config.json) |
+| `eeg/neu06` | 4688 | [Weights](https://huggingface.co/internlm/Sage-SciPerception/resolve/main/projectors/glm-5.3-flash/eeg/neu06/projector.safetensors?download=true) | [config.json](https://huggingface.co/internlm/Sage-SciPerception/blob/main/projectors/glm-5.3-flash/eeg/neu06/config.json) |
+| `rna/ncrna` | 200 | [Weights](https://huggingface.co/internlm/Sage-SciPerception/resolve/main/projectors/glm-5.3-flash/rna/ncrna/projector.safetensors?download=true) | [config.json](https://huggingface.co/internlm/Sage-SciPerception/blob/main/projectors/glm-5.3-flash/rna/ncrna/config.json) |
+| `xrd/simxrd` | 500 | [Weights](https://huggingface.co/internlm/Sage-SciPerception/resolve/main/projectors/glm-5.3-flash/xrd/simxrd/projector.safetensors?download=true) | [config.json](https://huggingface.co/internlm/Sage-SciPerception/blob/main/projectors/glm-5.3-flash/xrd/simxrd/config.json) |
+| `protein-struct/psr` | 200 | [Weights](https://huggingface.co/internlm/Sage-SciPerception/resolve/main/projectors/glm-5.3-flash/protein-struct/psr/projector.safetensors?download=true) | [config.json](https://huggingface.co/internlm/Sage-SciPerception/blob/main/projectors/glm-5.3-flash/protein-struct/psr/config.json) |
 
-Download this repository (or the selected component plus the two root Python modules), then install `torch` and `safetensors`.
+## Scientific inputs
+
+The following is an interface summary. Exact feature extraction and preprocessing must match each checkpoint's `scientific_inputs`; arbitrary tensors with the same shape do not reproduce its scientific behavior.
+
+| Task | Input to the projector | Scientific dependency |
+|---|---|---|
+| `cif/jarvis` | 64-dimensional state per atom, plus per-atom position indices | CHGNet 0.3.0 states entering the energy MLP |
+| `protein-seq/mpbind` | 1,280-dimensional state per residue; 2-dimensional side features; residue counts | ESM-2 states plus a task-adapted ESMC readout; the adapted weights and side-feature construction are not included |
+| `spectra/qm9s` | 50-dimensional spectral patches, positions, and a 3-way spectrum-type index | DiffSpectra-style `log10(x + 1)` transform and patch geometry for IR, Raman, and UV-Vis |
+| `ecg/phu01` | 768-dimensional cached position features | The ECG encoder/cache pipeline used for the released checkpoint; extraction runner is not included |
+| `dna/splice` | One 3-dimensional probability readout | Task-adapted DNABERT-2; its scientific weights are not included |
+| `eeg/neu06` | 512-dimensional patch states with matching electrode and time positions | REVE-base with the position and tail-window handling declared in the configuration |
+| `rna/ncrna` | 640-dimensional RNA-FM state per nucleotide; 13-dimensional side input | RNA-FM plus a task-adapted RiNALMo ensemble readout; adapted weights and the full ensemble preprocessing are not included |
+| `xrd/simxrd` | 110 convolutional states, each 512-dimensional | The legacy XRD CNN and its normalized 3,501-point, square-root input pipeline; scientific weights are not included |
+| `protein-struct/psr` | 384-dimensional state per residue/bin | ProteinMPNN v48-020; concatenate its three encoder layers, then use at most 256 contiguous mean bins |
+
+The task-adapted scientific checkpoint paths in the configurations describe dependencies; those paths are not downloadable encoder directories in this release. Some encoder metadata records an upstream component but not the complete preparation pipeline. The [vLLM crystal example](https://huggingface.co/internlm/Sage-SciPerception/blob/main/examples/vllm_cif.py) shows the serving path from prepared features; raw scientific inputs require the matching preprocessing pipeline.
+
+## Local loading
+
+Install `torch` and `safetensors`. From a downloaded repository containing the two root modules:
 
 ```python
 from load_projector import load_projector
 
-model, config = load_projector("projectors/glm-5.3-flash/cif/jarvis")
+projector, config = load_projector("projectors/glm-5.3-flash/cif/jarvis", device="cpu")
 ```
 
-The loader returns the projector module and its configuration. Supply the scientific representation declared in `scientific_inputs`, and use the exact language backbone revision and prompt declared in `config.json`.
+This returns a frozen projector module in evaluation mode and its configuration. It does not load scientific encoders, the language backbone, or a complete generation pipeline. Consult the input table above before calling the projector for another task.
 
-Scientific encoder weights and the language backbone are separate dependencies. Task-adapted encoder weights referenced by these configurations are not included in this projector-only release. The loader does not provide an end-to-end scientific input processing or generation pipeline.
+For integration questions or missing assets, [open a GitHub issue](https://github.com/InternLM/Sage-SciPerception/issues/new) with the task, input format, and the step you want to run.