llama.cpp 在网络盘上 mmap 失败
llama.cpp 从 NFS、SMB 或 CIFS 网络盘加载 GGUF 模型时崩溃或卡顿。最快修复：加 --no-mmap（DirectIO 开着时再加 --no-direct-io），或把模型拷到本地盘。
#local-llm
带有该标签的文章
llama.cpp 换更激进量化后质量明显下降
从 Q5_K_M 或 Q8_0 换到 Q4_0、IQ4_XS 或更低量化后输出变差：选对量化档位、修复劣质重量化文件，并用 perplexity 验证。
LM Studio 加载模型时报 out of memory
LM Studio 加载 GGUF 模型时崩溃或报 out of memory。先降 Context Length、开 Flash Attention、调 GPU offload 即可解决，附按显存分级的选型表。
本地 embedding 服务在 batch 请求下崩溃
Ollama、llama-server、vLLM 或 sentence-transformers 批量 embedding 时 OOM 崩溃或返回 500。从 batch size、num_batch、序列长度、并发四方面定位修复，附确切参数。
Chat-Template 不匹配导致本地 LLM 输出乱码
本地 LLM 把你的问题原样吐回、在回复里夹着 [INST] 或 <|im_start|> 标签、或者一句话重复个没完，这都是 chat-template 不匹配。教你找到模型真正的模板，并强制引擎使用它。
多 GPU 没分配上，模型只跑在卡 0
本地 LLM 只用一张卡，其余卡 0% 空闲。用 llama.cpp --split-mode、vLLM --tensor-parallel-size、Ollama 自动分布，以及 PCIe 机器需要的 NCCL 参数把它分到多卡上。
本地模型输出在 token 中间被截断（Ollama / llama.cpp）
本地模型生成到一半停在单词或汉字中间，没有 EOS、没有报错。逐一排查 num_predict 上限、按显存推算的 num_ctx 默认值、stop 序列、代理缓冲与 UTF-8 字节切割。
RoPE scaling 设错让长上下文输出乱掉
本地模型在原生上下文长度内正常，超过后就开始重复、乱码。手把手诊断并修复 llama.cpp 和 vLLM 的 RoPE scaling（YaRN、llama3、rope_theta）配置。
本地模型冷启动后首 token 极慢
本地 LLM 加载后首 token 要等 30-120 秒，之后就很快。定位磁盘 I/O、模型被卸载、CUDA/Metal shader 编译、KV cache 分配等冷启动瓶颈，并把模型常驻内存。
Tokenizer 漂移：本地模型 token 计数对不上
应用层的 token 计数与本地 llama.cpp 或 Ollama 服务对不上，导致上下文溢出或静默截断。用服务端自带的 tokenizer 作为基准来消除漂移。
本地模型不遵守 tool calling 格式
本地 LLM 返回纯文本描述而不是 JSON 工具调用，或格式错误导致解析失败。用支持 tool calling 的模型、llama-server 的 --jinja 参数和 Ollama 的 format JSON Schema 约束彻底修好。
本地 RAG 索引重建慢到无法忍受
本地向量索引重建从几分钟拖到数小时？修正 batch 大小、跳过未变文档、批量写入向量库、合理设置 chunk 大小，把 6 小时降到 15 分钟内。
mlx_lm.convert 转换 HuggingFace 模型失败
在 Apple Silicon 上用 mlx_lm.convert 把 HuggingFace 模型转成 MLX 时报错：Model type not supported、GatedRepoError 401 或内存不足 OOM。修复步骤已于 2026 年 6 月核实。
Ollama pull 卡住或下载进度回退 — 修复方法
ollama pull 停在某个百分比、进度条往回跑、或报 max retries exceeded: EOF。分析网络、磁盘、partial 分片三类原因，给出可干净续传的修复步骤。
Ollama 探测不到 GPU，全跑在 CPU
Ollama 启动后模型在 CPU 上运行，生成极慢。读懂 inference-compute 日志，定位驱动、CUDA、ROCm 不匹配，强制开启 GPU 卸载。
Ollama pull 成功但 ollama list 看不到
ollama pull 显示 success，但 ollama list 里没有这个模型，运行时报 model not found。修复 OLLAMA_MODELS 路径分裂、ollama 服务用户不一致、manifest 损坏等根因。
Ollama Modelfile 里的 SYSTEM prompt 被忽略
Ollama Modelfile 的 SYSTEM 设置对模型行为毫无效果。最快修复：确认 TEMPLATE 真的渲染了 .System、排查 RENDERER/PARSER 继承覆盖、阻止客户端覆盖 system 消息。
修复 Ollama 端口被占用 (11434)
Ollama 因 11434 端口被占用而无法启动。教你定位占用进程、释放端口，或把 Ollama 换到其他端口——macOS、Linux、Windows 的精确命令。
修复 vLLM context length exceeded 报错
vLLM 返回 This model's maximum context length is X tokens 报错。合理设置 max-model-len、提高显存配额、启用 fp8 KV cache 并预留输出 token 即可解决。
修复 vLLM CUDA 版本不匹配与 undefined symbol 报错
vLLM 启动崩溃，报 undefined symbol、no kernel image 或 CUDA 不匹配。用全新环境加 uv --torch-backend=auto 安装，并对齐驱动、CUDA 与 PyTorch。