Diffra 使用指南

使用预训练模型从 XRD 图谱提取 embedding。以下命令在 Diffra 项目根目录执行。 项目代码：Bin-Cao/Diffra。

1. 选择并下载模型

模型	下载子目录
Legacy 1B	Legacy-1B
Legacy 3B	Legacy-3B
Delta 1B	Delta-1B
Delta 3B	Delta-3B

以 Legacy 3B 为例：

hf download Licht0812/Diffra \
  --include 'Legacy-3B/*' --include 'tokenizer/*' \
  --local-dir output/hub

下载其他模型时，将 Legacy-3B 替换为表中对应名称。四个模型共用 RVQ tokenizer。

2. 准备 XRD 文件

输入文件为 scan.csv，第一行为 angle,intensity，后续两列分别为 $2\theta$ 角度（度）和强度。推理脚本将图谱对齐至 10–90°、3,500 点，并归一化强度。

3. Legacy 推理

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 使用 历史版本的推理代码。 从 Git 历史提取到 archive/，再运行推理：

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：

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]。