mudler/LocalAI · 上手攻略

仓库：mudler/LocalAI
链接：https://github.com/mudler/LocalAI
分类：skill（本地 AI 推理引擎）
作者：Tom
更新：2026-07-10

这是什么

LocalAI 是一个开源的本地 AI 推理引擎，2026 年 7 月 Stars 约 4.7 万，周增约 +126。核心理念是「小核心 + 按需加载后端」：每个后端（llama.cpp、vLLM、whisper.cpp、stable-diffusion、MLX 等）都是独立的 OCI 镜像，只在你需要某类模型时才拉取安装。最新稳定版为 v4.3.0（2026 年 5 月），支持：

LLM 推理：文本生成、工具调用、Agent
多模态：图像生成、语音合成（ TTS）、语音识别（ASR）、视频生成、视觉理解
RAG 与知识库：内置 embedding 和向量存储
MCP（Model Context Protocol）：Agent 工具调用标准
多用户平台：API Key 认证、OIDC、多租户配额
分布式模式：水平扩展，VRAM 感知路由，PostgreSQL + NATS 协调

硬件支持覆盖 NVIDIA GPU（CUDA 12/13）、AMD GPU（ROCm）、Intel GPU（oneAPI/SYCL）、Apple Silicon（Metal）、Vulkan，以及纯 CPU 运行。

解决什么问题

隐私顾虑：数据不离本地，适合医疗、金融、法律等敏感数据场景
成本控制：无需按 token 付费，自托管在自有 GPU 上，长期成本低于云端 API
工具调用本地化：需要 Agent 能力（RAG、MCP、工具调用）但不想依赖 OpenAI
多模态一站式：图像、语音、视频本地推理不需要启动多个独立服务
硬件兼容：支持 NVIDIA / AMD / Intel / Apple Silicon / CPU，MacBook 也能跑大模型

快速安装

Docker 安装（推荐，最快）

# CPU 运行
docker run -ti --name local-ai -p 8080:8080 localai/localai:latest-cpu

# NVIDIA GPU（CUDA 12）
docker run -ti --name local-ai -p 8080:8080 --gpus all \
  localai/localai:latest-gpu-nvidia-cuda-12

# AMD GPU（ROCm）
docker run -ti --name local-ai -p 8080:8080 \
  --device=/dev/kfd --device=/dev/dri --group-add=video \
  localai/localai:latest-gpu-hipblas

# Apple Silicon（M 系列芯片）
docker run -ti --name local-ai -p 8080:8080 \
  localai/localai:latest-gpu-metal

# Intel GPU
docker run -ti --name local-ai -p 8080:8080 \
  --device=/dev/dri/card1 --device=/dev/dri/renderD128 \
  localai/localai:latest-gpu-intel

# Vulkan（通用 GPU）
docker run -ti --name local-ai -p 8080:8080 \
  localai/localai:latest-gpu-vulkan

macOS 应用安装（桌面端）

# 下载 DMG（未签名，需手动放行）
# https://github.com/mudler/LocalAI/releases/latest/download/LocalAI.dmg
sudo xattr -d com.apple.quarantine /Applications/LocalAI.app

从源码构建

git clone https://github.com/mudler/LocalAI.git
cd LocalAI
make docker-build
# 或参考 https://localai.io/basics/build/ 获取完整构建指南

Kubernetes 部署

参考官方文档：https://localai.io/basics/getting_started/#run-localai-in-kubernetes

核心用法

1. Web UI 使用（最直观）

启动后打开 http://localhost:8080，可直接： - 浏览模型市场，安装模型 - 聊天界面与模型对话 - 创建和管理 AI Agent（支持 MCP 工具） - 生成图像、音频 - 监控资源使用和已加载模型

2. 下载并运行模型（CLI）

# 安装本地 CLI（Docker 方式直接用内置 local-ai 命令）
# 终端 1：运行模型
local-ai run llama-3.2-1b-instruct:q4_k_m

# 终端 2：交互式聊天
local-ai chat --model llama-3.2-1b-instruct:q4_k_m

# 从 Hugging Face 安装
local-ai run huggingface://TheBloke/phi-2-GGUF/phi-2.Q8_0.gguf

# 从 Ollama 镜像库
local-ai run ollama://gemma:2b

# 列出可用模型
local-ai models list

# 安装指定模型
local-ai models install llama-3.2-1b-instruct:q4_k_m

3. OpenAI 兼容 API 调用

