smg

当你有10块GPU卡，却只有1个模型在跑：SMG 的破局之道

想象这样一个场景：团队花了 60 万购置了 8 卡 H100 集群，运维满心欢喜部署了 vLLM，结果监控大屏上一看——GPU 利用率只有 15%，剩下 85% 的算力在晒太阳。更糟的是，算法工程师过来说：「我们还要再加 SGLang、TensorRT-LLM 和 Ollama，每个跑不同的模型。」运维沉默了：「那……我每套都单独部署？」

Shepherd Model Gateway（SMG） 就是来解决这个问题的。它是一个用 Rust 编写的高性能 LLM 网关，一个入口、N 种后端、统一路由。无论你用的是 vLLM、SGLang、TensorRT-LLM 还是云端 OpenAI，只要走 SMG 一个地址，应用层完全不用改。

背景故事：为什么需要模型网关

大模型推理有两条路：自托管（vLLM/SGLang/TensorRT-LLM）和云端 API（OpenAI/Anthropic/Gemini）。自托管成本低、数据隐私好，但运维复杂；云端省心，但贵且有数据出境顾虑。

现实是企业往往两条路都要，于是出现了经典问题：多个推理后端如何统一管理？

早期方案是硬编码 URL，改一个后端地址要发一次版。后来有人用 Nginx 反代，但 Nginx 不懂 LLM 的 streaming、chat template 和 token 计数。vLLM 自己的代理层又只能代理 vLLM 实例。

SMG 的出现填补了这个空白：做一个 engine-agnostic（引擎无关）的高性能网关，同时理解 LLM 协议栈，能做智能路由、负载均衡、熔断、可观测性。

核心功能拆解

1. 统一入口：OpenAI 兼容协议

SMG 对外暴露标准的 OpenAI API 接口：

接口	说明
`POST /v1/chat/completions`	通用聊天补全
`POST /v1/completions`	文本补全
`POST /v1/responses`	Agent 工作流（支持工具调用）
`POST /v1/embeddings`	向量嵌入
`POST /messages`	Anthropic 风格消息 API

这意味着应用层代码完全不用改。原本指向 OpenAI 的请求，只需改个 base URL 就指向私有集群。SDK 重用、Prompt 模板复用、监控接入——全都无缝迁移。

2. 智能路由：8 种策略适配不同场景

cache_aware（生产默认）：SMG 最引以为傲的特性。维护 Radix Tree 镜像推理引擎的 KV Cache 状态，让相同前缀的请求路由到同一台机器，最大化 Cache 命中率，可减少 60-90% 的冗余计算。

power_of_two（轻量均衡）：随机选两台，选负载更轻的那台。O(1) 复杂度，无需全局状态。

consistent_hashing（会话亲和）：基于请求头哈希路由，同一会话的请求永远路由到同一 worker。

bucket（PD 分离）：专为 Prefill-Decode 分离架构设计，按请求长度分段路由。

3. 双协议栈：HTTP 代理 vs gRPC 全栈

HTTP 模式（Smart Proxy）：推理引擎跑完整 OpenAI 兼容服务器，SMG 只做路由和熔断。适合快速接入已有部署。

gRPC 模式（Full Server）：推理引擎只跑 raw inference，SMG 承担完整协议处理：tokenization（两级缓存，减少 60-90% CPU 开销）、Jinja2 chat template 填充、reasoning chain 提取、tool call 解析和 MCP 循环。

4. MCP 集成：给模型装上工具手

Model Context Protocol（MCP）让模型可以在一次对话中调用多个外部工具（Web Search、代码执行、数据库查询等）。SMG 内置 MCP Orchestrator，支持自动工具发现、Policy 审批和审计日志，模型永远无法直接接触网络，安全性有保障。

5. 企业级可靠性

Circuit Breaker（熔断器）：worker 连续失败时自动摘掉，防止雪崩
Multi-tenant Rate Limiting：多租户 token bucket 限流，支持 OIDC JWT 认证
HA Mesh：基于 SWIM 协议的分布式 mesh，多节点无单点故障
WASM 插件：自定义请求/响应转换逻辑，无需修改核心代码
Chat History：对话历史支持 PostgreSQL/Redis/Oracle 等多种存储后端

6. 可观测性：40+ Prometheus 指标

内置 40+ metrics 覆盖请求延迟/吞吐量/错误率/Cache 命中率，OpenTelemetry 分布式追踪，结构化 JSON 日志带 request correlation ID。

技术架构解析

SMG 采用 Rust 语言，选择 Rust 是因为性能和内存安全——LLM 网关需要处理大量并发连接和高速数据吞吐，Rust 的 zero-cost abstraction 和无 GC 保证了稳定的低延迟。

代码采用 Cargo workspace 组织，包含 17 个内部 crate：

