update swanlab launch command (#53)

.vitepress/config.mts

@@ -233,7 +233,7 @@ function sidebarAPI(): DefaultTheme.SidebarItem[] {
       { text: 'swanlab login', link: 'cli-swanlab-login' },
       { text: 'swanlab logout', link: 'cli-swanlab-logout' },
       { text: 'swanlab convert', link: 'cli-swanlab-convert' },
-      { text: '(内测中) swanlab task', link: 'cli-swanlab-task' },
+      { text: '(内测中) swanlab remote gpu', link: 'cli-swanlab-remote-gpu' },
       { text: '其他', link: 'cli-swanlab-other' },
     ]
   },

zh/api/cli-swanlab-task.md → zh/api/cli-swanlab-remote-gpu.md

@@ -1,26 +1,41 @@
-# SwanLab Task使用文档（Beta功能）
+# SwanLab 远程任务部署使用文档（Beta功能）
 
 ::: danger
 <strong>警告：</strong> 目前该功能正在内测中，请充分阅读下文档中的 <strong>功能测试说明</strong> 章节再使用该功能。**内测的一些限制：**
+
 1. 最大任务时长为4小时
 2. 内测的更多信息请联系 <[email protected]>, <[email protected]>(产品经理邮箱)
 :::
 
+启动实验命令
+
+``` bash
+swanlab launch [OPTIONS]
+```
+
+| 选项 | 描述 |
+| --- | --- |
+| `-f,--file <yaml file>` | 根据配置文件执行任务 |
+| `--help <yaml file>` | 打印帮助信息 |
+
+查看、暂停任务命令
+
 ``` bash
 swanlab task [OPTIONS]
 ```
 
 | 选项 | 描述 |
 | --- | --- |
-| `launch -e <py file>` | 使用云端GPU服务器运行训练 |
 | `list` | 查看开始的训练任务状态 |
 | `search <task id>` | 查看某一特定任务的运行情况 |
+| `stop <task id>` | 停止某一个正在运行的命令 |
+| `--help` | 打印帮助信息 |
 