LocalAI 完全兼容 OpenAI API 格式，现有应用无需修改代码即可切换：

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.2-1b-instruct:q4_k_m",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

# OpenAI Python SDK 对接示例
# import openai
# openai.api_base = "http://localhost:8080/v1"
# response = openai.ChatCompletion.create(
#     model="llama-3.2-1b-instruct:q4_k_m",
#     messages=[{"role": "user", "content": "Hello!"}]
# )

4. 内置 Agent（支持 MCP）

在 Web UI 的 Agents 页面创建 Agent，配置系统提示词和 MCP 工具后即可自主执行任务（浏览网页、执行代码、调用外部 API 等）。

# 通过 API 使用 Agent（需要模型支持 tool calling）
# 参考：https://localai.io/features/agents/

5. RAG 知识库

# LocalAI 内置 embedding + 向量存储
# 参考：https://localai.io/features/embeddings/
# 使用 /v1/embeddings 接口
curl http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{"input": "你的文档内容", "model": "bge-model"}'

6. 分布式模式（生产部署）

# 启动协调节点
local-ai coordinator

# GPU worker 节点自注册
local-ai worker --gpu --join <coordinator-url>

# P2P 联邦模式
local-ai p2p --join <peer-url>

典型适用场景

场景	推荐配置
个人开发隐私推理	Docker CPU/GPU，单一模型
公司内部 AI 平台	分布式 + 多用户 + OIDC 认证
语音/图像多模态应用	对应后端（parakeet.cpp / stable-diffusion）
Agent + RAG 系统	内置 Agent + MCP + embedding
Apple Silicon 本地开发	Metal 加速 Docker 镜像
低配硬件试用	CPU 模式 + Q4_K_M 量化模型

坑与注意

内存和显存要求：不同量化级别要求差异极大。Q4_K_M 量化的 7B 模型约需 6-8 GB 显存，Q8_0 约需 10-12 GB，FP16 约需 14-16 GB。CPU 模式下 7B Q4 模型约需 5-6 GB RAM。
macOS DMG 未签名：安装后需执行 sudo xattr -d com.apple.quarantine /Applications/LocalAI.app，否则无法启动。
模型需要支持 tool calling 才能用 Agent 功能：并非所有 GGUF 模型都支持工具调用，phi-2、llama-3.2 以上版本通常支持。
后端按需拉取首次慢：第一次使用某类模型（如图像生成）时，LocalAI 会从 OCI 镜像市场拉取对应后端，约 500MB-2GB，耐心等待。
v4 架构变化较大：v4.0 以后 Agent、RAG、MCP 功能已内置，早期 v3.x 用户升级后需重新配置工作流。
API Key 默认无角色隔离：LOCALAI_API_KEY=xxx 启动时 API Key 具有完全 admin 权限，如需多用户隔离请用 LOCALAI_AUTH=true 开启 OAuth 模式。
国产 GPU 支持有限：目前主要针对 NVIDIA/AMD/Intel/Apple，国产 GPU（昇腾等）暂无官方支持。

与同类对比

工具	Stars	特点	优势场景
LocalAI	4.7 万	多模态全包，OpenAI 兼容，Agent+RAG 内置	需要多模态 + Agent 的本地部署
Ollama	14 万+	最流行的本地 LLM 工具，简单直接	快速跑模型，单一 LLM 场景
llama.cpp	5 万+	C++ 原生量化推理，轻量	低配硬件，CPU 推理
vLLM	12 万+	高吞吐量 LLM 服务	生产级 LLM 推理，高并发
GPT4All	3 万+	桌面端 GUI，模型捆绑	非技术用户快速上手
Jan AI	1 万+	开源 ChatGPT 替代，跨平台	个人本地助手

结论：LocalAI 是目前功能最全面的本地 AI 推理平台，Ollama 适合追求极简的用户，llama.cpp 是底层引擎级选择，vLLM 适合高并发生产服务。LocalAI 的差异化在于「OpenAI 兼容 + 多模态 + Agent 内置」三合一，对需要本地 Agent+RAG 系统的用户最有吸引力。

一句话推荐结论

LocalAI 将本地 AI 推理能力打包成一站式平台：无需 GPU 也能跑模型、支持多模态和 Agent 内置、API 与 OpenAI 完全兼容——如果你需要在本地或私有环境部署完整的 AI 应用栈（不只是跑 LLM），LocalAI 是目前最省心的选择。