# rbg

**Repository Path**: underdogs/rbg

## Basic Information

- **Project Name**: rbg
- **Description**: No description available
- **Primary Language**: Go
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-08
- **Last Updated**: 2025-12-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RoleBasedGroup API 中文文档

[English](./README.md)｜简体中文

**RoleBasedGroup**：用于编排分布式、有状态的 AI 推理工作负载，支持多角色协同和内置服务发现。它为生产环境中的大语言模型推理（尤其是解耦架构，如 Prefill/Decode 分离场景）提供了通用的部署范式。  

## 最新消息 🔥

[2025-09-23] 发布 RBG v0.4.0 版本，
发布内容请参考[release notes](https://github.com/sgl-project/rbg/releases/v0.4.0)。

[2025-07-21] 发布 RBG v0.3.0 版本，
发布内容请参考[release notes](https://github.com/sgl-project/rbg/releases/v0.3.0)。

## 概述

传统的 Kubernetes 原语（如原生 StatefulSet / Deployment）难以很好地支持具有以下特点的大语言模型推理服务：

- 以多角色拓扑（如网关/路由/Prefill/Decode）的形式运行；
- 对 GPU/网络拓扑结构性能敏感；
- 需要跨角色的原子操作（部署、升级、扩缩容和故障恢复）。

RBG 将推理服务视为一个基于角色的组，而非一组松散的工作负载。它将服务建模为一个具备拓扑结构、有状态、可协同的多角色有机体，并将其作为一个整体单元进行管理。

## 核心概念

- **角色**  
  基础调度与发布单元。每个角色（如 prefill、decode）拥有独立的配置、生命周期和策略。

- **角色组**  
  由多个角色共同构成的一个逻辑服务（例如一次 LLM 推理部署）。

## 核心特性

RBG 将“角色”视为调度编排的原子单位，并建立不同角色之间的可配置关系。它将一个推理服务视为一个具备拓扑结构、有状态、可协同的“角色有机体”，而非多个孤立 Deployment 的集合。

基于此理念，RBG 构建了 **SCOPE 五大核心能力**：

### 🔁 稳定
- 基于唯一 RoleID 注入与最小替换域原则，实现拓扑感知的确定性运维。

### 🤝 协同
- 跨角色策略引擎，支持部署配对、协同升级、联动恢复与协调伸缩。

### 🧭 编排
- 在角色组中定义角色依赖与精确启动顺序；
- 拓扑自感知服务发现——将完整角色拓扑信息注入 Pod，无需依赖外部服务发现组件。

### ⚡ 性能
- 拓扑感知调度，支持硬件亲和性（GPU-NVLink > PCIe > RDMA > VPC）与角色亲和性调度策略。

### 🧩 可扩展
- 基于声明式 API 与插件机制，实现面向未来的部署抽象，可无侵入的快速适配新架构。

## 架构图

![rbgs-concept](doc/rbgs-concept.png)

## 快速开始

- [安装 RBG Controller](doc/install.md)
- [快速开始](doc/quick_start.md)

## Documentation

如果需要详细了解 RBG 的特性及使用示例，请参考[文档](doc/TOC.md).

## 参与贡献

欢迎通过提交 Issue 和 PR 参与贡献！详见[贡献指南](CONTRIBUTING.md)

### Community, discussion, contribution, and support

访问 [Kubernetes 社区页面](https://kubernetes.io/community/)了解参与方式。

项目维护者联系方式：

- [Slack](https://sgl-fru7574.slack.com/archives/C098X0LQZV5)

### 行为准则

参与 Kubernetes 社区需遵守 [Kubernetes 行为准则](doc/code-of-conduct.md)。

## Acknowledgment

我们在设计和实现时参考了这些优秀的开源项目：[lws](https://github.com/kubernetes-sigs/lws)