Start on ModelScope

0. 环境准备

在任意路径下安装git lfs；
```
git lfs install
```
根据本工程目录下./scripts/requirements.txt文件安装脚本运行所需依赖；
```
cd scripts
pip install -r requirements.txt
```

如果选择使用uv管理模型工程内的python运行环境，需要在本地安装uv；否则可跳过此步。

# 推荐使用官网源码安装
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# 也可pip安装
pip install uv

创建ModelScope账号，登录后从账号设置>>访问控制页面获取访问令牌（Token）。

1. 初始化模型仓库

配置含模型基本信息的yaml文件，要求详见本工程目录下./scripts/mdinfo.yaml文件，可参考./scripts/egs/目录下的示例配置文件1_mdinfo_eg*.yaml；
运行本工程目录下./scripts/1_init_model_dirfns.py脚本，会依次完成以下步骤以初始化本地模型目录：
1. 在ModelScope上创建模型；（可选）
  
  也可参考创建自己的模型库自行创建，若已自行创建，则须在脚本运行命令中增加--created配置。
2. 将创建的模型clone至本地；（可选）
  
  也可自行将创建好的模型 使用Git下载 至本地（须在下载命令中 使用Token（即访问令牌），否则后续无法上传更新），若已下载，则须在脚本运行命令中增加--cloned配置。
3. 更新master分支内容；
4. 根据配置的Icraft版本（icraft_ver）创建新分支 （例：版本配置为3.33.1，则将创建分支mdz_v3.33），并首次上传至远程仓库；
5. 在模型目录下根据配置创建相应的目录和文件：
  - 如果配置为选择使用uv管理模型工程内的python运行环境（use_uv），会初始化模型目录下MODEL_icraft的uv环境；
  - 生成模型编译及运行时所需初始文件；
  - 下载运行时工程所需modelzoo_utils文件，并根据配置的Icraft版本（icraft_ver）选取最适合的分支内容；
  - 生成包含模型信息的初始yaml文件（MODEL_icraft/MODEL.yaml）。
脚本运行命令：
```
cd scripts
python 1_init_model_dirfns.py
       --cfgfn "mdinfo.yaml"        # 默认读取./scripts/mdinfo.yaml文件，也可自行配置yaml文件路径
       --created                    # 默认为False，若配置，则表示该模型已在ModelScope上进行创建，脚本运行时会跳过创建步骤
       --cloned                        # 默认为False，若配置，则表示已将创建好的模型初始内容拉取至本地
```

2. 添加模型文件

上一步中脚本运行完毕后，目标模型工程目录下将根据配置生成与 3. 工程结构说明 中目录结构相同的所需初始文件，请根据实际情况，进一步修改和补充其中的内容。

1. 添加模型源码文件

将模型MODEL源码文件复制到已创建好的MODEL_icraft文件夹内。
删除源码中的.git文件夹及.gitignore文件。

2. 更新icraft相关文件

根据需求，相应增删改模型文件 （可分步执行git add&git commit命令，以便后续追溯修改）：

目录结构说明请参见3. 工程结构说明；
工程模板请参考：
- 仅有CRT：mobilenetv2
- 仅有PYRT：UNet
- 同时有CRT & PYRT：yolov5_7.0
MODEL_icraft/2_compile/config & MODEL_icraft/3_deploy/cfg & MODEL_icraft/3_deploy/metrics/logs目录下已生成对应后端及量化精度的 编译toml文件、运行时cfg配置yaml文件 和 测试结果log文件夹，用于单例测试（正确性检查中使用），三者文件名对应方式参考如下，前两者文件中各参数配置请根据模型实际情况修改（如：toml文件中parse/quantize段参数、yaml文件中dataset/param段配置等），若需修改imodel文件路径，请在两者文件中同步修改：
```
MODEL
└── MODEL_icraft
    ├── 2_compile
    │   └── config
    │       ├── BY
    │       │   └── MODEL_int8.toml
    │       ├── ZG
    │       │   └── MODEL_int8.toml
    │       └── WL
    │           └── MODEL_int8.toml
    └── 3_deploy
        ├── cfg
        │   ├── MODEL_BY_int8_demo.yaml
        │   ├── MODEL_ZG_int8_demo.yaml
        │   └── MODEL_WL_int8_demo.yaml
        └── metrics
            └── logs
                ├── BY_int8/
                │   ├── XXX_time.*    # 时间log文件（CRT模型为txt格式，PYRT模型为xlsx格式）
                │   └── XXX_metrics.log    # 精度log文件（若该模型不测精度，可无）
                │── ZG_int8/
                └── WL_int8/
```
注：
1. cfg配置文件名中的 demo 为后续正确性检查判断依据，如果不是用于单例测试，请 务必不要 在文件名中写入demo；
2. 用于单例测试的cfg配置文件名格式：XXX_TARGET_QDTYPE_demo.yaml，其中TARGET与QDTYPE分别代表实际适配的硬件后端（BY/ZG）及量化精度（int8/int16/bf16/mix等），与 2_compile/config目录下toml文件名 及 3_deploy/metrics/logs目录下文件夹名 均 须保持一致。
如需在模型编译中用到customop或额外dll等特别配置，可参考本工程icraft_folders/special目录下内容；
准备模型工程内的python运行环境配置文件：
- 如果选择使用uv管理，可根据uv模型库使用参考中的说明，在MODEL_icraft目录下更新pyproject.toml和uv.lock文件 （自动生成） ；
- 如果选择不使用uv管理，请在MODEL_icraft目录下添加包含所有所需环境依赖安装命令的文件。

