10 分钟跑通 LocalAI：本地部署私有 AI 推理服务的完整指南

10 分钟跑通 LocalAI：本地部署私有 AI 推理服务的完整指南

【免费下载链接】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

LocalAI 是一个开源的本地 AI 推理服务，对外讲 OpenAI 与 Anthropic 的 API 协议，在 CPU 或 GPU 硬件上运行文本、图像、音频、视频等多模态模型。它适合两类人：想在自己的机器上跑模型、不愿把数据发去云端的开发者；以及已有基于 OpenAI API 写成的应用、希望把 base_url 换成本地地址的用户。

10 分钟跑通 LocalAI 本地部署

先跑起来，再谈原理。有 Docker（或 Podman）的话，下面这条命令会拉取镜像并在 8080 端口启动服务：

docker run -ti --name local-ai -p 8080:8080 localai/localai:latest

这条镜像是 CPU 版本，不带预配置模型，但已经包含了全部后端能力——缺什么模型装什么，后文会解释它是怎么做到轻量的。

浏览器打开http://localhost:8080就能看到内置 WebUI：与模型对话、在 Models 页面安装和管理模型、配置 Agent、查看资源占用，都不需要额外装任何工具。

装第一个模型有两条路。WebUI 里打开 Models → Explore，搜到一个模型点 Install 即可；命令行则直接在启动时带上模型名，服务会在 API 就绪前自动下载安装：

local-ai run llama-3.2-1b-instruct:q4_k_m

这里选llama-3.2-1b-instruct的q4_k_m量化版本，文件只有 1-3 GB 量级，纯 CPU 也能动。装好后打开 Chat 页面选它发消息，几秒内就能收到回复；也可以用 API 验证服务是否就绪：

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

这个端点与 OpenAI 的/v1/chat/completions完全同构，任何 OpenAI SDK 改一下 base_url 就能接上；Anthropic Messages API 和 Open Responses API 同样可用。

最后提醒一句安全配置：服务如果要暴露到局域网以外，用环境变量LOCALAI_API_KEY=your-key给接口加一道密钥，或设置LOCALAI_AUTH=true开启多用户认证（角色、OAuth 登录、使用量跟踪）。遇到启动异常时设置DEBUG=true可以看到更多日志。

硬件与后端架构：需要哪些资源

没有 GPU 能否运行，模型占多少空间

能。GPU 是可选的加速器而非前提，官方明确标注 "No GPU required"。容量上，1-3B 参数的模型大约占 1-3 GB，7-13B 约 4-8 GB，30B 以上要 15-30 GB；FAQ 建议预留模型体积 2-3 倍的空间给下载和临时文件，用 SSD 效果更好。模型比内存还大时运行效率会明显下降，选型时先看看自己的 RAM。

有 GPU 时按硬件选镜像即可：NVIDIA 用localai/localai:latest-gpu-nvidia-cuda-12（CUDA 13 有对应 tag）并加--gpus all，AMD ROCm 用latest-gpu-hipblas，Intel 用latest-gpu-intel，Vulkan 用latest-gpu-vulkan，另有 Jetson 的 L4T 镜像。启动时 LocalAI 会自动探测 GPU 能力并下载匹配的后端，多数场景不用手工配置。

后端按需拉取，核心只有一个

LocalAI 是"小核心、不打包"的设计：核心进程只提供 OpenAI 兼容 API、请求路由、WebUI 和 Agent，每个推理引擎（llama.cpp、vLLM、whisper.cpp、stable-diffusion、MLX 等）都是一个独立的 OCI 镜像，只有当某个模型需要它时才被拉下来。跑一个 1B 对话模型，就不会下载图像生成的引擎。

目前内置了 60 多个后端，全部通过同一套 gRPC 接口与核心通信。这意味着任何兼容模型都可以加载，也可以用任意语言写一个自己的后端接入——接口是开放的，核心没有封闭。

模型来源不止画廊一处：可以从 HuggingFace 直接拉 GGUF（local-ai run huggingface://...）、从 Ollama 注册表取（ollama://gemma:2b）、用一份 YAML 配置定义，或指向任意 OCI 注册表。下载位置默认是命令行下的./models、容器内/models、macOS 应用~/.localai/models，用LOCALAI_MODELS_PATH环境变量可以改到别的盘。

核心功能：文本、视觉、语音、检索与多模态

文本生成由 llama.cpp、vLLM、SGLang、transformers 等后端驱动，支持 OpenAI 兼容的工具调用 API 和约束语法（限制模型只能按你给的格式输出 JSON 之类的结构）。

视觉和音频方向覆盖得比较宽：Vision API 支持图片输入，对象检测、开放词汇检测（locate-anything.cpp）、人脸检测与识别、深度估计各有对应后端；音频侧有 whisper.cpp 系列的语音转文字、Piper 等后端做文字转语音、说话人分离（diarization）、语音活动检测（Silero-VAD），还有实时 Realtime API 支持语音到语音、通过 WebRTC 通话。

多模态与检索补齐了剩下的拼图：stable-diffusion-ggml 等后端做图像生成，LTX-2 和 wan-ggml 做视频生成；嵌入（embeddings）生成与重排序（reranker）API 可直接接 RAG 管道，项目还自带 local-store 这个本地向量数据库。终端里有local-ai chat内置 Agent，能读文件、执行命令，改状态的操作会先征求你的同意。

多用户、Agent 与分布式推理场景

单台机器用完后，有几条横向扩展的路。多用户层面支持 API key、OIDC 登录、管理员/用户角色、按 API key 和按用户的使用量配额，适合在团队内网里共用一个实例。Agent 是内置平台而非外挂：支持工具使用、RAG、技能（skills）和 MCP（Model Context Protocol，一种让模型调用外部工具的标准协议），在 WebUI 里创建 Agent 时配上工具和系统提示词，对话时它会自主调用工具。

算力不够时再上分布式模式：GPU 工作节点向协调器自注册，请求按 VRAM 感知路由并自动扩缩；P2P 联邦可以把多台 LocalAI 实例连起来做负载均衡，大模型还能跨机分片。这套模式依赖 PostgreSQL 与 NATS 做状态和消息，属于进阶部署，官方文档在 docs/content/features/distributed-mode.md。

文档入口与下一步

仓库自带完整文档，按主题组织：安装与快速上手 覆盖容器、macOS、Linux、Kubernetes 等路径，features 目录 按模态逐一介绍每种能力，FAQ 集中回答"是否要装全部后端""模型存哪里"这类高频问题。代码层面，backend/ 下每个子目录对应一个推理引擎的封装（llama-cpp、whisper、vllm-cpp、kokoros 等），gallery/ 是可一键安装的模型清单配置，core/ 是核心服务本身。

建议的下一步：先用 CPU 镜像把服务拉起来，装一个 Q4 量化的 1-3B 模型完成对话，然后把现有 OpenAI 客户端的 base_url 指到http://localhost:8080/v1验证兼容性——这三步走完，你就有了一个可以接进现有工作流的本地推理端点。

【免费下载链接】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