spark-nlp 2.6.3rc1__py2.py3-none-any.whl → 6.2.1__py2.py3-none-any.whl

sparknlp/annotator/embeddings/camembert_embeddings.py

@@ -0,0 +1,210 @@
+#  Copyright 2017-2022 John Snow Labs
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+"""Contains classes for CamemBertEmbeddings."""
+
+from sparknlp.common import *
+
+
+class CamemBertEmbeddings(AnnotatorModel,
+                          HasEmbeddingsProperties,
+                          HasCaseSensitiveProperties,
+                          HasStorageRef,
+                          HasBatchedAnnotate,
+                          HasEngine,
+                          HasMaxSentenceLengthLimit):
+    """The CamemBERT model was proposed in CamemBERT: a Tasty French Language Model by
+        Louis Martin, Benjamin Muller, Pedro Javier Ortiz Suárez, Yoann Dupont, Laurent
+        Romary, Éric Villemonte de la Clergerie, Djamé Seddah, and Benoît Sagot.
+
+        It is based on Facebook's RoBERTa model released in 2019. It is a model trained
+        on 138GB of French text.
+
+        Pretrained models can be loaded with ``pretrained`` of the companion object:
+
+        >>> embeddings = CamemBertEmbeddings.pretrained() \\
+        ...     .setInputCols(["token", "document"]) \\
+        ...     .setOutputCol("camembert_embeddings")
+
+
+        The default model is ``"camembert_base"``, if no name is provided.
+
+        For available pretrained models please see the
+        `Models Hub <https://sparknlp.org/models?task=Embeddings>`__.
+
+        For extended examples of usage, see the
+        `Examples <https://github.com/JohnSnowLabs/spark-nlp/blob/master/examples/python/training/english/dl-ner/ner_bert.ipynb>`__
+        and the
+        `CamemBertEmbeddingsTestSpec <https://github.com/JohnSnowLabs/spark-nlp/blob/master/src/test/scala/com/johnsnowlabs/nlp/embeddings/CamemBertEmbeddingsTestSpec.scala>`__.
+
+        To see which models are compatible and how to import them see
+        https://github.com/JohnSnowLabs/spark-nlp/discussions/5669.
+
+        ====================== ======================
+        Input Annotation types Output Annotation type
+        ====================== ======================
+        ``DOCUMENT, TOKEN``    ``WORD_EMBEDDINGS``
+        ====================== ======================
+
+        Parameters
+        ----------
+
+        batchSize
+            Size of every batch , by default 8
+        dimension
+            Number of embedding dimensions, by default 768
+        caseSensitive
+            Whether to ignore case in tokens for embeddings matching, by default False
+        maxSentenceLength
+            Max sentence length to process, by default 128
+        configProtoBytes
+            ConfigProto from tensorflow, serialized into byte array.
+
+        References
+        ----------
+
+        `CamemBERT: a Tasty French Language Model <https://arxiv.org/abs/1911.03894>`__
+
+        https://huggingface.co/camembert
+
+        **Paper abstract**
+
+        *Pretrained language models are now ubiquitous in Natural Language Processing.
+        Despite their success, most available models have either been trained on English
+        data or on the concatenation of data in multiple languages. This makes practical
+        use of such models --in all languages except English-- very limited. In this
+        paper, we investigate the feasibility of training monolingual Transformer-based
+        language models for other languages, taking French as an example and evaluating
+        our language models on part-of-speech tagging, dependency parsing, named entity
+        recognition and natural language inference tasks. We show that the use of web
+        crawled data is preferable to the use of Wikipedia data. More surprisingly, we
+        show that a relatively small web crawled dataset (4GB) leads to results that are
+        as good as those obtained using larger datasets (130+GB). Our best performing
+        model CamemBERT reaches or improves the state of the art in all four downstream
+        tasks.*
+
+        Examples
+        --------
+        >>> import sparknlp
+        >>> from sparknlp.base import *
+        >>> from sparknlp.annotator import *
+        >>> from pyspark.ml import Pipeline
+        >>> documentAssembler = DocumentAssembler() \\
+        ...     .setInputCol("text") \\
+        ...     .setOutputCol("document")
+        >>> tokenizer = Tokenizer() \\
+        ...     .setInputCols(["document"]) \\
+        ...     .setOutputCol("token")
+        >>> embeddings = CamemBertEmbeddings.pretrained() \\
+        ...     .setInputCols(["token", "document"]) \\
+        ...     .setOutputCol("camembert_embeddings")
+        >>> embeddingsFinisher = EmbeddingsFinisher() \\
+        ...     .setInputCols(["camembert_embeddings"]) \\
+        ...     .setOutputCols("finished_embeddings") \\
+        ...     .setOutputAsVector(True)
+        >>> pipeline = Pipeline().setStages([
+        ...     documentAssembler,
+        ...     tokenizer,
+        ...     embeddings,
+        ...     embeddingsFinisher
+        ... ])
+        >>> data = spark.createDataFrame([["C'est une phrase."]]).toDF("text")
+        >>> result = pipeline.fit(data).transform(data)
+        >>> result.selectExpr("explode(finished_embeddings) as result").show(5, 80)
+        +--------------------------------------------------------------------------------+
+        |                                                                          result|
+        +--------------------------------------------------------------------------------+
+        |[0.08442357927560806,-0.12863239645957947,-0.03835778683423996,0.200479581952...|
+        |[0.048462312668561935,0.12637358903884888,-0.27429091930389404,-0.07516729831...|
+        |[0.02690504491329193,0.12104076147079468,0.012526623904705048,-0.031543646007...|
+        |[0.05877285450696945,-0.08773420006036758,-0.06381352990865707,0.122621834278...|
+        +--------------------------------------------------------------------------------+
+        """
+
+    name = "CamemBertEmbeddings"
+
+    inputAnnotatorTypes = [AnnotatorType.DOCUMENT, AnnotatorType.TOKEN]
+
+    outputAnnotatorType = AnnotatorType.WORD_EMBEDDINGS
+
+    configProtoBytes = Param(
+        Params._dummy(),
+        "configProtoBytes",
+        "ConfigProto from tensorflow, serialized into byte array. Get with config_proto.SerializeToString()",
+        TypeConverters.toListInt,
+    )
+
+    def setConfigProtoBytes(self, b):
+        """Sets configProto from tensorflow, serialized into byte array.
+
+        Parameters
+        ----------
+        b : List[int]
+            ConfigProto from tensorflow, serialized into byte array
+        """
+        return self._set(configProtoBytes=b)
+
+    @keyword_only
+    def __init__(self, classname="com.johnsnowlabs.nlp.embeddings.CamemBertEmbeddings", java_model=None):
+        super(CamemBertEmbeddings, self).__init__(
+            classname=classname,
+            java_model=java_model
+        )
+        self._setDefault(
+            batchSize=8,
+            dimension=768,
+            maxSentenceLength=128,
+            caseSensitive=True
+        )
+
+    @staticmethod
+    def loadSavedModel(folder, spark_session):
+        """Loads a locally saved model.
+
+        Parameters
+        ----------
+        folder : str
+            Folder of the saved model
+        spark_session : pyspark.sql.SparkSession
+            The current SparkSession
+
+        Returns
+        -------
+        CamemBertEmbeddings
+            The restored model
+        """
+        from sparknlp.internal import _CamemBertLoader
+        jModel = _CamemBertLoader(folder, spark_session._jsparkSession)._java_obj
+        return CamemBertEmbeddings(java_model=jModel)
+
+    @staticmethod
+    def pretrained(name="camembert_base", lang="fr", remote_loc=None):
+        """Downloads and loads a pretrained model.
+
+        Parameters
+        ----------
+        name : str, optional
+            Name of the pretrained model, by default "camembert_base"
+        lang : str, optional
+            Language of the pretrained model, by default "fr"
+        remote_loc : str, optional
+            Optional remote address of the resource, by default None. Will use
+            Spark NLPs repositories otherwise.
+
+        Returns
+        -------
+        CamemBertEmbeddings
+            The restored model
+        """
+        from sparknlp.pretrained import ResourceDownloader
+        return ResourceDownloader.downloadModel(CamemBertEmbeddings, name, lang, remote_loc)

