LocalAI 本地部署与模型运行：Docker 安装和 OpenAI 兼容接口验证

LocalAI 是一个可以在本机运行大模型并提供 OpenAI 兼容 API 的开源工具，适合想在自己服务器或电脑上调用模型、又不想依赖云端接口的场景。
下面按 Docker 部署、模型准备、接口调用和排错顺序，带你把第一个本地模型跑起来。

运行前需要确认的条件

LocalAI 对机器有一定要求，部署前先核对几项，能少走很多弯路：

• 操作系统：Linux 服务器或支持 Docker 的 Windows/macOS 均可，本文以 Linux 命令为例。
• Docker 与 Docker Compose 已安装，执行 docker --version 能返回版本号。
• 内存建议至少 8GB，运行 7B 级别模型时 16GB 更稳妥；如果只用小参数模型，4GB 也能尝试。
• 磁盘预留 10GB 以上，模型文件本身通常有几个 GB。
• 如果使用 GPU，需要提前装好对应驱动和容器运行时；只用 CPU 也能跑，但速度会慢一些。

LocalAI 官方提供 Docker 镜像，最省事的方式是直接用镜像启动，不需要从源码编译。

用 Docker 启动 LocalAI 服务

先拉取镜像并创建数据目录，模型和配置都会放在这个目录里：

mkdir -p /opt/localai/models /opt/localai/images
docker run -d --name localai \
  -p 8080:8080 \
  -v /opt/localai/models:/models \
  -v /opt/localai/images:/tmp/generated/images \
  localai/localai:latest

启动后检查容器状态：

docker ps --filter name=localai
docker logs -f localai

当日志出现监听 8080 端口的信息后，在浏览器访问 http://服务器IP:8080，能看到 LocalAI 的 Web 界面就说明服务已经正常启动。
如果服务器有防火墙或安全组，需要放行 8080 端口，否则本机 curl 通、外网访问却打不开。

模型下载与加载方式

LocalAI 支持多种模型格式，新手优先用 GGUF 单文件模型，管理最简单。
有两种常见做法：

方式一：通过 WebUI 下载。 进入界面后找到 Models 区域，搜索或填写模型名称，按提示下载。
下载完成后模型文件会出现在 /opt/localai/models 目录下。

方式二：手动放入模型文件。 把已经下载好的 .gguf 文件上传到 /opt/localai/models，然后重启容器让 LocalAI 重新扫描：

docker restart localai
docker logs -f localai

无论哪种方式，都要确认模型文件权限可读。
如果日志提示找不到模型或加载失败，先检查文件名、路径和文件大小是否完整。

用 curl 验证模型是否能正常对话

服务起来后，不要急着接第三方客户端，先用一条命令验证接口是否可用。
LocalAI 提供兼容 OpenAI 的接口，调用方式如下：

curl http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "你的模型名称",
    "messages": [{"role": "user", "content": "你好，请用一句话介绍你自己"}]
  }'

把 model 换成实际加载的模型名，如果返回 JSON 中包含 choices 和回复内容，说明推理链路已经打通。
也可以先请求模型列表确认名称：

curl http://127.0.0.1:8080/v1/models

返回结果里能看到模型标识，再把它填到对话请求里，可以避免因模型名写错导致 404 或模型不存在。

常见报错和避坑点

• 端口被占用：启动时报 bind: address already in use，把 -p 8080:8080 改成 -p 8081:8080，再用新端口访问。
• 外网打不开：先在本机执行 curl http://127.0.0.1:8080，本机通但外网不通，通常是防火墙或云安全组未放行端口。
• 模型列表为空：检查模型是否放在 /opt/localai/models，文件扩展名是否为支持的格式，必要时重启容器并看日志。
• 内存不足：日志出现 Killed 或推理中途断开，换更小参数的模型，或增加内存、限制并发请求。
• 不要直接暴露公网：LocalAI 默认没有鉴权，测试阶段尽量只在内网或本机访问；需要对外提供服务时，在前面加反向代理和访问控制。

验证部署是否成功

完成以上步骤后，按三个层面确认：容器持续运行且日志无反复报错；/v1/models 能返回预期模型；/v1/chat/completions 能返回完整回复。
三项都通过，就可以把 LocalAI 的接口地址填到支持 OpenAI 兼容协议的客户端里继续使用。
遇到问题时优先回看日志和模型目录，大多数故障都能从这两处定位。