LocalAI 使用攻略：在懒猫微服上跑通你的本地 AI 引擎

## 一句话概览


https://appstore.lazycat.cloud/#/shop/detail/fun.selfstudio.app.migration.localai


LocalAI 是一个开源的本地 AI 引擎。它可以在懒猫微服上运行大语言模型对话、文生图、语音
合成与识别、向量嵌入等能力，并提供与 OpenAI 兼容的 API。

这份攻略的目标不是把所有功能一次讲完，而是带你完成一条可靠的上手路径：打开服务、安装
或导入一个小模型、完成第一轮对话，再用 API 验证它能作为本地 OpenAI 替代服务使用。

## 适合谁使用

适合这几类人：

- 想要一个私有 ChatGPT 平替，对话内容不上传到第三方。
- 手上有依赖 OpenAI API 的小工具 / 脚本 / 自动化，想换成本地后端。
- 想在自己的设备上玩文生图、语音合成、做知识库 RAG。
- 开发者，需要一个常驻的本地推理服务做接口联调。

LocalAI 强调「No GPU required」——没有显卡也能跑，靠 CPU 推理。懒猫微服这个版本就是
CPU 版：小模型（0.5B~4B）体验流畅，大模型也能跑、只是慢一些。

## 开始前准备

- 一台已安装本应用的懒猫微服设备，设备能正常联网（安装模型时需要联网下载）。
- 想清楚你主要用哪个能力：纯聊天选小语言模型即可；要文生图、语音另外装对应模型。
- 预留一些磁盘空间：模型从几十 MB 到十几 GB 不等，按需安装。

不需要：账号、密码、访问凭据、外部数据库——打开即用。

## 推荐上手路线

第一次使用建议只做四件事：

1. 打开 LocalAI Web 界面，确认服务能正常进入。
2. 安装或导入一个 0.5B~1B 的小聊天模型。
3. 在 Chat 页面发出第一句话，确认模型可以回复。
4. 用 `/v1/models` 或 `/v1/chat/completions` 验证 OpenAI 兼容接口可用。

先用小模型把流程跑通，比一开始就下载十几 GB 的大模型更稳。流程确认没有问题后，再按需求
使用更大的聊天模型、图像模型或语音模型。

## 第一步：打开应用

在懒猫微服里点开 LocalAI，浏览器进入它的 Web 界面。左侧是导航栏，首页能看到内存占用、
已加载的模型，还带一个可以直接打字的快捷对话框。

刚装好时模型列表是空的——这是正常的，LocalAI 不预装任何模型，由你自己挑。