sparknlp/annotator/embeddings/chunk_embeddings.py

@@ -0,0 +1,149 @@
+#  Copyright 2017-2022 John Snow Labs
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+"""Contains classes for ChunkEmbeddings"""
+
+from sparknlp.common import *
+
+
+class ChunkEmbeddings(AnnotatorModel):
+    """This annotator utilizes WordEmbeddings, BertEmbeddings etc. to generate
+    chunk embeddings from either Chunker, NGramGenerator, or NerConverter
+    outputs.
+
+    For extended examples of usage, see the `Examples <https://github.com/JohnSnowLabs/spark-nlp/blob/master/examples/python/annotation/text/english/embeddings/ChunkEmbeddings.ipynb>`__.
+
+    ========================== ======================
+    Input Annotation types     Output Annotation type
+    ========================== ======================
+    ``CHUNK, WORD_EMBEDDINGS`` ``WORD_EMBEDDINGS``
+    ========================== ======================
+
+    Parameters
+    ----------
+    poolingStrategy
+        Choose how you would like to aggregate Word Embeddings to Chunk
+        Embeddings, by default AVERAGE.
+        Possible Values: ``AVERAGE, SUM``
+    skipOOV
+        Whether to discard default vectors for OOV words from the
+        aggregation/pooling.
+
+    Examples
+    --------
+    >>> import sparknlp
+    >>> from sparknlp.base import *
+    >>> from sparknlp.annotator import *
+    >>> from pyspark.ml import Pipeline
+
+    Extract the Embeddings from the NGrams
+
+    >>> documentAssembler = DocumentAssembler() \\
+    ...     .setInputCol("text") \\
+    ...     .setOutputCol("document")
+    >>> sentence = SentenceDetector() \\
+    ...     .setInputCols(["document"]) \\
+    ...     .setOutputCol("sentence")
+    >>> tokenizer = Tokenizer() \\
+    ...     .setInputCols(["sentence"]) \\
+    ...     .setOutputCol("token")
+    >>> nGrams = NGramGenerator() \\
+    ...     .setInputCols(["token"]) \\
+    ...     .setOutputCol("chunk") \\
+    ...     .setN(2)
+    >>> embeddings = WordEmbeddingsModel.pretrained() \\
+    ...     .setInputCols(["sentence", "token"]) \\
+    ...     .setOutputCol("embeddings") \\
+    ...     .setCaseSensitive(False)
+
+    Convert the NGram chunks into Word Embeddings
+
+    >>> chunkEmbeddings = ChunkEmbeddings() \\
+    ...     .setInputCols(["chunk", "embeddings"]) \\
+    ...     .setOutputCol("chunk_embeddings") \\
+    ...     .setPoolingStrategy("AVERAGE")
+    >>> pipeline = Pipeline() \\
+    ...     .setStages([
+    ...       documentAssembler,
+    ...       sentence,
+    ...       tokenizer,
+    ...       nGrams,
+    ...       embeddings,
+    ...       chunkEmbeddings
+    ...     ])
+    >>> data = spark.createDataFrame([["This is a sentence."]]).toDF("text")
+    >>> result = pipeline.fit(data).transform(data)
+    >>> result.selectExpr("explode(chunk_embeddings) as result") \\
+    ...     .select("result.annotatorType", "result.result", "result.embeddings") \\
+    ...     .show(5, 80)
+    +---------------+----------+--------------------------------------------------------------------------------+
+    |  annotatorType|    result|                                                                      embeddings|
+    +---------------+----------+--------------------------------------------------------------------------------+
+    |word_embeddings|   This is|[-0.55661, 0.42829502, 0.86661, -0.409785, 0.06316501, 0.120775, -0.0732005, ...|
+    |word_embeddings|      is a|[-0.40674996, 0.22938299, 0.50597, -0.288195, 0.555655, 0.465145, 0.140118, 0...|
+    |word_embeddings|a sentence|[0.17417, 0.095253006, -0.0530925, -0.218465, 0.714395, 0.79860497, 0.0129999...|
+    |word_embeddings|sentence .|[0.139705, 0.177955, 0.1887775, -0.45545, 0.20030999, 0.461557, -0.07891501, ...|
+    +---------------+----------+--------------------------------------------------------------------------------+
+    """
+
+    name = "ChunkEmbeddings"
+
+    inputAnnotatorTypes = [AnnotatorType.CHUNK, AnnotatorType.WORD_EMBEDDINGS]
+
+    outputAnnotatorType = AnnotatorType.WORD_EMBEDDINGS
+
+    @keyword_only
+    def __init__(self):
+        super(ChunkEmbeddings, self).__init__(classname="com.johnsnowlabs.nlp.embeddings.ChunkEmbeddings")
+        self._setDefault(
+            poolingStrategy="AVERAGE"
+        )
+
+    poolingStrategy = Param(Params._dummy(),
+                            "poolingStrategy",
+                            "Choose how you would like to aggregate Word Embeddings to Chunk Embeddings:" +
+                            "AVERAGE or SUM",
+                            typeConverter=TypeConverters.toString)
+    skipOOV = Param(Params._dummy(), "skipOOV",
+                    "Whether to discard default vectors for OOV words from the aggregation / pooling ",
+                    typeConverter=TypeConverters.toBoolean)
+
+    def setPoolingStrategy(self, strategy):
+        """Sets how to aggregate Word Embeddings to Chunk Embeddings, by default
+        AVERAGE.
+
+        Possible Values: ``AVERAGE, SUM``
+
+        Parameters
+        ----------
+        strategy : str
+            Aggregation Strategy
+        """
+        if strategy == "AVERAGE":
+            return self._set(poolingStrategy=strategy)
+        elif strategy == "SUM":
+            return self._set(poolingStrategy=strategy)
+        else:
+            return self._set(poolingStrategy="AVERAGE")
+
+    def setSkipOOV(self, value):
+        """Sets whether to discard default vectors for OOV words from the
+        aggregation/pooling.
+
+        Parameters
+        ----------
+        value : bool
+            whether to discard default vectors for OOV words from the
+            aggregation/pooling.
+        """
+        return self._set(skipOOV=value)

