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 不预装任何模型，由你自己挑。  ## 第二步：安装第一个模型 点左侧导航栏的 **Install Models**，这里是内置的模型市场，有近千个模型可选，可以按名称 搜索，也能按 Chat / Image / TTS / STT 等能力分类筛选。 新手建议从一个小的聊天模型开始，比如搜索 `qwen3-0.6b`(0.6B，下载约 0.5 GB，CPU 上 响应快)。在卡片上点 **Install**。  点下去之后，页面会显示下载进度。**第一次安装某一类模型时，LocalAI 会顺带把对应的推理 后端（比如 llama.cpp）一起下载**，所以首次会多花几分钟。后端只下一次，之后再装同类 模型就快了。装好后，模型在列表里的状态会变成绿色的 **INSTALLED**。  ## 如果模型下载失败：先下载，再导入 有些网络环境访问 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`，在输入框里打字发送即可。  小提示： - **第一句会偏慢**。模型要先加载进内存，加载完之后同一个模型的后续对话会快很多。 - 想换模型直接在下拉里切，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` 文件名是否完全一致；保存配置后是否重启过应用。 ## 相关链接 - 上游项目：<https://github.com/mudler/LocalAI> - 官方文档：<https://localai.io> - 模型安装文档：<https://localai.io/getting-started/models/>