# Jetson Orin NX 部署技术路线：Open3DVQA Qwen3-VL 4B 蒸馏模型

## 1. 当前结论

本目录已经生成并本地验证了 Qwen3-VL GGUF 部署产物，可通过 llama.cpp 和 Ollama 运行：

```text
student_4b_merged-Q4_K_M.gguf          # 文本/LLM 主模型，Q4_K_M 量化
mmproj-student_4b_merged-f16.gguf      # 视觉 encoder + projector，F16
Modelfile.ollama                       # Ollama 导入配置
```

本地 smoke test 已通过：

- `llama-mtmd-cli` 成功加载 Q4_K_M 主模型和 F16 mmproj，并对验证集图片回答 `A.Yes`。
- Ollama `0.30.8` 成功导入同一组 GGUF 文件，并通过 `/api/chat` 图片接口回答 `A.Yes`。

重要说明：Qwen3-VL 是视觉语言模型，不是普通纯文本 LLM。完整推理需要 **两个 GGUF 文件**：

```text
text model GGUF + mmproj GGUF
```

只上传/加载 `student_4b_merged-Q4_K_M.gguf` 不能完成图片理解。

## 2. Ollama 路线的结论

你的原始设想是：

```text
LoRA merged HF 模型 -> GGUF -> Ollama 支持的 q4_K_M -> 上传 -> Orin NX 下载部署
```

这个思路对本模型可行，但必须保留视觉投影文件。Qwen3-VL 需要 `mmproj`，不能只上传主模型 GGUF。

当前本机已验证：

```text
Ollama Modelfile: FROM Q4_K_M 主模型 + ADAPTER F16 mmproj
Ollama API: 使用 /api/chat，不使用 /api/generate
输入: messages[].images 传 base64 图片
输出: A.Yes
```

`/api/generate` 虽然能触发图像处理，但本次验证中返回空字符串；`/api/chat` 是当前可用路径。

## 3. 已完成的转换流程

### 3.1 HF merged 模型

输入：

```text
outputs/open3d_vqa/student_4b_merged
```

这是 LoRA 合并后的完整 4B 学生模型。

### 3.2 导出 F16 text GGUF

```bash
python tools/llama.cpp/convert_hf_to_gguf.py \
  outputs/open3d_vqa/student_4b_merged \
  --outfile outputs/open3d_vqa/jetson_ollama_gguf/student_4b_merged-f16.gguf \
  --outtype f16
```

### 3.3 导出 F16 mmproj GGUF

```bash
python tools/llama.cpp/convert_hf_to_gguf.py \
  outputs/open3d_vqa/student_4b_merged \
  --mmproj \
  --outfile outputs/open3d_vqa/jetson_ollama_gguf/mmproj-student_4b_merged-f16.gguf \
  --outtype f16
```

### 3.4 Q4_K_M 量化 text GGUF

```bash
tools/llama.cpp/build/bin/llama-quantize \
  outputs/open3d_vqa/jetson_ollama_gguf/student_4b_merged-f16.gguf \
  outputs/open3d_vqa/jetson_ollama_gguf/student_4b_merged-Q4_K_M.gguf \
  Q4_K_M
```

注意：mmproj 通常保留 F16，不做 Q4_K_M K-quant。

## 4. 当前文件大小

| 文件 | 作用 | 大小 |
|---|---|---:|
| `student_4b_merged-Q4_K_M.gguf` | Q4_K_M 主模型 | 约 2.4G |
| `mmproj-student_4b_merged-f16.gguf` | 视觉 mmproj | 约 798M |
| 合计 | 可部署最小组合 | 约 3.2G |
| `student_4b_merged-f16.gguf` | 中间 F16 文件，可不上传 | 约 7.5G |

建议上传部署时只上传：

```text
student_4b_merged-Q4_K_M.gguf
mmproj-student_4b_merged-f16.gguf
Modelfile.ollama
README_JETSON_ORIN_NX_DEPLOY.md
```

## 5. Jetson Orin NX 备用部署方式：llama.cpp

### 5.1 在 Jetson 上编译 llama.cpp

Jetson Orin NX 上如果 Ollama 不稳定，可以编译 llama.cpp CUDA/cuBLAS 后端：

```bash
git clone https://github.com/ggml-org/llama.cpp.git
cd llama.cpp
cmake -S . -B build -G Ninja -DGGML_CUDA=ON -DLLAMA_OPENSSL=OFF
cmake --build build --target llama-mtmd-cli llama-server -j$(nproc)
```

如果没有 Ninja：

```bash
sudo apt-get update
sudo apt-get install -y cmake ninja-build build-essential git
```

### 5.2 本地命令行测试

