# 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](https://github.com/alibaba/higress) 构建，负责 API 路由与负载均衡。
- **SQL Database：** 默认使用嵌入式 PostgreSQL，也支持外部 PostgreSQL 或 MySQL。

![architecture](docs/assets/gpustack-v2-architecture.png)

详细架构说明请参见 [架构文档](docs/architecture.md)。

## 部署方式

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

| 部署方式 | 适合场景 | 文档 |
|----------|---------|------|
| **Docker 单容器** | 快速体验、演示、单节点 | [下方快速开始](#快速开始) |
| **Docker Compose** | 开发测试、小团队、含监控部署 | [Docker Compose 部署指南](docs/deployment/docker-compose.md) |
| **Kubernetes (Helm)** | 生产环境、大规模、多节点 | [Kubernetes 部署指南](docs/deployment/kubernetes.md) |

## 快速开始

### 前置要求

1. Linux 节点（支持 NVIDIA GPU、AMD GPU、Ascend NPU 等加速器）。
2. 已安装 [Docker](https://docs.docker.com/engine/install/)。
3. GPU 节点需安装对应驱动和 [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)（NVIDIA GPU 场景）。

### 1. 部署 Server

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

```bash
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 合一）

```bash
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. 获取管理员密码

```bash
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 兼容接口：

```bash
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 部署指南](docs/deployment/docker-compose.md) — 最小部署 + 完整监控部署
- [Worker 节点部署指南](docs/deployment/worker.md) — 多 GPU 节点 Worker 部署、多厂商 GPU 支持
- [Kubernetes (Helm) 部署指南](docs/deployment/kubernetes.md) — 生产环境大规模部署

## 构建

### 构建 Wheel 包

1. 安装 Python 3.10 ~ 3.12。

2. 执行构建：

```bash
make build
```

构建产物位于 `dist` 目录。

### 构建容器镜像

```bash
make package
```

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

## 开发

### 本地开发

```bash
# 安装开发依赖
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](docs/development.md)。

## 文档

完整文档请访问 [官方文档站点](https://docs.gpustack.ai)。

项目内文档：

- [架构文档](docs/architecture.md)
- [Docker Compose 部署指南](docs/deployment/docker-compose.md)
- [Worker 节点部署指南](docs/deployment/worker.md)
- [Kubernetes (Helm) 部署指南](docs/deployment/kubernetes.md)

## 加入社区

有任何问题或建议，欢迎加入我们的 [Discord 社区](https://discord.gg/VXYJzuaqwD) 获取支持。

## 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](./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.
