LocalAI：OpenAI API 兼容的本地模型服务安装与使用指南
一、官方信息
| 项目名称 | LocalAI |
| 仓库地址 | https://github.com/mudler/LocalAI |
| 官方网站 | https://localai.io |
| 最新更新 | 持续高频迭代（2026-10-20） |
| Star 数 | 30k+ |
| 项目定位 | 用 Go 编写的 OpenAI API 兼容本地推理网关，统一封装 llama.cpp、vLLM、Diffusers 等多种后端，让你一键替换 OpenAI |
二、项目背景
LocalAI 由 Ettore Di Giacinto（mudler）于 2023 年发起，目标是打造一个"自托管的 OpenAI 替代方案"。它本身不实现推理 kernel，而是作为网关层，把 llama.cpp、llama-server、vLLM、Diffusers、Stable Diffusion、Coqui TTS 等多种后端统一暴露成 OpenAI 兼容 API（/v1/chat/completions、/v1/images/generations、/v1/audio/speech 等）。
使用 LocalAI 后，原本调用 OpenAI SDK 的代码只需修改 base_url 和 api_key 就能切到本地模型，零代码改造。它支持文本对话、图片生成、语音合成、嵌入向量、函数调用、RAG 等 OpenAI 全套接口，是个人和小企业做"OpenAI 平替"的热门选择。
三、核心特性
- OpenAI 完全兼容：/v1/chat/completions、/v1/embeddings、/v1/images、/v1/audio 等接口对齐。
- 多后端抽象：统一调用 llama.cpp、vLLM、TensorRT-LLM、Diffusers 等后端，按需切换。
- Go 单二进制：无 Python 依赖，单文件部署到路由器、NAS、边缘设备都能跑。
- 模型库一键下载：内置 model gallery，一条命令拉取社区预配置模型。
- 多模态：同时支持文本、图片生成、TTS、STT、嵌入向量。
- 容器友好：官方提供 Docker 镜像，K8s 可直接部署。
- 内置 WebUI：自带简洁聊天界面，开箱即用。
四、环境要求
- 操作系统：Linux / macOS / Windows / Docker
- 内存：7B Q4 模型 ≥ 8GB；图片生成需 8GB+ 显存
- GPU（可选）：NVIDIA 显卡 ≥ 6GB（CUDA 11+）
- Docker：推荐方式，自带所有运行时
五、详细部署步骤
方式一：Docker（推荐）
# 1. 拉取镜像（CPU 版）
docker pull localai/localai:latest
# 2. GPU 版（需 nvidia-container-toolkit）
docker pull localai/localai:latest-gpu
# 3. 创建数据目录
mkdir -p ~/localai/models ~/localai/configuration
# 4. 启动 CPU 版
docker run -d \
--name localai \
-p 8080:8080 \
-v ~/localai/models:/models \
-v ~/localai/configuration:/configuration \
localai/localai:latest \
run
# 5. 启动 GPU 版
docker run -d \
--name localai \
--gpus all \
-p 8080:8080 \
-v ~/localai/models:/models \
localai/localai:latest-gpu \
run方式二：单二进制（裸机）
# 下载最新 release
curl -Lo localai https://github.com/mudler/LocalAI/releases/latest/download/localai-$(uname -s)-x86_64
chmod +x localai
# 启动
./localai run --address :8080 --models-path ./models从 Gallery 一键下载模型
# LocalAI 提供官方 model gallery
# 访问 http://localhost:8080/browse 可视化选择
# 或命令行下载
localai models run qwen2.5-7b-instruct
# 也可以用 API
curl http://localhost:8080/models/apply \
-H "Content-Type: application/json" \
-d '{
"url": "github:mudler/LocalAI/gallery/qwen2.5-7b-instruct.yaml",
"name": "qwen25"
}'手动放置 GGUF 模型
# 1. 下载 GGUF 模型
mkdir -p ~/localai/models/qwen25
wget -O ~/localai/models/qwen25/qwen2.5-7b-instruct-q4_k_m.gguf \
"https://modelscope.cn/models/Qwen/Qwen2.5-7B-Instruct-GGUF/resolve/master/qwen2.5-7b-instruct-q4_k_m.gguf"
# 2. 创建模型配置文件 ~/localai/models/qwen25/config.yaml
cat > ~/localai/models/qwen25/config.yaml << 'EOF'
name: qwen25
backend: llama-cpp
parameters:
model: qwen2.5-7b-instruct-q4_k_m.gguf
context_size: 8192
temperature: 0.7
top_p: 0.9
max_tokens: 1024
template:
chat: qwen25-chat
chat_message: |
<|im_start|>{{role}}
{{content}}<|im_end|>
chat_system: |
<|im_start|>system
{{content}}<|im_end|>
EOF
# 3. 重启容器
docker restart localai调用 API
# 列出已安装模型
curl http://localhost:8080/v1/models
# 对话（与 OpenAI SDK 完全兼容）
curl http://localhost:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-localai" \
-d '{
"model": "qwen25",
"messages": [{"role":"user","content":"你好"}],
"stream": false
}'
# Python SDK 直接切换
python3 -c "
from openai import OpenAI
client = OpenAI(base_url='http://localhost:8080/v1', api_key='sk-localai')
r = client.chat.completions.create(
model='qwen25',
messages=[{'role':'user','content':'你好'}]
)
print(r.choices[0].message.content)
"图片生成（Stable Diffusion）
# /v1/images/generations 接口
curl http://localhost:8080/v1/images/generations \
-H "Content-Type: application/json" \
-d '{
"prompt": "一只可爱的橘猫在窗台上晒太阳，电影质感",
"size": "512x512",
"n": 1
}'六、常见问题（FAQ）
Q1：模型放进去后 /v1/models 看不到？
A：检查 config.yaml 是否与 .gguf 同目录，且 name 字段正确。容器内路径必须与挂载卷一致。
Q2：如何设置 API Key 鉴权？
A：启动时加环境变量 -e LOCALAI_API_KEY=sk-mykey，之后请求必须带 Authorization: Bearer sk-mykey。
Q3：支持 RAG / 向量库吗？
A：内置 /v1/embeddings 接口，可对接 LangChain、LlamaIndex；LocalAI 也有内置 RAG 模块。
Q4：能同时加载多个模型吗？
A：默认按请求动态加载/卸载。可通过 --models-preload 启动时预加载常用模型，避免冷启动延迟。
Q5：NAS/群晖能跑吗？
A：可以，LocalAI 提供 ARM64 镜像，群晖、威联通装 Container Manager 后即可部署。
七、跳转链接
- GitHub 仓库：https://github.com/mudler/LocalAI
- 官方文档：https://localai.io
- 模型 Gallery：https://localai.io/models
- Docker 镜像：https://hub.docker.com/r/localai/localai