diff --git a/docs/mindspore/source_zh_cn/mindformers/faq/mindformers_contribution.md b/docs/mindspore/source_zh_cn/mindformers/faq/mindformers_contribution.md index c0dd31a7b900fbd7ad33670de858a3a6dfba7378..4a91db1b9cc10c12bac6908ae5c805235b927938 100644 --- a/docs/mindspore/source_zh_cn/mindformers/faq/mindformers_contribution.md +++ b/docs/mindspore/source_zh_cn/mindformers/faq/mindformers_contribution.md @@ -1,3 +1,244 @@ # MindFormers贡献指南 -[![查看源文件](https://mindspore-website.obs.cn-north-4.myhuaweicloud.com/website-images/master/resource/_static/logo_source.svg)](https://gitee.com/mindspore/docs/blob/master/docs/mindspore/source_zh_cn/mindformers/faq/mindformers_contribution.md) \ No newline at end of file +[![查看源文件](https://mindspore-website.obs.cn-north-4.myhuaweicloud.com/website-images/master/resource/_static/logo_source.svg)](https://gitee.com/mindspore/docs/blob/master/docs/mindspore/source_zh_cn/mindformers/faq/mindformers_contribution.md) + +## 上传模型至社区的要求 +用户可以将自定义模型上传至openMind社区进行托管。 +### 1. Mindformers内置模型 +1. 若用户的自定义模型使用了Mindformers提供的内置模型,即模型代码位于mindformers/models下的模型,且对模型结构代码未进行任何修改,则只需上传模型的权重文件和配置即可。 +如用户使用Mindformers的内置Llama-7B模型,进行了微调训练,想分享微调后的模型权重,那么上传模型配置和权重文件即可。 +下面是保存模型配置和权重的代码 + +```python +import mindspore as ms +from mindformers import LlamaConfig, LlamaForCausalLM + +# 自定义超参的LlamaConfig +config = LlamaConfig() + +# 初始化模型 +model = LlamaForCausalLM(config) + +# 加载自定义权重 +ms.load_checkpoint("path/model.ckpt", model) + +# 保存预训练模型 +model.save_pretrained("./my_llama", save_json=True) +``` +2. 保存后可使用openmind_hub库,进行模型上传 + +```python +from openmind_hub import MdsApi + +# 创建MdsApi实例,使用特定的token +api = MdsApi(token="xxx") + +# 上传文件到openmind_hub +api.upload_file( + path_or_fileobj="./my_llama/config.json", + path_in_repo="config.json", + repo_id="username/test-dataset", +) + +``` +### 2. 自定义模型 +若用户有自定义的模型代码,则需要同时上传模型代码文件,并在json配置文件中添加映射,使其可以通过Auto类导入。 +#### 命名规则 +上传到社区的自定义代码文件,一般有统一的命名规则,假设自定义模型名为xxx,其代码命名应当如下 + +``` +---- xxx +|-configuration_xxx.py # Config类代码文件 +|-modeling_xxx.py # Model类代码文件 +|-tokenization_xxx.py # Tokenizer代码文件 +``` +#### 添加映射 +为让Auto类使用时,能够顺利找到用户自定义的模型类,需要在config.json文件中,添加auto映射。添加内容如下 + +```json +{ + "auto_map": { + "AutoConfig": "configuration_xxx.MyConfig", + "AutoModel": "modeling_xxx.MyModel", + "AutoModelForCausalLM": "modeling_xxx.MyModelForCausalLM" + } +} +``` +#### 上传模型 +可使用openmind_hub库,进行模型上传 + +```python +from openmind_hub import MdsApi + +# 创建MdsApi实例,使用特定的token +api = MdsApi(token="xxx") + +# 调用upload_file方法上传文件到openmind_hub +api.upload_file( + path_or_fileobj="./my_llama/config.json", # 指定本地文件路径 + path_in_repo="config.json", # 指定在仓库中的路径 + repo_id="username/test-dataset" # 指定目标仓库的ID +) +``` + +## 贡献代码至MindFormers +### 代码风格要求 +请遵循此风格,以便Mindformers审查、维护和开发。 +- 编码指南 +Mindformers社区使用`Python PEP 8` 编码风格。建议在IDE中安装以下插件,用于检查代码格式:`Lizard`、`ShellCheck` 和`PyLint`。 +- 单元测试指南 +Mindformers社区使用Python单元测试框架pytest。注释名称需反映测试用例的设计意图。 +重构指南 +我们鼓励开发人员重构我们的代码,以消除代码坏味道。所有代码都要符合编码风格和测试风格,重构代码也不例外。无注释的代码行(nloc)的Lizard阈值为100,圈复杂度(cnc)的阈值为20。当收到Lizard警告时,必须重构要合并的代码。 +- 文档指南 + +我们使用MarkdownLint来检查Markdown文档格式。基于默认配置修改了以下规则 + - MD007(无序列表缩进):参数indent设置为4,表示无序列表中的所有内容都需要缩进4个空格。 + - MD009(行尾空格):参数br_spaces设置为2,表示行尾可以有0或2个空格。 + - MD029(有序列表的序列号):参数style设置为ordered,表示升序。 + +### Fork-Pull 开发模型指导 +- Fork Mindformers代码仓 +在提交代码至Mindformers项目之前,请确保已fork此项目到您自己的代码仓。Mindformers代码仓和您自己的代码仓之间可能会并行开发,请注意它们之间的一致性。 +- 克隆远程代码仓 +如果您想将代码下载到本地计算机,最好使用git方法 + +``` +# 在Gitee上克隆仓库 +git clone https://gitee.com/(insert_your_forked_repo)/mindformers.git +``` +- 本地开发代码 +为避免分支不一致,建议切换到新分支 + +``` +git checkout -b {新分支名称} origin/dev +``` +- 提交PR到MindSpore代码仓 +在最后一步中,您需要在新分支和Mindformers主分支之间拉取比较请求。完成拉取请求后,Jenkins CI将自动设置,进行构建测试。PR应该尽快合并到上游dev分支中,以降低合并的风险。 + +``` +# 添加所有更改到暂存区 +git add + +# 查看更新状态 +git status + +# 提交更改,使用-m选项添加commit标题 +git commit -m "你的commit标题" + +# 添加commit的具体描述,使用-s选项添加签名,-amend选项修改最近一次提交 +git commit -s --amend + +# 推送更改到远程仓库的新分支 +git push origin {新分支名称} + +``` + +### 文件及代码格式 +若希望将自定义模型合入Mindformers代码仓库,需要注意几点 +1. 文件格式及位置要遵循规范 +2. 将新模型在代码中进行注册,以适配高阶接口使用 +#### 文件格式及位置 +1. 模型代码文件统一放置于mindformers/models文件夹下,格式如下 +```plaintext +mindformers/models +├── XXX +| ├── init.py +| ├── convert_weight.py # Torch权重转MindSpore权重脚本(迁移模型需提供) +| ├── convert_reversed.py # MindSpore权重转Torch权重脚本(迁移模型需提供) +| ├── configuration_xxx.py # Config类代码文件 +| ├── modeling_xxx.py # Model类代码文件 +| └── tokenization_xxx.py # Tokenizer代码文件 +``` +2. 模型文档放置于docs/model_cards文件夹下 +```plaintext +docs/model_cards +├── XXX.md +``` +#### 注册机制 +1. 使用MindFormerRegister类进行注册 +需要将自定义模型的主要类通过该类进行注册,实例如下 + +```python +from mindformers.tools.register import MindFormerRegister, MindFormerModuleType + +@MindFormerRegister.register(MindFormerModuleType.CONFIG) +class LlamaConfig(PretrainedConfig): + pass + +``` + +```python +class MindFormerModuleType: + TRAINER = 'trainer' + PIPELINE = 'pipeline' + PROCESSOR = 'processor' + TOKENIZER = 'tokenizer' + DATASET = 'dataset' + MASK_POLICY = 'mask_policy' + DATASET_LOADER = 'dataset_loader' + DATASET_SAMPLER = 'dataset_sampler' + TRANSFORMS = 'transforms' + ENCODER = 'encoder' + MODELS = 'models' + MODULES = 'modules' + TRANSFORMER = 'transformer' + BASE_LAYER = 'base_layer' + CORE = 'core' + HEAD = 'head' + LOSS = 'loss' + LR = 'lr' + OPTIMIZER = 'optimizer' + CONTEXT = 'context' + CALLBACK = 'callback' + WRAPPER = 'wrapper' + METRIC = 'metric' + CONFIG = 'config' + TOOLS = 'tools' + FEATURE_EXTRACTOR = 'feature_extractor' +``` + +## 提交PR的要求 +### 提交的PR要求只有一个commit +对于多commit的PR,请使用`git rebase` 命令将多个commit合并为一个 +例如使用 + +``` +git rebase -i HEAD^3 +``` +可以看到 +``` +pick 1234567 添加新功能A +pick 89abcdef 修复了功能A中的bug +pick 01234567 对功能A进行了一些优化 +``` +squash合并commit(可简化为 s,p等简写) +``` +pick 1234567 添加新功能A +squash 89abcdef 修复了功能A中的bug +squash 01234567 对功能A进行了一些优化 +``` +### PR描述 +请使用以下md模板 +``` +### 相关的Issue + + +### 原因(目的、解决的问题等) + + +### 描述(做了什么,变更了什么) + + +### check list + +#### 是否完成方案评审或问题根因分析(Y/N) + +#### 是否完成了功能模块的UT/ST,并执行通过,附上结果(Y/N) + +#### 是否涉及公共组件或对外接口修改,涉及时需给出修改范围和影响评估(Y/N) + +#### 是否涉及资料修改,涉及时需同步修改(Y/N) + +``` +对于文档的合入,可以使用 `code_docs_xxx`前缀跳过NPU门禁检查 \ No newline at end of file