LocalAI本地部署指南让多模态模型跑在自己的硬件上【免费下载链接】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/LocalAILocalAI 是一个开源的本地推理引擎能把 LLM、语音、图像、视频模型跑在自己的机器上不强制要求 GPU。刚 clone 完仓库最容易卡住的是第一条命令之后的种种预期外模型列表为空、后端镜像迟迟不下来、API 里找不到刚装的模型。它的设计不像常见的一个巨型镜像打天下核心只是一个很小的二进制各个推理后端是按需拉取的独立镜像。看懂这一点后面大部分坑都能绕开。最小可运行路径下面这条命令把起服务 装模型一次做完结尾的参数是模型名LocalAI 会先下载模型和对应的后端镜像再启动 API省掉逐个在界面上操作的步骤。docker run -ti --name local-ai -p 8080:8080 \ localai/localai:latest qwen3-4b启动后做两个检查确认服务真的就绪curl http://localhost:8080/readyz # 期望返回 ok curl http://localhost:8080/v1/models # 期望看到 qwen3-4b如果不想走命令行打开 http://localhost:8080 进入 WebUI在 Discover 页面搜模型、点 Install 也能完成同样的事界面上还会直接显示每个量化变体的体积和显存占用。先搞懂核心 后端的结构LocalAI 把推理能力拆成了两部分。核心负责路由、WebUI、模型管理、Agent 这一套管理台而 llama.cpp、vLLM、whisper.cpp、stable-diffusion 这些真正干活的引擎各自独立成镜像第一次运行用到哪个模型才拉哪个后端的镜像。所以第一次加载模型明显比第二次慢是正常现象不是卡死。仓库里gallery/目录放了大量现成的模型配置样例backend/目录则列出了所有可用后端的实现翻一翻对理解结构很有帮助。API 用的模型名是你自己起的很多人第一次调用 API 报 404根因是模型名对不上。请求里的model字段必须和配置文件里的name完全一致而这个名字是你在 YAML 里自己定义的不是文件名。一份最小可用的配置长这样参考gallery/里的真实样例简化而来name: qwen3-4b config_file: | backend: llama-cpp parameters: model: qwen3-4b.Q4_K_M.gguf # 本地文件或 huggingface:// 地址 context_size: 8192 mmap: true temperature: 0.7仓库自带的docker-compose.yaml已经把/models和/configuration挂成卷改完配置重启容器即可生效不用重新拉镜像。配好之后发一条真实的对话请求试试curl http://localhost:8080/v1/chat/completions \ -H Content-Type: application/json \ -d {model: qwen3-4b, messages: [{role: user, content: 用一句话介绍你自己}]}你会在choices[0].message.content里看到模型的回复。接口与 OpenAI 兼容现有 OpenAI SDK 把 base_url 指过来就能直接用。⚠️ 高频报错速查按遇到频率排序基本覆盖新手前两周会碰到的问题现象原因处理API 返回 404 model not found请求里的名字和配置name不一致先打/v1/models核对注册名首次加载极慢甚至像卡死正在拉后端镜像 / 预热docker logs local-ai看进度Exec format error二进制架构不对uname -m后下对应架构GPU 没生效全在 CPU 上跑镜像选错按下表换镜像NVIDIA 加--gpus allmacOS 打不开 App未签名被隔离按文档说明解除 quarantine硬件和镜像的对应关系选错这一项后面调什么都白调硬件镜像纯 CPUlocalai/localai:latestNVIDIAlocalai/localai:latest-gpu-nvidia-cuda-12AMD (ROCm)localai/localai:latest-gpu-hipblasIntel GPUlocalai/localai:latest-gpu-intelVulkanlocalai/localai:latest-gpu-vulkan更完整的排障步骤仓库里docs/content/getting-started/troubleshooting.md按类别整理得挺细遇到怪问题先去翻那里。进阶一台机器不够用时可跳过这一节适合已经有多台 GPU 机器、或者要给多人提供并发服务的读者只是自己跑着玩的可以略过。LocalAI 提供三种扩展方式分布式节点GPU worker 向前端节点自注册、P2P 联邦多实例之间负载均衡、模型分片把大模型拆到多台机器。入口都在 WebUI 的 Nodes 页面不需要改代码。如果打算长期对外提供服务顺手把鉴权也开了单 key 用LOCALAI_API_KEY多用户场景用LOCALAI_AUTHtrue后者带角色和用量统计。卡住了去哪看快速上手与容器镜像全表docs/content/getting-started/模型配置语法样例gallery/排障手册docs/content/getting-started/troubleshooting.md官方文档站本地 docs 目录就是它的源码docs/现在去把你的模型配置里context_size从 8192 改成 16384重启容器再发一段长对话——你会看到模型终于能记住开头说了什么而不是聊着聊着把上下文截断掉。【免费下载链接】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），仅供参考