-详细使用方法请查[SwanLab Task命令](#swanlab-task命令)
+详细使用方法请查[SwanLab远程任务部署命令](#SwanLab远程任务部署命令)
 
 ## SwanLab Task三分钟快速入门教程
 
-本教程将以一个简单的一元二次函数回归任务来帮助读者了解如何使用**SwanLab Task**功能。
+本教程将以一个简单的一元二次函数回归任务来帮助读者了解如何使用**SwanLab 远程任务部署使用文档**功能。
 
 ### 前置步骤，登录和获取key
 
@@ -41,7 +56,7 @@ swanlab -v
 
 ### 第一步，准备代码
 
-使用已经准备好的开源案例，使用git下载[SwanLab Task测试代码](https://github.com/SwanHubX/SwanLab-LaunchExample.git)，并进入到项目的根目录下
+使用已经准备好的开源案例，使用git下载[SwanLab远程任务部署测试代码](https://github.com/SwanHubX/SwanLab-LaunchExample.git)，并进入到项目的根目录下
 
 ```bash
 # 下载项目
@@ -57,25 +72,14 @@ cd SwanLab-LaunchExample
 使用`swanlab task launch`执行训练的入口函数，命令如下：
 
 ```bash
-swanlab task launch -e <待运行的python脚本>
+swanlab task launch -f swanlab.yaml
 ```
 
-接下来SwanLab将会提示你是否将本地目录下的代码打包并上传到GPU服务器上（如下图），输入`y`确认。
-
-![launch-upload](../../assets/task-upload.png)
-
-**SwanLab Task**将会自动将本地代码打包，上传到GPU服务器，并启动训练。
+**SwanLab 远程任务部署使用文档**将会根据配置文件自动将本地代码打包，上传到GPU服务器，并启动训练。
 
----
-
-如果想跳过确认步骤，则在命令中添加`-y`参数：
-
-```bash
-swanlab task launch -y -e <待运行的python脚本>
-```
-
-这样将会直接执行打包上传操作。
+![launch-upload](../../assets/api/cli-swanlab-task/launch.png)
 
+有关配置文件的详细功能（如指定环境、挂载数据集等），请参考[YAML配置文件及功能](#YAML配置文件及功能)
 
 ### 第三步，查看实验
 
@@ -85,9 +89,9 @@ swanlab task launch -y -e <待运行的python脚本>
 swanlab task list
 ```
 
-这将在端口中开启一个表格（如下图），最上面的一个为当前开启的实验。其中*Status*表示当前实验的状态，*PREPARE*表示该实验正在部署（其他状态可参考[swanlab task list](#swanlab-task-list)章节）。
+这将在端口中开启一个表格（如下图），最上面的一个为当前开启的实验。其中*Status*表示当前实验的状态（关于状态可参考[swanlab task list](#swanlab-task-list)章节）。
 
-![task-list-prepare](../../assets/task-prepare.png)
+![task-list](../../assets/api/cli-swanlab-task/task-list.png)
 
 当开始训练时（*Status*切换为*RUNNING*），可点击*URL*中的链接在[swanlab.cn](https://swanlab.cn)中查看到开始的实验。
 
@@ -109,11 +113,11 @@ swanlab task list
 
 ![launch-remote-device](../../assets/task-remote-device.png)
 
-关于调试、终止正在进行的实验等命令参考[SwanLab Task命令](#swanlab-task命令)
+关于调试、终止正在进行的实验等命令参考[SwanLab远程任务部署命令](#SwanLab远程任务部署命令)
 
 ## 设计理念
 
-**SwanLab Task**功能目标是帮助AI研究者轻松高效的利用起多个不同的本地GPU服务器，并且方便的规划自己的训练任务。因此**SwanLab Task**功能专注于解决怎么让用户更方便的将训练快速部署到GPU服务器上。
+**SwanLab 远程任务部署使用文档**功能目标是帮助AI研究者轻松高效的利用起多个不同的本地GPU服务器，并且方便的规划自己的训练任务。因此**SwanLab 远程任务部署使用文档**功能专注于解决怎么让用户更方便的将训练快速部署到GPU服务器上。
 
 ![launch对比](../../assets/task-compare.png)
 
@@ -131,28 +135,89 @@ swanlab task list
 * 多节点实验需要在多个服务器上重复这些动作
 * ...
 
-使用**SwanLab Task**功能只需要做如下几个操作（见上图右）：
+使用**SwanLab 远程任务部署使用文档**功能只需要做如下几个操作（见上图右）：
 
 1. GPU服务器后台运行**SwanLab Agent**
 2. 在本地完成实验脚本撰写和制定环境依赖
-3. 使用`swanlab task launch ...`命令部署到GPU服务器开始训练
+3. 使用`swanlab launch ...`命令部署到GPU服务器开始训练
 
 SwanLab会自动完成本地代码打包上传、GPU服务器安装环境、根据GPU服务器的显卡空闲情况分配对应的GPU卡训练等工作。让研究人员不用去做烦琐的环境配置、查看服务器空闲情况等，可以专注于训练本身。
 
-## SwanLab Task命令
+## SwanLab远程任务部署命令
 
 :::warning
-由于该功能尚在迭代，CLI命令和接口可能会随时变动。可以通过`swanlab task --help`来查看最新的命令。
+由于该功能尚在迭代，CLI命令和接口可能会随时变动。可以通过在命令后方使用`--help`来查看最新的命令。
 :::
 
-### swanlab task launch
+### 功能导航
+
+| 需求 | 导览 |
+| --- | --- |
+| 上传数据集 | [swanlab upload](#swanlab-upload) |
+| 部署远程GPU训练任务 | [swanlab launch](#swanlab-launch) |
+| 查看上传的任务、数据集 | [swanlab task list](#swanlab-task-list) |
+| 查看任务运行状态、失败日志 | [swanlab task search](#swanlab-task-search) |
+| 停止运行任务 | [swanlab task stop](#swanlab-task-stop) |
+| 查看命令使用方法 | 任意命令后跟`--help`参数 |
+
+### swanlab launch
 
 ```bash
-swanlab task launch -e <启动训练的入口python脚本>
+swanlab task launch -f <yaml配置文件>
 ```
 
 将文件夹下的任务打包、上传至远程GPU服务器，并且执行入口训练函数
 
+### YAML配置文件及功能
+
+下面展示一个完整的YAML文件，及其功能说明。
+
+```yaml
+apiVersion: swanlab/v1  # 接口版本，无需更改
+kind: Folder  # 加载任务类型，后续支持通过
+metadata:
+  name: "Launch-Example"  # 本次任务名称
+  desc: ""          # 用于描述该实验，可微孔
+  combo: RTX3090-1  # 使用的算力队列，可选RTX3090-1队列和H800-1队列
+spec:
+  python: "3.10"  # 暂时只支持3.8, 3.9, 3.10
+  entry: "train.py" # 要执行的入口函数
+  volumes:
+    - id: "<存储数据ID>"    # 填入挂载的存储ID
+  exclude:
+    - "<文件or文件夹名称>"  # 打包上传时需要忽略的文件（用于屏蔽传输当前文件夹下的数据集、模型权重等无用文件）
+```
+
+对于一个新的实验，需要关注如下配置信息
+
+* **combo** 用于指定GPU类型，可选"H800-1"和"RTX3090-1"两种GPU类型，均为单卡
+* **entry** 用于指定开始训练的入口函数
+* **volumes** 对于较大的文件，推荐以存储挂载的形式载入
+
+### swanlab upload
+
+该命令用于上传较大的，需要在多次实验中重复使用的数据。命令如下：
+
+```bash
+swanlab upload <文件or文件夹>
+```
+
+运行效果如下：
+
+![upload](../../assets/api/cli-swanlab-task/upload.png)
+
+完成上传后会显示`dataset id`，可以在[YAML配置文件](#yaml配置文件及功能)中挂载
+
+挂载后文件的位置将会在`/data/`文件夹当中。
+
+也可以通过命令`swanlab task list`中查看已经挂载的文件（红色框部分）：
+
+![upload-list](../../assets/api/cli-swanlab-task/upload-list.png)
+
+### swanlab download（开发中）
+
+<span style="color: red;">（等待补充）</span>
+
 ### swanlab task list
 
 ```bash
@@ -161,7 +226,7 @@ swanlab task list
 
 打印出已完成运行或者正在运行的实验（默认打印最新的10条）效果如下：
 
-![task-list](../../assets/task-list.png)
+![task-list](../../assets/api/cli-swanlab-task/task-list.png)
 
 其中：
 
@@ -213,11 +278,19 @@ Finished At: 2024-07-30 18:52:49
 
 ![remote-error-log](../../assets/task-remote-error-log.png)
 
+## swanlab task stop
+
+终止已经开启的任务，使用方法如下：
+
+```bash
+swanlab task stop <任务ID>
+```
+
 ## SwanLab Agent安装（开发中）
 
 <span style="color: red;">（等待补充）</span>
 
->目前该功能正在开发和测试，为了方便使用，SwanLab提供了云端免费的测试算力使用。可以直接通过`SwanLab Task`使用云端算力运行和部署
+>目前该功能正在开发和测试，为了方便使用，SwanLab提供了云端免费的测试算力使用。可以直接通过`swanlab launch`使用云端算力运行和部署
 
 ## 工作过程和原理
 
@@ -229,11 +302,11 @@ Finished At: 2024-07-30 18:52:49
 强烈建议在使用本功能前[点击链接](https://geektechstudio.feishu.cn/wiki/Te1EwcLbrimD7Zk1fsrcCovanyg)加入到测试群当中，我们将会在群中第一时间回复解决可能遇到的问题。
 :::
 
-**SwanLab Task**功能涉及将所需运行的代码和数据集上传到公有云服务器当中，我们尽力保障您的数据安全，但测试阶段仍有可能出现数据泄漏、丢失等风险，**请勿将重要数据上传至测试功能当中**。
+**SwanLab 远程任务部署使用文档**功能涉及将所需运行的代码和数据集上传到公有云服务器当中，我们尽力保障您的数据安全，但测试阶段仍有可能出现数据泄漏、丢失等风险，**请勿将重要数据上传至测试功能当中**。
 
-**SwanLab Task**功能的迭代依赖于社区用户的积极反馈，如果您遇到任何问题，欢迎积极联系我们。可以通过[Github Issue](https://github.com/SwanHubX/SwanLab/issues)，联系邮箱 <[email protected]> 加入到[微信测试群](https://geektechstudio.feishu.cn/wiki/Te1EwcLbrimD7Zk1fsrcCovanyg)当中与我们直接交流。
+**SwanLab 远程任务部署使用文档**功能的迭代依赖于社区用户的积极反馈，如果您遇到任何问题，欢迎积极联系我们。可以通过[Github Issue](https://github.com/SwanHubX/SwanLab/issues)，联系邮箱 <[email protected]> 加入到[微信测试群](https://geektechstudio.feishu.cn/wiki/Te1EwcLbrimD7Zk1fsrcCovanyg)当中与我们直接交流。
 
-为了方便测试的顺利进行，**SwanLab Task**为参与测试的用户提供了免费的测试运行服务器，我们尽力满足每一位用户的测试和算力需求，但是由于团队资源有限和功能迭代，仍可能出现训练任务排队、训练被迫终止等情况。
+为了方便测试的顺利进行，**SwanLab 远程任务部署使用文档**为参与测试的用户提供了免费的测试运行服务器，我们尽力满足每一位用户的测试和算力需求，但是由于团队资源有限和功能迭代，仍可能出现训练任务排队、训练被迫终止等情况。
 
 ## 致谢
 

zh/examples/pretrain_llm.md

@@ -359,7 +359,7 @@ print("GENERATE:", pipe("人工智能", num_return_sequences=1)[0]["generated_te
 确保swanlab版本为0.3.19
 :::
 
-预训练LLM对于GPU的算力和显存要求非常高，本文推荐使用[SwanLab Launch](../api/cli-swanlab-task.md)利用云上GPU进行预训练。
+预训练LLM对于GPU的算力和显存要求非常高，本文推荐使用[SwanLab Launch](../api/cli-swanlab-remote-gpu.md)利用云上GPU进行预训练。
 
 首先使用`swanlab upload -n WIKI_CN WIKI_CN`命令上传数据集