maas-base

MASS-Base

MASS-Base（Model-as-a-Service Base）是一个开源的模型服务（Model-as-a-Service）基础平台，用于高效管理和调度 AI 模型推理服务。它支持多种推理引擎（vLLM、SGLang、TensorRT-LLM 等），可跨多节点进行性能优化与资源编排。

核心特性

• 多集群管理： 统一管理多个环境中的计算节点，支持本地服务器和云平台。
• 可插拔推理引擎： 自动配置 vLLM、SGLang、TensorRT-LLM 等高性能推理引擎，也支持自定义引擎接入。
• 开箱即用的模型部署： 新模型发布即可快速部署，内置模型目录和兼容性检查。
• 性能优化配置： 内置低延迟与高吞吐预调优模式，支持扩展 KV Cache（如 LMCache、HiCache）以降低 TTFT，并内置投机解码（EAGLE3、MTP、N-grams）支持。
• 企业级运维能力： 支持自动故障恢复、负载均衡、监控（Prometheus + Grafana）、认证与访问控制。
• 多硬件支持： NVIDIA GPU、AMD GPU、Ascend NPU、Hygon DCU、MThreads GPU、Iluvatar GPU、MetaX GPU、Cambricon MLU、T-Head PPU。

架构

MASS-Base 由以下核心组件构成：

• API Server： 基于 FastAPI 构建的 RESTful 接口层，处理认证与授权。
• Scheduler： 负责将模型实例调度分配到工作节点。
• Controllers： 管理系统资源状态，处理模型实例的扩缩容。
• Worker： 检测 GPU 设备，管理模型实例的生命周期并导出性能指标。
• AI Gateway： 基于 Higress 构建，负责 API 路由与负载均衡。
• SQL Database： 默认使用嵌入式 PostgreSQL，也支持外部 PostgreSQL 或 MySQL。

详细架构说明请参见 架构文档。

部署方式

MASS-Base 支持多种部署方式，请根据场景选择：

部署方式	适合场景	文档
Docker 单容器	快速体验、演示、单节点	下方快速开始
Docker Compose	开发测试、小团队、含监控部署	Docker Compose 部署指南
Kubernetes (Helm)	生产环境、大规模、多节点	Kubernetes 部署指南

快速开始

前置要求

1. Linux 节点（支持 NVIDIA GPU、AMD GPU、Ascend NPU 等加速器）。
2. 已安装 Docker。
3. GPU 节点需安装对应驱动和 NVIDIA Container Toolkit（NVIDIA GPU 场景）。

1. 部署 Server

方式 A：无 GPU 的 CPU 节点（纯 Server）

sudo docker run -d --name mass-base \
    --restart unless-stopped \
    -p 80:80 \
    --volume mass-base-data:/var/lib/mass-base \
    mass-base/mass-base

方式 B：有 GPU 的节点（Server + Worker 合一）

sudo docker run -d --name mass-base \
    --restart unless-stopped \
    --privileged \
    --network host \
    --ipc host \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v /var/run/cdi:/var/run/cdi \
    -v mass-base-data:/var/lib/mass-base \
    -v /var/lib/kubelet/device-plugins:/var/lib/kubelet/device-plugins \
    -e NVIDIA_VISIBLE_DEVICES=all \
    -e NVIDIA_DRIVER_CAPABILITIES=compute,utility \
    mass-base/mass-base

2. 获取管理员密码

sudo docker exec mass-base cat /var/lib/mass-base/initial_admin_password

3. 访问 UI

在浏览器中打开 http://<服务器IP>，使用用户名 admin 和上一步获取的密码登录。

4. 部署模型

1. 在 MASS-Base UI 中进入 Catalog 页面。
2. 选择可用模型，通过兼容性检查后点击 Save 部署。
3. 部署状态变为 Running 后即可通过 UI Playground 或 API 调用。

5. 使用 API

1. 在 UI 中进入 API Keys 页面，创建新的 API Key。

2. 使用 API Key 调用 OpenAI 兼容接口：

   export MASS_API_KEY=your_api_key
   curl http://your_mass_base_server_url/v1/chat/completions \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $MASS_API_KEY" \
   -d '{
   "model": "your-model-name",
   "messages": [
     { "role": "system", "content": "You are a helpful assistant." },
     { "role": "user", "content": "Tell me a joke." }
   ],
   "stream": true
   }'
   

完整部署指南

如需更详细的部署说明（含 Docker Compose 完整监控栈、Worker 节点独立部署、Kubernetes Helm 部署等），请参见：

• Docker Compose 部署指南 — 最小部署 + 完整监控部署
• Worker 节点部署指南 — 多 GPU 节点 Worker 部署、多厂商 GPU 支持
• Kubernetes (Helm) 部署指南 — 生产环境大规模部署

构建

构建 Wheel 包

1. 安装 Python 3.10 ~ 3.12。

2. 执行构建：

   make build
   

构建产物位于 dist 目录。

构建容器镜像

make package

注意： 镜像构建仅支持 Linux/macOS。

开发

本地开发

# 安装开发依赖
make install

# 本地开发启动（需先运行数据库）
uv run gpustack start \
  --database-url postgresql://postgres:mysecretpassword@localhost:5432/postgres \
  --gateway-mode disabled \
  --api-port 80

常用命令

命令	说明
make install	安装 uv、同步依赖、设置 pre-commit hooks
make deps	同步锁定依赖
make generate	生成代码（OpenAPI Client 等）
make lint	运行代码检查（flake8、black 等）
make test	运行单元测试
make build	构建 wheel 包
make ci	完整 CI 流水线

详细开发指南请参见 Development Guide。

文档

完整文档请访问 官方文档站点。

项目内文档：

• 架构文档
• Docker Compose 部署指南
• Worker 节点部署指南
• Kubernetes (Helm) 部署指南

加入社区

有任何问题或建议，欢迎加入我们的 Discord 社区 获取支持。

License

Copyright (c) 2024-2026 The MASS-Base authors

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at LICENSE.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.