llama.cpp 在网络盘上 mmap 失败
llama.cpp 从 NFS、SMB 或 CIFS 挂载的网络盘加载模型时报 mmap failed 错误。定位文件系统 mmap 限制、改用流式加载或本地缓存的修复方案。
#local-llm
带有该标签的文章
llama.cpp 换更激进量化后质量明显下降
从 Q8_0 换到 Q4_K_M 或 IQ4_XS 后，模型输出质量骤降、逻辑错误增多。通过基准测评、量化选择与参数补偿策略恢复可用质量。
LM Studio 加载模型时显存 OOM
LM Studio 加载 GGUF 模型时报 out of memory 或直接崩溃。从显存估算、GPU offload 层数、量化选择三个维度给出可执行的修复方案。
本地 embedding 服务在 batch 请求下崩溃
本地 embedding 服务处理单条请求正常，批量请求时 OOM 崩溃或返回 500 错误。从 batch size 限制、显存管理、序列长度截断三个维度定位并修复问题。
Chat template 不匹配导致输出全是乱码
本地 LLM 输出大量重复符号、乱码或毫无意义的 token 序列。通常是 chat template 格式与模型不匹配所致，定位模板来源并强制指定正确格式即可修复。
多 GPU 没分配上，模型只跑在卡 0
本地 LLM 服务在多 GPU 机器上启动后，所有计算只在第一张卡上进行，其他卡显存占用为零。从 tensor parallel 配置、NVLink、环境变量三个层面给出强制分布的修复方案。
本地模型输出在 token 中间被截断
本地 LLM 在输出中间突然停止，响应不完整，有时在单词或汉字中间截断。定位 max_tokens 限制、EOS token 误触、流式传输缓冲三类根因并给出修复方法。
RoPE scaling 设错让长上下文输出乱掉
本地模型处理超过原生上下文长度的输入时输出开始乱码、重复或完全随机。RoPE scaling 参数配置错误是主因，给出正确参数对照和验证方法。
本地模型冷启动后首 token 极慢
本地 LLM 第一次请求时等待 10-60 秒才开始输出，后续请求正常。定位模型加载、KV cache 预热、GPU 初始化等冷启动瓶颈并给出可执行的优化方案。
Tokenizer 版本不一致导致 token 计数对不上
本地模型的 token 计数与 API 端不一致，导致截断位置错误或上下文溢出。从 tokenizer 版本管理、GGUF 内嵌 tokenizer 与外部库的差异给出对齐方案。
本地模型不遵守 tool calling 格式
本地 LLM 收到 tool calling 请求后，返回纯文本描述而不是 JSON 格式的工具调用，或者格式错误导致解析失败。从模型能力、prompt 格式、解析容错三个层面给出修复方案。
本地 RAG 索引重建慢到无法忍受
本地 RAG 知识库重建时间从预期的几分钟变成数小时。从 embedding batch 策略、向量库写入、文档分块三个瓶颈排查并给出可量化的提速方案。
MLX 转换 HuggingFace 模型失败
在 Apple Silicon 上用 mlx_lm.convert 将 HuggingFace 模型转换为 MLX 格式时报错或转换后无法加载。定位架构支持、内存不足、量化配置三类失败原因并给出修复步骤。
Ollama 探测不到 GPU，全跑在 CPU
Ollama 启动后模型在 CPU 上运行，生成速度极慢。定位 CUDA/ROCm 驱动缺失、环境变量遮蔽、多显卡配置等根因并给出可执行修复命令。
Ollama 下载模型卡在某个百分比
Ollama pull 模型时进度条停在某个百分比不动，重试后依然卡住。分析网络、磁盘、注册表三类原因并给出可直接执行的修复步骤。
Ollama pull 成功但 list 看不到
ollama pull 命令返回成功，但 ollama list 输出里没有这个模型，运行时报 model not found。定位 manifest 写入失败、多 OLLAMA_MODELS 路径、权限问题等根因。
Ollama 启动报 port already in use
执行 ollama serve 时报 address already in use，端口 11434 被占用无法启动。快速定位占用进程、清理僵尸实例、修改默认端口的完整操作步骤。
Ollama Modelfile 里的 SYSTEM prompt 被忽略
在 Ollama Modelfile 中设置了 SYSTEM prompt，但模型运行时完全不遵守设定的人格或行为规则。定位 template 覆盖、API 参数优先级、chat template 兼容性三类根因。
vLLM 报 context length exceeded
vLLM 服务返回 context length exceeded 错误，请求被拒绝。从 max_model_len 配置、KV cache 分配、prefix caching 三个层面排查并给出具体修复参数。
vLLM 启动报 CUDA 版本不匹配
vLLM 启动时报 CUDA 版本不兼容错误，ImportError 或 undefined symbol。从 CUDA 工具链版本对齐、wheel 选择、conda 环境隔离给出完整修复步骤。