# llama.cpp

## 概述

[llama.cpp](https://github.com/ggml-org/llama.cpp) 为 [RVC4](/hardware/platform/rvc/rvc4.md)
独立应用程序中的大型语言模型 (LLM) 和视觉语言模型 (VLM) 提供了推理路径。 官方的 [`oakapp-base`](https://github.com/luxonis/oakapp-base#llamacpp-image) 镜像包含 CPU 和
Hexagon 后端，允许应用程序加载 GGUF 模型并将支持的操作卸载到设备的 Hexagon Tensor Processor (HTP)。

将此路径用于诸如回答有关相机帧的问题、描述选定区域或在设备本地生成文本等任务。 此处描述的部署完全在 RVC4 独立 OAK 应用程序中运行，并且不支持 RVC2 设备。

与通过 `dai.node.NeuralNetwork` 部署的模型不同，GGUF 模型由 llama.cpp 在 DepthAI 图之外加载。 DepthAI 处理相机捕获和流式传输；应用程序准备输入并将其发送到 llama.cpp。 此路径没有 SNPE
或 NN Archive 转换步骤。

## 推理流程

典型的 VLM 应用程序使用以下流程：

 1. 将语言模型及其匹配的视觉投影仪与应用程序打包。
 2. 在设备上启动 `llama-server` 并等待其 `/health` 端点报告就绪。
 3. 使用 DepthAI 捕获帧，可选地裁剪区域，并将准备好的图像编码为 JPEG。
 4. 将图像和文本提示发送到本地 `/v1/chat/completions` 端点。
 5. 视觉投影仪对图像进行编码，语言模型处理图像嵌入和提示以生成答案。
 6. 在应用程序中消费答案或将答案令牌流式传输到前端。

服务器在设备上公开一个与 OpenAI 兼容的 HTTP API；对此本地端点的请求不使用云推理服务。 对于纯文本推理，请省略投影仪和图像输入。

| 路径 | 模型工件 | 执行目标 | 集成 |
| --- | --- | --- | --- |
| llama.cpp CPU | GGUF 模型，加上用于视觉的匹配投影仪 | RVC4 ARM CPU | 本地服务器 API 或 llama.cpp 库 |
| llama.cpp Hexagon | 相同的 GGUF 工件，具有与后端兼容的操作和张量类型 | HTP，不支持的操作在 CPU 上执行 | 本地服务器 API 或 llama.cpp 库 |
| 原生 DepthAI | 转换后的 RVC4 模型，通常通过 NN Archive 提供 | 原生 RVC4 推理运行时 | DepthAI 图中的 `NeuralNetwork` 节点 |

对于需要 ONNX Runtime API 的应用程序，请参阅 [ONNX Runtime with
QNN](/software-v3/ai-inference/inference/onnx-runtime-qnn.md)。 llama.cpp 使用其自己的 Hexagon 后端，而不是 ONNX
Runtime QNN Execution Provider。

## 要求

 * 运行 Luxonis OS 1.40.0 或更高版本的基于 RVC4 的 OAK 设备。
 * 使用 `luxonis/oakapp-base:1.5.0-llamacpp` 或兼容的更新 llama.cpp 镜像的 [独立 OAK
   应用程序](/software-v3/oak-apps.md)。
 * 镜像中 llama.cpp 版本支持的 GGUF 模型，以及用于视觉输入的匹配多模态投影仪。
 * 足够的设备存储和内存用于权重、投影仪、推理缓冲区和选择的上下文大小。
 * 对于 Hexagon 加速，需要访问 FastRPC 设备和容器内 OS 提供的 NPU 运行时。

### 基础镜像包含的内容

`1.5.0-llamacpp` 镜像包含适用于 `linux/arm64` 的 llama.cpp v0.5.0，支持 CPU 和 Hexagon v73。 它在 `PATH` 上提供 `llama-server`、`llama-cli` 和
`llama-bench`，以及 `/opt/llama.cpp` 下的共享库、多模态支持和 C/C++ 头文件。 固定的源修订和构建功能记录在 `/opt/llama.cpp/build-info.json` 中。

镜像配置了 llama.cpp 和设备 NPU 运行时的库搜索路径。 FastRPC 库来自 Luxonis OS 的 `/opt/luxonis/npu-runtime/lib`，必须挂载到加速应用程序中。 纯 CPU 应用程序不需要 NPU
挂载或设备直通。

基础镜像不包含模型权重，也不会自动启动 `llama-server`。 此构建中禁用了内置 HTTPS 模型下载，因此请提供本地模型文件或在容器构建期间使用应用程序工具下载它们。

### OAK 应用程序配置

以下 `oakapp.toml` 配置了一个启动包含服务器的 Python 应用程序。 保留标准 `/entrypoint.sh` 入口点，并从 `requirements.txt` 安装应用程序的 Python 依赖项。

```toml
identifier = "com.example.llamacpp"
app_version = "1.0.0"
base_image = "luxonis/oakapp-base:1.5.0-llamacpp"

entrypoint = ["/entrypoint.sh", "python3.12", "-u", "/app/main.py"]

prepare_container = [
    { type = "COPY", source = "requirements.txt", target = "requirements.txt" },
    { type = "RUN", command = "python3.12 -m pip install --no-cache-dir -r /app/requirements.txt" },
]

optional_devices = [
    "/dev/fastrpc-cdsp",
    "/dev/adsprpc-smd",
    "/dev/dma_heap/qcom,system",
    "/dev/dma_heap/system",
]
required_mounts = [
    "/opt/luxonis/npu-runtime:/opt/luxonis/npu-runtime:ro,rbind",
]
allowed_devices = [{ allow = true, access = "rw" }]
```

此配置使用必需的 NPU 运行时挂载，如 VLM 示例中所示，因此如果该运行时不可用，部署会提前失败。 旨在支持纯 CPU 操作的应用程序可以使用 `optional_mounts`，但也必须选择适当的 CPU 服务器选项。 有关完整的清单参考，请参阅
[`oakapp.toml` 配置](/software-v3/oak-apps/configuration.md)。

## 准备模型

使用镜像固定 llama.cpp 版本支持的 GGUF 导出。 GGUF 是一种文件格式，不能保证每个架构、量化或操作都可以在 Hexagon 上执行。 在验证设置时，从 [llama.cpp VLM
示例](https://github.com/luxonis/oak-examples/tree/main/apps/llamacpp-vlm)中使用的模型开始：

 * 语言模型：`Qwen3.5-0.8B-Q4_0.gguf`。
 * 视觉投影仪：来自同一模型仓库和修订的 `mmproj-F16.gguf`。
 * 来源：[`unsloth/Qwen3.5-0.8B-GGUF`](https://huggingface.co/unsloth/Qwen3.5-0.8B-GGUF/tree/6ab461498e2023f6e3c1baea90a8f0fe38ab64d0)。

投影仪包含模型特定的图像编码和投影组件。 不要仅仅因为文件名也是 `mmproj-F16.gguf` 就替换来自不同模型的投影仪。
有关模型准备的详细信息，请参阅上游[多模态文档](https://github.com/ggml-org/llama.cpp/blob/7fe450e19305b828c199d602c23a8337aaa1f03b/tools/mtmd/README.md)。

您可以在应用程序目录中包含本地权重，例如 `/app/models/model.gguf` 和 `/app/models/projector.gguf`，或者通过 `prepare_container` 将它们下载到运行时容器层。 VLM 示例的
[`models.py`](https://github.com/luxonis/oak-examples/tree/main/apps/llamacpp-vlm/backend/src/models.py) 固定了仓库修订，验证了 SHA-256
校验和，并在构建期间将两个文件存储在 `/opt/qwen-models` 下。 这使得推理独立于运行时模型下载。

## 启动推理服务器

在应用程序容器内，以下命令使用本地模型文件启动一个支持视觉的服务器：

```bash
llama-server \
    --model /app/models/model.gguf \
    --mmproj /app/models/projector.gguf \
    --device HTP0 --mmproj-device HTP0 -ngl 99 \
    --host 127.0.0.1 --port 8081 \
    --ctx-size 2048 --parallel 1 \
    --threads 4 --threads-batch 4 \
    --batch-size 256 --ubatch-size 256 \
    --jinja
```

`--device HTP0` 选择 Hexagon 后端进行语言模型卸载，`-ngl 99` 请求卸载多达 99 层，`--mmproj-device HTP0` 请求 Hexagon 执行视觉投影仪。 这些设置请求放置；不支持的操作仍可能在 CPU
上执行。 检查服务器日志以了解实际的模型和投影仪放置。

| 模式 | 语言模型选项 | 视觉投影仪选项 |
| --- | --- | --- |
| Hexagon | `--device HTP0 -ngl 99` | `--mmproj /path/to/projector.gguf --mmproj-device HTP0` |
| 纯 CPU | `--device none -ngl 0` | `--mmproj /path/to/projector.gguf --no-mmproj-offload` |

对于纯文本模型，请省略所有视觉投影仪选项。

在 Python 应用程序中，使用 `subprocess.Popen` 启动命令，并在处理请求时保持进程活动。 在启用推理之前，等待来自 `http://127.0.0.1:8081/health` 的 HTTP 成功响应，并设置启动超时和检查早期进程退出。
将服务器输出转发到应用程序日志；如果您管道 stdout 或 stderr，请持续排空它，以免管道满导致服务器阻塞。 应用程序关闭时终止并等待子进程。 示例的
[`runtime.py`](https://github.com/luxonis/oak-examples/tree/main/apps/llamacpp-vlm/backend/src/runtime.py) 实现了此生命周期和流式请求。

## 发送相机帧和提示

以下 Python 代码片段在本地服务器准备就绪后在应用程序内部运行。 它需要在 `requirements.txt` 中包含 `depthai`、`opencv-python-headless` 和 `requests`。 它捕获一帧，将其编码为 JPEG
数据 URL，并请求非流式答案。

```python
import base64

import cv2
import depthai as dai
import requests

with dai.Pipeline() as pipeline:
    camera = pipeline.create(dai.node.Camera).build(dai.CameraBoardSocket.CAM_A)
    frames = camera.requestOutput(size=(448, 252)).createOutputQueue(
        maxSize=1, blocking=False
    )
    pipeline.start()
    frame = frames.get().getCvFrame()

ok, jpeg = cv2.imencode(".jpg", frame)
if not ok:
    raise RuntimeError("Could not encode the camera frame")
image_url = "data:image/jpeg;base64," + base64.b64encode(jpeg).decode("ascii")

response = requests.post(
    "http://127.0.0.1:8081/v1/chat/completions",
    json={
        "messages": [{
            "role": "user",
            "content": [
                {"type": "image_url", "image_url": {"url": image_url}},
                {"type": "text", "text": "Describe what you see in this image."},
            ],
        }],
        "stream": False,
        "max_tokens": 128,
        "temperature": 0.0,
        # Qwen3.5-specific template setting; adapt for other models.
        "chat_template_kwargs": {"enable_thinking": False},
    },
    timeout=(10, 180),
)
response.raise_for_status()
print(response.json()["choices"][0]["message"]["content"])
```

对于连续相机应用程序，保持捕获独立于生成运行，并在有界队列中保留最新帧。 对于区域提示，在调整大小之前裁剪原始帧，以便选定区域保留有用的细节。 VLM 示例默认保留图像纵横比并缩小到最大边缘 448
像素；这是一个应用程序设置，而不是所有模型的固定输入形状要求。 llama.cpp 处理所选模型的内部视觉预处理。

要流式传输答案，请将 `stream` 设置为 `true`，并从响应中消费服务器发送事件，从 `choices[].delta.content` 读取答案文本，直到流完成。 使用请求超时并将服务器错误显示给调用者。

## 运行完整的 VLM 示例

[llama.cpp VLM 示例](https://github.com/luxonis/oak-examples/tree/main/apps/llamacpp-vlm) 结合了服务器生命周期、模型下载、相机管道和前端。 它使用 Qwen3.5-0.8B
Q4_0 及其 F16 投影仪，请求 Hexagon 执行两者，并一次处理一个推理请求。 前端支持全帧问题、区域选择、流式答案和延迟报告。

在示例目录中，使用 [`oakctl`](/software-v3/oak-apps/oakctl.md) 以开发模式运行它：

```bash
oakctl connect <DEVICE_IP>
oakctl app run .
```

第一个容器构建需要互联网访问才能下载依赖项和大约 712 MB 的模型资产。 打开 `oakctl` 打印的前端 URL，通常是 `https://<DEVICE_IP>:9000/`，并在提交提示之前等待模型准备就绪。

## 性能和限制

 * 模型兼容性： 支持取决于固定的 llama.cpp 版本、模型架构和张量类型。在采用其他 GGUF 模型之前，请在设备上验证它。
 * 混合执行： 选择 `HTP0` 并不能保证每个操作都在 HTP 上运行。检查日志以了解语言模型和投影仪的放置，并与显式纯 CPU 执行进行比较。
 * 内存使用： 权重只是要求的一部分。上下文大小、图像令牌、批次、缓存和并发请求也会消耗内存。从小型模型和一次一个请求开始。
 * 延迟： 图像编码、提示评估和令牌生成是单独的成本。相机流的 FPS 不代表 VLM 推理吞吐量。较小的图像或裁剪以及较短的输出可以减少工作量，但可能会损失细节或答案完整性。
 * 测量： 将模型启动与请求延迟分开。示例测量从模型 HTTP 请求到第一个和最后一个答案文本事件的时间，包括视觉编码和提示评估，但不包括应用程序端的裁剪/JPEG 准备和前端传输。
 * 应用程序集成： 帧选择、预处理、服务器生命周期、请求调度和结果处理属于应用程序，而不是 DepthAI `NeuralNetwork` 节点。

## 故障排除

| 症状 | 检查内容 |
| --- | --- |
| HTP 不可用或 FastRPC 初始化失败 | 确认 Luxonis OS 1.40.0 或更高版本、设备直通、NPU 运行时挂载以及 `/entrypoint.sh` 的使用。检查服务器的启动日志。 |
| 模型或投影仪加载失败 | 验证本地文件路径和校验和、匹配的模型/投影仪修订以及镜像中 llama.cpp 版本的支持。 |
| 服务器正在运行但推理未就绪 | 等待 `/health` 成功。检查模型加载错误或进程退出，而不是仅仅依赖启动延迟。 |
| 内存不足或上下文容量错误 | 减少上下文大小、图像令牌需求、批处理大小或并发；如果需要，使用较小的支持模型或量化。 |
| 推理速度异常慢 | 检查实际的 HTP 放置、图像大小、提示长度、输出令牌限制以及设备上的其他工作负载。 |
| 模型下载选项失败 | 此镜像禁用内置 HTTPS 下载。打包本地 GGUF 文件或在应用程序的构建工具中下载并验证它们。 |
