本文记录了在本地服务器上成功部署 SpaceLLaVA 多模态推理系统的全过程，重点解决了空间不足、NumPy 兼容性、模型加载失败（clip.has_text_encoder）等常见疑难问题，最终成功实现 llama.cpp + CUDA 后端的轻量化推理。

---

✅ 环境说明

• 系统：Ubuntu 20.04

• GPU：NVIDIA RTX 3090 ×1

• CUDA：12.1

• Conda 环境：Python 3.10

• llama-cpp-python：v0.2.45（cublas 加速）

• PyTorch：2.2.2+cu121

---

🧱 步骤一：新建 Conda 环境并准备缓存路径（避免磁盘爆满）

默认 / 分区空间非常小（约 20MB 剩余），必须显式指定临时缓存目录为大容量挂载盘。

conda create -n llama_cpp python=3.10 -y
conda activate llama_cpp

# 建议提前创建 pip 临时目录，避免“no space left on device”
mkdir -p /data1/maliang/tmp/pip_temp
mkdir -p /data1/maliang/tmp/pip_cache

---

🧱 步骤二：安装 llama-cpp-python（开启 CUDA cublas 加速）

TMPDIR=/data1/maliang/tmp/pip_temp \
PIP_NO_CACHE_DIR=off \
PIP_CACHE_DIR=/data1/maliang/tmp/pip_cache \
CMAKE_ARGS="-DLLAMA_CUBLAS=on" \
pip install llama-cpp-python==0.2.45 --force-reinstall

• 注意：编译时默认使用 /tmp 目录，若 /tmp 关联在 / 分区（空间小）会失败，务必指定 TMPDIR

• 推荐使用 --force-reinstall 避免使用 pip 缓存中的旧编译结果

---

🧱 步骤三：安装匹配版本的 PyTorch（cu121）

TMPDIR=/data1/maliang/tmp/pip_temp \
PIP_CACHE_DIR=/data1/maliang/tmp/pip_cache \
pip install torch==2.2.2+cu121 torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

如果遇到以下错误：

OSError: [Errno 28] No space left on device

依然是由于默认临时路径在 /tmp，请确认 TMPDIR 已正确指定到大容量目录（如 /data1/...）

---

🧱 步骤四：下载 SpaceLLaVA 模型权重（gguf 格式）

# LLaMA 主干模型（量化后）
wget -O ggml-model-q4_0.gguf "https://huggingface.co/remyxai/SpaceLLaVA/resolve/main/ggml-model-q4_0.gguf?download=true"

# 多模态投影头（CLIP）
wget -O mmproj-model-f16.gguf "https://huggingface.co/remyxai/SpaceLLaVA/resolve/main/mmproj-model-f16.gguf?download=true"

---

 🧱 步骤五：修复 NumPy 2.x 与 PyTorch 编译不兼容问题

🚩 尝试运行模型推理代码

import os
os.environ["CUDA_VISIBLE_DEVICES"] = "7"
import io
import base64
import numpy as np
import torch
from PIL import Image

from llama_cpp import Llama
from llama_cpp.llama_chat_format import Llava15ChatHandler



def image_to_base64_data_uri(image_input):
    # Check if the input is a file path (string)
    if isinstance(image_input, str):
        with open(image_input, "rb") as img_file:
            base64_data = base64.b64encode(img_file.read()).decode('utf-8')

    # Check if the input is a PIL Image
    elif isinstance(image_input, Image.Image):
        buffer = io.BytesIO()
        image_input.save(buffer, format="PNG")  # You can change the format if needed
        base64_data = base64.b64encode(buffer.getvalue()).decode('utf-8')

    else:
        raise ValueError("Unsupported input type. Input must be a file path or a PIL.Image.Image instance.")

    return f"data:image/png;base64,{base64_data}"



mmproj=r"/data1/xxx/SpatialVLM/SpaceLLaVA/SpaceLLaVA/mmproj-model-f16.gguf"
model_path=r"/data1/xxx/SpatialVLM/SpaceLLaVA/SpaceLLaVA/ggml-model-q4_0.gguf"
chat_handler = Llava15ChatHandler(clip_model_path=mmproj, verbose=True)
spacellava = Llama(model_path=model_path, chat_handler=chat_handler, n_ctx=2048, logits_all=True, n_gpu_layers = -1)


# @title Set your image and prompt
image_path =r'/data1/vincia/data/xxx/000_1.png' # @param {type:"string"}
prompt = r'How many blocks are there?' # @param {type:"string"}


data_uri = image_to_base64_data_uri(image_path)
messages = [
    {"role": "system", "content": "You are an assistant who perfectly describes images."},
     {
         "role": "user",
         "content": [
             {"type": "image_url", "image_url": {"url": data_uri}},
              {"type" : "text", "text": prompt}
             ]
         }
    ]
results = spacellava.create_chat_completion(messages = messages)
print(results["choices"][0]["message"]["content"])

 🚩 NumPy 2.x 与 PyTorch 编译不兼容问题

在运行时可能会遇到致命错误：

A module that was compiled using NumPy 1.x cannot be run in NumPy 2.2.6 as it may crash...

解决办法：降级回 NumPy 1.x 安全版本：

TMPDIR=/data1/maliang/tmp/pip_temp \
PIP_CACHE_DIR=/data1/maliang/tmp/pip_cache \
pip install numpy==1.26.4 --force-reinstall

解释：NumPy 2.x 引入 ABI 不兼容变更，导致 PyTorch、某些 C/CUDA 模块全部崩溃。

---

🎉 步骤六：再次运行推理代码，成功

python infer.py

如果一切正常，应该能看到模型成功加载、CUDA 初始化，并输出结果：

---

🧨 常见错误 & 排查

❌ 1. OSError: [Errno 28] No space left on device

• 根源：pip 编译缓存写入了 /tmp（实际上是根分区）

• 解决：显式设置 TMPDIR=/data1/... 且提前创建 pip_cache

---

❌ 2. A module that was compiled using NumPy 1.x cannot be run in NumPy 2.2.6...

• 根源：PyTorch 目前编译基于 NumPy 1.x，无法运行在 NumPy 2.x 上

• 解决：降级 NumPy：pip install numpy==1.26.4

---

❌ 3. Aborted (core dumped) + key clip.has_text_encoder not found in file

• 根源：加载的 .gguf 模型缺失 CLIP 编码器元数据（SpaceLLaVA 特有）

• 解决：检查代码的模型路径，mmproj 和 model_path 切换为服务器本地路径

---

✅ 参考资料

• 🤗 模型链接：remyxai/SpaceLLaVA - Hugging Face

• 📓 官方 Colab Notebook 示例（含图片推理）：SpaceLLaVA Colab Demo

---

✅ 最终目录结构建议

SpatialVLM/
├── infer.py
├── ggml-model-q4_0.gguf
└── mmproj-model-f16.gguf

---

✅ 总结

本地部署 SpaceLLaVA 时，建议提前规划：

项目	建议值
Python	3.10
llama-cpp-python	v0.2.45 + CUBLAS
PyTorch	2.2.2 + cu121
NumPy	1.26.4
临时目录	显式设置 TMPDIR