```bash
./build/bin/llama-mtmd-cli \
  -m /path/to/student_4b_merged-Q4_K_M.gguf \
  --mmproj /path/to/mmproj-student_4b_merged-f16.gguf \
  --image /path/to/test.jpg \
  -p "Describe the image." \
  -n 64 \
  -c 4096 \
  --image-min-tokens 1024 \
  --temp 0
```

`--image-min-tokens 1024` 是 llama.cpp 对 Qwen-VL 的提示建议，用于提升 grounding 任务稳定性。

## 6. Ollama 部署方式

Jetson 上安装 Ollama 官方方式：

```bash
curl -fsSL https://ollama.com/install.sh | sh
```

官方安装脚本会检测 Jetson `/etc/nv_tegra_release`，并下载对应 JetPack 包：

```text
ollama-linux-arm64-jetpack6
ollama-linux-arm64-jetpack5
```

本机已验证的 Modelfile：

```text
FROM ./student_4b_merged-Q4_K_M.gguf
ADAPTER ./mmproj-student_4b_merged-f16.gguf
PARAMETER temperature 0
PARAMETER num_ctx 4096
```

创建模型：

```bash
ollama create open3dvqa-qwen3vl:4b-q4km -f Modelfile.ollama
```

图片问答 API 示例：

```python
import base64
import json
import urllib.request

img_path = "test.jpg"
payload = {
    "model": "open3dvqa-qwen3vl:4b-q4km",
    "messages": [
        {
            "role": "user",
            "content": "Does the blue and white apartment building appear over the cluster of cars in foreground?\nA.Yes.\nB.No.\nAnswer with exactly one option.",
            "images": [base64.b64encode(open(img_path, "rb").read()).decode()],
        }
    ],
    "stream": False,
    "options": {"temperature": 0, "num_predict": 16, "num_ctx": 4096},
}

opener = urllib.request.build_opener(urllib.request.ProxyHandler({}))
req = urllib.request.Request(
    "http://127.0.0.1:11434/api/chat",
    data=json.dumps(payload).encode(),
    headers={"Content-Type": "application/json"},
)
print(opener.open(req, timeout=600).read().decode())
```

注意：当前服务器环境存在 `http_proxy=127.0.0.1:7890`，访问本机 Ollama API 时必须绕过代理，否则会得到代理返回的 `502 Bad Gateway`。可使用：

```bash
env -u http_proxy -u https_proxy -u HTTP_PROXY -u HTTPS_PROXY \
  NO_PROXY=127.0.0.1,localhost no_proxy=127.0.0.1,localhost \
  python your_ollama_client.py
```

## 7. 上传建议

建议上传到 Hugging Face Hub，目录结构：

```text
student_4b_merged-Q4_K_M.gguf
mmproj-student_4b_merged-f16.gguf
Modelfile.ollama
README.md
```

建议仓库名：

```text
open3dvqa-qwen3vl-4b-distill-q4_k_m-gguf
```

## 8. 当前本机验证命令

本机已通过以下命令验证 llama.cpp：

```bash
tools/llama.cpp/build/bin/llama-mtmd-cli \
  -m outputs/open3d_vqa/jetson_ollama_gguf/student_4b_merged-Q4_K_M.gguf \
  --mmproj outputs/open3d_vqa/jetson_ollama_gguf/mmproj-student_4b_merged-f16.gguf \
  --image data/open3d_vqa/sharegpt_sample/images/UrbanScene_Residence_33_RGBVis_300.png \
  -p 'Does the blue and white apartment building appear over the cluster of cars in foreground?
A.Yes.
B.No.' \
  -n 16 \
  -c 4096 \
  -t 8 \
  --temp 0
```

输出：

```text
A.Yes
```

本机 Ollama 验证结果：

```text
Ollama version: 0.30.8
Model: open3dvqa-qwen3vl:adapter
Loaded runner VRAM: 3.3 GiB
API: /api/chat
Image prompt result: A.Yes
Total duration: 7.80 s after model load/cache warmup
Prompt eval: 1074 tokens, 7.07 s
Decode: 3 tokens, 0.014 s
```

## 9. 下一步

1. 删除或不上传中间文件 `student_4b_merged-f16.gguf`，节省空间。
2. 上传 `Q4_K_M.gguf + mmproj.gguf + Modelfile.ollama` 到 Hugging Face Hub 或其他文件服务。
3. 在 Jetson Orin NX 上优先尝试 Ollama `ollama create` + `/api/chat`。
4. 如果 JetPack 5 上的 Ollama 包不能稳定运行 Qwen3-VL，则回退到本机已验证的 llama.cpp/llama-mtmd-cli 路线。