README.md

# pi05_gguf 文件来源说明

本目录用于存放 `openvla.cpp/tools/pi05` 推理所需/相关 GGUF 文件。

## 文件与来源

| 文件 | 来源模型/用途 | 典型生成方式 |
|---|---|---|
| `siglip.gguf` | OpenPI 中 PaliGemma 视觉塔（SigLIP）权重 | `openvla.cpp/tools/pi05/export_pi05_gguf.py` 导出 |
| `paligemma.gguf` | OpenPI 中 `paligemma_with_expert.paligemma.language_model`（pi05 主流程使用） | `openvla.cpp/tools/pi05/export_pi05_gguf.py` 导出 |
| `action_expert.gguf` | OpenPI 中 `paligemma_with_expert.gemma_expert.model`（含 AdaRMS 相关参数） | `openvla.cpp/tools/pi05/export_pi05_gguf.py` 导出 |
| `action_proj.gguf` | 动作输入/输出投影层与时间相关投影参数 | `openvla.cpp/tools/pi05/export_pi05_gguf.py` 导出 |
| `norm_stats.json` | 归一化统计信息（动作/状态后处理） | 来自 OpenPI checkpoint 的 `assets/.../norm_stats.json` |
| `paligemma_tokenizer.model` | PaliGemma SentencePiece tokenizer | 通常来自 `~/.cache/openpi/big_vision/paligemma_tokenizer.model` |
| `paligemma_f16.gguf` | 单独导出的 Gemma language model（F16 版本） | HF 导出后，用 `convert_hf_to_gguf.py --outtype f16` |
| `paligemma_bf16.gguf` | 单独导出的 Gemma language model（BF16 版本） | HF 导出后，用 `convert_hf_to_gguf.py --outtype bf16` |
| `paligemma_q8_0.gguf` | `paligemma_f16.gguf` 或 `paligemma_bf16.gguf` 的量化版本 | `llama-quantize ... q8_0` |
| `paligemma_tokenizer.lock` | tokenizer 相关锁文件 | 运行时产生，可忽略 |

## 主要导出脚本

1. Pi0.5 拆分导出（`siglip.gguf` / `paligemma.gguf` / `action_expert.gguf` / `action_proj.gguf`）

```bash
cd /home/ubuntu/data_1/chenxing/openvla.cpp/tools/pi05
python export_pi05_gguf.py \
  --checkpoint_dir /home/ubuntu/data_1/chenxing/openpi/pi05_droid_pytorch/model \
  --output_dir /home/ubuntu/data_1/chenxing/pi05_gguf \
  --config_name pi05_droid
```

2. 单独导出 Gemma language model（HF -> GGUF）

```bash
# 先导出 HF 目录（见export_hf_language_model.py）
python /home/ubuntu/data_1/chenxing/openpi/export_hf_language_model.py

# 再转 GGUF（主干 BF16 + norm 保留 F32”的混合精度导出）
python /home/ubuntu/data_1/chenxing/openvla.cpp/convert_hf_to_gguf.py \
  /home/ubuntu/data_1/chenxing/openpi/pi05_paligemma_lang_hf \
  --outfile /home/ubuntu/data_1/chenxing/pi05_gguf/paligemma_bf16.gguf \
  --outtype bf16
```

3. 量化为 Q8_0

```bash
cd /home/ubuntu/data_1/chenxing/openvla.cpp/build/bin
./llama-quantize \
  /home/ubuntu/data_1/chenxing/pi05_gguf/paligemma_bf16.gguf \
  /home/ubuntu/data_1/chenxing/pi05_gguf/paligemma_q8_0.gguf \
  q8_0
```

## 使用建议

1. `tools/pi05` 主流程优先使用同批次导出的四件套：`siglip.gguf`、`paligemma.gguf`、`action_expert.gguf`、`action_proj.gguf`。
2. `paligemma_f16/bf16/q8_0.gguf` 主要用于语言干路对比或单模型转换验证，不应与不匹配批次的 expert/proj 混用。
3. 若出现结果偏移，先确认：模型文件是否同批次、tokenizer 是否一致、norm 语义是否重复处理。