LocalAI 加载模型时出现 CUDA out of memory 怎么解决【免费下载链接】LocalAILocalAI is the open-source AI engine. Run any model - LLMs, vision, voice, image, video - on any hardware. No GPU required.项目地址: https://gitcode.com/GitHub_Trending/lo/LocalAI在 LocalAI 中加载模型时如果后端日志出现out of memory、CUDA error: out of memory或者加载过程中进程被杀掉说明模型及其 KV cache 放不进 GPU 显存。本文按 LocalAI 项目文档给出的路径处理这个问题先从服务端日志确认真实错误再调整模型 YAML 降低显存占用量化、context_size、gpu_layers、low_vram然后释放其他进程或已加载模型占用的显存最后重新加载并验证。先确认是不是显存不足用户侧的失败通常表现为 HTTP500响应体只是一句简短的通用信息真正的原因在服务端日志里。先打开 debug 日志让后端引擎的 stdout/stderr 完整落盘DEBUGtrue local-ai run # 或 local-ai run --log-leveldebug按 LocalAI 侧的前缀匹配错误行而不是依赖后端的措辞...部分的文案由 llama.cpp、vLLM 等后端引擎产生会随后端版本变化日志中的错误含义could not load model: ...后端已启动但拒绝了模型路径错误、GGUF 损坏或截断、架构不匹配、不支持的量化等...是后端自己的报错could not load model (no success): ...后端响应了加载请求但报告失败尾部文字写明具体原因out of memory、不支持的选项、缺文件grpc service not ready后端进程启动后 gRPC 服务未就绪或启动时崩溃这类崩溃的常见原因之一就是 out of memory注意区分一个相似但不同的错误CUDA 环境下出现invalid pitch表示提示词超出了模型的上下文大小处理方式是缩短提示词或在模型 YAML 中调大context_size:而不是按显存不足处理。如果是 Docker 部署先确认 CUDA 本身可用排除GPU 没被识别这类不同问题# 宿主机验证 CUDA nvidia-smi # 验证容器 GPU 透传NVIDIA docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smiGPU 工作正常时LocalAI 日志应出现ggml_init_cublas: found X CUDA devices如果完全看不到这类初始化信息属于 GPU 未被识别的问题不在本文范围内。降低单个模型的显存占用确认是显存不足后按文档列出的方式调整该模型的 YAML 配置换更小的量化版本Q4_K_S、Q2_K比Q8_0、Q6_K占用显著更少量化模型例如Q4_K_M比全精度模型需要更少显存。调小context_size上下文越大KV cache 越大。调小gpu_layers减少卸载到 GPU 的层数把部分层留在 CPU。在模型配置中加low_vram: true启用 low VRAM 模式。以 llama.cpp 后端为例文档中的模型配置示例如下对应要调整的就是权重文件、context_size和gpu_layersname: my-model-name parameters: # 相对于 models 目录的路径 model: llama.cpp-model.ggmlv3.q5_K_M.bin context_size: 1024 threads: 1 f16: true # enable with GPU acceleration gpu_layers: 22 # GPU Layers (only used when built with cublas)多 GPU 主机上先确认模型不是被整个塞进了一张卡llama.cpp 会在多张 NVIDIA GPU 之间自动分配层可以用CUDA_VISIBLE_DEVICES环境变量控制参与推理的设备例如设为0,1只让 GPU 0 和 GPU 1 参与在容器启动命令如docker run --gpus all ...中一并传入即可。选模型时也可以先看模型 Gallery它按模型展示多个上下文长度下的估算显存占用estimated VRAM footprint可以在安装前判断某个量化变体是否放得下。释放已被占用的显存LocalAI 默认在模型首次使用后一直保留在内存中加载新模型时的 OOM 往往来自已驻留的模型或机器上的其他 GPU 进程。先看看当前加载了哪些模型curl http://localhost:8080/v1/models手动卸载指定模型把model-name替换为要卸载的模型名curl -X POST http://localhost:8080/backend/shutdown \ -H Content-Type: application/json \ -d {model: model-name}该卸载是优雅关闭默认最多等待 30 秒让在途请求完成超时会返回model is still busy错误。要停止全部模型需要对每个已加载模型分别调用该端点或在 Web UI 中一次性停止。如果机器上还有 LocalAI 之外的 GPU 进程用nvidia-smi查看占用nvidia-smi --loop1可每秒刷新自行释放这部分显存。如果多个模型交替使用、显存反复被占满是常态问题属于多模型部署场景可选用文档中的自动管理机制详见 VRAM and Memory Management# 同时最多加载 1 个模型请求新模型时自动卸载当前模型 local-ai run --max-active-backends1 # 空闲 10 分钟未使用的模型自动卸载 local-ai run --enable-watchdog-idle --watchdog-idle-timeout10m对于与其他 GPU 负载共享的机器还可以用--vram-budget或环境变量LOCALAI_VRAM_BUDGET给 LocalAI 的显存分配设硬上限例如--vram-budget80%或--vram-budget12GB为其他进程预留 headroom。它只能降低可用显存、不能超过物理显存也可以在 Web UI 的 Settings 页 Performance 区直接修改 VRAM Budget无需改 flag 重启。重新加载并验证改完配置后重新发送最初触发加载的请求把my-model替换为你的模型名curl http://localhost:8080/v1/chat/completions \ -H Content-Type: application/json \ -d {model: my-model, messages: [{role: user, content: Hello}], stream: true}验证时注意两个文档记录的行为加载失败冷却模型加载失败后LocalAI 会在一段时间内拒绝该模型的新加载尝试期间返回 HTTP503并带Retry-After头。窗口从--model-load-failure-cooldown默认10s开始连续失败每次翻倍、上限 5m首次成功后重置。所以刚失败完不要立刻连续重试等满Retry-After给出的秒数再试或重启 LocalAI 清除冷却--model-load-failure-cooldown 0或LOCALAI_MODEL_LOAD_FAILURE_COOLDOWN0可完全禁用该冷却。卸载等待/backend/shutdown的 30 秒优雅等待与model is still busy响应见上文。加载成功时debug 级别的服务端日志会出现 CUDA 初始化与层卸载信息文档示例如下ggml_init_cublas: found 1 CUDA devices: Device 0: Tesla T4 llama_model_load_internal: offloading 10 repeating layers to GPU llama_model_load_internal: offloaded 10/35 layers to GPU llama_model_load_internal: total VRAM used: 1598 MB llama_init_from_file: kv self size 512.00 MB以上数值是文档示例不是固定预期值。推理期间再运行nvidia-smi确认GPU-Util与Memory-Usage非零即可说明模型确实在使用 GPU且显存占用落在预期范围内。相关文档Runtime errors and troubleshooting错误字符串与处理对照表、如何读取真实错误TroubleshootingOOM 解决方案清单与快速诊断命令VRAM and Memory ManagementLRU 驱逐、并发组、watchdog、VRAM budgetGPU Acceleration模型 GPU 配置示例与 GPU 监控【免费下载链接】LocalAILocalAI is the open-source AI engine. Run any model - LLMs, vision, voice, image, video - on any hardware. No GPU required.项目地址: https://gitcode.com/GitHub_Trending/lo/LocalAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考