llama-dash 懒猫微服使用攻略

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

适合谁

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

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

开始前准备

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、延迟和错误率会随着请求实时变化，下面会显示最近请求。

截图里已经有一次测试请求，因此能看到错误率和最近请求记录。真实接入模型后，成功调用会在这里显示为 200 状态，并逐步积累延迟、Token 和请求量指标。

02 添加第一组模型配置

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

可以从一个最小配置开始：

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 页面可以看模型是否出现在列表中。

如果列表为空，通常是配置还没保存、模型文件路径不对，或者启动命令需要根据你的模型和硬件继续调整。

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

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

如果页面提示没有配置 API Key，代理会处于开放模式，适合首次内网调试；长期运行建议创建 key，并按模型、RPM、TPM 或月度 Token 配额做限制。

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

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

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

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

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 和事件流。

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

06 用 Request Log 排查问题

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

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

07 进阶：System、Policies 和 Metrics

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

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

• 给不同客户端创建不同 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 里限制可用模型和速率。