可用于评测的模型介绍
====================

本项目的文本情感分析模型评测模块评测的是文本情感分析模型的鲁棒性。本模块内置了一些示例模型，可以直接使用；也可以从 Huggingface Hub 上下载其他模型，然后使用本项目进行评测；同时还支持自定义模型。

内置模型
------------------

本项目在 :code:`text.Models.TestModel` 中内置了以下模型：

-   :code:`bert-amazon-zh` ：BERT结构，5 分类模型，中文，对商品评论进行1-5分评分预测。
-   :code:`roberta-chinanews` ：RoBERTa结构，7 分类模型，中文，依据新闻标题或内容对新闻的主题进行7分类。
-   :code:`roberta-ifeng` ：RoBERTa结构，5 分类模型，中文，依据新闻标题或内容对新闻的主题进行5分类。
-   :code:`roberta-dianping` ：RoBERTa结构，2 分类模型，中文，对餐饮店评论进行好评/差评2分类。
-   :code:`roberta-sst` ：RoBERTa结构，2 分类模型，英文，对电影影评进行好评/差评2分类。


Huggingface Hub上的模型
--------------------------------

本项目支持从 Huggingface Hub 上下载模型，然后使用本项目进行评测。 Huggingface Hub 上的模型可以在 \ `Huggingface官网 <https://huggingface.co/models>`__\ 找到。在使用文本情感分析模型评测模块的命令行工具 :code:`text.cli.py` 时，可以使用 :code:`--model huggingface/xxx` 参数指定模型。例如 :code:`--model huggingface/IDEA-CCNL/Erlangshen-Roberta-110M-Sentiment` 指定了一个RoBERTa结构的模型，模型任务是中文的情感2分类。

需要注意的是，这些模型必须能通过 :code:`transformers.AutoModelForSequenceClassification.from_pretrained` 加载，相应的 tokenizer 也必须能通过 :code:`transformers.AutoTokenizer.from_pretrained` 加载。例如，模型 :code:`huggingface/microsoft/Multilingual-MiniLM-L12-H384` 明确指出了（见 \ `此模型介绍页面 <https://huggingface.co/microsoft/Multilingual-MiniLM-L12-H384>`__\ ）：

  Please note: This checkpoint uses BertModel with XLMRobertaTokenizer so AutoTokenizer won't work with this checkpoint!

这意味着，这个模型不能直接通过用命令行工具 :code:`cli.py` 传递参数 :code:`--model huggingface/microsoft/Multilingual-MiniLM-L12-H384` 来加载，而需要使用者自定义模型，具体方法见下文。

用户也可以自行把模型的权重文件下载到本地，然后通过传递参数 :code:`--model huggingface --model-path /xxx/yyy/zzz` 来加载存在本地的 transformers 模型，其中不带模型具体名称的参数  :code:`--model huggingface` 是用来提示程序需要加载的是 transformers 模型。这些模型也是要求必须能通过 :code:`transformers.AutoModelForSequenceClassification.from_pretrained` 加载。

要注意的是，如果 transformers 模型的具体名称以及本地地址都传递了的话，那么 :code:`--model` 参数的值会被忽略，同时触发如下警告

  模型名称和模型路径同时指定，将忽略模型名称，从输入的模型路径加载模型。

例如 :code:`--model huggingface/microsoft/Multilingual-MiniLM-L12-H384  --model-path /xxx/yyy/zzz` 将会在程序内部触发 :code:`transformers.AutoModelForSequenceClassification.from_pretrained("/xxx/yyy/zzz")` 来加载模型，而 :code:`/microsoft/Multilingual-MiniLM-L12-H384` 将会被忽略。

自定义模型
------------------

本项目支持自定义模型。自定义模型的方法是，使用者需要自己在文件夹 :code:`text.Models.UserModel` 中新建一个Python文件，在该文件中实现一个类，继承自 :code:`text.Models.base.NLPVictimModel` ，并实现 :code:`__call__` 方法。

为了调用方便，还可以（ **这一步是可选的，不是必须完成的** ）进一步在文件 :code:`text.Models.UserModel.__init__.py` 中将该类导入。例如，如果用户想要使用一个自定义的RoBERTa模型，可以在文件 :code:`text.Models.UserModel.__init__.py` 中添加如下代码：

::

  from .roberta import MyRoBERTa

并在该文件的列表 :code:`__all__` 中添加 :code:`"MyRoBERTa"` 。

在文件 :code:`text.Models.UserModel.dummy.py` 中有一个示例，可以参考，该示例实现了一个随机的2分类模型。代码如下：

::

  from typing import Optional, Sequence, List, Any, Dict

  import torch

  from ..base import NLPVictimModel


  __all__ = ["DummyVictimModel"]


  class DummyVictimModel(NLPVictimModel):
    """
    A dummy victim model produces random logits for binary classification.
    """

    def __init__(self, path: Optional[str] = None) -> None:
      """
      Implementations of this method is **required**.
      Loading the model (and tokenizer) from the given path(s).
      """
      pass

    def __call__(self, text_input_list: Sequence[str], **kwargs: Any) -> torch.Tensor:
      """
      Implementations of this method is **required**.
      This method should return the model's logits for the given inputs.
      """
      # random logits of shape (n_samples, 2)
      logits = torch.rand(len(text_input_list), 2)
      return logits

    def get_grad(self, text_input: str) -> Dict[str, torch.Tensor]:
      """
      Implementations of this method is **optional**.
      Get gradient of loss with respect to input tokens.
      """
      raise NotImplementedError

    def _tokenize(self, inputs: Sequence[str]) -> List[List[str]]:
      """
      Implementations of this method is **optional**.
      Helper method for `tokenize`.
      """
      raise NotImplementedError