Backend.AI

Backend.AI 是一个精简的、基于容器的计算集群平台，支持主流的计算和机器学习框架以及多种编程语言，并且能够插拔式地接入异构加速器，包括 CUDA GPU、ROCm GPU、Rebellions、FuriosaAI、HyperAccel、Google TPU、Graphcore IPU 等 NPU。

它通过名为“Sokovan”的编排器，利用自定义的任务调度器，按需或批量为多租户计算会话分配并隔离底层计算资源。

其所有功能均以 REST 和 GraphQL API 的形式对外暴露。

要求

Python 及构建工具

• Python: 3.13.x（主分支需要 CPython 3.13.7）
• Pantsbuild: 2.27.x
• 请参阅 完整的版本兼容性表

基础设施

必需：

• Docker 20.10+（带 Compose v2）
• PostgreSQL 16+（已测试 16.3）
• Redis 7.2+（已测试 7.2.11）
• etcd 3.5+（已测试 3.5.14）
• Prometheus 3.x（已测试 3.1.0）

推荐（用于可观测性）：

• Grafana 11.x（已测试 11.4.0）
• Loki 3.x（已测试 3.5.0）
• Tempo 2.x（已测试 2.7.2）
• OpenTelemetry 收集器

→ 详细的基础设施设置：基础设施文档

系统

• 操作系统：Linux（基于 Debian/RHEL）或 macOS
• 权限：安装时需具有 sudo 权限
• 资源：建议开发环境至少配备 4 核 CPU 和 8GB 内存

快速入门

快速入门（开发）

1. 克隆并安装

git clone https://github.com/lablup/backend.ai.git
cd backend.ai
./scripts/install-dev.sh

该脚本将执行以下操作：

• 检查所需的依赖项（Docker、Python 等）
• 使用 Pantsbuild 设置 Python 虚拟环境
• 启动半堆栈基础设施（PostgreSQL、Redis、etcd、Grafana 等）
• 初始化数据库模式
• 创建默认的 API 密钥对和用户账户

2. 启动 Backend.AI 服务

在不同的终端中分别启动各个组件：

管理器（终端 1）：

./backend.ai mgr start-server --debug

代理（终端 2）：

./backend.ai ag start-server --debug

存储代理（终端 3）：

./py -m ai.backend.storage.server

Web 服务器（终端 4）：

./py -m ai.backend.web.server

应用代理（终端 5-6，可选，用于容器内服务访问）：

./backend.ai app-proxy-coordinator start-server --debug
./backend.ai app-proxy-worker start-server --debug

3. 运行您的第一个会话

设置客户端环境：

source env-local-user-session.sh
# 该脚本会打印您的默认用户 ID 和密码；
./backend.ai login
# 在提示时输入上述显示的用户 ID 和密码。

运行一个简单的 Python 会话：

./backend.ai run python -c "print('Hello Backend.AI!')"

或者使用 env-local-*.sh 文件中的凭据，访问 Web UI：http://localhost:8090。

访问计算会话（即内核）

Backend.AI 提供了到各个计算会话（容器）的 WebSocket 隧道，使用户能够通过浏览器和客户端 CLI 安全地直接访问容器内的应用程序。

• Jupyter：数据科学家最喜爱的工具
  • 大多数容器镜像都内置了 Jupyter 和 JupyterLab 支持。
• 基于 Web 的终端
  • 所有容器会话都内置了 ttyd 支持。
• SSH
  • 所有容器会话都内置了 SSH/SFTP/SCP 支持，并自动生成每个用户的 SSH 密钥对。 PyCharm 和其他 IDE 可以使用 SSH 远程解释器来创建按需会话。
• VSCode
  • 大多数容器会话都内置了基于 Web 的 VSCode 支持。

存储操作

Backend.AI 在现有的网络存储（如 NFS/SMB）之上提供了一个抽象层，称为 vfolder（虚拟文件夹）。 每个 vfolder 就像一个云存储，可以挂载到任何计算会话中，并可在用户和用户组之间共享，同时赋予不同的权限。

多节点测试及生产环境的安装

请参阅我们的 文档，获取社区支持的相关资料。 如需专业的付费支持和部署方案，请联系销售团队（contact@lablup.com）。

