# MACS 容器化示例

## 概述

MACS 容器化利用容器运行时库和实用工具集构建运行模型和应用服务。我们提供高效稳定的镜像，内置了基础环境依赖和模型示例，帮助用户快速完成模型开发和应用部署，开箱即用，灵活高效，更方便快捷的利用墨芯 AI 计算卡的算力资源。

## 前提条件

- 物理服务器已安装 Docker，且 Docker 版本不低于 Docker 18.03。

     ```Bash
     $ docker --version 
     $ docker info
     ```

- 启动 Docker 服务。启动命令如下：

   ```Bash
   $ systemctl status docker
   $ systemctl start docker 
   $ systemctl enable docker
   ```

- 在物理服务器上已安装 SOLA，安装的详细步骤请参见《SOLA Toolkit 安装指南》。

   注意：

  - *我们已经在镜像内集成 SOLA 稳定版本，您无需在容器中再次安装 SOLA。*

  - *容器内和物理服务器安装的 SOLA 版本需保持一致。您可通过以下命令确认版本信息：*

  ```Bash
    #查询 sola版本信息
  $ ls -al /usr/local/
  ```

## 使用镜像服务

为了方便不同用户环境使用，我们发布的镜像均包括在线版镜像和离线版镜像。

- 使用离线版镜像，请在下载镜像包后将其导入到本地 Docker 仓库。

- 使用在线版镜像，请确保测试服务器可访问互联网及 Dockerhub。

### 使用基础镜像

基础镜像基于主流操作系统发行版构建，包括一些基础环境环境依赖和 sola-toolkit，具备运行基本应用的能力，并可在您创建容器中方便地使用墨芯 AI 计算卡。

#### 获取镜像

- 下载离线版镜像

  ```Bash
  $ wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/images/macs/macs-base-sola-3.10.0.tar              
  ```
  
- 下载在线版版镜像

  ```Bash
  $ docker pull moffett/macs-base:sola-3.10.0
  ```

#### 导入镜像（离线版）

获取在线版镜像后，无需执行导入步骤。

获取离线版镜像后，请执行以下命令将镜像导入到本地 Docker 环境。

```Bash
$ docker load -i macs-base-sola-3.10.0.tar     
```

#### 创建容器

使用基础镜像，创建一个容器实例。

```Bash
# 创建容器命令格式
$ docker run -itd --privileged -name <CONTAINER_NAME> <IMAGE_REPO>/<IMAGE_NAME>:<IMAGE_TAG> /bin/bash
#sample
$ docker images |grep macs
$ docker run -itd --privileged --name macs-1.6  moffett/macs-base:sola-3.10.0 /bin/bash
```

创建容器参数选项如下：

**说明**：*命令启动参数可根据需要灵活调整，根据业务需要动态删减，简要说明如下表，详情请参见 Docker 官方文档。*

| **参数**                                                     | **是否必选** | **说明**                                                     |
| ------------------------------------------------------------ | ------------ | ------------------------------------------------------------ |
| $(CONTAINER_NAME)                                            | 否           | 容器名称。建议您定义一个容器名。                             |
| $(IMAGE_REPO)/$(IMAGE_NAME):$(IMAGE_TAG)                     | 是           | 镜像名，包括 3 部分，镜像仓库地址/镜像名：镜像 tag 镜像 ID。 |
| /bin/bash                                                    | 是           | 指定进入容器 shell 环境为 bash。                             |
| -itd                                                         | 是           | 交互方式后台运行容器。                                       |
| -v                                                           | 否           | --volume，声明将宿主机目录挂载到容器内对应的目录。方便宿主机和容器间文件共享。 |
| --privileged                                                 | 否           | （推荐启用）使用特权模式。                                   |
| --net=host                                                   | 否           | 容器网络默认为 bridge 模式，容器网络与宿主机网络隔离； 设置该参数为 host 后，容器网络为主机模式，可方便共享宿主机网络环境。 |
| --pid=host                                                   | 否           | 在容器中直接看到宿主机的进程信息。                           |
| --restart always                                             | 否           | 容器退出时应用的重新启动策略为 always，默认为 no。           |
| --device /dev/mf-ctl:/dev/mf-ctl<br /> --device /dev/mf-remap-pfn:/dev/mf-remap-pfn <br />--device /dev/mf-pci-endpoint.0:/dev/mf-pci-endpoint.0 | 否           | 如您不启用特权模式（--privileged），则必须指定该参数，将安装在宿主机上的墨芯计算卡设备节点挂载进容器中。若使用本参数，则需指定--device /dev/mf-ctl:/dev/mf-ctl --device /dev/mf-remap-pfn:/dev/mf-remap-pfn ，<br />参数后面的部分您可以根据实际情况灵活调整。endpoint 后指定设备 index ID。 |