3. 添加模型说明

1. `MODEL.yaml`文件

在目标模型工程目录下MODEL_icraft文件夹内已生成初始MODEL.yaml文件，文件中含${}处需要补充填写内容，${|XX,XX,…|}表示须从中选择一项填写，格式可参考本工程./scripts/egs/目录下的示例配置文件2_model_eg*.yaml；

yaml中部分填写项说明如下：（若初始化模型仓库时各配置正确，无需自行新增字段）

MODEL:  # 模型名 —— 已生成，与初始配置文件中的[model]配置相同
  model:  # 代表模型名 —— 已生成，与初始配置文件中的[repr_model]配置相同

    style: ${}
    # 模型类型，如选项中无匹配项，可先自行填写一个类型缩写，并在其后备注具体类型名，如：cv-det  # Computer Vision - Object Detection

    status:
      speed: ${|slow,ok|}  # 适配模型速度状态，从选项中选择
      metrics: ${|untested,low-acc,ok|}  # 适配模型精度状态，从选项中选择

    contributor: ${}  # 开发人员名字首字母

    model_source:  # 源码及原始权重信息
      code: ${}  # 源码仓库url
      branch: ${}  # 选用分支
      commit_id: ${}  # 选用内容的commit id
      weights: ${}  # 选用权重文件的下载url

    input_shape:  # 模型输入大小 —— 如为多网络模型，请按网络分开填写
    - ${}

    pyenv_prep: ${}
    # 如何管理模型工程内的python运行环境 —— 若使用uv，则已生成配置uv，否则需填写用于安装环境依赖的脚本执行命令（如：python pyenv_prep.py）

    deploy_cmd:  # CRT单例AXI模式测试运行命令 —— 若配置crt为true，则已初步生成，可按需求修改；若无crt，无需此配置
    pyrt_cmd:  # PYRT单例测试运行命令 —— 若配置pyrt为true，则已初步生成，可按需求修改；若无pyrt，无需此配置

    fpga_op:  # 模型使用的硬算子 —— 已根据配置初步生成，可按需求修改
    
    test_cmd:  # 精度测试运行命令 —— 已根据配置初步生成，可按需求修改
    dataset:
    - ${}  # 精度测试数据集名
    - ${}  # 精度测试数据集下载url
    rt_metrics:  # 精度测试工程是否直接输出指标结果 —— 已根据配置初步生成，可按需求修改
    evalpy: ${}  # 精度测试指标计算脚本，若上述rt_metrics配置为True，无需此配置

    time:  # 网络前向时间（Hardop_Hard_Time），选取不同ocmopt配置下的最短时间，请根据初步生成内容的格式填写

    posttime:  # 运行时工程中软件后处理时间（不包含画图、打印等不影响功能的时间），CRT模型必须填写，请根据初步生成内容的格式填写

    metrics:  # 精度数据，请根据初步生成内容的格式填写

2. `README.md`文件

运行本工程目录下./scripts/2_yaml2md.py脚本，在目标模型工程目录下生成README.md初始文件；

脚本运行命令：
```
cd scripts
python 2_yaml2md.py
       "XXX/XXX/MODEL"        # 目标模型工程路径，例："F:/models/yolov5"
```
请仔细阅读脚本生成的README.md文件，并再 根据实际需要进行修改 ，包括但不限于其中含💡提示处。

4. 上传

在当前 非master分支 上将上文所述模型文件 全部添加完毕，即做好模型入库准备后，依次执行以下步骤以上传模型文件：

