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`