如不使用特权模式启动容器，需将使用的设备节点挂载到容器中。

```bash
# sample: 将宿主机设备节点 device0 挂载到容器中对应的设备节点device0
$ docker run -it --rm --device /dev/mf-ctl:/dev/mf-ctl --device /dev/mf-remap-pfn:/dev/mf-remap-pfn --device /dev/mf-pci-endpoint.0:/dev/mf-pci-endpoint.0 --name test moffett/macs-base:sola-3.10.0 /bin/bash
# sample: 将宿主机设备节点device12 挂载到容器中的设备节点 device1
$ docker run -it --rm --device /dev/mf-ctl:/dev/mf-ctl --device /dev/mf-remap-pfn:/dev/mf-remap-pfn --device /dev/mf-pci-endpoint.0:/dev/mf-pci-endpoint.0 --device /dev/mf-pci-endpoint.12:/dev/mf-pci-endpoint.1 --name test-sola moffett/macs-base:3.10.0 /bin/bash
```

#### 验证使用

镜像中已集成稳定版本驱动程序和 sola-toolkit，您无需安装，可在容器内直接执行 sola 相关命令选项：

- 使用 mx-smi ，使用方式请参见《mx-smi 使用说明》。
- 使用 mx-qual，使用方式请参见《mx-qual 使用说明》。

基本示例如下：

```Bash
$ docker exec -it macs-1.6 /bin/bash
# 在容器中使用 mx-smi 
$ mx-smi list 
# 在容器中使用 mx-qual 
$ mx-qual list -i 0
```

### 使用业务镜像

业务镜像主要为应用/工具和模型提供运行环境。 本文以 sola-demo 和 DCSM 为例，说明业务镜像的使用。

## 业务容器化示例

### sola-demo

#### 获取 sola-demo 镜像

- 下载离线版镜像

  ```Bash
  $ wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/images/Ubuntu/business/sola-demo/sola-demo-3.10.0.tar
  ```

- 下载在线版镜像

  ```Bash
  $ docker pull moffett/sola-demo:3.10.0
  $ docker images |grep sola-demo 
  ```

#### 导入镜像（可选）

如果您下载的是离线版镜像，请执行以下命令导入镜像。否则，您可跳过该步骤。

```Bash
$ docker load -i sola-demo-3.10.0.tar
```

#### 准备数据

```Bash
# 下载数据包
$ curl -OL https://moffett-oss-bucket.tos-cn-shanghai.volces.com/sola-demo/sola-demo-3.10.0-data-offline.tar.gz
# 解压：标准解压
$ tar -zxvf sola-demo-3.10.0-data-offline.tar.gz
# 解压: 多线程解压（推荐）  
$ tar --use-compress-program=pigz -xvpf sola-demo-3.10.0-data-offline.tar.gz
```

#### 创建容器并验证模型

##### 创建容器

**注意**：*创建容器前请注意所在位置，`$PWD`为当前目录，查看当前目录下是否有解压的模型数据。*

```bash
$ docker run -itd --privileged -v $PWD/sola-demo-3.10.0-data-offline:/home/moffett/workspace/sola-demo-3.10.0 --name sola-demo-3.10.0 moffett/sola-demo:3.10.0 /bin/bash
$ docker ps -a |grep sola-demo-3.10.0
```

##### ResNet50

- 进入容器内运行模型

  ```Bash
  $ docker exec -it sola-demo-3.10.0 /bin/bash
  $ sola-demo-3.10.0/models/resnet50/run.sh && sola-demo-3.10.0/models/resnet50/verify.sh
  ```

- 创建临时容器并运行模型

  ```Bash
  $ docker run -it --rm --privileged -v $PWD/sola-demo-3.10.0-data-offline:/home/moffett/workspace/sola-demo-3.10.0 moffett/sola-demo:3.10.0 /bin/bash -c "sola-demo-3.10.0/models/resnet50/run.sh && sola-demo-3.10.0/models/resnet50/verify.sh"
  ```

##### Bert

- 进入容器内运行模型

  ```Bash
  $ docker exec -it sola-demo-3.10.0 /bin/bash
  $ sudo sola-demo-3.10.0/models/bert/run.sh && sola-demo-3.10.0/models/bert/verify.sh
  ```

- 创建临时容器并运行模型

  ```Bash
  $ docker run -it --rm --privileged -v $PWD/sola-demo-3.10.0-data-offline:/home/moffett/workspace/sola-demo-3.10.0 moffett/sola-demo:3.10.0 /bin/bash -c "sudo sola-demo-3.10.0/models/bert/run.sh && sola-demo-3.10.0/models/bert/verify.sh"
  ```

##### Bloom7b

