| --- |
| library_name: transformers |
| pipeline_tag: feature-extraction |
| tags: |
| - materials-science |
| --- |
| |
| # Diffra 使用指南 |
|
|
| 使用预训练模型从 XRD 图谱提取 embedding。以下命令在 Diffra 项目根目录执行。 |
| 项目代码：[Bin-Cao/Diffra](https://github.com/Bin-Cao/Diffra)。 |
|
|
| ## 1. 选择并下载模型 |
|
|
| | 模型 | 下载子目录 | |
| |---|---| |
| | [Legacy 1B](https://huggingface.co/Licht0812/Diffra/tree/main/Legacy-1B) | `Legacy-1B` | |
| | [Legacy 3B](https://huggingface.co/Licht0812/Diffra/tree/main/Legacy-3B) | `Legacy-3B` | |
| | [Delta 1B](https://huggingface.co/Licht0812/Diffra/tree/main/Delta-1B) | `Delta-1B` | |
| | [Delta 3B](https://huggingface.co/Licht0812/Diffra/tree/main/Delta-3B) | `Delta-3B` | |
|
|
| 以 Legacy 3B 为例： |
|
|
| ```bash |
| hf download Licht0812/Diffra \ |
| --include 'Legacy-3B/*' --include 'tokenizer/*' \ |
| --local-dir output/hub |
| ``` |
|
|
| 下载其他模型时，将 `Legacy-3B` 替换为表中对应名称。四个模型共用 |
| [RVQ tokenizer](https://huggingface.co/Licht0812/Diffra/blob/main/tokenizer/codebook_best.ckpt)。 |
|
|
| ## 2. 准备 XRD 文件 |
|
|
| 输入文件为 `scan.csv`，第一行为 `angle,intensity`，后续两列分别为 |
| $2\theta$ 角度（度）和强度。推理脚本将图谱对齐至 10–90°、3,500 点，并归一化强度。 |
|
|
| ## 3. Legacy 推理 |
|
|
| ```bash |
| python -m foundation.inference \ |
| --model output/hub/Legacy-3B \ |
| --codebook-checkpoint output/hub/tokenizer/codebook_best.ckpt \ |
| --input scan.csv --output xrd_embedding.npz --device cuda |
| ``` |
|
|
| 使用 Legacy 1B 时，将 `--model` 改为 `output/hub/Legacy-1B`。 |
| 使用 CPU 时，将 `--device cuda` 改为 `--device cpu`。 |
|
|
| ## 4. Delta 推理 |
|
|
| Delta 使用 [历史版本的推理代码](https://github.com/Bin-Cao/Diffra/tree/0eef014/DiffraDelta-3B)。 |
| 从 Git 历史提取到 `archive/`，再运行推理： |
|
|
| ```bash |
| mkdir -p archive |
| git archive 0eef014 DiffraDelta-3B | tar -x -C archive |
| |
| python archive/DiffraDelta-3B/inference.py \ |
| --model output/hub/Delta-3B \ |
| --codebook-checkpoint output/hub/tokenizer/codebook_best.ckpt \ |
| --codebook-root codebook \ |
| --input scan.csv --output xrd_embedding.npz --device cuda |
| ``` |
|
|
| 使用 Delta 1B 时，将 `--model` 改为 `output/hub/Delta-1B`。 |
|
|
| ## 5. 读取结果 |
|
|
| 输出文件 `xrd_embedding.npz` 包含 `embedding` 和预处理后的 `aligned_xrd`： |
|
|
| ```python |
| import numpy as np |
| |
| with np.load("xrd_embedding.npz") as result: |
| embedding = result["embedding"] |
| xrd = result["aligned_xrd"] |
| |
| print(embedding.shape) |
| ``` |
|
|
| 单条 XRD 的输出形状为：Legacy `[1,768]`，Delta `[1,1024]`。 |
|
|
