maas-base

MaaS-Base

MaaS-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。

架构

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

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

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

部署方式

MaaS-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 maas-base \
    --restart unless-stopped \
    -p 80:80 \
    --volume maas-base-data:/var/lib/maas-base \
    maas-base/maas-base

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

sudo docker run -d --name maas-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 maas-base-data:/var/lib/maas-base \
    -v /var/lib/kubelet/device-plugins:/var/lib/kubelet/device-plugins \
    -e NVIDIA_VISIBLE_DEVICES=all \
    -e NVIDIA_DRIVER_CAPABILITIES=compute,utility \
    maas-base/maas-base

2. 获取管理员密码

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

3. 访问 UI

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

注意： 本项目为纯后端服务，前端请使用独立部署的 UI 镜像。

4. 部署模型

1. 在前端 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
   }'
   

API 接口文档

本项目为纯后端服务，提供 RESTful API 供前端调用。所有 API 基础路径为 http://<服务器IP>。

认证方式

方式	说明
Cookie 认证	登录后通过 Cookie gpustack_session 访问
Bearer Token	在 Header 中添加 Authorization: Bearer <token>
API Key	在 Header 中添加 X-API-Key: <api_key>
Basic Auth	用户名密码 Basic 认证

核心管理 API（/v2 前缀）

资源	路径	说明
用户	/v2/users	用户管理（CRUD）
我的信息	/v2/users/me	当前用户信息
API 密钥	/v2/api-keys	API Key 管理
用量统计	/v2/usage	API 调用用量统计
集群	/v2/clusters	集群管理
Worker	/v2/workers	Worker 节点管理
Worker 池	/v2/worker-pools	Worker 池管理
GPU 设备	/v2/gpu-devices	GPU 设备信息
云凭证	/v2/cloud-credentials	云厂商凭证管理
模型	/v2/models	模型管理
模型实例	/v2/model-instances	模型实例管理
模型文件	/v2/model-files	模型文件管理
模型集	/v2/model-sets	模型集合
Draft 模型	/v2/draft-models	草稿模型
推理后端	/v2/inference-backends	推理后端配置
模型提供商	/v2/model-providers	模型提供商
模型路由	/v2/model-routes	模型路由配置
模型路由目标	/v2/model-route-targets	模型路由目标
模型路由主体	/v2/model-routes	模型路由主体（Principal）
模型评估	/v2/model-evaluations	模型评估
基准测试	/v2/benchmarks	基准测试
测试配置	/v2/benchmark-profiles	基准测试配置
组织	/v2/organizations	组织管理
组织成员	/v2/organizations/members	组织成员管理
用户组	/v2/user-groups	用户组管理
我的组织	/v2/users/me/orgs	当前用户所属组织
仪表板	/v2/dashboard	仪表板数据（仅管理员）
集群访问	/v2/cluster-access	集群访问控制

推理 API（OpenAI 兼容）

路径	说明
/v1/chat/completions	对话补全
/v1/completions	文本补全
/v1/embeddings	Embedding 向量
/v1/models	可用模型列表
/v1/rerank	重排序

/v1-openai/* 为旧版兼容路径，推荐使用 /v1/*。

健康检查

路径	说明
/healthz	健康检查
/readyz	就绪检查

认证相关

路径	说明
/auth/login	用户登录
/auth/token	Token 相关

WebSocket

路径	说明
/ws/*	WebSocket 代理

OpenAPI 文档

启动后可访问 http://<服务器IP>/docs 查看完整的 Swagger/OpenAPI 文档。

完整部署指南

如需更详细的部署说明（含 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 MaaS-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.