model_gateway：核心网关，src/main.rs 是双二进制入口（smg / amg 变体）
crates/protocols：OpenAI 和 Anthropic 协议解析
crates/reasoning_parser：CoT 推理链解析（支持 DeepSeek-R1、Qwen3 等 thinking 模型）
crates/tool_parser：function calling 解析
crates/workflow：WASM 工作流引擎
crates/tokenizer：tokenization + 两级缓存
crates/auth：OIDC/JWT 多租户认证
crates/mcp：MCP 客户端 + 策略引擎
crates/mesh：HA mesh 网络（SWIM 协议）
crates/kv_index：Radix Tree，KV Cache 状态镜像
crates/wasm：WASM 插件运行时
bindings/python、bindings/golang：多语言 SDK

上手体验

三种安装方式

# Docker（推荐，生产环境）
docker pull lightseekorg/smg:latest

# Python 包
pip install smg

# Rust 源码编译
cargo install smg

最简运行

# 单个 worker
smg launch --worker-urls http://localhost:8000

# 多个 worker + 缓存感知路由
smg launch --worker-urls http://gpu1:8000 http://gpu2:8000 --policy cache_aware

# Kubernetes 服务发现（自动感知 Pod 扩缩容）
smg launch --service-discovery --selector app=sglang-worker --service-discovery-namespace inference

发请求测试

curl http://localhost:30000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "llama3", "messages": [{"role": "user", "content": "Hello!"}]}'

局限与争议

1. 无 Web UI：没有图形界面，配置全靠命令行和配置文件，对非 DevOps 团队不够友好。

2. Rust 编译门槛：源码编译时 Rust 工具链安装和首次编译（10+ 分钟）是门槛。虽然有 Docker 镜像缓解，但自定义构建还是要面对 Rust 编译问题。

3. MCP 生态尚在成熟：MCP 协议相对新（2024 年底才火起来），官方 MCP Server 生态还比较小，第三方工具集成需要自己动手。

4. 团队规模有限：主要维护者 3 人，虽然 CI/CD 流程完善，但长期维护的人力风险需要注意。

行业意义

SMG 的出现代表了一个趋势：LLM 推理基础设施的专业化分工。随着模型越来越多、部署场景越来越复杂，市场需要专门的网关层来统一管理。SMG 的核心价值在于：

降低多引擎管理复杂度：一条命令同时管理 vLLM + SGLang + TensorRT-LLM
最大化 GPU 利用率：cache-aware 路由直接减少无效计算，省的是真金白银的电费
统一协议层：让应用层不用关心背后跑的是什么引擎

快速参考

维度	信息
编程语言	Rust（核心）+ Python/Go（bindings）
License	Apache-2.0
支持后端	vLLM, TensorRT-LLM, TokenSpeed, SGLang, Ollama, OpenAI, Anthropic, Gemini, Bedrock, Azure
协议接口	OpenAI Chat/Completions/Embeddings, Anthropic Messages, Responses API, MCP
部署方式	Docker / PyPI / Cargo / Kubernetes
硬件需求	Gateway 本身无需 GPU（1GB RAM），GPU 由后端推理引擎承载
路由策略	8 种（含 cache_aware/power_of_two/consistent_hashing/bucket 等）
可靠性	熔断、重试、多租户限流、WASM 插件、HA Mesh
可观测性	40+ Prometheus metrics、OpenTelemetry tracing、结构化日志
Docker 镜像	`ghcr.io/lightseekorg/smg`

当你有10块GPU卡，却只有1个模型在跑：SMG 的破局之道

背景故事：为什么需要模型网关

现实是企业往往两条路都要，于是出现了经典问题：多个推理后端如何统一管理？

SMG 的出现填补了这个空白：做一个 engine-agnostic（引擎无关）的高性能网关，同时理解 LLM 协议栈，能做智能路由、负载均衡、熔断、可观测性。

核心功能拆解

1. 统一入口：OpenAI 兼容协议

SMG 对外暴露标准的 OpenAI API 接口：

接口	说明
`POST /v1/chat/completions`	通用聊天补全
`POST /v1/completions`	文本补全
`POST /v1/responses`	Agent 工作流（支持工具调用）
`POST /v1/embeddings`	向量嵌入
`POST /messages`	Anthropic 风格消息 API

2. 智能路由：8 种策略适配不同场景

power_of_two（轻量均衡）：随机选两台，选负载更轻的那台。O(1) 复杂度，无需全局状态。

consistent_hashing（会话亲和）：基于请求头哈希路由，同一会话的请求永远路由到同一 worker。

bucket（PD 分离）：专为 Prefill-Decode 分离架构设计，按请求长度分段路由。

3. 双协议栈：HTTP 代理 vs gRPC 全栈

HTTP 模式（Smart Proxy）：推理引擎跑完整 OpenAI 兼容服务器，SMG 只做路由和熔断。适合快速接入已有部署。

4. MCP 集成：给模型装上工具手

5. 企业级可靠性

