Vitolearns/KVHarbor
机器学习面向单张 NVIDIA GPU 的 C++20 LLM 服务层,提供 HTTP/SSE 请求排队、流式背压和可选语音接口。
项目介绍
KVHarbor 是 C++20 编写的 HTTP 服务,包在 llama.cpp 推理之前,负责请求准入、超时、取消、流式背压和 worker 释放;模型分词与执行仍在进程内交给 llama.cpp。可选的语音能力在 CPU 上通过 sherpa-onnx 跑 Qwen3-ASR 识别和 Kokoro 合成。适合需要在单张 GPU 上服务本地 GGUF 模型、并且关心过载行为而非只看解码速度的场景。
仓库对边界写得很明确:它不实现跨请求连续批处理,不把多条序列合并进一个 llama_batch,也不替换上游 KV 分配器;引擎调度只是在独立 worker 上下文之间串行交错调用,每个上下文只持有一条序列(见架构与实现说明)。
快速使用
最快路径不需要 GPU 和模型权重,而是用 CPU 测试后端把 HTTP/SSE 链路跑通。在 Ubuntu 24.04(原生或 WSL2)上安装 git、curl、python3、build-essential、cmake、libboost-dev、nlohmann-json3-dev,克隆仓库后编译:
cmake -S serving -B build-serving-cpu -DCMAKE_BUILD_TYPE=Release
cmake --build build-serving-cpu --parallel 2
./build-serving-cpu/kvharbor-server --test-backend --port 18082
另开终端发送流式请求,设置 stream: true 和 max_tokens: 4。预期收到四个内容分块、一个带 finish_reason: "stop" 和 token 用量的最终 JSON 分块,最后是 data: [DONE](快速启动)。用 Ctrl+C 停止服务。
真实文本生成需要先下载锁定版本的 Qwen3.8-27B Q4_K_M GGUF,按文本运行时锁文件校验 SHA-256,再构建 llama.cpp 运行时和服务器,然后用文档给出的 worker、上下文、批大小和调度参数启动 scripts/native_serving.sh serve。健康检查在 /health,对话请求发到 /v1/chat/completions(真实模型流程)。语音能力需要先运行准备脚本,再以 KVHARBOR_AUDIO=1 重新构建;识别和合成接口分别是 /v1/audio/transcriptions 和 /v1/audio/speech(语音配置)。
使用约束
参考环境是 Ubuntu 24.04 加 RTX 5090 Laptop GPU,锁定的 CUDA 构建面向 SM120,其他 GPU 架构需要兼容的构建配置。运行真实模型需要可访问 NVIDIA GPU 的 Docker、Python 3.12+、Bash、Git、curl,以及 Boost 和 nlohmann-json 开发包。可选语音模型也需要准备脚本下载并校验的锁定运行时资源。
请求处理有可见限制:max_tokens、语音 voice ID 等整数字段必须是 JSON 整数,布尔、字符串和浮点数会被拒绝;当前适配器只消费单序列调用的最后一行 logits,多序列批处理需要重新评估这个假设。许可证为 PolyForm Noncommercial 1.0.0,继承代码和模型条款记录在 NOTICE 中。
HotRepo 点评
站内目前只有 2026-11-20 一条 Python 新项目快照:107 星、0 fork,在约 1.5 小时的窗口内净增 4 星,没有记录到 GitHub 日榜名次。历史太短,不足以判断持续关注度,更值得看的是仓库本身:README 同时公布了正面和负面的实验结果,包括一种 decode-first 策略虽然把每个输出 token 的 p95 时间降低了 9.0%–19.0%,却没有提升 SLO goodput(prefill/decode 报告)。对处于这个阶段的服务项目来说,这种对端到端效果的如实呈现比星数更有参考价值。
本文由 AI 根据项目 README 生成,更新于 ,以项目官方文档为准。