LocalAI：本地跑多模态模型的开源推理引擎

本地跑模型的麻烦往往在周边：文本生成一套依赖，语音识别一套，图像生成又是一套，接口形态还各不相同。LocalAI 把这些收进一个进程，对外只暴露 OpenAI、Anthropic、ElevenLabs 风格的 API。你给它一个模型名或一个模型文件，它返回本地的推理结果，数据不出自有机器。

LocalAI 是一个用 Go 编写的开源本地 AI 推理引擎，输入模型名或模型文件，输出统一的 OpenAI 兼容 API 响应，覆盖文本、视觉、语音、图像与视频。

这个定位换来的是另一套活儿。模型不跑在别人的机房里，显卡驱动、容器运行时、模型文件就得自己准备。仓库当前 49305 star、4475 fork、130 个开放 issue，许可证是 MIT，主要语言 Go（占 69.9%），作者是 Ettore Di Giacinto，代码在 mudler/LocalAI。需要在一台自有机器上同时提供多种模态、又不打算改客户端 SDK 的团队，是它最直接的受众。

它不做什么

它不把各个推理引擎塞进一个巨大的镜像。llama.cpp、vLLM、whisper.cpp、stable-diffusion、MLX 这些引擎各自是独立镜像，只有模型真正用到时才拉取。README 把这条设计写成「A small core, not a bundle」，用到什么装什么。

它也不分发模型权重。模型要从模型库、HuggingFace、Ollama 的 OCI registry、标准 OCI registry，或者一个 YAML 配置地址取。手上没有模型文件，服务起来了也没有东西可推理。

托管服务不在范围内。项目以隐私为先，数据留在自有基础设施里，代价是机器、驱动与容器环境都要自己维护。

用之前先准备好什么

最省事的路是容器。纯 CPU 版本只要有 Docker 或 podman。用 GPU 的话，驱动与容器 GPU 支持得先装好：NVIDIA 要有可用的 CUDA 环境，AMD 要能访问 /dev/kfd 与 /dev/dri，Intel 要能看到 /dev/dri 下的设备节点。

macOS 用户走官方 DMG，但那个包没有 Apple 签名，装完要手动执行 sudo xattr -d com.apple.quarantine /Applications/LocalAI.app，否则会被系统拦下，README 为此指向了 issue #6268。

磁盘要留足。仓库自身约 119 MB，这只是代码，真正的模型文件从几百 MB 到几十 GB 不等，README 里没有给出各模型的体积清单。多用户场景还要规划 API key 与配额怎么发，仓库列出了 API key 认证、用户配额和角色权限这几项能力，具体配置字段在 README 节选里没有展开。

从源码构建则需要 Go 工具链，顶层有 Makefile 与 .goreleaser.yaml，构建细节不在快速开始的范围里。

主要功能

• 一套 API 覆盖多种模态。文本生成、视觉、语音、图像、视频都从同一个服务出，仓库把它描述为 drop-in 兼容，OpenAI、Anthropic、ElevenLabs 的接口形态都能对上。
• 后端按需拉取。每个后端包裹一个成熟引擎（llama.cpp、vLLM、whisper.cpp、stable-diffusion、MLX 等），模型用到哪个才装哪个。也可以按开放接口，用任意语言写自己的后端。
• 模型来源多样。local-ai run 后面可以跟模型库里的名字、huggingface://、ollama://、oci://，或指向 YAML 配置的 https 地址。
• 硬件覆盖广。NVIDIA、AMD、Intel、Apple Silicon、Vulkan，以及纯 CPU。README 提到自动后端检测：启动时判断 GPU 能力并下载合适的后端。
• 多用户能力。API key 认证、按用户配额、基于角色的访问，都在功能列表里。
• 内置 agent。自主 agent 支持工具调用、RAG、MCP 与 skills。
• 终端 agent。另开一个 shell 跑 local-ai chat --model <name> 就能连上正在运行的服务，它能读你的文件、在你机器上执行命令，凡是会改变状态的操作都会先请你批准。会话内 /models 列模型，/model <name> 切模型。
• 微调与量化。README 的引导视频里包含 Fine-tuning and Quantization 一节。

安装与最短示例

容器方式最直接，纯 CPU 一条命令就能起：

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

NVIDIA 显卡换对应 tag，并直通 GPU：

docker run -ti --name local-ai -p 8080:8080 --gpus all localai/localai:latest-gpu-nvidia-cuda-12

AMD ROCm 需要额外挂设备与用户组：