架构

有关完整的系统架构、组件交互及基础设施细节，请参阅：

组件架构文档

本文档涵盖：

• 系统架构图和组件流程
• 端口号和基础设施设置
• 组件依赖关系和通信协议
• 开发与生产环境配置

本仓库内容

本仓库包含所有开源的服务器端组件以及 Python 客户端 SDK， 作为 API 客户端的参考实现。

目录结构

• src/ai/backend/: 源代码
  • manager/: 管理器作为集群控制平面
  • manager/api: 管理器的 API 处理程序
  • account_manager/: 统一的用户档案和 SSO 管理
  • agent/: 代理作为每个节点的控制器
  • agent/docker/: 代理的 Docker 后端
  • agent/k8s/: 代理的 Kubernetes 后端
  • agent/dummy/: 代理的虚拟后端
  • kernel/: 代理的内核运行时对应组件
  • runner/: 代理在内核中预编译的二进制文件
  • helpers/: 代理在内核中的辅助工具包
  • common/: 共享工具
  • client/: 客户端 SDK
  • cli/: 所有组件的统一命令行界面
  • install/: 基于 SCIE 的 TUI 安装程序
  • storage/: 存储代理，用于卸载存储操作
  • storage/api: 存储代理面向管理器和客户端的 API
  • appproxy/: 应用代理，用于从外部访问容器应用
  • appproxy/coordinator: 应用代理协调器，负责配置路由电路
  • appproxy/worker: 应用代理工作节点，负责转发流量
  • web/: Web UI 服务器
    • static/: Backend.AI WebUI 发布产物
  • logging/: 日志子系统
  • plugin/: 插件子系统
  • test/: 集成测试套件
  • testutils/: 单元测试中使用的共享工具
  • meta/: 旧版元数据包
  • accelerator/: 内置加速器插件
• docs/: 统一日志文档
• tests/
  • manager/, agent/, ...: 各组件的单元测试
• configs/
  • manager/, agent/, ...: 各组件的示例配置
• docker/: 辅助容器的 Dockerfile
• fixtures/
  • manager/, ...: 各组件的开发环境和测试用例
• plugins/: 用于放置加速器、监控器等插件的目录
• scripts/: 用于辅助开发流程的脚本
  • install-dev.sh: 从工作副本进行单节点开发环境搭建的脚本
