本地大模型报错速查
把卡住你的那一行报错贴过来对照。每一条都从项目源码里逐字核对，说明含义，并给出带真实参数和命令的解决办法。
19 条报错
显存不足
- llama.cppCUDA error: out of memory 怎么解决
CUDA error: out of memoryllama.cpp 向显卡申请显存时已经没有剩余：权重、你设定的上下文所需的 KV 缓存和计算缓冲区加起来，超过了显卡的空闲显存。 - llama.cppunable to allocate CUDA0 buffer 报错
unable to allocate CUDA0 bufferllama.cpp 加载模型时，没能在这块设备上为权重分配到空间。设备名随后端不同而变化：CUDA0、ROCm0、Vulkan0 或 Metal。 - llama.cppfailed to allocate buffer for kv cache 报错
failed to allocate buffer for kv cache权重已经加载成功，但按你要求的上下文长度，已经没有空间放 KV 缓存。后面通常还会跟一行 "failed to initialize the context"。 - llama.cppMac 上 Metal failed to allocate buffer
ggml_metal_buffer_init: error: failed to allocate buffer, size = <n> MiB在 Mac 上，llama.cpp 没能从 Metal 拿到这么大的 GPU 缓冲区。macOS 默认只允许 GPU 使用统一内存的一部分 —— 大多数机器上约为四分之三。 - vLLMCUDA out of memory. Tried to allocate 报错
CUDA out of memory. Tried to allocate <n> GiB. GPU 0 has a total capacity of <n> GiB of which <n> MiB is free.vLLM 和 Transformers 底层的 PyTorch 没能分配下一个张量。在 vLLM 里，这通常意味着按你给的设置，模型加上预留的 KV 缓存装不下。 - vLLMvLLM 启动报 Free memory on device 不足
Free memory on device <dev> (<free>/<total> GiB) on startup is less than desired GPU memory utilization (<u>, <n> GiB). Decrease GPU memory utilization or reduce GPU memory used by other processes.vLLM 启动时会预留显卡的固定比例（--gpu-memory-utilization，当前版本不设时为 0.92）。显卡已经被别的东西占用了一部分，这个比例的显存已经不空闲。
模型文件的问题
- llama.cppllama.cpp 报 unknown model architecture
llama_model_load: error loading model: unknown model architecture: '<arch>'这个 GGUF 文件所属的模型架构，你用的 llama.cpp 版本还不认识。新架构会先合入 llama.cpp，Ollama 和 LM Studio 要等更新内置的 llama.cpp 后才支持。 - llama.cppllama.cpp 报 wrong number of tensors
done_getting_tensors: wrong number of tensors; expected <n>, got <m>文件里的张量数量和这个版本的 llama.cpp 对该架构的预期不一致 —— 文件和程序对模型结构的理解不同。类似的报错还有 "tensor … has wrong shape"。 - llama.cppinvalid magic characters：不是 GGUF 文件
gguf_init_from_reader: invalid magic characters: '<xxxx>', expected 'GGUF'每个 GGUF 文件都以 "GGUF" 这四个字节开头。这个文件不是，所以它根本不是 GGUF 文件 —— 通常是网页、Git LFS 指针文件，或改名成 .gguf 的 safetensors 文件。
没用上显卡
- llama.cppfailed to initialize CUDA：没识别到显卡
ggml_cuda_init: failed to initialize CUDA: <reason>CUDA 版本的 llama.cpp 启动了，但连接不上任何 NVIDIA 显卡，于是退回 CPU 运行。冒号后面是 CUDA 自己给出的原因。 - DockerDocker 报 could not select device driver
could not select device driver "" with capabilities: [[gpu]]Docker 收到了使用 GPU 的请求（--gpus all），但没有注册任何 GPU 设备驱动。在 NVIDIA 上，这个驱动来自 NVIDIA Container Toolkit，它没有安装或没有配置好。 - OllamaOllama 显示 100% CPU，没用上显卡
100% CPU`ollama ps` 会显示已加载模型放在哪里。"100% CPU" 表示完全没有放到显卡上；"48%/52% CPU/GPU" 这样的拆分表示显存装不下，有一部分在内存里运行。 - PyTorchsm_120 is not compatible with PyTorch 报错
<GPU> with CUDA capability sm_<nn> is not compatible with the current PyTorch installation.安装的 PyTorch 没有为这一代显卡编译 —— 最常见的是 RTX 50 系（sm_120）配上了为旧 CUDA 编译的 PyTorch。vLLM 和 Transformers 随后会报错或退回 CPU。
AMD 与 ROCm
- ROCmrocBLAS 报错找不到 TensileLibrary.dat
rocBLAS error: Cannot read <path>/TensileLibrary.dat: No such file or directory for GPU arch : gfx<nnnn>rocBLAS 只为 ROCm 支持的显卡型号附带编译好的计算内核。你的显卡型号（末尾的 gfx 编号）不在其中，所以没有可加载的内核文件。 - ROCmHSA_OVERRIDE_GFX_VERSION 怎么设置
HSA_OVERRIDE_GFX_VERSION一个环境变量，让 ROCm 把你的 Radeon 当成相近的受支持型号，从而让 ROCm 版的 Ollama 和 llama.cpp 能用上 ROCm 不支持的显卡。仅限 Linux。
Ollama
- OllamaOllama 报 model may be incompatible
this model may be incompatible with your version of Ollama. If you previously pulled this model, try updating it by running `ollama pull <model>`Ollama 内置的 llama.cpp 加载不了这个文件。要么模型比你的 Ollama 新，要么你很久以前拉取的模型后来被重新发布过。 - OllamaOllama 报 model requires ollama version
model requires ollama version <x.y.z> or newer (current version is v<a.b.c>)模型清单里声明了最低 Ollama 版本，而你的版本更旧。下载本身没问题；Ollama 知道自己跑不了，所以在加载前就拒绝了。 - OllamaOllama 报 model not found, try pulling it first
model "<name>" not found, try pulling it firstAPI 请求的模型名在这台机器上不存在。Ollama 的 API 不会自动下载；模型名必须和已拉取的模型完全一致，包括标签。 - OllamaOllama 报 pull model manifest: file does not exist
pull model manifest: file does not exist仓库里没有这个名字和标签的模型。几乎都是名字拼错，或者这个模型根本没有发布过你写的那个标签，而不是网络或代理的问题。
没找到你的报错？这里没有的，是我们在能读到的源码里没找到原文，所以没有收录。欢迎把完整的日志行发到 zjy@quantized.uk。