docker run -ti --name local-ai -p 8080:8080 --device=/dev/kfd --device=/dev/dri --group-add=video localai/localai:latest-gpu-hipblas

容器起来后加载模型。下面这条从模型库取，也可以换成 HuggingFace 或 Ollama registry：

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

# 从 HuggingFace 取
local-ai run huggingface://TheBloke/phi-2-GGUF/phi-2.Q8_0.gguf

# 从 Ollama 的 OCI registry 取
local-ai run ollama://gemma:2b

想用终端 agent，在另一个终端连上去：

local-ai chat --model llama-3.2-1b-instruct:q4_k_m

容器之前已经跑过的话，用 docker start -i local-ai 重启，不用重新创建。

关键参数

• -p 8080:8080：容器内服务默认监听 8080，映射出来宿主机才能访问。
• --gpus all：NVIDIA 显卡直通。
• --device=/dev/kfd --device=/dev/dri --group-add=video：AMD ROCm 需要的设备与用户组。
• --device=/dev/dri/card1 --device=/dev/dri/renderD128：Intel oneAPI 需要的设备节点。
• 镜像 tag 决定硬件后端：latest（纯 CPU）、latest-gpu-nvidia-cuda-12、latest-gpu-nvidia-cuda-13、latest-nvidia-l4t-arm64、latest-nvidia-l4t-arm64-cuda-13、latest-gpu-hipblas、latest-gpu-intel、latest-gpu-vulkan。
• local-ai run <来源>：来源前缀决定模型从哪儿取。
• local-ai chat --model <name>：连接本机服务的终端 agent。
• 分布式部署对应 docker-compose.distributed.yaml，单机用 docker-compose.yaml；配置目录是 configuration/，环境变量样例在 .env。这些文件里的字段在 README 节选里没有逐个展开。

结果在哪里看

服务监听 8080，HTTP 请求直接打 http://localhost:8080/v1/completions 这类 OpenAI 兼容路径，仓库 issue 里给出的复现命令用的就是这个地址。

模型清单用 local-ai models list 查，也可以到 models.localai.io 看可选模型。终端 agent 会话内用 /models 和 /model <name> 管理。容器以前台模式运行，日志直接打在终端上。文档站是 localai.io，README 顶部还列了多语言的机器翻译链接。

Web 界面的访问路径，仓库的快速开始里没有说明这一步。

实际使用中的坑

AMD 后端的容器构建很麻烦。有人反映用 rocm 后端构建 Docker 镜像时，构建过程里多个环节会各自失败。这条 issue 累计 78 条评论，是仓库里讨论最多的一条，目前状态为已解决。

启动后连不上，报 127.0.0.1 连接被拒。典型报错是 rpc error: code = Unavailable ... dial tcp 127.0.0.1:37785: connect: connection refused，60 条评论，已解决。这类问题通常出在服务进程与请求方不在同一网络命名空间里。

显卡驱动更新后 GPU 加速失效。有用户在升级图形驱动之后，CUDA 12.5 环境的加速不再工作，30 条评论，已解决。容器里的 CUDA 运行时版本要和宿主机驱动对得上，换 tag 之前值得先确认这一点。

没有 AVX 指令集的老 CPU 上模型不响应。有人在缺少 AVX 支持的机器上发请求，模型没有任何返回，22 条评论，已解决。另外官方模型文档里写着一句老提醒：兼容 LocalAI 的模型要按 ggml 格式量化。

同类项目对比

如果要的是单机高并发吞吐，LocalAI 不占优势，vLLM 这类专注推理服务的方案更对口；如果诉求只是通过 MCP 调托管模型、连硬件都不想碰，runapi-ai/mcp 更省事。LocalAI 划算的地方在两头：一次把多种模态收进同一个 API，同时把数据留在自己的机器上。这两条都不需要的话，它的维护成本就白付了。

适合谁

适合有自有服务器或工作站的团队，尤其是有纯 CPU 机器、又需要给内部应用提供一个兼容 OpenAI 的推理端点的人。需要在一个进程里同时提供文本、语音、图像能力，或者对数据不出内网有硬要求，它接得上。要给多个用户分发 API key 和配额，也在它的能力范围内。

不适合打算长期只调托管 API、不愿意维护显卡驱动和容器环境的人。只跑一个大模型、追求极限吞吐的场景，换成专注推理服务的引擎更省心。CPU 不支持 AVX 指令集的老设备上，这个项目跑不起来，issue 里已经有过这样的反馈。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 10.0 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。