kvmux：一个零依赖、高性能的LLM推理网关，用C++20打造

kvmux是一个单二进制、零Kubernetes的OpenAI兼容网关，支持多后端（vLLM、llama.cpp、Ollama）统一接入，具备前缀亲和路由、熔断故障转移和细粒度延迟监控。

• 原作者/维护者：mickelsamuel
• 来源平台：github
• 原始标题：kvmux
• 原始链接：https://github.com/mickelsamuel/kvmux
• 来源发布时间/更新时间：2026-06-13T01:14:34Z

原作者与来源

• 原作者/维护者：mickelsamuel
• 来源平台：github
• 原始标题：kvmux
• 原始链接：https://github.com/mickelsamuel/kvmux
• 来源发布时间/更新时间：2026-06-13T01:14:34Z 原作者与来源\n\n- 原作者/维护者： mickelsamuel\n- 来源平台： GitHub\n- 原始标题： kvmux\n- 原始链接： https://github.com/mickelsamuel/kvmux\n- 发布时间： 2026年6月13日\n\n---\n\n背景：自托管LLM推理的痛点\n\n当你开始自托管大语言模型（LLM）推理服务时，很快会遇到一个现实问题：很少只运行单一推理引擎。一个真实的生产环境往往混合了多种后端——vLLM用于GPU高性能推理、llama.cpp-server用于CPU上的GGUF模型、Ollama用于快速原型和小模型测试。\n\n但应用层期望的是一个统一的OpenAI兼容端点，它要求：\n- 统一的API格式，无需为每个后端写不同客户端\n- 流式响应（SSE），保持token间延迟不被缓冲破坏\n- 后端故障时的自动故障转移\n- 多轮对话能命中已有KV缓存的后端，减少重复计算\n\n这就是kvmux要解决的核心问题。\n\n项目概述：kvmux是什么\n\nkvmux是一个用C++20编写的单二进制LLM推理网关，不需要Kubernetes或其他编排工具。它将异构后端（vLLM、llama.cpp-server、Ollama）统一在一个OpenAI兼容的HTTP端点后面。\n\n关键特性包括：\n- OpenAI兼容API：支持POST /v1/chat/completions（流式和非流式）、GET /v1/models、健康检查和Prometheus指标端点\n- SSE流式传输：每帧数据立即写入并刷新，配合TCP_NODELAY保持token间延迟（ITL）不被聚合\n- 前缀亲和路由：相同前缀的请求会被路由到同一后端，复用其前缀缓存（一种客户端前缀哈希亲和，无需订阅引擎KV事件）\n- 熔断与准入控制：每个后端有独立的健康检查和熔断器，全局并发上限和FIFO等待队列保护后端，溢出时返回429并带Retry-After头\n- 延迟仪表：TTFT（首token时间）、token间延迟、端到端延迟、队列时间，以及网关自身增加的延迟，全部以Prometheus直方图暴露\n\n架构设计：请求如何流动\n\n请求进入kvmux后的处理流程：\n\n\n客户端 → 监听器 → 会话 → 准入控制 → 路由层 → 后端\n ↓ ↓ ↓\n SSE重流 并发限制+队列 前缀亲和/轮询\n (逐帧flush) +健康熔断\n\n\n每个后端都有独立的健康检查和熔断逻辑。路由层根据前缀哈希或轮询策略选择健康后端。SSE写入器将上游响应逐帧转发给下游客户端。\n\n快速上手：十分钟内跑起来\n\n以Ollama作为单一后端的最简配置为例：\n\n1. 安装并启动Ollama\n\nbash\ncurl -fsSL https://ollama.com/install.sh | sh\nollama serve &\nollama pull llama3.2:1b\n\n\n2. 构建kvmux\n\n需要CMake ≥ 3.28、GCC 13或Clang 18、Boost ≥ 1.83：\n\nbash\ngit clone https://github.com/mickelsamuel/kvmux.git\ncd kvmux\ncmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release\ncmake --build build\n\n\n3. 运行网关\n\nbash\n./build/kvmux --config config/ollama-quickstart.toml\n\n\n4. 测试流式响应\n\nbash\ncurl -N http://127.0.0.1:8080/v1/chat/completions \\\n -H 'Content-Type: application/json' \\\n -d '{\"model\":\"llama3.2:1b\",\"stream\":true,\n \"messages\":[{\"role\":\"user\",\"content\":\"什么是LLM网关？\"}]}'\n\n\n你会看到data: {...}帧逐个token流式返回。\n\n配置详解：TOML格式\n\nkvmux使用单一TOML配置文件。未知键会硬失败并指出行列号，避免静默忽略配置错误。配置包括：\n\n- 网关监听地址和端口\n- 指标端点端口\n- 全局并发限制和队列大小\n- 后端列表：每个后端指定URL、模型列表、健康检查参数、熔断阈值\n- 路由策略：prefix_affinity或round_robin\n\n前缀亲和路由的原理\n\nkvmux的前缀亲和是一种客户端哈希策略：根据请求消息的前缀计算哈希，将相同前缀的请求路由到同一后端。这利用了LLM推理引擎的前缀缓存机制——当相同前缀的KV缓存已存在于某后端时，后续请求可以复用，显著降低TTFT。\n\n注意：这是v1.0的近似实现，不订阅引擎KV事件。v1.1可能会引入更精确的缓存感知。\n\n延迟监控与Prometheus指标\n\nkvmux在:9090/metrics暴露Prometheus格式的指标，使用OpenTelemetry GenAI直方图桶：\n\n- kvmux_request_duration_seconds：端到端请求延迟\n- kvmux_time_to_first_token_seconds：首token时间\n- kvmux_inter_token_latency_seconds：token间延迟\n- kvmux_queue_time_seconds：队列等待时间\n- kvmux_gateway_overhead_seconds：网关自身处理开销\n\n这些指标可用于构建SLA监控和自动扩缩容策略。\n\n局限与未来方向\n\n当前kvmux处于"公开构建中"状态。主要局限：\n\n- 前缀亲和是近似实现，非精确的KV缓存感知\n- 基准测试结果（亲和vs轮询） pending裸机运行\n- 当前README中的性能数据仅来自WSL2环境的初步测试\n\n未来v1.1可能引入：\n- 引擎KV事件订阅，实现精确缓存感知\n- 更多后端类型支持\n- 更丰富的路由策略\n\n为什么用C++20？\n\n作者坦诚说明：选择C++20是因为其系统编程背景，以及代理热路径（逐帧重流token）值得直接控制。这不是声称"必须用C++"，而是诚实的技术选择。\n\n结语\n\nkvmux为自托管LLM推理场景提供了一个轻量、高性能的网关解决方案。它填补了"简单反向代理"和"复杂服务网格"之间的空白——单二进制、零依赖、功能完整。对于需要统一多后端、关心延迟指标、希望保持基础设施简单的团队，kvmux值得评估。