llama-cpp-python用法，模型加载gpu踩坑全记录
llama-cpp-python的主分支貌似很久不更新了，直接pip install用有问题，因为安装时候他会自动编译最新版的llama-cpp，但是这个llama-cpp接口变了的话而llama-cpp-python没及时更新就会报错。因此我用的另一个分支：https://github.com/JamePeng/llama-cpp-python
模型要加载到gpu有几种方法，加载到核显，以及使用cuda。一般使用cuda，我也想过加载到核显，因为我用lamasudio就能加载到核显，感觉很强，自己也想做然后发现其实挺麻烦的就放弃了，也没必要，用cuda独显才是主流的。
然后显卡不需要太好，我就两个机器，1660ti 1080ti都能跑的挺不错。
显卡要装两个东西
1、显卡驱动，这个直接升级到最新就行了，显示支持cuda 13就够了，
如果要手动下载：
2、CUDA Toolkit（nvcc ），需要达到13.0
下载地址（NVIDIA 官方稳定版）：https://developer.nvidia.com/
如果CUDA Toolkit存在旧版本需要先卸载再安装
安装完成后检查两个cuda环境变量是否自动加了
# 验证nvcc（编译器）版本（核心！必须显示13.2） nvcc -V
# 验证驱动和CUDA运行时兼容性 nvidia-smi
nvidia-smi输出右上角显示「CUDA Version: 13.2」，驱动版本≥535.54.03。
nvcc -V输出示例（关键看 release 13.2）：plaintext
nvcc: NVIDIA (R) Cuda compiler driver Copyright (c) 2005-2023 NVIDIA Corporation Built on Tue_Aug_15_22:02:13_Pacific_Daylight_Time_2023 Cuda compilation tools, release 13.2, V13.2.152 Build cuda_13.2.r13.2/compiler.33053471_0 然后，安装llama-cpp-python，最好的办法就是下载他的release的轮子，我下载的是llama_cpp_python-0.3.24+cu130.basic-cp310-cp310-win_amd64.whl
cu130就是cuda版本，cp310就是python3.10
安装后，就可以用了。
我用的QWEN视觉模型，加载到gpu快了不少，。要注意这个需要加载两个gguf文件。写法也比较特殊（摸索了很久）
以下是一个测试脚本：
#!/usr/bin/env python3 # -*- coding: utf-8 -*- """ 加载两个 GGUF（主模型 + 视觉编码器 mmproj）。 """ import os from llama_cpp import Llama import llama_cpp.llama_chat_format as llama_chat_format # ============ 路径配置（按你本机修改） ============ # 主模型 GGUF（文本 + 推理） MODEL_PATH = os.path.join( os.path.dirname(__file__), "..", "LamacppServer", "models", "Qwen3-VL-4B-Instruct-Q4_K_M.gguf" ) # 视觉编码器 GGUF（mmproj，处理图像）；须与主模型配套（同尺寸/同系列） MMPROJ_PATH = os.path.join( os.path.dirname(__file__), "..", "LamacppServer", "models", "mmproj-Qwen3-VL-4B-Instruct-F16.gguf" ) # 也可直接写绝对路径，例如： MODEL_PATH = r".\models\Qwen3-VL-4B-Instruct-Q4_K_M.gguf" MMPROJ_PATH = r".\models\mmproj-Qwen3-VL-4B-Instruct-F16.gguf" def main(): # 确保两个文件存在 if not os.path.isfile(MODEL_PATH): raise FileNotFoundError(f"主模型不存在: {MODEL_PATH}") if not os.path.isfile(MMPROJ_PATH): raise FileNotFoundError(f"视觉模型(mmproj)不存在: {MMPROJ_PATH}") chat_handler = llama_chat_format.Qwen25VLChatHandler( clip_model_path=MMPROJ_PATH, verbose=True, ) # 纯 CPU：n_gpu_layers=0，不卸载任何层到 GPU llm = Llama( model_path=MODEL_PATH, chat_handler=chat_handler, # clip_model_path=MMPROJ_PATH, n_gpu_layers=-1, # 全部在 CPU n_ctx=10240, # 上下文长度，可按需调大 n_threads=os.cpu_count() or 4, verbose=True, ) # ---------- 图文对话示例（可选） ---------- # 若需“图+文”输入，把下面几行取消注释并改成你的图片路径 import base64 image_path = "test.png" # 或任意图片路径 with open(image_path, "rb") as f: b64 = base64.b64encode(f.read()).decode() url = f"data:image/png;base64,{b64}" image_path = "test2.png" # 或任意图片路径 with open(image_path, "rb") as f: b64 = base64.b64encode(f.read()).decode() url2 = f"data:image/png;base64,{b64}" resp2 = llm.create_chat_completion( messages=[{ "role": "user", "content": [ { "type": "text", "text": "请告诉我 图1和 图2 分别是什么"}, { "type": "image_url", "image_url": { # 注意这里的格式：需要添加data URI前缀 "url": f"{url}" } }, { "type": "image_url", "image_url": { # 注意这里的格式：需要添加data URI前缀 "url": f"{url2}" } } ] }], max_tokens=10000, ) print(resp2["choices"][0]["message"]["content"]) if __name__ == "__main__": main() 
