LocalAI：本地运行 OpenAI 兼容 AI 模型完整教程
LocalAI：本地运行 OpenAI 兼容 AI 模型
LocalAI 是一个免费、开源的 OpenAI 替代方案。它提供了一个与 OpenAI API 兼容的 REST API，可以在本地或企业环境中运行 AI 推理，支持消费者级硬件。最重要的是，不需要 GPU！
LocalAI 由 Ettore Di Giacinto 创建并维护，是一个社区驱动的项目。它允许你运行 LLM、生成图像、音频（以及更多功能）在本地或企业环境中，支持多个模型系列，无需 GPU 即可在消费级硬件上运行。
为什么选择 LocalAI？
隐私保护：数据完全在本地处理，不会上传到云端
成本控制：无需支付 API 调用费用，一次性部署永久使用
离线可用：不依赖网络连接，完全本地运行
API 兼容：与 OpenAI API 兼容，可直接替换现有代码中的 OpenAI 调用
灵活部署：支持 Docker、Kubernetes 等多种部署方式
核心特性
多模态 AI 支持
文本生成：使用 GPT 系列模型（llama.cpp、transformers、vllm 等）
文本转音频（TTS）：支持 1100+ 种语言的高级语音合成
音频转文本（ASR）：OpenAI Whisper、faster-whisper 等语音识别
图像生成：Stable Diffusion、Diffusers 等图像生成模型
语音活动检测（VAD）：Silero-VAD 支持
对象检测：rf-detr 实时对象检测
音乐生成：ACE-Step 音乐生成模型
OpenAI API 兼容性
Chat Completions API：与 OpenAI 对话接口完全兼容
Functions/Tools API：支持函数调用和工具使用
Realtime API：语音到语音的实时处理
Vision API：多模态视觉理解
Embeddings API：向量嵌入生成，用于语义搜索
Reranker API：文档重排序，提升检索质量
高级功能
MCP（Model Context Protocol）：智能体能力与外部工具集成
内置智能体：自主 AI 智能体，支持工具使用、知识库（RAG）、技能等
P2P 推理：去中心化的分布式推理，可将任务分配到多个设备
MLX 分布式：支持 P2P 和 RDMA 的分布式推理
约束语法：确保输出符合特定格式要求
WebRTC：实时音频流支持
硬件支持
NVIDIA GPU：CUDA 12.0/13.0，包括 Jetson 系列
AMD GPU：ROCm 支持
Intel GPU：oneAPI 支持，包括 Arc 和集成显卡
Apple Silicon：Metal 加速（M1/M2/M3+）
Vulkan：跨平台 GPU 支持
CPU：无需 GPU，纯 CPU 运行，支持 AVX/AVX2/AVX512
后端系统
LocalAI 引入了后端管理功能，后端从主二进制文件中分离，使其更加轻量。LocalAI 会自动检测系统的 GPU 能力，并下载所需的运行模型后端。
Local Stack 生态系统
LocalAI 是一个综合 AI 基础设施工具套件的一部分：
LocalAGI：AI 智能体编排平台，具有 OpenAI Responses API 兼容性和高级智能体能力
LocalRecall：MCP/REST API 知识库系统，为 AI 智能体提供持久化内存和存储
Cogito：Go 语言库，用于构建智能、协作的智能体软件和 LLM 驱动的工作流
Wiz：基于终端的 AI 智能体，通过 Ctrl+Space 快捷键访问
SkillServer：通过 MCP 管理智能体技能的中央数据库
安装方式
macOS
对于 macOS 用户，可以直接下载预编译的 DMG 文件：
# 从 GitHub 下载最新的 DMG 文件
# 访问: https://github.com/mudler/LocalAI/releases/latest/download/LocalAI.dmg注意：DMG 文件可能被 Apple 隔离。如果遇到打开问题，请参考 issue #6268 了解解决方案。
Docker 容器（推荐）
LocalAI 提供了多种 Docker 镜像，支持不同的硬件加速方案。
Docker 提示：
docker run会创建并启动一个新容器。如果已存在同名容器，命令会失败。如果之前已经运行过 LocalAI，想要重新启动现有容器，请使用docker start -i local-ai。
CPU 镜像（适用于所有平台）
最简单的启动方式，无需 GPU：
docker run -ti --name local-ai -p 8080:8080 localai/localai:latestNVIDIA GPU 镜像
支持 CUDA 12.0 和 13.0，以及 Jetson 系列：
# CUDA 13.0
docker run -ti --name local-ai -p 8080:8080 --gpus all localai/localai:latest-gpu-nvidia-cuda-13
# CUDA 12.0
docker run -ti --name local-ai -p 8080:8080 --gpus all localai/localai:latest-gpu-nvidia-cuda-12
# NVIDIA Jetson (L4T) ARM64 - CUDA 12 (适用于 Nvidia AGX Orin 等平台)
docker run -ti --name local-ai -p 8080:8080 --gpus all localai/localai:latest-nvidia-l4t-arm64
# NVIDIA Jetson (L4T) ARM64 - CUDA 13 (适用于 Nvidia DGX Spark)
docker run -ti --name local-ai -p 8080:8080 --gpus all localai/localai:latest-nvidia-l4t-arm64-cuda-13AMD GPU 镜像（ROCm）
docker run -ti --name local-ai -p 8080:8080 \
--device=/dev/kfd --device=/dev/dri --group-add=video \
localai/localai:latest-gpu-hipblasIntel GPU 镜像（oneAPI）
docker run -ti --name local-ai -p 8080:8080 \
--device=/dev/dri/card1 --device=/dev/dri/renderD128 \
localai/localai:latest-gpu-intelVulkan GPU 镜像
docker run -ti --name local-ai -p 8080:8080 localai/localai:latest-gpu-vulkan加载和使用模型
启动 LocalAI 后，可以通过多种方式加载模型：
从模型库加载
LocalAI 提供了一个模型库，可以在 WebUI 中浏览，或使用命令行工具：
# 查看可用模型
local-ai models list
# 从模型库运行模型
local-ai run llama-3.2-1b-instruct:q4_k_m
# 也可以在 WebUI 中从模型标签页浏览和安装模型
# 或访问: https://models.localai.io/从 HuggingFace 直接运行
可以直接从 HuggingFace 下载并运行模型：
# 直接从 HuggingFace 运行模型
local-ai run huggingface://TheBloke/phi-2-GGUF/phi-2.Q8_0.gguf从 Ollama OCI Registry 安装
# 安装并运行 Ollama OCI registry 中的模型
local-ai run ollama://gemma:2b从配置文件运行
可以从 URL 加载模型配置文件：
# 从 GitHub Gist 或其他 URL 运行配置文件
local-ai run https://gist.githubusercontent.com/.../phi-2.yaml从标准 OCI Registry
支持从 Docker Hub 等标准 OCI registry 安装：
# 从标准 OCI registry（如 Docker Hub）运行
local-ai run oci://localai/phi-2:latest⚡ 自动后端检测：当从模型库或 YAML 文件安装模型时，LocalAI 会自动检测系统的 GPU 能力（NVIDIA、AMD、Intel）并下载相应的后端。这大大简化了配置过程。有关高级配置选项，请查看 GPU 加速文档。
支持的后端和硬件加速
文本生成和语言模型
| 后端 | 描述 | 加速支持 |
|---|---|---|
| llama.cpp | C/C++ 中的 LLM 推理 | CUDA 12/13, ROCm, Intel SYCL, Vulkan, Metal, CPU |
| vLLM | 具有 PagedAttention 的快速 LLM 推理 | CUDA 12/13, ROCm, Intel |
| transformers | HuggingFace transformers 框架 | CUDA 12/13, ROCm, Intel, CPU |
| MLX | Apple Silicon LLM 推理 | Metal (M1/M2/M3+) |
| MLX-VLM | Apple Silicon 视觉-语言模型 | Metal (M1/M2/M3+) |
| vLLM Omni | 具有视觉和音频的多模态 vLLM | CUDA 12/13, ROCm, Intel |
音频和语音处理
| 后端 | 描述 | 加速支持 |
|---|---|---|
| whisper.cpp | C/C++ 中的 OpenAI Whisper | CUDA 12/13, ROCm, Intel SYCL, Vulkan, CPU |
| faster-whisper | 使用 CTranslate2 的快速 Whisper | CUDA 12/13, ROCm, Intel, CPU |
| moonshine | 适用于低端设备的超快速转录引擎 | CUDA 12/13, Metal, CPU |
| coqui | 支持 1100+ 种语言的高级 TTS | CUDA 12/13, ROCm, Intel, CPU |
| kokoro | 轻量级 TTS 模型 | CUDA 12/13, ROCm, Intel, CPU |
| chatterbox | 生产级 TTS | CUDA 12/13, CPU |
| piper | 快速神经 TTS 系统 | CPU |
| kitten-tts | Kitten TTS 模型 | CPU |
| silero-vad | 语音活动检测 | CPU |
| neutts | 具有语音克隆功能的文本转语音 | CUDA 12/13, ROCm, CPU |
| vibevoice | 具有语音克隆功能的实时 TTS | CUDA 12/13, ROCm, Intel, CPU |
| pocket-tts | 轻量级基于 CPU 的 TTS | CUDA 12/13, ROCm, Intel, CPU |
| qwen-tts | 高质量 TTS，支持自定义语音、语音设计和语音克隆 | CUDA 12/13, ROCm, Intel, CPU |
| nemo | NVIDIA NeMo 语音模型框架 | CUDA 12/13, ROCm, Intel, CPU |
| outetts | 具有语音克隆功能的 OuteTTS | CUDA 12/13, CPU |
| faster-qwen3-tts | 更快的 Qwen3 TTS | CUDA 12/13, ROCm, Intel, CPU |
| qwen-asr | Qwen ASR 语音识别 | CUDA 12/13, ROCm, Intel, CPU |
| voxcpm | VoxCPM 语音理解 | CUDA 12/13, Metal, CPU |
| whisperx | 增强的 Whisper 转录 | CUDA 12/13, ROCm, Intel, CPU |
| ace-step | 从文本描述、歌词或音频样本生成音乐 | CUDA 12/13, ROCm, Intel, Metal, CPU |
图像和视频生成
| 后端 | 描述 | 加速支持 |
|---|---|---|
| stablediffusion.cpp | C/C++ 中的 Stable Diffusion | CUDA 12/13, Intel SYCL, Vulkan, CPU |
| diffusers | HuggingFace 扩散模型 | CUDA 12/13, ROCm, Intel, Metal, CPU |
专业 AI 任务
| 后端 | 描述 | 加速支持 |
|---|---|---|
| rfdetr | 实时对象检测 | CUDA 12/13, Intel, CPU |
| rerankers | 文档重排序 API | CUDA 12/13, ROCm, Intel, CPU |
| local-store | 向量数据库 | CPU |
| huggingface | HuggingFace API 集成 | 基于 API |
硬件加速矩阵
| 加速类型 | 支持的后端 | 硬件支持 |
|---|---|---|
| NVIDIA CUDA 12 | 所有 CUDA 兼容后端 | Nvidia 硬件 |
| NVIDIA CUDA 13 | 所有 CUDA 兼容后端 | Nvidia 硬件 |
| AMD ROCm | llama.cpp, whisper, vllm, transformers, diffusers, rerankers, coqui, kokoro, neutts, vibevoice, pocket-tts, qwen-tts, ace-step | AMD 显卡 |
| Intel oneAPI | llama.cpp, whisper, stablediffusion, vllm, transformers, diffusers, rfdetr, rerankers, coqui, kokoro, vibevoice, pocket-tts, qwen-tts, ace-step | Intel Arc, Intel 集成显卡 |
| Apple Metal | llama.cpp, whisper, diffusers, MLX, MLX-VLM, moonshine, ace-step | Apple M1/M2/M3+ |
| Vulkan | llama.cpp, whisper, stablediffusion | 跨平台 GPU |
| NVIDIA Jetson (CUDA 12) | llama.cpp, whisper, stablediffusion, diffusers, rfdetr, ace-step | ARM64 嵌入式 AI (AGX Orin 等) |
| NVIDIA Jetson (CUDA 13) | llama.cpp, whisper, stablediffusion, diffusers, rfdetr | ARM64 嵌入式 AI (DGX Spark) |
| CPU 优化 | 所有后端 | AVX/AVX2/AVX512, 量化支持 |
最新项目动态
2026 年 3 月
Agent 管理：新增智能体管理功能
新 React UI：全新的 React 前端界面
WebRTC：实时音频流支持
MLX-distributed via P2P and RDMA：通过 P2P 和 RDMA 的 MLX 分布式推理
MCP Apps, MCP Client-side：MCP 应用和客户端支持
2026 年 2 月
Realtime API：音频到音频的实时 API，支持工具调用
ACE-Step 1.5 支持：新增 ACE-Step 1.5 模型支持
2026 年 1 月
LocalAI 3.10.0：重大版本更新
Anthropic API 支持
Open Responses API 用于有状态智能体
视频和图像生成套件（LTX-2）
统一的 GPU 后端
工具流式传输和 XML 解析
系统感知的后端画廊
修复 AVX-only CPU 和 AMD VRAM 报告的崩溃问题
请求追踪
新后端：Moonshine（超快速转录）、Pocket-TTS（轻量级 TTS）
Vulkan arm64 构建现已可用
2025 年 10 月
MCP（Model Context Protocol）：添加了用于智能体功能与外部工具的 MCP 支持
2025 年 8 月
Apple Silicon 支持：MLX、MLX-VLM、Diffusers 和 llama.cpp 现已支持 Mac M1/M2/M3+ 芯片（在画廊中使用 development 后缀）
2025 年 7 月/8 月
对象检测：新增对象检测功能，支持 rf-detr
2025 年 7 月
后端迁移：所有后端已从主二进制文件中迁移。LocalAI 现在更加轻量、小型，并会自动下载运行模型所需的后端
2025 年 6 月
后端管理：已添加后端管理功能。注意：extra 镜像将在下一个版本中被弃用！
访问和使用方式
启动 LocalAI 后，可以通过以下方式访问：
WebUI
访问 http://localhost:8080 查看内置的 Web 界面。WebUI 提供了以下功能：
Chat Interface：聊天界面，支持多会话和历史记录
Models Gallery：模型库，可以浏览和安装模型
Image Generation：图像生成界面
Audio Generation：音频生成界面
Talk Interface：语音对话界面
Home Dashboard：主仪表板
P2P Dashboard：P2P 分布式推理仪表板
REST API
使用与 OpenAI 兼容的 API 端点：
Chat Completions：POST /v1/chat/completions
Completions：POST /v1/completions
Embeddings：POST /v1/embeddings
Models：GET /v1/models
CLI 工具
使用 local-ai 命令行工具管理模型：
# 列出可用模型
local-ai models list
# 运行模型
local-ai run llama-3.2-1b-instruct:q4_k_m社区和资源
官方资源
文档网站：https://localai.io/
GitHub 仓库：https://github.com/mudler/LocalAI
模型库：https://models.localai.io/
示例仓库：https://github.com/mudler/LocalAI-examples
Discord 社区：https://discord.gg/uJAeKSAGDy
社区集成
LangChain：官方集成
Home Assistant：多个集成可用
VSCode 扩展：官方插件
Helm Chart：Kubernetes 部署支持
P2P Explorer：https://explorer.localai.io
社区项目
LocalAI-admin：WebUI 管理界面
LocalAI-frontend：前端项目
QA-Pilot：交互式聊天项目，利用 LocalAI LLM 快速理解和导航 GitHub 代码仓库
VoxInput：语音输入工具
ShellOracle：终端实用工具
Shell-Pilot：通过纯 shell 脚本与 LLM 交互
Hellper：Telegram Bot
GitHelper：GitHub Bot
Reflexia：自动文档生成
自主开发团队
LocalAI 现在由一个完整的自主 AI 智能体团队（由 AI Scrum Master 领导）协助维护（用于小任务！）。这个实验展示了开源项目如何利用 AI 智能体进行可持续的长期维护。
📊 Live Reports：自动生成的报告
📋 Project Board：智能体任务跟踪
📝 博客文章：了解自主开发团队实验
技术特性详解
P2P 分布式推理
LocalAI 支持 P2P（点对点）分布式推理，可以将模型推理任务分布到多个设备上执行。这包括：
去中心化 llama.cpp：通过 libp2p 实现 P2P llama.cpp
分布式推理：支持跨设备的分布式推理
MLX-distributed：支持 P2P 和 RDMA 的 MLX 分布式推理
P2P Explorer：可视化 P2P 网络状态
P2P Dashboard：P2P 联邦模式和 AI 群体（Swarm）
智能体功能
LocalAI 提供了完整的智能体支持：
内置智能体：自主 AI 智能体，支持工具使用、知识库（RAG）、技能、SSE 流式传输、导入/导出
Agent Hub：智能体中心
MCP 支持：Model Context Protocol，支持智能体功能与外部工具集成
LocalAGI：智能体编排平台
LocalRecall：知识库系统，为智能体提供持久化内存和存储
后端画廊系统
LocalAI 的后端画廊系统允许动态安装和卸载后端：
OCI 镜像驱动：通过 OCI 镜像安装/卸载后端
完全可定制：支持自定义后端
API 驱动：通过 API 管理后端
自动检测：自动检测系统 GPU 能力并下载相应后端
总结
LocalAI 是一个功能强大、灵活的开源 AI 推理平台，特别适合需要本地运行 AI 模型的场景。它提供了与 OpenAI API 兼容的接口，支持多种硬件加速，无需昂贵的 GPU 也能运行大型语言模型。
主要优势
隐私安全：数据完全在本地处理
成本效益：无需支付 API 费用
灵活部署：支持 Docker、Kubernetes 等多种方式
丰富功能：支持文本、图像、音频、视频等多种 AI 任务
社区活跃：持续更新，社区支持
API 兼容：可直接替换 OpenAI 调用
适用场景
需要隐私保护的企业应用
离线环境的 AI 部署
需要降低 AI 成本的场景
学习和研究 AI 模型
构建自定义 AI 应用
智能家居、自动化等嵌入式场景
提示：如果你对 AI 技术感兴趣，LocalAI 是一个非常好的入门选择，让你在不依赖云服务的情况下体验和学习 AI 模型的强大功能。无论你是个人开发者还是企业用户，都可以利用 LocalAI 构建隐私安全、成本可控的 AI 应用。