概述
oakapp-base 镜像包含 CPU 和 Hexagon 后端,允许应用程序加载 GGUF 模型并将支持的操作卸载到设备的 Hexagon Tensor Processor (HTP)。将此路径用于诸如回答有关相机帧的问题、描述选定区域或在设备本地生成文本等任务。 此处描述的部署完全在 RVC4 独立 OAK 应用程序中运行,并且不支持 RVC2 设备。与通过 dai.node.NeuralNetwork 部署的模型不同,GGUF 模型由 llama.cpp 在 DepthAI 图之外加载。 DepthAI 处理相机捕获和流式传输;应用程序准备输入并将其发送到 llama.cpp。 此路径没有 SNPE 或 NN Archive 转换步骤。推理流程
- 将语言模型及其匹配的视觉投影仪与应用程序打包。
- 在设备上启动
llama-server并等待其/health端点报告就绪。 - 使用 DepthAI 捕获帧,可选地裁剪区域,并将准备好的图像编码为 JPEG。
- 将图像和文本提示发送到本地
/v1/chat/completions端点。 - 视觉投影仪对图像进行编码,语言模型处理图像嵌入和提示以生成答案。
- 在应用程序中消费答案或将答案令牌流式传输到前端。
| 路径 | 模型工件 | 执行目标 | 集成 |
|---|---|---|---|
| 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 节点 |
要求
- 运行 Luxonis OS 1.40.0 或更高版本的基于 RVC4 的 OAK 设备。
- 使用
luxonis/oakapp-base:1.5.0-llamacpp或兼容的更新 llama.cpp 镜像的 独立 OAK 应用程序。 - 镜像中 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
1identifier = "com.example.llamacpp"
2app_version = "1.0.0"
3base_image = "luxonis/oakapp-base:1.5.0-llamacpp"
4
5entrypoint = ["/entrypoint.sh", "python3.12", "-u", "/app/main.py"]
6
7prepare_container = [
8 { type = "COPY", source = "requirements.txt", target = "requirements.txt" },
9 { type = "RUN", command = "python3.12 -m pip install --no-cache-dir -r /app/requirements.txt" },
10]
11
12optional_devices = [
13 "/dev/fastrpc-cdsp",
14 "/dev/adsprpc-smd",
15 "/dev/dma_heap/qcom,system",
16 "/dev/dma_heap/system",
17]
18required_mounts = [
19 "/opt/luxonis/npu-runtime:/opt/luxonis/npu-runtime:ro,rbind",
20]
21allowed_devices = [{ allow = true, access = "rw" }]optional_mounts,但也必须选择适当的 CPU 服务器选项。 有关完整的清单参考,请参阅 oakapp.toml 配置。准备模型
- 语言模型:
Qwen3.5-0.8B-Q4_0.gguf。 - 视觉投影仪:来自同一模型仓库和修订的
mmproj-F16.gguf。 - 来源:
unsloth/Qwen3.5-0.8B-GGUF。
mmproj-F16.gguf 就替换来自不同模型的投影仪。 有关模型准备的详细信息,请参阅上游多模态文档。您可以在应用程序目录中包含本地权重,例如 /app/models/model.gguf 和 /app/models/projector.gguf,或者通过 prepare_container 将它们下载到运行时容器层。 VLM 示例的 models.py 固定了仓库修订,验证了 SHA-256 校验和,并在构建期间将两个文件存储在 /opt/qwen-models 下。 这使得推理独立于运行时模型下载。启动推理服务器
Command Line
1llama-server \
2 --model /app/models/model.gguf \
3 --mmproj /app/models/projector.gguf \
4 --device HTP0 --mmproj-device HTP0 -ngl 99 \
5 --host 127.0.0.1 --port 8081 \
6 --ctx-size 2048 --parallel 1 \
7 --threads 4 --threads-batch 4 \
8 --batch-size 256 --ubatch-size 256 \
9 --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 |
subprocess.Popen 启动命令,并在处理请求时保持进程活动。 在启用推理之前,等待来自 http://127.0.0.1:8081/health 的 HTTP 成功响应,并设置启动超时和检查早期进程退出。 将服务器输出转发到应用程序日志;如果您管道 stdout 或 stderr,请持续排空它,以免管道满导致服务器阻塞。 应用程序关闭时终止并等待子进程。 示例的 runtime.py 实现了此生命周期和流式请求。发送相机帧和提示
requirements.txt 中包含 depthai、opencv-python-headless 和 requests。 它捕获一帧,将其编码为 JPEG 数据 URL,并请求非流式答案。Python
1import base64
2
3import cv2
4import depthai as dai
5import requests
6
7
8with dai.Pipeline() as pipeline:
9 camera = pipeline.create(dai.node.Camera).build(dai.CameraBoardSocket.CAM_A)
10 frames = camera.requestOutput(size=(448, 252)).createOutputQueue(
11 maxSize=1, blocking=False
12 )
13 pipeline.start()
14 frame = frames.get().getCvFrame()
15
16ok, jpeg = cv2.imencode(".jpg", frame)
17if not ok:
18 raise RuntimeError("Could not encode the camera frame")
19image_url = "data:image/jpeg;base64," + base64.b64encode(jpeg).decode("ascii")
20
21response = requests.post(
22 "http://127.0.0.1:8081/v1/chat/completions",
23 json={
24 "messages": [{
25 "role": "user",
26 "content": [
27 {"type": "image_url", "image_url": {"url": image_url}},
28 {"type": "text", "text": "Describe what you see in this image."},
29 ],
30 }],
31 "stream": False,
32 "max_tokens": 128,
33 "temperature": 0.0,
34 # Qwen3.5-specific template setting; adapt for other models.
35 "chat_template_kwargs": {"enable_thinking": False},
36 },
37 timeout=(10, 180),
38)
39response.raise_for_status()
40print(response.json()["choices"][0]["message"]["content"])stream 设置为 true,并从响应中消费服务器发送事件,从 choices[].delta.content 读取答案文本,直到流完成。 使用请求超时并将服务器错误显示给调用者。运行完整的 VLM 示例
oakctl 以开发模式运行它:Command Line
1oakctl connect <DEVICE_IP>
2oakctl app run .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 文件或在应用程序的构建工具中下载并验证它们。 |