LocalAI：3 条命令跑通本地 OpenAI 兼容 API

LocalAI：3 条命令跑通本地 OpenAI 兼容 API

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

把 OpenAI 的base_url改成http://localhost:8080，你的代码就能直接跑在本地。LocalAI 是一个开源 AI 引擎，一个服务同时承载 LLM、语音、图像、视频等多种模型的本地部署与推理，不需要 GPU。

⚡ 30 秒认知

LocalAI 解决的核心问题：在消费级硬件上把多种模态的模型收敛到一套 REST API 后面，数据不出内网。它自带 Web 界面，模型安装、对话测试、Agent 配置都在http://localhost:8080完成，不用再装别的工具。

和 Ollama 的差异：Ollama 管的主要是 LLM；LocalAI 把 LLM、视觉、语音、图像、视频放进同一套服务，后端按模型需求按需拉取，不用的不装。

和 OpenAI 官方 API 的差异：接口形态一致，但推理完全发生在你的机器上。

一句话推荐：适合需要多模态、要求数据不出内网的本地部署，不适合只需要一个轻量 LLM 管理器的场景

🚀 跑通最小闭环

先用 Docker 起服务，CPU 机器用latest标签即可，NVIDIA 机器加--gpus all并换latest-gpu-nvidia-cuda-13标签：

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

跑通标准：浏览器打开http://localhost:8080，能看到 Web 界面；再跑curl http://localhost:8080/v1/models应返回模型列表。

接着装一个 CPU 友好的小模型。Web 界面走 Models → Explore 搜qwen3-4b，点 Install 等下载完成；CLI 走一条命令：

local-ai models install qwen3-4b

装完在 Chat 页选择该模型发一句话，几秒内应收到回复；或直接用 curl 验证 API：

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

返回含choices的 JSON 即代表链路通了。

不想用 Docker 的话有两条替代入口：源码编译走git clone仓库后执行make build，产出./local-ai二进制；或者直接从官方 Releases 下载二进制，./local-ai-linux-x86_64 run qwen3-4b一步起服务并带载模型。

🧩 接进你的工作流

现有代码零改造切换。任何 OpenAI SDK 或 OpenAI 兼容客户端都指得过来，只改 base_url 和 api_key：

from openai import OpenAI client = OpenAI(base_url="http://localhost:8080/v1", api_key="your-key")

服务端对应配LOCALAI_API_KEY=your-key环境变量即可开启鉴权。

CI 与脚本里的批量任务。把 LocalAI 当无状态服务用：构建流水线里起一个容器，测试代码直接调http://localhost:8080/v1，跑完销毁，不留外部依赖。它同时兼容 Chat Completions、Anthropic Messages、Open Responses 三类端点，多端点场景不用换服务。

⚠️ 踩坑速查

端口被占，服务起不来→ 本机 8080 已被占用 → 跑ss -tlnp | grep 8080看占用方，或换-p 9090:8080重启。

请求返回 404 或 "model not found"→ 请求里的模型名和已加载名对不上 → 跑curl http://localhost:8080/v1/models对照实际加载的 id，请求必须用这个名字。

模型找到了但加载失败，日志刷后端错误→ 缺对应后端或模型格式不匹配 → 跑local-ai backends list确认，缺了就local-ai backends install llama-cpp。

GPU 镜像跑不起来→ 标签和驱动不匹配，或容器拿不到设备 → 跑nvidia-smi验证宿主机驱动，再核对镜像标签与--gpus all参数是否对应。

🔩 配置关键项

模型级参数写在模型配置里（仓库gallery/目录下的 YAML 可参考），最常调的四个：

保守默认值示例（内存紧张时照抄即可）：

parameters: context_size: 4096 num_thread: 4 mmap: true temperature: 0.7

📡 下一步

官方文档的 getting-started 章节（docs/content/getting-started/）覆盖容器、构建、排障全链路；模型清单与参数细节以仓库gallery/和官方文档为准。

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