## 项目概述

LocalAI 是一个开源的 AI 引擎，旨在让用户在任何硬件上运行各种 AI 模型，包括大语言模型（LLM）、视觉、语音、图像和视频模型，且无需 GPU。它采用模块化架构，核心是一个轻量级二进制文件，通过按需拉取独立的推理后端（如 llama.cpp、vLLM、whisper.cpp 等）来支持不同模型。LocalAI 提供与 OpenAI、Anthropic 和 ElevenLabs API 兼容的接口，支持多用户认证、内置 AI 代理、RAG、MCP 等功能，并强调隐私保护，数据可完全留在用户自己的基础设施中。

## 核心功能

- **多模态支持**：文本生成、语音识别（ASR）、文本转语音（TTS）、图像生成、视频生成、3D 生成、目标检测、人脸识别等。
- **API 兼容**：提供 OpenAI、Anthropic、ElevenLabs 兼容的 API，可无缝替换现有应用。
- **模块化后端**：支持 60+ 后端，按需安装，无需安装不需要的组件。
- **硬件加速**：支持 NVIDIA CUDA、AMD ROCm、Intel oneAPI、Apple Silicon Metal、Vulkan 等，也支持纯 CPU 运行。
- **内置 AI 代理**：支持自主代理、工具调用、RAG、MCP、技能系统，可通过 WebUI 或 API 管理。
- **多用户与认证**：支持 API 密钥、用户配额、基于角色的访问控制。
- **分布式推理**：支持 P2P 和分布式模式，可水平扩展。
- **模型管理**：内置模型画廊，可一键安装模型，支持从 Hugging Face、Ollama 等导入。
- **WebUI**：提供完整的 Web 界面，用于模型管理、聊天、配置等。

## 适用与不适用场景

**适用场景：**

- 希望在本地或私有云中运行 AI 模型，注重数据隐私的用户。
- 需要在不具备 GPU 的硬件上运行 AI 模型的场景。
- 希望使用 OpenAI 兼容 API 但不想依赖云服务的开发者。
- 需要多模态能力（文本、语音、图像、视频）的统一 API 平台。
- 需要构建自主代理、RAG 应用或 MCP 集成的开发者。

**不适用场景：**

- 需要超大规模模型（如数千亿参数）且对性能要求极高的场景，可能不如专用云服务。
- 需要官方技术支持的企业级部署，LocalAI 是社区驱动项目。
- 对模型推理延迟有极致要求的场景，本地硬件可能不如云端 GPU 集群。

## 技术架构与依赖

LocalAI 采用 Go 语言编写，核心是一个轻量级二进制文件，通过 gRPC 与各个后端通信。后端是独立的可执行文件或容器镜像，按需下载。主要依赖包括：

- **Go 1.21+**（项目当前使用 Go 1.26）
- **C/C++ 工具链**（用于编译原生后端）
- **Protocol Buffers**（用于 gRPC 代码生成）
- **ffmpeg**（用于音频/视频处理）
- **可选**：CUDA、ROCm、oneAPI、Vulkan 等 GPU 驱动

后端引擎包括 llama.cpp、vLLM、whisper.cpp、stable-diffusion、MLX 等，每个后端封装在独立镜像中。

## 安装与快速开始

### 使用 Docker（推荐）

```bash
# CPU 版本
docker run -ti --name local-ai -p 8080:8080 localai/localai:latest

# NVIDIA GPU 版本
docker run -ti --name local-ai -p 8080:8080 --gpus all localai/localai:latest-gpu-nvidia-cuda-13
```

### 使用命令行工具

```bash
# 安装 CLI（macOS 可下载 DMG）
# 运行模型
local-ai run llama-3.2-1b-instruct:q4_k_m
```

### 从源码构建

```bash
git clone https://github.com/mudler/LocalAI.git
cd LocalAI
make build
./local-ai
```

## 典型使用方法

### 加载模型

```bash
# 从模型画廊
local-ai run 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
```

### 调用 API

```bash
# 聊天补全
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "llama-3.2-1b-instruct", "messages": [{"role": "user", "content": "Hello"}]}'

# 音频转录
curl http://localhost:8080/v1/audio/transcriptions \
  -H "Content-Type: multipart/form-data" \
  -F file="@audio.wav" -F model="whisper-1"
```

### 使用内置代理

```bash
# 启动代理聊天
local-ai chat --model llama-3.2-1b-instruct:q4_k_m
```

## 配置与部署要点

- **环境变量**：LocalAI 主要通过环境变量配置，如 `LOCALAI_MODELS_PATH`、`LOCALAI_API_KEY`、`LOCALAI_THREADS` 等。
- **模型配置**：使用 YAML 文件定义模型参数、后端、模板等，可放在 models 目录或通过 URL 指定。
- **GPU 加速**：根据硬件选择对应的 Docker 镜像，并设置 `gpu_layers` 等参数。
- **反向代理**：支持通过 Nginx、HAProxy 等配置 HTTPS 和子路径。
- **VRAM 管理**：支持 LRU 淘汰、并发组、看门狗等机制，自动管理模型内存。
- **分布式部署**：支持 PostgreSQL + NATS 的分布式模式，可水平扩展。
- **认证**：可配置 API 密钥、OIDC 等。

## 限制、风险与许可证

- **许可证**：MIT 许可证，由 Ettore Di Giacinto 创建，社区维护。
- **风险**：模型下载可能来自不可信来源，存在安全漏洞风险；社区驱动，无官方支持。
- **限制**：VRAM 估算不精确；某些后端可能不支持所有硬件；SYCL 后端存在 mmap 挂起问题。

## 官方链接

- GitHub 仓库：https://github.com/mudler/LocalAI
- 文档：https://localai.io/
- 模型画廊：https://models.localai.io/
- Discord：https://discord.gg/uJAeKSAGDy
- 发布说明：https://github.com/mudler/LocalAI/releases

## 信息来源和分析时间

- 信息来源：GitHub 仓库 README、文档、CONTRIBUTING.md 等。
- 分析时间：2026-08-07（基于最新发布 v4.8.2）。