![首页](https://dl.playground.lazycat.cloud/guidelines/558/5b1c1b1f-da2e-4550-98fb-ed2d4a5201ad.png "tutorial-01-home.png")

## 第二步：安装第一个模型

点左侧导航栏的 **Install Models**，这里是内置的模型市场，有近千个模型可选，可以按名称
搜索，也能按 Chat / Image / TTS / STT 等能力分类筛选。

新手建议从一个小的聊天模型开始，比如搜索 `qwen3-0.6b`(0.6B，下载约 0.5 GB，CPU 上
响应快)。在卡片上点 **Install**。

![模型市场](https://dl.playground.lazycat.cloud/guidelines/558/2a6d1ad2-f441-4890-9670-9eb9cfb7005b.png "tutorial-02-gallery.png")

点下去之后，页面会显示下载进度。**第一次安装某一类模型时，LocalAI 会顺带把对应的推理
后端（比如 llama.cpp）一起下载**，所以首次会多花几分钟。后端只下一次，之后再装同类
模型就快了。装好后，模型在列表里的状态会变成绿色的 **INSTALLED**。

![装好的模型显示 INSTALLED](https://dl.playground.lazycat.cloud/guidelines/558/96183937-8fe3-4303-a3b1-05b5a89494e7.png "tutorial-03-installed.png")

## 如果模型下载失败：先下载，再导入

有些网络环境访问 Hugging Face、GitHub Raw 或模型源会不稳定。如果在模型市场里一直卡在
下载、反复失败，建议换成手动导入路线：

1. 在电脑浏览器里打开模型来源网站，先把模型文件下载到本地。新手优先选择 `.gguf` 格式，
   并优先选择 `Q4_K_M`、`Q5_K_M` 这类量化版本，体积和速度更适合 CPU 使用。
2. 把下载好的模型文件放进 LocalAI 的模型目录。懒猫微服上的持久化目录是
   `/lzcapp/var/data/localai/models`，容器内对应 `/models`。
3. 回到 LocalAI 的 **Import Model** 页面。如果页面支持填本地 URI，可以填写：

   ```text
   file:///models/你的模型文件名.gguf
   ```

4. 如果需要高级配置，切到 Advanced / YAML 模式，使用下面这个最小配置，把文件名改成你
   实际下载的文件名：

   ```yaml
   name: my-local-chat
   backend: llama-cpp
   parameters:
     model: 你的模型文件名.gguf
   context_size: 2048
   threads: 4
   ```

5. 保存后回到 **Chat** 页面选择 `my-local-chat` 发送一句话。若下拉框里暂时看不到新模型，可以
   重启应用，让 LocalAI 重新加载模型配置。

这条路线的关键点是：模型文件必须位于 LocalAI 的模型目录内。不要把电脑上的下载路径直接
填进 LocalAI，因为容器访问不到你的电脑本地磁盘。

## 第三步：开始对话

回到 **Chat** 页面，在模型下拉里选中刚装好的 `qwen3-0.6b`，在输入框里打字发送即可。

![对话](https://dl.playground.lazycat.cloud/guidelines/558/857e1219-2fac-457b-89cb-df0325caf18c.png "tutorial-04-chat.png")

小提示：

- **第一句会偏慢**。模型要先加载进内存，加载完之后同一个模型的后续对话会快很多。
- 想换模型直接在下拉里切，LocalAI 会自动加载新模型。
- CPU 推理速度和模型大小直接相关。日常聊天用 0.6B~4B 体验最舒服；追求质量再上更大的。

## 第四步：验证 OpenAI 兼容接口

这是 LocalAI 最实用的地方。它实现了 OpenAI 兼容接口，许多原本连接 OpenAI 的工具只要把
base URL 改成本应用地址，就能改用本地模型。先用下面的请求确认接口能返回模型列表：

```bash
curl https://localai.你的设备域名/v1/models
```

确认能看到模型后，再发一条对话请求：

```bash
curl https://localai.你的设备域名/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-0.6b",
    "messages": [{"role": "user", "content": "用一句话介绍懒猫微服"}]
  }'
```

常用接口都在：

| 能力 | 接口 |
|------|------|
| 对话 | `POST /v1/chat/completions` |
| 文生图 | `POST /v1/images/generations` |
| 语音合成 | `POST /v1/audio/speech` |
| 语音识别 | `POST /v1/audio/transcriptions` |
| 向量嵌入 | `POST /v1/embeddings` |
| 查看已装模型 | `GET /v1/models` |

把你现有的、原本连 OpenAI 的工具的接口地址换成上面这个，就完成了「本地化」。

如果你只是想做快速连通性检查，也可以直接访问：

```text
https://localai.你的设备域名/v1/models
```

能看到已安装模型列表，就说明服务和 API 路由已经正常工作。

## 进阶玩法

### 文生图

在 Install Models 里装一个图像模型（分类选 Image，或搜索 `sd` / `flux` 系列），然后进
**Studio** 页面输入描述文字出图。图像模型通常比聊天模型大，CPU 出图较慢，耐心等。

### 语音合成 / 识别

装一个 TTS 模型（分类选 TTS，如 `kokoro`、`piper`），就能通过 `/v1/audio/speech` 接口做
文字转语音；想要语音对话可以试试 **Talk** 页面。语音识别（STT）用 whisper 系列模型，走
`/v1/audio/transcriptions` 接口上传音频。

### 内置 AI Agent

LocalAI 自带 Agent 能力（LocalAGI），支持工具调用、RAG 知识库、MCP。可以在界面里建
一个能查资料、调工具的智能体。知识库的向量数据会存在持久化目录里。

### 给接口加一层访问保护

默认 Web 界面和接口是完全开放的（适合家庭内网）。如果你要把它暴露到更大范围，建议在
懒猫应用设置里启用访问密钥，并在客户端请求里带上 `Authorization: Bearer ...` 请求头。
密钥内容不要写进攻略、截图或公开脚本里。

## 使用心得

- **先小后大**：先用 0.6B 模型把流程跑通，确认好用了再按需要装更大的模型。
- **下载失败就手动导入**：先在电脑上下载 `.gguf` 模型文件，再放入 LocalAI 模型目录并
  通过 Import Model / YAML 配置导入。
- **后端只下一次**：第一次装模型慢是因为在下后端，别误以为卡住了，先看进度条和任务状态。
- **模型和数据都持久化**：已装的模型、后端、生成的图片音频、知识库都存在持久目录里，
  应用重启、升级都不会丢。
- **联网才能逛市场**：模型市场要联网拉取索引和模型文件，设备断网时市场会打不开。
- **它是引擎不是终点**：LocalAI 真正的价值是给你别的应用当 AI 后端。装好之后，回头
  把你那些用 OpenAI 的工具接过来，才算把它用透。

## 常见问题

### 模型市场打不开

模型市场需要访问外部模型索引。如果页面一直空白，先检查懒猫微服设备是否能正常访问外网。
如果只是模型文件下载失败，可以按上面的手动导入路线处理。

### 模型安装成功，但 Chat 页面没有回复

先确认 Chat 页面选择的是已安装模型，而不是空模型；再等一会儿看首次加载是否完成。CPU
推理首次加载会比较慢，尤其是模型超过 4B 时。

### 手动导入后找不到模型

检查三件事：模型文件是否真的放在 `/lzcapp/var/data/localai/models`；YAML 里的
`parameters.model` 文件名是否完全一致；保存配置后是否重启过应用。

## 相关链接

- 上游项目：
- 官方文档：
- 模型安装文档：