#  基本介绍

幻方萤火深度学习套件 hfai 是幻方 AI 多年深度学习经验的集成，其以**任务级分时调度共享 AI 算力的理念**将集群零散资源进行整合，充分发挥澎湃如海的算力。
无论是从底层的硬件还是上层的框架与算子，深度学习训练中的每一个环节都融合了幻方 AI 多年的优化经验，算力资源获得了极大的释放。
用户可以没有顾及地尽情研发模型提交任务，集群将算力在时间轴上分片，让您的任务获得合理的算力分配。
便捷的接口设计，简单明了的任务管理界面，hfai 可以让您获得畅快淋漓的模型训练体验。

更多信息可以参考:

**官方技术博客**：https://www.high-flyer.cn/blog

**模型仓库与示例代码**：https://github.com/HFAiLab/hfai-models


## 集群计算资源

幻方萤火集群每个计算节点有 8 张 GPU。用户提交任务时需选定节点数量 n，则该任务可获得 n\*8 个 GPU。每个任务**至少使用 8 张卡**。用户须合理定义模型运算方式（如：[分布式数据并行训练](https://www.high-flyer.cn/blog/pytorch/)），最大化使用GPU资源。

## 数据集格式

幻方萤火二号集群配备了[自研的高性能分布式存储系统 3FS](https://www.high-flyer.cn/blog/3fs/)，支持大数据集高并发读取。如果原始数据集含较多小文件，需要用户预处理聚合成大文件后再存储到平台。建议使用[ ffrecord 格式规范](https://www.high-flyer.cn/blog/ffrecord/)聚合文件。

集群是内网环境，用户个人的训练数据集需**预先上传**，平台以只读方式将数据集挂载到特定目录下，具体操作请[联系管理员](https://mp.weixin.qq.com/s/1orFQWkCzxH1sGZa8twleQ)。


## 任务调度
幻方萤火集群以[**分时调度**](../guide/schedule)的方式为任务分配计算节点，根据当前资源需求、集群忙闲程度等进行任务的中断和加载，**任务代码需要遵循平台编码规则以确保可以断点续跑**，具体包括：

1. 接受集群的打断信号；
2. 保存 checkpoint（模型参数，优化器参数等）；
3. 通知集群打断；
4. 从 checkpoint 恢复，继续运行。

具体操作请阅读 [分时调度](../guide/schedule) 篇章内容，您也可以访问 [hfai 模型仓库](https://github.com/HFAiLab/hfai-models) 阅读完整案例代码。


## 代码运行环境依赖

萤火集群的所有计算节点仅在内网通信，不支持访问公网安装环境。集群基础环境包含大部分主流依赖包，**建议用户在开始使用时先测试该环境是否可以满足您的代码运行需求**。使用方式如下：

```shell
HF_ENV_NAME=py38-202111 hfai python sample.py -- -n 1 --name test_202111
```

所提交的任务即可加载集群默认环境（`202111`）进行运行。


如果您有自己特殊环境的需求，可以通过 [`haienv`](https://www.high-flyer.cn/blog/hfai_venv/) 工具在 [Studio 开发容器中配置](../guide/dev_container)。对于自己创建环境的使用，如下例所示：

 ```shell
HF_ENV_NAME=<myenv> hfai python sample.py -- -n 1 --name test_myenv
```

后续的依赖都会在您所创建的这个虚拟环境中加载。


## 存储路径

训练任务运行在每个节点的计算容器中，计算容器启动时挂载若干个存储路径，包括数据集路径（只读）和用户工作路径（读写）。

开发容器相比计算容器额外运行了 JupyterLab 服务，支持可视化和交互式的开发方式，相关功能请查阅[Jupyter官方文档](https://jupyterlab.readthedocs.io/en/stable/)。

由于每次被调起都是一个新的容器，因此需要将用户的数据保留到某些路径中，做持久化。具体的存储路径有：
   - `/public_dataset`: 由萤火集群提供的公开数据集
   - `/private_dataset`: 用户提供的私有数据集，以账号组隔离
   - `/home/xxx`: 用户个人路径，常用于环境配置信息
   - `/ceph-jd/pub/jupyter/<username>/notebooks`: Jupyter 工作路径，也是开发容器的工作区，在浏览器展示如下：

        ![](../_static/pic/devcontainer_04.png)

   - `/weka-jd/prod/public/permanent/<cluster_path>`:  hfai workspace 路径。用户使用 [workspace](../cli/ugc) 从本地推工作区到集群：

        ![](../_static/pic/hfai_list_case.png)

其他路径均为容器本地路径，不做持久化。

### 集群workspace工作区存储容量规则

集群有定时巡检和回收机制，每个用户在集群上所有的workspace空间，如果存储使用超过5T，则该账号在下一次巡检时（每天一次）将被置为限制任务提交的状态，并启动回收。

1. 回收规则
    + 用户所有工作区内日期早于7天的文件目录被移入gc路径
        - 检查每个用户 workspaces 路径以下三级目录，更多层级不再展开、整体移入
    + 已保留超过7天的gc路径，将被彻底移除
    + 账号在限制提交状态时，运行中的任务将被打断挂起，直到限制解除后自动恢复任务

2. 恢复规则
    + 用户必须在开发容器中自行完成文件目录清理，需要保留的文件由用户自行移回工作区路径
    + 用户完成清理后在页面提交申请恢复
    + 集群在收到申请恢复请求后检查用户工作区，确认容量使用未超限后解除限制提交状态


## 工作区

工作区包含了您项目工程目录下的代码、数据、中间结果、训练好的模型等一系列内容，以本地工程目录为单位，进行本地和远程萤火集群的同步管理。

本地目录通过 [`hfai worksapce`](https://www.high-flyer.cn/blog/hfai_workspace/) 工具，可以实现本地和萤火之间的数据互传。

更多操作说明请阅读 [UGC命令](../cli/ugc.rst)