sparknlp/annotator/embeddings/deberta_embeddings.py

@@ -0,0 +1,208 @@
+#  Copyright 2017-2022 John Snow Labs
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+"""Contains classes for DeBertaEmbeddings."""
+from sparknlp.common import *
+
+
+class DeBertaEmbeddings(AnnotatorModel,
+                        HasEmbeddingsProperties,
+                        HasCaseSensitiveProperties,
+                        HasStorageRef,
+                        HasBatchedAnnotate,
+                        HasEngine,
+                        HasMaxSentenceLengthLimit):
+    """The DeBERTa model was proposed in DeBERTa: Decoding-enhanced BERT with
+    Disentangled Attention by Pengcheng He, Xiaodong Liu, Jianfeng Gao, Weizhu
+    Chen It is based on Google’s BERT model released in 2018 and Facebook’s
+    RoBERTa model released in 2019.
+
+    This model requires input tokenization with
+    SentencePiece model, which is provided by Spark NLP (See tokenizers
+    package).
+
+    It builds on RoBERTa with disentangled attention and enhanced mask decoder
+    training with half of the data used in RoBERTa.
+
+    Pretrained models can be loaded with pretrained of the companion object:
+
+    >>> embeddings = DeBertaEmbeddings.pretrained() \\
+    ...    .setInputCols(["sentence", "token"]) \\
+    ...    .setOutputCol("embeddings")
+
+    The default model is ``"deberta_v3_base"``, if no name is provided.
+
+    To see which models are compatible and how to import them see
+    `Import Transformers into Spark NLP 🚀
+    <https://github.com/JohnSnowLabs/spark-nlp/discussions/5669>`_.
+
+    ====================== ======================
+    Input Annotation types Output Annotation type
+    ====================== ======================
+    ``DOCUMENT, TOKEN``    ``WORD_EMBEDDINGS``
+    ====================== ======================
+
+    Parameters
+    ----------
+    batchSize
+        Size of every batch, by default 8
+    dimension
+        Number of embedding dimensions, by default 768
+    caseSensitive
+        Whether to ignore case in tokens for embeddings matching, by default
+        False
+    configProtoBytes
+        ConfigProto from tensorflow, serialized into byte array.
+    maxSentenceLength
+        Max sentence length to process, by default 128
+
+    References
+    ----------
+    https://github.com/microsoft/DeBERTa
+
+    https://www.microsoft.com/en-us/research/blog/microsoft-deberta-surpasses-human-performance-on-the-superglue-benchmark/
+
+    **Paper abstract:**
+
+    *Paper abstract: Recent progress in pre-trained neural language models has
+    significantly improved the performance of many natural language processing
+    (NLP) tasks. In this paper we propose a new model architecture DeBERTa (
+    Decoding-enhanced BERT with disentangled attention) that improves the BERT
+    and RoBERTa models using two novel techniques. The first is the disentangled
+    attention mechanism, where each word is represented using two vectors that
+    encode its content and position, respectively, and the attention weights
+    among words are computed using disentangled matrices on their contents and
+    relative positions. Second, an enhanced mask decoder is used to replace the
+    output softmax layer to predict the masked tokens for model pretraining. We
+    show that these two techniques significantly improve the efficiency of model
+    pretraining and performance of downstream tasks. Compared to RoBERTa-Large,
+    a DeBERTa model trained on half of the training data performs consistently
+    better on a wide range of NLP tasks, achieving improvements on MNLI by +0.9%
+    (90.2% vs. 91.1%), on SQuAD v2.0 by +2.3% (88.4% vs. 90.7%) and RACE by
+    +3.6% (83.2% vs. 86.8%). The DeBERTa code and pre-trained models will be
+    made publicly available at https://github.com/microsoft/DeBERTa.*
+
+    Examples
+    --------
+    >>> import sparknlp
+    >>> from sparknlp.base import *
+    >>> from sparknlp.annotator import *
+    >>> from pyspark.ml import Pipeline
+    >>> documentAssembler = DocumentAssembler() \\
+    ...     .setInputCol("text") \\
+    ...     .setOutputCol("document")
+    >>> tokenizer = Tokenizer() \\
+    ...     .setInputCols(["document"]) \\
+    >>> embeddings = DeBertaEmbeddings.pretrained() \\
+    ...     .setInputCols(["token", "document"]) \\
+    ...     .setOutputCol("embeddings")
+    >>> embeddingsFinisher = EmbeddingsFinisher() \\
+    ...     .setInputCols(["embeddings"]) \\
+    ...     .setOutputCols("finished_embeddings") \\
+    ...     .setOutputAsVector(True) \\
+    ...     .setCleanAnnotations(False)
+    >>> pipeline = Pipeline().setStages([
+    ...     documentAssembler,
+    ...     tokenizer,
+    ...     embeddings,
+    ...     embeddingsFinisher
+    ... ])
+    >>> data = spark.createDataFrame([["This is a sentence."]]).toDF("text")
+    >>> result = pipeline.fit(data).transform(data)
+    >>> result.selectExpr("explode(finished_embeddings) as result").show(5, 80)
+    +--------------------------------------------------------------------------------+
+    |                                                                          result|
+    +--------------------------------------------------------------------------------+
+    |[1.1342473030090332,-1.3855540752410889,0.9818322062492371,-0.784737348556518...|
+    |[0.847029983997345,-1.047153353691101,-0.1520637571811676,-0.6245765686035156...|
+    |[-0.009860038757324219,-0.13450059294700623,2.707749128341675,1.2916892766952...|
+    |[-0.04192575812339783,-0.5764210224151611,-0.3196685314178467,-0.527840495109...|
+    |[0.15583214163780212,-0.1614152491092682,-0.28423872590065,-0.135491415858268...|
+    +--------------------------------------------------------------------------------+
+    """
+
+    name = "DeBertaEmbeddings"
+
+    inputAnnotatorTypes = [AnnotatorType.DOCUMENT, AnnotatorType.TOKEN]
+
+    outputAnnotatorType = AnnotatorType.WORD_EMBEDDINGS
+
+    configProtoBytes = Param(Params._dummy(),
+                             "configProtoBytes",
+                             "ConfigProto from tensorflow, serialized into byte array. Get with config_proto.SerializeToString()",
+                             TypeConverters.toListInt)
+
+    def setConfigProtoBytes(self, b):
+        """Sets configProto from tensorflow, serialized into byte array.
+
+        Parameters
+        ----------
+        b : List[int]
+            ConfigProto from tensorflow, serialized into byte array
+        """
+        return self._set(configProtoBytes=b)
+
+    @keyword_only
+    def __init__(self, classname="com.johnsnowlabs.nlp.embeddings.DeBertaEmbeddings", java_model=None):
+        super(DeBertaEmbeddings, self).__init__(
+            classname=classname,
+            java_model=java_model
+        )
+        self._setDefault(
+            batchSize=8,
+            dimension=768,
+            maxSentenceLength=128,
+            caseSensitive=True
+        )
+
+    @staticmethod
+    def loadSavedModel(folder, spark_session):
+        """Loads a locally saved model.
+
+        Parameters
+        ----------
+        folder : str
+            Folder of the saved model
+        spark_session : pyspark.sql.SparkSession
+            The current SparkSession
+
+        Returns
+        -------
+        DeBertaEmbeddings
+            The restored model
+        """
+        from sparknlp.internal import _DeBERTaLoader
+        jModel = _DeBERTaLoader(folder, spark_session._jsparkSession)._java_obj
+        return DeBertaEmbeddings(java_model=jModel)
+
+    @staticmethod
+    def pretrained(name="deberta_v3_base", lang="en", remote_loc=None):
+        """Downloads and loads a pretrained model.
+
+        Parameters
+        ----------
+        name : str, optional
+            Name of the pretrained model, by default "deberta_v3_base"
+        lang : str, optional
+            Language of the pretrained model, by default "en"
+        remote_loc : str, optional
+            Optional remote address of the resource, by default None. Will use
+            Spark NLPs repositories otherwise.
+
+        Returns
+        -------
+        DeBertaEmbeddings
+            The restored model
+        """
+        from sparknlp.pretrained import ResourceDownloader
+        return ResourceDownloader.downloadModel(DeBertaEmbeddings, name, lang, remote_loc)