- 进入容器内运行模型

  ```Bash
  $ docker exec -it sola-demo-3.10.0 /bin/bash
  $ sola-demo-3.10.0/models/bloom-7b/run.sh && sola-demo-3.10.0/models/bloom-7b/verify.sh
  ```

- 创建临时容器并运行模型

  ```Bash
  $ docker run  -it --rm --privileged -v $PWD/sola-demo-3.10.0-data-offline:/home/moffett/workspace/sola-demo-3.10.0 moffett/sola-demo:3.10.0 /bin/bash -c "sola-demo-3.10.0/models/bloom-7b/build/bloom --module_path sola-demo-3.10.0/sola_demo_assets/models/bloom/v1/bloom7b_demo -f sola-demo-3.10.0/models/bloom-7b/data/questions.txt"
  ```

##### Bloom176b

- 进入容器内运行模型

  ```Bash
  $ docker exec -it sola-demo-3.10.0 /bin/bash
  $ sola-demo-3.10.0/models/bloom-176b/run.sh && sola-demo-3.10.0/models/bloom-176b/verify.sh
  ```

- 创建临时容器并运行模型

  ```Bash
  $ docker run -it --rm --privileged -v $PWD/sola-demo-3.10.0-data-offline:/home/moffett/workspace/sola-demo-3.10.0 moffett/sola-demo:3.10.0 /bin/bash -c "sola-demo-3.10.0/models/bloom-176b/build/bloom --module_path sola-demo-3.10.0/sola_demo_assets/models/bloom/v1/bloom176b_demo -f sola-demo-3.10.0/models/bloom-176b/data/questions.txt"
  ```

##### Chatglm2-6B

进入容器内运行模型

```Bash
$ docker exec -it sola-demo-3.10.0 /bin/bash
$ cd sola-demo-3.10.0/models/chatglm2-6b/
# run.sh 默认执行自动问答模式。
$ ./run.sh
# 也可以手动调整指定问答模式
$ export PYTHONPATH="$PYTHONPATH:$PWD/test"
$ export model_data=/home/moffett/workspace/sola-demo-3.10.0/sola_demo_assets/models/chatglmv2
# 互动问答模式，输入exit 退出程序
$ python3 test/chat_chatglmv26b.py --mode="qa" --model="$model_data/v1/chatglmv2_serving_splitkv/" --tokenizer="$model_data/v1/chatglm2-6b/"
# 自动问答模式
$ python3 test/chat_chatglmv26b.py --model="$model_data/v1/chatglmv2_serving_splitkv/" --tokenizer="$model_data/v1/chatglm2-6b/" --questions="data/questions.txt"
```

### DCSM

#### 获取 DCSM 镜像

- 在线版镜像

   ```Bash
    $ docker pull moffett/dcsm:1.0-sola-3.10.0
    $ docker images |grep dcsm
   ```

- 离线版镜像

   ```Bash
    $ wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/images/Ubuntu/business/dcsm/dcsm-1.0-sola-3.10.0.tar
   ```

#### 导入镜像（可选）

如果您选择离线版镜像，请执行以下命令导入镜像。否则，您可跳过该步骤。

```Bash
$ docker load -i dcsm-1.0-sola-3.10.0.tar
```

#### 创建容器

```Bash
$ docker run -itd --privileged --net=host --name test-dcgm moffett/dcsm:1.0-sola-3.10.0
```

**说明**：*容器启动后会自动拉起 dcsm 服务，无需启动服务步骤。*

#### 使用 DCSM

容器启动成功后，即可在容器中使用 DCSM 服务。详细使用方法详见《DCSM 用户手册》。

```Bash
# docker exec -it test-degm /bin/bash
# 运行level-1 诊断测试
$ dcsmi diag --run 1
# 在其他服务器上 通过 --host 参数 连接到本机的dcsm ，请以实际IP和端口为准
$ dcsmi discovery -l --host 10.1.XX.XX:9494
```

## 环境清理

**注意**：

*以下操作请在物理机上执行。*
- *$（CONTAINER_NAME/CONTAINER_ID）请替换为实际的容器名/容器 ID*
- *$（IMAGE_NAME:TAG/IMAGE_ID）请替换为实际的镜像名/镜像 ID*

### 停止并删除容器

```Bash
$ docker stop $(CONTAINER_NAME/CONTAINER_ID) && docker rm $(CONTAINER_NAME/CONTAINER_ID)
```

### 删除镜像

```Bash
$ docker rmi $(IMAGE_NAME:TAG/IMAGE_ID)
```

### 删除指定容器/镜像

```Bash
$ export container_name="your container name"
$ export image_name="your images name:tag or images id"
$ docker rm -f $(docker ps -a -q | grep -E "^($container_name)")
$ docker rmi -f $(docker images -a -q | grep -E "^($image_name:tag)")
```