llama-dash 懒猫微服使用攻略

> 一句话概览：llama-dash 是本地 LLM 网关控制台，用来管理 llama-swap / llama.cpp 模型、OpenAI 兼容接口、API Key、路由策略、请求日志和运行指标。


https://appstore.lazycat.cloud/#/shop/detail/fun.selfstudio.app.migration.llama-dash


## 适合谁

如果你已经在懒猫微服里放了本地大模型，或者准备把 GGUF 模型通过 `llama.cpp` 跑起来，llama-dash 会更像一个运维面板：它不直接替代模型推理，而是把模型加载状态、请求入口、调用日志、Playground 和指标监控放到同一个网页里。

懒猫版已经接入 LazyCat OIDC。安装后打开应用，优先点击 `Continue with LazyCat`，不用再维护一组单独的控制台账号。

![使用 LazyCat 免密登录](https://dl.playground.lazycat.cloud/guidelines/558/5d5fa141-9a72-48fe-b382-1db63fc22b76.png "image.png")
## 开始前准备

1. 在懒猫微服里安装 `llama-dash`。
2. 准备一个 GGUF 模型文件，例如 `llama-3.gguf`、`qwen2.5-7b-instruct-q4_k_m.gguf` 这类可以由 `llama-server` 启动的模型。
3. 把模型文件放入应用持久化模型目录。懒猫包内的容器路径是 `/models`，配置里也应使用这个路径。
4. 如果要给 OpenAI SDK、Continue、Open WebUI、Claude Code 等客户端使用，先决定是否需要 API Key。个人内网测试可以先不创建，长期使用建议创建。

## 01 首次打开：看 Dashboard 是否健康

登录后先看 `Dashboard`。这里最重要的是左侧 `upstream` 状态和 `/health`：绿色 `ok` 表示 llama-dash 已经连上内置的 `llama-swap` 后端。上方的 `req/s`、延迟和错误率会随着请求实时变化，下面会显示最近请求。

![Dashboard 概览](https://dl.playground.lazycat.cloud/guidelines/558/60d9051a-f576-4258-adac-bee78048734f.png "image.png")
截图里已经有一次测试请求，因此能看到错误率和最近请求记录。真实接入模型后，成功调用会在这里显示为 200 状态，并逐步积累延迟、Token 和请求量指标。

## 02 添加第一组模型配置

进入 `Config`，这是 llama-swap 的 `config.yaml` 编辑器。懒猫版默认把模型文件目录挂载到 `/models`，所以模型路径建议写成 `/models/你的模型文件.gguf`。


![配置 llama-swap 模型](https://dl.playground.lazycat.cloud/guidelines/558/7b617ff2-2239-4d2d-ba53-6e1a7189f2b7.png "image.png")
可以从一个最小配置开始：

```yaml
models:
  llama3:
    cmd: llama-server --port ${PORT} --model /models/llama-3.gguf
    ttl: 300
```

配置要点：

- `llama3` 是对外暴露的模型名，后面客户端请求时会用到。
- `cmd` 中的 `--model` 必须指向真实存在的 GGUF 文件。
- `${PORT}` 由 llama-swap 分配，不要写死端口。
- `ttl` 表示空闲多久后卸载模型，单位是秒。

编辑后先点 `Validate`，通过后再点 `Save`。保存后内置 llama-swap 会自动重载配置。回到 `Models` 页面可以看模型是否出现在列表中。


![模型列表](https://dl.playground.lazycat.cloud/guidelines/558/d6009381-8305-41ee-ac69-d7769022b451.png "image.png")
如果列表为空，通常是配置还没保存、模型文件路径不对，或者启动命令需要根据你的模型和硬件继续调整。

## 03 创建 API Key，给客户端一个稳定入口

`API Keys` 用来控制哪些客户端可以访问代理接口。你可以先在页面右上角点 `Create key`，给不同客户端单独建 key，比如 `open-webui-home`、`continue-laptop`。创建后只展示一次完整密钥，保存到客户端配置里即可，攻略和截图里不要展示真实密钥。

 
![API Key 管理](https://dl.playground.lazycat.cloud/guidelines/558/46c72e04-2fa7-47c4-9a38-367738c2d5df.png "image.png")
如果页面提示没有配置 API Key，代理会处于开放模式，适合首次内网调试；长期运行建议创建 key，并按模型、RPM、TPM 或月度 Token 配额做限制。

## 04 复制 Endpoint，接入 OpenAI 兼容客户端

打开 `Endpoints`，复制 Base URL。懒猫版的对外入口是：

```text
https://你的 llama-dash 域名/v1
```


![客户端接入示例](https://dl.playground.lazycat.cloud/guidelines/558/72423480-d587-4b5c-a104-54c9df92b495.png "image.png")

页面内置了 curl、Python、TypeScript、Home Assistant、Claude Code、opencode、Continue、Open WebUI 等示例。最小 curl 结构如下：

```bash
curl https://你的 llama-dash 域名/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

如果没有启用 API Key，可以先省略 `Authorization` 头做连通性测试；正式使用建议补上。

## 05 用 Playground 先跑小提示词

`Playground` 适合做第一条验证请求。选择模型后，输入一个短提示词，例如“用三句话介绍你自己”，再发送。右侧 Inspector 会显示 request、response、timing 和事件流。


![Playground 调试](https://dl.playground.lazycat.cloud/guidelines/558/472938f0-c383-4710-bc5b-6d1f34f42494.png "image.png")

如果模型下拉框为空，先回到 `Config` 检查模型名和文件路径。如果发送后一直没有响应，去 `Logs` 或 `Requests` 看后端启动错误。

## 06 用 Request Log 排查问题

所有完成的 `/v1/*` 请求都会进入 `Requests`。你可以按状态码、模型、API Key、路由规则、客户端和 end user 过滤。下面这张图是一条故意在未放入模型文件时发出的测试请求，所以状态是 502；如果模型配置正确，同样位置会显示 200 或流式请求的完成状态。


![image.png](https://dl.playground.lazycat.cloud/guidelines/558/678dc33e-33a4-47b5-8377-8adf7e64a874.png "image.png")

点开一条请求，可以看到方法、端点、模型、状态码、耗时、请求体、响应头、客户端来源和路由结果。排查“模型没启动”“路径写错”“客户端用错模型名”时，这个详情页比只看客户端报错更直接。


![image.png](https://dl.playground.lazycat.cloud/guidelines/558/19b84469-3642-410b-9236-8e3e06c24341.png "image.png")

## 07 进阶：System、Policies 和 Metrics

`System` 页面适合确认运行环境、GPU 采样、后端健康和版本信息；`Policies` 可以做模型改写、拒绝规则、鉴权透传和外部 `/v1` 上游转发；`/metrics` 则可以接 Prometheus，长期观察请求量、延迟、Token、队列、运行模型和 GPU 指标。


![image.png](https://dl.playground.lazycat.cloud/guidelines/558/6a562836-40c7-45c5-927b-30fdfedc45f4.png "image.png")

 
建议先把一个本地模型跑通，再逐步增加这些能力：

- 给不同客户端创建不同 API Key，方便统计和限流。
- 用 `Attribution` 把 `x-client-name`、`x-end-user-id`、`x-session-id` 映射到请求日志。
- 用 `Policies` 给 Claude Code、Continue 或 Open WebUI 设定不同路由。
- 用 `Settings` 设置全局请求大小限制，避免意外把超大上下文打到本地模型。

## 常见问题

- **登录后又回到登录页**：刷新一次应用入口，优先使用 `Continue with LazyCat`。如果仍失败，确认应用版本已经接入 OIDC。
- **Dashboard 是绿色，但模型列表为空**：说明 llama-dash 和 llama-swap 通了，但还没有可用模型。检查 `/models` 下是否有 GGUF 文件，并确认 `Config` 保存成功。
- **请求返回 502**：通常是模型启动命令失败、模型文件不存在、模型名写错，或者硬件资源不足。点开 `Requests` 详情，再去 `Logs` 看 llama-swap 的启动输出。
- **客户端能连上但没有日志**：确认客户端 Base URL 是 `/v1`，而不是直接指向 llama-swap；只有经过 llama-dash 的请求才会进入日志和指标。
- **需要远程客户端访问**：只给可信客户端发 API Key，并在 `API Keys` 里限制可用模型和速率。