最近，幻方 AI 发布了其沉淀多年的深度学习套件 hfai ，吸引了众多同行研究员和开发者们咨询试用。其中，不少用户朋友对 hfai 中一些功能不太熟悉，使用上存在疑惑，或者仅仅使用了其中非常少的一部分功能。如果说我们把 hfai 深度学习套件认为是一部武功秘籍，而您作为使用者若是习得了当中的心法要义，那么您将带着 hfai 这套“神功”游刃有余的应对深度学习作业的各项挑战，举重若轻、例不虚发。
为此，我们专门创建了 “hfai 使用心法” 系列专辑，从本期文章开始，我们会陆续为大家介绍 hfai 一些功能的设计思路和原理，帮助大家更好更快地习得心法。
本次文章为大家介绍 hfai workspace，其旨在同步本地工程目录代码到远程萤火集群中，更丝滑地利用萤火的算力运行您的项目工程。
使用场景
在介绍 hfai worksapce 之前，我们先简单描述其使用的场景。
幻方萤火是一个远程的服务集群。对于 hfai 的用户，他们需要将本地的数据、代码传到这个远程集群中，才可以训练其模型。之前，幻方 AI 提供了 Jupyter 控制台，让用户通过网页手动上传下载，这种方式有诸多不便。
为了解决这个问题，hfai workspace 应运而生，其可以让用户摆脱 Jupyter 操作的不方便，直接连通本地工程目录和远程萤火集群。您可以在您自己环境，如个人电脑、个人集群等，编写代码，调试模型，然后通过一行命令直接将调试好的代码上传远程萤火集群，利用算力来训练您的模型。实现这个过程，只需要您在自己环境里安装 hfai 深度学习套件，通过 VPN 连通集群，即可开始使用。
下面将为大家详细介绍 hfai workspace 的背后原理，使用可以参考官方文档。
整理架构
如上图简图所示，hfai workspace 分为 数据流 和 控制流，控制流主要是发送本地的请求到萤火服务器（Server）中，通过同步服务（Sync）进行本地文件和远程文件的同步控制。数据流使用外部 OSS 储服务，进行数据和代码上传和下载。这里，外部 OSS 存储通过内部代理（Proxy），实现数据的高速传输和安全保障。
为了保障您以及集群整体的隐私和安全，对于不同的用户来说，无论是在 OSS 外部存储，还是幻方集群存储（Weka），数据目录都彼此隔离。当前，幻方萤火集群仅支持从外部指定的 OSS 存储服务中拉取数据，我们配有专线联通以提升传输的速度、稳定和安全。
推送工作区
当您发起 hfai workspace push 命令，推送您的本地目录代码时，在您本地和远程萤火集群之间，会发生如下操作：
-
请求萤火，验证文件
如上图所示，当发起 push 请求时，本地请求会发送到远程萤火服务（Server），转交给同步服务（Sync），同步服务校验当前的请求，查询集群存储（Weka）中是否存在该工程目录，获取校验和（checksum），将信息返回给本地，与本地目录进行比对。
-
请求 OSS，准备上传
如上图所示，当完成远程目录和本地目录的校验之后，本地再一次发请求给萤火服务，由集群通过内部代理（Proxy）请求外部 OSS，获取安全的上传链接和校验（STS）。当获取到 OSS 的上传许可后，您的本地工程目录便可以上传了。
这里值得注意的是，待同步的本地工程目录原则上限制为不超过 200G，为更流畅的使用萤火平台，强烈推荐调用幻方的数据集仓库 hfai.datasets。若您所用数据集未被收录，或是私有大规模数据集，您可以联系幻方管理员，hfai 数据集详情请参考 hfai 官方文档
-
数据上传
如上图所示，本地目录代码和数据开始上传。这里，hfai 会对当前的目录自动进行整体打包，您可以将您的数据和代码整理好，都放在当前这个目录下。注意，数据的上传是增量的，只会对校验后有改动的文件进行打包上传。
目录包上传到 OSS 之后，会通过内部代理（Proxy）下载到萤火集群的存储（Weka）中，这里同步服务（Sync）会负责将包解开，并在集群存储中恢复本地目录设置。
数据传输的进度会通过萤火服务（Server）发送到本地。您可以实时获取到当前推送操作的进度详情。
拉取工作区
除了推送本地目录到远程萤火集群，您也可以通过 hfai workspace pull 命令从远程萤火中拉取您的训练代码，模型保存的 checkpoint，中间数据等信息。该过程与推送基本一致，在进行了文件校验，OSS 请求之后，数据链路如下所示：
数据过程与推送相反，从萤火存储（Weka）的工作区中拉取新增的文件，通过 OSS 传递到本地工程目录中。进度信息会通过萤火服务（Server）实时反馈。
此外，hfai workspace 还提供了 diff, list, download, remove 等命令，它们的执行过程都是上述描述流程的子流程，详细信息可以参考 hfai 官方文档
案例说明
我们以本地一个新的项目工程 WeatherBench 为例子，展示 hfai workspace 的使用。
初始化成 hfai 工作区：
初次推送到远程萤火集群，文件校验后在集群生成工作区 weatherbench ，通过 OSS 将本地工作区打包上传：
您可以在 hfai studio 中看到您的工作区在远程萤火集群中的位置：
当前目录会放置在集群中 hfai/{username}/ 中，按账号进行隔离。当对本地文件 /src/download_era5.py 进行修改，在推送时会展现文件校验结果：
当远程萤火集群完成训练，保存了训练好的模型，可以获取到：
通过 hfai workspace pull 拉取到本地：