Circuit Breaker（熔断器）：worker 连续失败时自动摘掉，防止雪崩
Multi-tenant Rate Limiting：多租户 token bucket 限流，支持 OIDC JWT 认证
HA Mesh：基于 SWIM 协议的分布式 mesh，多节点无单点故障
WASM 插件：自定义请求/响应转换逻辑，无需修改核心代码
Chat History：对话历史支持 PostgreSQL/Redis/Oracle 等多种存储后端

6. 可观测性：40+ Prometheus 指标

内置 40+ metrics 覆盖请求延迟/吞吐量/错误率/Cache 命中率，OpenTelemetry 分布式追踪，结构化 JSON 日志带 request correlation ID。

技术架构解析

代码采用 Cargo workspace 组织，包含 17 个内部 crate：

model_gateway：核心网关，src/main.rs 是双二进制入口（smg / amg 变体）
crates/protocols：OpenAI 和 Anthropic 协议解析
crates/reasoning_parser：CoT 推理链解析（支持 DeepSeek-R1、Qwen3 等 thinking 模型）
crates/tool_parser：function calling 解析
crates/workflow：WASM 工作流引擎
crates/tokenizer：tokenization + 两级缓存
crates/auth：OIDC/JWT 多租户认证
crates/mcp：MCP 客户端 + 策略引擎
crates/mesh：HA mesh 网络（SWIM 协议）
crates/kv_index：Radix Tree，KV Cache 状态镜像
crates/wasm：WASM 插件运行时
bindings/python、bindings/golang：多语言 SDK

上手体验

三种安装方式

# Docker（推荐，生产环境）
docker pull lightseekorg/smg:latest

# Python 包
pip install smg

# Rust 源码编译
cargo install smg

最简运行

# 单个 worker
smg launch --worker-urls http://localhost:8000

# 多个 worker + 缓存感知路由
smg launch --worker-urls http://gpu1:8000 http://gpu2:8000 --policy cache_aware

# Kubernetes 服务发现（自动感知 Pod 扩缩容）
smg launch --service-discovery --selector app=sglang-worker --service-discovery-namespace inference

发请求测试

curl http://localhost:30000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "llama3", "messages": [{"role": "user", "content": "Hello!"}]}'

局限与争议

1. 无 Web UI：没有图形界面，配置全靠命令行和配置文件，对非 DevOps 团队不够友好。

2. Rust 编译门槛：源码编译时 Rust 工具链安装和首次编译（10+ 分钟）是门槛。虽然有 Docker 镜像缓解，但自定义构建还是要面对 Rust 编译问题。

3. MCP 生态尚在成熟：MCP 协议相对新（2024 年底才火起来），官方 MCP Server 生态还比较小，第三方工具集成需要自己动手。

4. 团队规模有限：主要维护者 3 人，虽然 CI/CD 流程完善，但长期维护的人力风险需要注意。

行业意义

降低多引擎管理复杂度：一条命令同时管理 vLLM + SGLang + TensorRT-LLM
最大化 GPU 利用率：cache-aware 路由直接减少无效计算，省的是真金白银的电费
统一协议层：让应用层不用关心背后跑的是什么引擎

快速参考

维度	信息
编程语言	Rust（核心）+ Python/Go（bindings）
License	Apache-2.0
支持后端	vLLM, TensorRT-LLM, TokenSpeed, SGLang, Ollama, OpenAI, Anthropic, Gemini, Bedrock, Azure
协议接口	OpenAI Chat/Completions/Embeddings, Anthropic Messages, Responses API, MCP
部署方式	Docker / PyPI / Cargo / Kubernetes
硬件需求	Gateway 本身无需 GPU（1GB RAM），GPU 由后端推理引擎承载
路由策略	8 种（含 cache_aware/power_of_two/consistent_hashing/bucket 等）
可靠性	熔断、重试、多租户限流、WASM 插件、HA Mesh
可观测性	40+ Prometheus metrics、OpenTelemetry tracing、结构化日志
Docker 镜像	`ghcr.io/lightseekorg/smg`

社区活跃度

当你有10块GPU卡，却只有1个模型在跑：SMG 的破局之道

背景故事：为什么需要模型网关

核心功能拆解

1. 统一入口：OpenAI 兼容协议

2. 智能路由：8 种策略适配不同场景

3. 双协议栈：HTTP 代理 vs gRPC 全栈

4. MCP 集成：给模型装上工具手

5. 企业级可靠性

6. 可观测性：40+ Prometheus 指标

技术架构解析

上手体验

三种安装方式

最简运行

发请求测试

局限与争议

行业意义

快速参考

社区活跃度

当你有10块GPU卡，却只有1个模型在跑：SMG 的破局之道

背景故事：为什么需要模型网关

核心功能拆解

1. 统一入口：OpenAI 兼容协议

2. 智能路由：8 种策略适配不同场景

3. 双协议栈：HTTP 代理 vs gRPC 全栈

4. MCP 集成：给模型装上工具手

5. 企业级可靠性

6. 可观测性：40+ Prometheus 指标

技术架构解析

上手体验

三种安装方式

最简运行

发请求测试

局限与争议

行业意义

快速参考