确认已在模型信息汇总页面上登记当前模型信息，页面表格中模型名/源码链接栏内容须与本MODEL名一致；
运行本工程目录./scripts/3_set_githooks.py脚本，为目标模型工程设置hooks路径；（此步骤仅需为目标模型工程执行一次）

脚本运行命令：
```
cd scripts
python 3_set_githooks.py
       "XXX/XXX/MODEL"        # 目标模型工程路径，例："F:/models/yolov5"
```
如果无法通过此脚本为模型设置hooks路径，请参照MS_hooks中说明自行操作。
在目标模型工程目录下，上传模型文件：
1. 执行git命令上传：
```
cd XXX/XXX/MODEL
git add .
git commit -m "..."
# 若成功运行第一节中所述初始化模型仓库脚本，当前分支已完成首次上传操作，可直接执行
git push
# 否则，若为首次上传当前分支（如：mdz_v3.33），需执行
git push -u origin mdz_v3.33
```
2. git push命令执行后，根据终端中显示内容确定上传检查结果：
  - 若终端中显示以下内容，则表示模型目录下文件结构与内容均已通过上传检查；
```
...

PASSED the preliminary check, ready to push ...
```
  - 若终端中显示以下内容，则表示模型目录下存在内容不符合要求，已阻止上传，请完整查看终端中错误信息，根据提示对模型目录下文件进行修改：
```
...

error: failed to push some refs to 'https://www.modelscope.cn/AIBS/MODEL.git'
```

注：

ModelScope上只能看到 master分支 及 tag版本 内容，即无法看到上传的 mdz_vX.X分支 内容，如需在网页上确认分支文件，可先临时标记一个tag版本（tag与分支名不可重复）上传，确认后再删除。
```
# 标记临时tag版本，如：mdz_v3.31_test
git tag mdz_v3.31_test
# 上传tag
git push origin mdz_v3.31_test
# 删除远程tag
git push --delete origin mdz_v3.31_test
# 删除本地tag
git tag -d mdz_v3.31_test
```

上传时可能遇到大文件推送失败问题：

报错内容：

...
Total XX (delta XX), reused XX (delta XX), pack-reused XX
remote: Resolving deltas: 100% (XX/XX), completed with X local object.
remote: GitLab: LFS objects are missing. Ensure LFS is properly set up or try a manual "git lfs push --all".
To https://www.modelscope.cn/AIBS/XXX.git
 ! [remote rejected] XXX -> XXX (pre-receive hook declined)
error: failed to push some refs to 'https://www.modelscope.cn/AIBS/XXX.git'

解决方法：

按报错内容中提示将大文件一次性上传后，再正常推送分支内容。

# 1. 上传大文件
git lfs push --all origin
# 2. 重新上传分支内容
# 若为首次上传该分支，如：mdz_v3.31
git push -u origin mdz_v3.31
# 否则，可直接
git push

ModelScope存在服务器网络不稳定的情况，有时可能上传失败，包括但不限于以下报错：

GL_HOOK_ERR

报错内容：

...
Total XX (delta XX), reused XX (delta XX), pack-reused XX
remote: Resolving deltas: XX% (XX/XX), completed with X local object.
remote: GL_HOOK_ERR: Modification refused by ModelScope.
remote: error: hook declined to update XXX
To https://www.modelscope.cn/AIBS/XXX
 ! [remote rejected] XXX -> XXX (hook declined)
error: failed to push some refs to 'https://www.modelscope.cn/AIBS/XXX.git'

可尝试解决的方法：
- 重新执行git push命令

HTTP 500

报错内容：

...
Total XX (delta XX), reused XX (delta XX), pack-reused XX
error: RPC failed; HTTP 500 curl 22 The requested URL returned error: 500
send-pack: unexpected disconnect while reading sideband packet
fatal: the remote end hung up unexpectedly
Everything up-to-date

可尝试解决的方法：
- 重新执行git push命令

push过程中卡死
- 显示内容：
```
...
Total 0 (delta 0), reused 0 (delta 0), pack-reused 0
```
- 可尝试解决的方法：（暂未探索到其它简便途径）
  - 创建新模型后重新上传

5. 检查反馈

设置hooks路径并上传成功后，会触发对目标模型工程的正确性检查，并在之后通过飞书通知检查结果，若检查未通过，则会一并发送出错内容，请根据信息进一步修改。

Start on ModelScope

0. 环境准备

1. 初始化模型仓库

2. 添加模型文件

1. 添加模型源码文件

2. 更新icraft相关文件

3. 添加模型说明

1. MODEL.yaml文件

2. README.md文件

4. 上传

5. 检查反馈

1. `MODEL.yaml`文件

2. `README.md`文件