• stubs/: 我们编写的类型注解存根包
• tools/: 用于存放与 Pants 工具相关的文件的目录
• dist/: 用于存放构建产物（.whl 文件）和由 Pants 导出的虚拟环境的目录
• changes/: 用于 towncrier 的新闻片段
• pants.toml: Pants 构建工具的配置文件
• pyproject.toml: 工具配置文件（towncrier、pytest、mypy）
• BUILD: 根级构建配置文件
• **/BUILD: 各目录的构建配置文件
• BUILD_ROOT: 用于标记 Pants 构建根目录的标识符
• CLAUDE.md: 代理辅助开发的指导手册
• requirements.txt: 统一的依赖清单
• *.lock, tools/*.lock: 依赖锁定文件
• docker-compose.*.yml: 各版本推荐的半栈容器配置
• README.md: 当前文件
• MIGRATION.md: 主要版本间升级的迁移指南
• VERSION: 统一的版本声明

服务器端组件采用 LGPLv3 许可证，旨在促进开源社区中的非专有开放创新；而其他共享库和客户端 SDK 则采用 MIT 许可证。

如果您仅按原样运行服务器端组件（例如，直接以守护进程方式运行，或在您的代码中不加修改地导入这些组件），则没有义务公开您的服务或系统源代码。 如需商业咨询及针对具体使用场景的更多许可细节和选项，请联系我们（contact-at-lablup-com）。

主要组件

Backend.AI 由以下核心组件组成：

服务器端组件

管理器 - 中央 API 网关和编排器

• 路由 REST/GraphQL 请求并编排集群操作
• 通过 Sokovan 编排器进行会话调度
• 用户身份验证和 RBAC 授权
• 插件接口：backendai_scheduler_v10、backendai_agentselector_v10、backendai_hook_v20、backendai_webapp_v20、backendai_monitor_stats_v10、backendai_monitor_error_v10
• 旧版仓库：https://github.com/lablup/backend.ai-manager

代理 - 计算节点上的内核生命周期管理

• 管理各个节点上的 Docker 容器（内核）
• 通过心跳机制自动注册到集群
• 插件接口：backendai_accelerator_v21、backendai_monitor_stats_v10、backendai_monitor_error_v10
• 旧版仓库：https://github.com/lablup/backend.ai-agent

存储代理 - 虚拟文件夹和存储后端抽象

• 提供多存储后端的统一接口
• 实时性能指标和加速 API
• 旧版仓库：https://github.com/lablup/backend.ai-storage-proxy

Web 服务器 - Web UI 托管和会话管理

• 托管 Backend.AI WebUI（SPA）
• 会话管理和 API 请求签名
• 旧版仓库：https://github.com/lablup/backend.ai-webserver

同步静态 Backend.AI WebUI 版本：

$ scripts/download-webui-release.sh <要下载的目标版本>

应用代理 - 服务路由和负载均衡

• 将流量路由到容器内的服务（Jupyter、VSCode 等）
• 动态电路配置和健康监测

容器运行时组件

内核 - 容器镜像配方

• 基于 Dockerfile 的计算环境配方
• 支持流行的机器学习框架和编程语言

Jail - 可编程沙盒（Rust）

• 基于 ptrace 的系统调用过滤
• 资源控制和安全强化

Hook - 容器内运行时库

• libc 替换以实现资源控制
• 基于 Web 的交互式 stdin 支持

客户端 SDK 库

我们提供多种流行编程语言的客户端 SDK（MIT 许可证）：

• Python - pip install backend.ai-client | GitHub | 包含 CLI
• Java - 发布页面
• Javascript - npm install backend.ai-client | GitHub
• PHP - （准备中）composer require lablup/backend.ai-client | GitHub

插件

Backend.AI 通过 Python 包的入口点支持基于插件的扩展性：

加速器插件 (backendai_accelerator_v21)

• CUDA - NVIDIA GPU 支持
• CUDA Mock - 无需实际 GPU 的开发环境
• ROCm - AMD GPU 支持
• Furiosa - Furiosa NPU（Warboy / RNGD）支持
• Hyperaccel - Hyperaccel LPU 支持
• IPU - Graphcore IPU 支持
• Rebellions - Rebellions NPU（ATOM、ATOM+、ATOM Max）支持
• Tenstorrent - Tenstorrent NPU（Wormhole、Blackhole）支持
• TPU - Google TPU（v2、v3）支持

监控插件

• backendai_monitor_stats_v10 - Datadog 统计信息收集器
• backendai_monitor_error_v10 - Sentry 异常收集器

遗留组件

媒体库 - 多媒体输出支持（已不再维护）

IDE 扩展 - （已弃用：请改用内核中的 Jupyter Lab、VSCode Server 或 SSH）

• VSCode Live Code Runner
• Atom Live Code Runner

开发

构建软件包

构建 Python 的 wheel 文件或 SCIE（自包含可安装执行文件）：

./scripts/build-wheels.sh  # 构建 .whl 包
./scripts/build-scies.sh   # 构建 SCIE 包

生成的包会放置在 dist/ 目录下。

代码质量钩子

Backend.AI 使用 Git 的 pre-commit 钩子来保持代码质量：

# 每次提交时自动运行：
# - 自动格式化（pants fmt）
# - 代码检查（pants lint）

# 如有需要可绕过钩子（请谨慎使用）
git commit --no-verify

pre-commit 钩子会验证：

• 代码风格和格式

类型检查和测试则在 CI 中运行，以确保全面覆盖。

详细钩子系统文档请参阅 CLAUDE.md。

开发指南

有关详细的开发环境搭建、构建系统使用以及贡献指南：

• 开发环境搭建 - Python 版本、Pantsbuild、依赖管理
• CONTRIBUTING.md - 贡献指南和开发流程
• MIGRATION.md - 主要版本更新迁移指南

开发时启用 CLI Tab 补全功能

在开发过程中为 Backend.AI CLI 启用 Shell Tab 补全功能：

# 对于 bash/zsh（从仓库根目录） - 必须使用 'source'，不能直接执行
source scripts/setup-dev-completion.sh

# 对于 fish shell
source scripts/setup-dev-completion.fish

# 或者创建永久别名
# bash/zsh:
echo 'alias bai-dev="cd /path/to/backend.ai && source scripts/setup-dev-completion.sh"' >> ~/.zshrc
# fish:
echo 'alias bai-dev="cd /path/to/backend.ai; and source scripts/setup-dev-completion.fish"' >> ~/.config/fish/config.fish

这将启用以下 Tab 补全功能：

• backend.ai <tab> - 显示所有命令
• backend.ai session <tab> - 会话管理
• backend.ai admin <tab> - 管理操作
• backend.ai --<tab> - 全局选项

支持 bash、zsh 和 fish shell。

许可证

请参阅 LICENSE 文件。

Backend.AI 快速上手指南

Backend.AI 是一个基于容器的计算集群平台，支持多种机器学习框架和编程语言，并提供对 CUDA、ROCm、TPU 等多种异构加速器的插件式支持。它通过 REST 和 GraphQL API 暴露所有功能，适合多租户按需或批量分配计算资源。

环境准备

系统要求

• 操作系统: Linux (基于 Debian/RHEL) 或 macOS
• 权限: 需要 sudo 权限进行安装
• 硬件资源: 开发环境推荐 4+ CPU 核心，8GB+ 内存

前置依赖

请确保已安装以下基础软件：

必需组件:

• Python: 3.13.x (主分支要求 CPython 3.13.7)
• Docker: 20.10+ (需包含 Compose v2)
• PostgreSQL: 16+ (测试版本 16.3)
• Redis: 7.2+ (测试版本 7.2.11)
• etcd: 3.5+ (测试版本 3.5.14)
• Prometheus: 3.x (测试版本 3.1.0)

可选组件 (用于可观测性):

• Grafana 11.x, Loki 3.x, Tempo 2.x, OpenTelemetry Collector

构建工具:

• Pantsbuild: 2.27.x

提示: 国内用户若遇到 Python 包下载缓慢，可配置国内镜像源（如清华源、阿里源）加速 pip 和 pants 依赖下载。

安装步骤

1. 克隆代码并初始化环境

执行官方提供的开发安装脚本，该脚本会自动检查依赖、创建虚拟环境、启动基础设施服务（数据库、缓存等）并初始化默认账户。

git clone https://github.com/lablup/backend.ai.git
cd backend.ai
./scripts/install-dev.sh

2. 启动后端服务

需要在不同的终端窗口中分别启动以下核心组件：

终端 1 - Manager (集群控制平面):

./backend.ai mgr start-server --debug

终端 2 - Agent (节点控制器):

./backend.ai ag start-server --debug

终端 3 - Storage Proxy (存储代理):

./py -m ai.backend.storage.server

终端 4 - Web Server (Web UI 服务):

./py -m ai.backend.web.server

终端 5 & 6 - App Proxy (可选，用于容器内应用访问):

./backend.ai app-proxy-coordinator start-server --debug
./backend.ai app-proxy-worker start-server --debug

基本使用

1. 配置客户端会话

加载本地用户环境变量并登录。脚本会打印默认的用户 ID 和密码。

source env-local-user-session.sh
# 根据提示输入上面脚本输出的 User ID 和 Password
./backend.ai login

2. 运行第一个计算任务

使用 CLI 运行一个简单的 Python 会话：

./backend.ai run python -c "print('Hello Backend.AI!')"

3. 访问 Web 界面

打开浏览器访问 http://localhost:8090，使用 env-local-*.sh 文件中生成的凭证登录。

4. 常用功能入口

登录后，您可以直接通过浏览器或 CLI 访问容器内的开发环境：

• Jupyter/JupyterLab: 大多数镜像内置支持，适合数据科学开发。
• Web Terminal: 所有会话内置 ttyd 支持，提供网页版终端。
• VSCode: 多数会话内置网页版 VSCode 支持。
• SSH/SFTP: 所有会话支持 SSH 连接，可使用 PyCharm 等 IDE 通过远程解释器连接。
• 虚拟文件夹 (vfolders): 类似云存储，可挂载到任意计算会话并在用户间共享。