Metadata-Version: 2.1
Name: PyCLUE
Version: 2019.12.5
Summary: Python toolkit for Chinese Language Understanding Evaluation benchmark.
Home-page: https://github.com/ChineseGLUE/PyCLUE
Author: Liu Shaoweihua
Author-email: liushaoweihua@126.com
Maintainer: CLUE
Maintainer-email: chineseGLUE@163.com
License: UNKNOWN
Description: # PyCLUE
        
        Python toolkit for Chinese Language Understanding Evaluation benchmark.
        
        中文语言理解测评基准的Python工具包，快速测评代表性数据集、基准（预训练）模型，并针对自己的数据选择合适的基准（预训练）模型进行快速应用。
        
        ## 安装PyCLUE
        
        现在，可以通过pip安装PyCLUE:
        
        ```bash
        pip install PyCLUE 
        ```
        
        ## 使用PyCLUE
        
        ### 分类/句子对 任务
        
        #### 快速测评CLUE数据集
        
        以下以在CPU/GPU上运行为例，完整例子可参见`PyCLUE/examples/classifications/run_clue_task.py`。在TPU上运行的例子参照`PyCLUE/examples/classifications/run_clue_task_tpu.py`。
        
        ```python
        # 指定使用的GPU，如无GPU则不指定
        import os
        os.environ["CUDA_VISIBLE_DEVICES"] = "0"
        
        # 导入分类/句子对测评任务相关组件
        from PyCLUE.tasks.run_classifier import clue_tasks, configs
        ```
        
        其中，`clue_tasks`函数接受测评任务的`dict`类型参数，`configs`为测评任务的`dict`类型参数，默认值和说明如下：
        
        ```json
        {
            # 测评任务名
            #     CLUE benchmark: afqmc, cmnli, copa, csl, iflytek, tnews, wsc
            #     chineseGLUE: bq, xnli, lcqmc, inews, thucnews
            "task_name": "afqmc",
            # 预训练语言模型
            #     如果该参数为None，需要指定vocab_file, bert_config_file和init_checkpoint三参数。
            #     或者可以直接指定以下基准（预训练）模型：
            #         bert, bert_wwm_ext, albert_xlarge, albert_large, albert_base, albert_base_ext,
            #         albert_small, albert_tiny, roberta, roberta_wwm_ext, roberta_wwm_ext_large
            "pretrained_lm_name": "bert",
            # 执行内容
            "do_train": true,
            "do_eval": true,
            "do_predict": true,
            # 数据路径
            #     如不指定，则默认为：PyCLUE/datasets
            #     路径中的文件后缀名可接受 "txt", "tsv", "json"等
            #     如果 do_train = True，数据目录中应至少包含train文件，前缀名为"train"
            #     如果 do_eval = True，数据目录中应至少包含dev文件，前缀名为"dev"
            #     如果 do_predict = True，数据目录中应至少包含test文件，前缀名为"test"
            "data_dir": null,
            # 输出结果保存路径
            #     如不指定，则默认为：PyCLUE/task_outputs
            #     包含训练的模型文件，tf_record数据以及输出的验证结果dev_results.txt/test_results.txt/test_results.tsv
            "output_dir": null,
            # 自行指定预训练语言模型三参数
            "vocab_file": null,
            "bert_config_file": null,
            "init_checkpoint": null,
            # 训练参数
            "do_lower_case": true,
            "max_seq_length": 128,
            "train_batch_size": 8,
            "eval_batch_size": 8,
            "predict_batch_size": 8,
            "learning_rate": 2e-05,
            "num_train_epochs": 1,
            "warmup_proportion": 0.1,
            "save_checkpoints_steps": 1000,
            "iterations_per_loop": 1000,
            # TPU选项
            "use_tpu": false,
            "tpu_name": null,
            "tpu_zone": null,
            "gcp_project": null,
            "master": null,
            "num_tpu_cores": 8,
            # 是否输出训练过程
            "verbose": 0
        }
        ```
        
        执行以下评测过程：
        
        ```python
        # task_name
        configs["task_name"] = "wsc"
        
        # pretrained_lm_name
        configs["pretrained_lm_name"] = "bert"
        
        # actions
        configs["do_train"] = True
        configs["do_eval"] = True
        configs["do_predict"] = True
        
        # train parameters
        configs["max_seq_length"] = 128
        configs["train_batch_size"] = 8
        configs["learning_rate"] = 2e-5
        configs["warmup_proportion"] = 0.1
        configs["num_train_epochs"] = 50
        
        # show training process
        configs["verbose"] = 0
        
        wsc_result = clue_tasks(configs)
        print(wsc_result)
        ```
        
        测评结果由`clue_tasks`返回，形式如下：
        
        ```json
        {
            # 验证集指标结果
            "dev_res":{
                "eval_accuracy": "",
                "eval_loss": "",
                "global_step": "",
                "loss": ""
            },
            # 测试集指标结果（部分测试集有label，具有参考意义；部分则没有label，无参考意义）
            "test_res":{
                "eval_accuracy": "",
                "eval_loss": "",
                "global_step": "",
                "loss": ""
            },
            # 测试集预测结果
            "test_outputs": [
                {
                    "guid": "test-0",
                    "text_a": "",
                    "text_b": "",
                    "label": ""
                },
                ...
            ]
        }
        ```
        
        测评结果同时保存在`configs`中指定的输出目录`${output_dir}/classifications/${task_name}/${pretrained_lm_name}`中，如本例的`PyCLUE/task_outputs/classifications/wsc/bert`中。其中`dev_results.txt`保存了验证集的指标结果，`test_results.txt`保存了测试集的指标结果（部分测试集有label，具有参考意义；部分则没有label，无参考意义）。`test_results.tsv`则保存了测试集的预测结果，具体形式如下：
        
        ```json
        {"guid": "test-0", "text_a": "_毛德和朵拉_看到火车冲过大草原，引擎上冒着滚滚黑烟。从远处就能听见它们的轰鸣声和狂野而清晰的汽笛声。当[它们]行进到近处时，马都跑开了。", "text_b": null, "label": "false"}
        {"guid": "test-1", "text_a": "毛德和朵拉看到_火车_冲过大草原，引擎上冒着滚滚黑烟。从远处就能听见它们的轰鸣声和狂野而清晰的汽笛声。当[它们]行进到近处时，马都跑开了。", "text_b": null, "label": "false"}
        {"guid": "test-2", "text_a": "毛德和朵拉看到火车冲过大草原，引擎上冒着滚滚_黑烟_。从远处就能听见它们的轰鸣声和狂野而清晰的汽笛声。当[它们]行进到近处时，马都跑开了。", "text_b": null, "label": "false"}
        {"guid": "test-3", "text_a": "毛德和朵拉看到火车冲过大草原，引擎上冒着滚滚黑烟。从远处就能听见它们的_轰鸣声_和狂野而清晰的汽笛声。当[它们]行进到近处时，马都跑开了。", "text_b": null, "label": "false"}
        {"guid": "test-4", "text_a": "毛德和朵拉看到火车冲过大草原，引擎上冒着滚滚黑烟。从远处就能听见它们的轰鸣声和狂野而清晰的_汽笛声_。当[它们]行进到近处时，马都跑开了。", "text_b": null, "label": "false"}
        {"guid": "test-5", "text_a": "毛德和朵拉看到火车冲过大草原，引擎上冒着滚滚黑烟。从远处就能听见它们的轰鸣声和狂野而清晰的汽笛声。当[它们]行进到近处时，_马_都跑开了。", "text_b": null, "label": "false"}
        ```
        
        #### 应用于自定义数据集
        
        以下以在CPU/GPU上运行为例，完整例子可参见`PyCLUE/examples/classifications/run_user_task.py`。在TPU上运行的例子参照`PyCLUE/examples/classifications/run_user_task_tpu.py`。
        
        ```python
        # 指定使用的GPU，如无GPU则不指定
        import os
        os.environ["CUDA_VISIBLE_DEVICES"] = "0"
        
        # 导入分类/句子对测评任务相关组件
        from PyCLUE.tasks.run_classifier import user_tasks, configs
        
        # task_name: default is "user_defined_task"
        configs["task_name"] = "" 
        
        # pretrained_lm_name
        configs["pretrained_lm_name"] = "bert"
        
        # actions
        configs["do_train"] = True
        configs["do_eval"] = True
        configs["do_predict"] = True
        
        # data_dir
        configs["data_dir"] = "my_file_path"
        
        # data configs
        configs["labels"] = ["0", "1"]
        # label_, text_a_column , text_b_column & delimiter:
        #     examples_1，txt文件，分隔符为_!_，句子对任务：
        #         0_!_我想要回家_!_我准备回家
        #         1_!_我想要回家_!_我准备吃饭
        #     >> label_column = 0, text_a_column = 1, text_b_column = 2, delimiter = "_!_"
        #     examples_2，tsv文件，分隔符为\t，分类任务：
        #         0\t我很生气
        #         1\t我很开心
        #     >> label_column = 0, text_a_column = 1, text_b_column = None, delimiter = "\t"
        #     examples_3，json文件，句子对任务：
        #         {"label": 0, "sentence1": "我想要回家", "sentence2": "我很生气"}
        #     >> label_column = "label", text_a_column = "sentence1", text_b_column = "sentence2", delimiter = None
        configs["label_column"] = ""
        configs["text_a_column"] = ""
        configs["text_b_column"] = ""
        configs["delimiter"] = ""
        # ignore_header
        #     是否丢弃第一行（往往是第一行为各列说明的时候设置为True）
        configs["ignore_header"] = False
        # min_seq_length
        #     删除最小句长小于min_seq_length的训练数据
        configs["min_seq_length"] = 3
        # file_type
        #     数据文件后缀名，可以为 "txt", "tsv", "json"
        configs["file_type"] = ""
        
        # output_dir
        configs["output_dir"] = ""
        
        # 预训练语言模型组件
        #     如果 pretrained_lm_name 不为 None, 以下部分不需要指定。
        configs["vocab_file"] = "vocab.txt"
        configs["bert_config_file"] = "XXX_config.json"
        configs["init_checkpoint"] = "XXX_model.ckpt"
        
        # train parameters
        configs["max_seq_length"] = 128
        configs["train_batch_size"] = 8
        configs["learning_rate"] = 2e-5
        configs["warmup_proportion"] = 0.1
        configs["num_train_epochs"] = 50
        
        # show training process
        configs["verbose"] = 0
        
        my_result = user_tasks(configs)
        print(my_result)
        ```
        
        结果的输出和保存形式与测评CLUE数据集时一致。
        
        ### 阅读理解任务
        
        #### 快速测评CLUE数据集
        
        即将加入。
        
        #### 应用于自定义数据集
        
        即将j加入。
        
        ### 命名实体识别任务
        
        #### 快速测评CLUE数据集
        
        即将加入。
        
        #### 应用于自定义数据集
        
        即将j加入。
        
        ## 基准（预训练）模型
        
        **现已支持以下模型：**
        
        1. [BERT-base](https://github.com/google-research/bert)
        2. [BERT-wwm-ext](https://github.com/ymcui/Chinese-BERT-wwm)
        3. [albert_xlarge](https://github.com/brightmart/albert_zh)
        4. [albert_large](https://github.com/brightmart/albert_zh)
        5. [albert_base](https://github.com/brightmart/albert_zh)
        6. [albert_base_ext](https://github.com/brightmart/albert_zh)
        7. [albert_small](https://github.com/brightmart/albert_zh)
        8. [albert_tiny](https://github.com/brightmart/albert_zh)
        9. [roberta](https://github.com/brightmart/roberta_zh)
        10. [roberta_wwm_ext](https://github.com/ymcui/Chinese-BERT-wwm)
        11. [roberta_wwm_ext_large](https://github.com/ymcui/Chinese-BERT-wwm)
        
        即将加入：
        
        1. [XLNet_mid](https://github.com/ymcui/Chinese-PreTrained-XLNet)
        2. [ERNIE_base](https://github.com/PaddlePaddle/ERNIE)
        
        ## 支持任务类型
        
        ### 分类任务
        
        **现已支持以下数据集：**
        
        #### CLUEBenchmark任务
        
        参考：https://github.com/CLUEbenchmark/CLUE
        
        1. **AFQMC 蚂蚁金融语义相似度**
        
           ```
           数据量：训练集（34334）验证集（4316）测试集（3861）
                例子：
                {"sentence1": "双十一花呗提额在哪", "sentence2": "里可以提花呗额度", "label": "0"}
                每一条数据有三个属性，从前往后分别是 句子1，句子2，句子相似度标签。其中label标签，1 表示sentence1和sentence2的含义类似，0表示两个句子的含义不同。
           ```
        
        2. **TNEWS' 今日头条中文新闻（短文本）分类 Short Text Classificaiton for News**
        
           ```
           数据量：训练集(266,000)，验证集(57,000)，测试集(57,000)
                例子：
                {"label": "102", "label_des": "news_entertainment", "sentence": "江疏影甜甜圈自拍，迷之角度竟这么好看，美吸引一切事物"}
                每一条数据有三个属性，从前往后分别是 分类ID，分类名称，新闻字符串（仅含标题）。
           ```
        
        3. **IFLYTEK' 长文本分类 Long Text classification**
        
           该数据集共有1.7万多条关于app应用描述的长文本标注数据，包含和日常生活相关的各类应用主题，共119个类别："打车":0,"地图导航":1,"免费WIFI":2,"租车":3,….,"女性":115,"经营":116,"收款":117,"其他":118(分别用0-118表示)。
        
           ```
           数据量：训练集(12,133)，验证集(2,599)，测试集(2,600)
               例子：
               {"label": "110", "label_des": "社区超市", "sentence": "朴朴快送超市创立于2016年，专注于打造移动端30分钟即时配送一站式购物平台，商品品类包含水果、蔬菜、肉禽蛋奶、海鲜水产、粮油调味、酒水饮料、休闲食品、日用品、外卖等。朴朴公司希望能以全新的商业模式，更高效快捷的仓储配送模式，致力于成为更快、更好、更多、更省的在线零售平台，带给消费者更好的消费体验，同时推动中国食品安全进程，成为一家让社会尊敬的互联网公司。,朴朴一下，又好又快,1.配送时间提示更加清晰友好2.保障用户隐私的一些优化3.其他提高使用体验的调整4.修复了一些已知bug"}
               每一条数据有三个属性，从前往后分别是 类别ID，类别名称，文本内容。
           ```
        
        4. **CMNLI 语言推理任务 Chinese Multi-Genre NLI**
        
           CMNLI数据由两部分组成：XNLI和MNLI。数据来自于fiction，telephone，travel，government，slate等，对原始MNLI数据和XNLI数据进行了中英文转化，保留原始训练集，合并XNLI中的dev和MNLI中的matched作为CMNLI的dev，合并XNLI中的test和MNLI中的mismatched作为CMNLI的test，并打乱顺序。该数据集可用于判断给定的两个句子之间属于蕴涵、中立、矛盾关系。
        
           ```
           数据量：train(391,782)，matched(12,426)，mismatched(13,880)
               例子：
               {"sentence1": "新的权利已经足够好了", "sentence2": "每个人都很喜欢最新的福利", "label": "neutral"}
               每一条数据有三个属性，从前往后分别是 句子1，句子2，蕴含关系标签。其中label标签有三种：neutral，entailment，contradiction。
           ```
        
        5. **COPA 因果推断-中文版 Choice of Plausible Alternatives**
        
           自然语言推理的数据集，给定一个假设以及一个问题表明是因果还是影响，并从两个选项中选择合适的一个。遵照原数据集，我们使用了acc作为评估标准。
        
           ```
           数据量：训练集(400)，验证集(100)，测试集(500)
               例子： 
               {"idx": 7, "premise": "那人在杂货店买东西时打折了。", "choice0": "他向收银员打招呼。", "choice1": "他用了一张优惠券。", "question": "cause", "label": 1}
               其中label的标注，0表示choice0，1 表示choice1。原先的COPA数据集是英文的，我们使用机器翻译以及人工翻译的方法，并做了些微的用法习惯上的调整，并根据中文的习惯进行了标注，得到了这份数据集。
           ```
        
        6. **WSC Winograd模式挑战中文版 The Winograd Schema Challenge,Chinese Version**
        
           威诺格拉德模式挑战赛是图灵测试的一个变种，旨在判定AI系统的常识推理能力。参与挑战的计算机程序需要回答一种特殊但简易的常识问题：代词消歧问题，即对给定的名词和代词判断是否指代一致。
        
           ```
           数据量：训练集(532)，验证集(104)，测试集(143) 
           例子：
           {"target": 
               {"span2_index": 28, 
                "span1_index": 0, 
                "span1_text": "马克", 
                "span2_text": "他"
               }, 
                "idx": 0, 
                "label": "false", 
                "text": "马克告诉皮特许多关于他自己的谎言，皮特也把这些谎言写进了他的书里。他应该多怀疑。"
           }
               其中label标签，true表示指代一致，false表示指代不一致。
           ```
        
        7. **CSL 论文关键词识别 Keyword Recognition**
        
           中文科技文献数据集包含中文核心论文摘要及其关键词。 用tf-idf生成伪造关键词与论文真实关键词混合，生成摘要-关键词对，关键词中包含伪造的则标签为0。
        
           ```
           数据量：训练集(20,000)，验证集(3,000)，测试集(3,000)
               例子： 
               {"id": 1, "abst": "为解决传统均匀FFT波束形成算法引起的3维声呐成像分辨率降低的问题,该文提出分区域FFT波束形成算法.远场条件下,以保证成像分辨率为约束条件,以划分数量最少为目标,采用遗传算法作为优化手段将成像区域划分为多个区域.在每个区域内选取一个波束方向,获得每一个接收阵元收到该方向回波时的解调输出,以此为原始数据在该区域内进行传统均匀FFT波束形成.对FFT计算过程进行优化,降低新算法的计算量,使其满足3维成像声呐实时性的要求.仿真与实验结果表明,采用分区域FFT波束形成算法的成像分辨率较传统均匀FFT波束形成算法有显著提高,且满足实时性要求.", "keyword": ["水声学", "FFT", "波束形成", "3维成像声呐"], "label": "1"}
               每一条数据有四个属性，从前往后分别是 数据ID，论文摘要，关键词，真假标签。
           ```
        
        #### ChineseGLUE任务
        
        参考：https://github.com/ChineseGLUE/ChineseGLUE
        
        1. **LCQMC口语化描述的语义相似度任务 Semantic Similarity Task**
        
           输入是两个句子，输出是0或1。其中0代表语义不相似，1代表语义相似。
        
           ```
           数据量：训练集(238,766)，验证集(8,802)，测试集(12,500)
               例子： 
                1.聊天室都有哪些好的 [分隔符] 聊天室哪个好 [分隔符] 1
                2.飞行员没钱买房怎么办？ [分隔符] 父母没钱买房子 [分隔符] 0
           ```
        
        2. **XNLI语言推断任务 Natural Language Inference**
        
           跨语言理解的数据集，给定一个前提和假设，判断这个假设与前提是否具有蕴涵、对立、中性关系。
        
           ```
           数据量：训练集(392,703)，验证集(2,491)，测试集(5,011)
               例子： 
                1.从 概念 上 看 , 奶油 收入 有 两 个 基本 方面 产品 和 地理 .[分隔符] 产品 和 地理 是 什么 使 奶油 抹 霜 工作 . [分隔符] neutral
                2.我们 的 一个 号码 会 非常 详细 地 执行 你 的 指示 [分隔符] 我 团队 的 一个 成员 将 非常 精确 地 执行 你 的 命令  [分隔符] entailment
               
               原始的XNLI覆盖15种语言（含低资源语言）。我们选取其中的中文，并将做格式转换，使得非常容易进入训练和测试阶段。
           ```
        
        3. **INEWS 互联网情感分析任务 Sentiment Analysis for Internet News**
        
           ```
           数据量：训练集(5,356)，验证集(1,000)，测试集(1,000)     
               例子：
               1_!_00005a3efe934a19adc0b69b05faeae7_!_九江办好人民满意教育_!_近3年来，九江市紧紧围绕“人本教育、公平教育、优质教育、幸福教育”的目标，努力办好人民满意教育，促进了义务教育均衡发展，农村贫困地区办学条件改善。目前，该市特色教育学校有70所 ......
               每行为一条数据，以_!_分割的个字段，从前往后分别是情感类别，数据id，新闻标题，新闻内容
           ```
        
        5. **BQ 智能客服问句匹配 Question Matching for Customer Service**
        
           该数据集是自动问答系统语料，共有120,000对句子对，并标注了句子对相似度值，取值为0或1（0表示不相似，1表示相似）。数据中存在错别字、语法不规范等问题，但更加贴近工业场景。
        
           ```
           数据量：训练集(100,000)，验证集(10,000)，测试集(10,000)
               例子： 
                1.我存钱还不扣的 [分隔符] 借了每天都要还利息吗 [分隔符] 0
                2.为什么我的还没有额度 [分隔符] 为啥没有额度！！ [分隔符] 1
           ```
        
        6. **THUCNEWS 长文本分类 Long Text classification**
        
           该数据集共有4万多条中文新闻长文本标注数据，共14个类别: "体育":0, "娱乐":1, "家居":2, "彩票":3, "房产":4, "教育":5, "时尚":6, "时政":7, "星座":8, "游戏":9, "社会":10, "科技":11, "股票":12, "财经":13。
        
           ```
           数据量：训练集(33,437)，验证集(4,180)，测试集(4,180)
               例子： 
            11_!_科技_!_493337.txt_!_爱国者A-Touch MK3533高清播放器试用　　爱国者MP5简介:　　"爱国者"北京华旗资讯，作为国内知名数码产品制>造商。1993年创立于北京中关村，是一家致力于......
            每行为一条数据，以_!_分割的个字段，从前往后分别是 类别ID，类别名称，文本ID，文本内容。
           ```
        
        ### 阅读理解任务
        
        即将加入。
        
        ### 命名实体识别任务
        
        即将加入。
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
