flair.models#

Classes

`EntityMentionLinker`(candidate_generator, ...)	Entity linking model for the biomedical domain.
`SpanClassifier`(embeddings, label_dictionary)	Entity Linking Model.
`LanguageModel`(dictionary, is_forward_lm, ...)	Container module with an encoder, a recurrent module, and a decoder.
`Lemmatizer`([embeddings, label_type, ...])
`TextPairClassifier`(embeddings, label_type[, ...])	Text Pair Classification Model for tasks such as Recognizing Textual Entailment, build upon TextClassifier.
`TextTripleClassifier`(embeddings, label_type)	Text Triple Classification Model for tasks such as Query-Ad Matching, build upon TextPairClassifier.
`TextPairRegressor`(embeddings, label_type[, ...])	Text Pair Regression Model for tasks such as Semantic Textual Similarity Benchmark.
`RelationClassifier`(embeddings, ...[, ...])	Relation Classifier to predict the relation between two entities.
`RelationExtractor`(embeddings, label_type, ...)
`RegexpTagger`(mapping)
`SequenceTagger`(embeddings, tag_dictionary, ...)	The SequenceTagger is one of two main architectures in Flair used for sequence tagging.
`PrefixedSequenceTagger`(*args, ...)
`TokenClassifier`(embeddings, ...[, span_encoding])	This is a simple class of models that tags individual words in text.
`WordTagger`(embeddings, label_dictionary, ...)
`FewshotClassifier`()
`TARSClassifier`([task_name, ...])	TARS model for text classification.
`TARSTagger`([task_name, label_dictionary, ...])	TARS model for sequence tagging.
`TextClassifier`(embeddings, label_type, ...)	Text Classification Model.
`TextRegressor`(document_embeddings[, label_name])
`MultitaskModel`(models[, task_ids, ...])	Multitask Model class which acts as wrapper for creating custom multitask models.

class flair.models.EntityMentionLinker(candidate_generator, preprocessor, entity_label_types, label_type, dictionary, batch_size=1024)View on GitHub #

Bases: Model[Sentence]

Entity linking model for the biomedical domain.

get_entity_label_types(entity_label_types)View on GitHub #

Find out what NER labels to extract from sentence.

Parameters:: entity_label_types (Union[str, Sequence[str], dict[str, set[str]]]) – A label type or sequence of label types of the required entities. You can also specify a label filter in a dictionary with the label type as key and the valid entity labels as values in a set. E.g. to use only ‘disease’ and ‘chemical’ labels from a NER-tagger: {‘ner’: {‘disease’, ‘chemical’}}. To use all labels from ‘ner’, pass ‘ner’
Return type:: dict[str, set[str]]

property label_type#: Each model predicts labels of a certain type.

property dictionary: EntityLinkingDictionary#

extract_entities_mentions(sentence, entity_label_types)View on GitHub #

Extract tagged mentions from sentences.

Return type:: list[Label]

predict(sentences, top_k=1, pred_label_type=None, entity_label_types=None, batch_size=None)View on GitHub #

Predicts the best matching top-k entity / concept identifiers of all named entities annotated with tag input_entity_annotation_layer.

Parameters:

sentences (Union[list[Sentence], Sentence]) – One or more sentences to run the prediction on
top_k (int) – Number of best-matching entity / concept identifiers
entity_label_types (Union[str, Sequence[str], dict[str, set[str]], None]) – A label type or sequence of label types of the required entities. You can also specify a label filter in a dictionary with the label type as key and the valid entity labels as values in a set. E.g. to use only ‘disease’ and ‘chemical’ labels from a NER-tagger: {‘ner’: {‘disease’, ‘chemical’}}. To use all labels from ‘ner’, pass ‘ner’
pred_label_type (Optional[str]) – The label under which the predictions of the linker should be stored
batch_size (Optional[int]) – Batch size to encode mentions/dictionary names

Return type:

None

classmethod build(model_name_or_path, label_type='link', dictionary_name_or_path=None, hybrid_search=True, batch_size=128, similarity_metric=SimilarityMetric.INNER_PRODUCT, preprocessor=None, sparse_weight=0.5, entity_type=None, dictionary=None, dataset_name=None)View on GitHub #

Builds a model for biomedical named entity normalization.

Parameters:

model_name_or_path (str) – the name to an transformer embedding model on the huggingface hub or “exact-string-match”
label_type (str) – the label-type the predictions should be assigned to
dictionary_name_or_path (Union[str, Path, None]) – the name or path to a dictionary. If the model name is a common biomedical model, the dictionary name is asigned by default. Otherwise you can pass any of “gene”, “species”, “disease”, “chemical” to get the respective biomedical dictionary.
hybrid_search (bool) – if True add a character-ngram-tfidf embedding on top of the transformer embedding model.
batch_size (int) – the batch_size used when indexing the dictionary.
similarity_metric (SimilarityMetric) – the metric used to compare similarity between two embeddings.
preprocessor (Optional[EntityPreprocessor]) – The preprocessor used to preprocess. If None is passed, it used an AD3P processor.
sparse_weight (float) – if hybrid_search is added, the sparse weight will weight the importance of the character-ngram-tfidf embedding. For the common models, this will be overwritten with a specific value.
entity_type (Optional[str]) – the entity type of the mentions
dictionary (Optional[EntityLinkingDictionary]) – the dictionary provided in memory. If None, the dictionary is loaded from dictionary_name_or_path.
dataset_name (Optional[str]) – the name to assign the dictionary for reference.

Return type:

EntityMentionLinker

forward_loss(data_points)View on GitHub #

Performs a forward pass and returns a loss tensor for backpropagation.

Implement this to enable training.

Return type:: tuple[Tensor, int]

classmethod load(model_path)View on GitHub #

Loads a Flair model from the given file or state dictionary.

Parameters:: model_path (Union[str, Path, dict[str, Any]]) – Either the path to the model (as string or Path variable) or the already loaded state dict.
Return type:: EntityMentionLinker
Returns:: The loaded Flair model.

evaluate(data_points, gold_label_type, out_path=None, embedding_storage_mode='none', mini_batch_size=32, main_evaluation_metric=('accuracy', 'f1-score'), exclude_labels=None, gold_label_dictionary=None, return_loss=True, k=1, **kwargs)View on GitHub #

Evaluates the model. Returns a Result object containing evaluation results and a loss value.

Implement this to enable evaluation.

Parameters:

data_points (Union[list[Sentence], Dataset]) – The labeled data_points to evaluate.
gold_label_type (str) – The label type indicating the gold labels
out_path (Union[str, Path, None]) – Optional output path to store predictions.
embedding_storage_mode (str) – One of ‘none’, ‘cpu’ or ‘gpu’. ‘none’ means all embeddings are deleted and freshly recomputed, ‘cpu’ means all embeddings are stored on CPU, or ‘gpu’ means all embeddings are stored on GPU
mini_batch_size (int) – The batch_size to use for predictions.
main_evaluation_metric (tuple[str, str]) – Specify which metric to highlight as main_score.
exclude_labels (Optional[list[str]]) – Specify classes that won’t be considered in evaluation.
gold_label_dictionary (Optional[Dictionary]) – Specify which classes should be considered, all other classes will be taken as <unk>.
return_loss (bool) – Weather to additionally compute the loss on the data-points.
**kwargs – Arguments that will be ignored.

Return type:

Result

Returns:

The evaluation results.

class flair.models.SpanClassifier(embeddings, label_dictionary, pooling_operation='first_last', label_type='nel', span_label_type=None, candidates=None, **classifierargs)View on GitHub #

Bases: DefaultClassifier[Sentence, Span]

Entity Linking Model.

The model expects text/sentences with annotated entity mentions and predicts entities to these mentions. To this end a word embedding is used to embed the sentences and the embedding of the entity mention goes through a linear layer to get the actual class label. The model is able to predict ‘<unk>’ for entity mentions that the model can not confidently match to any of the known labels.

emb_first(span, embedding_names)View on GitHub #

emb_last(span, embedding_names)View on GitHub #

emb_firstAndLast(span, embedding_names)View on GitHub #

emb_mean(span, embedding_names)View on GitHub #

property label_type#: Each model predicts labels of a certain type.

classmethod load(model_path)View on GitHub #

Loads a Flair model from the given file or state dictionary.

Parameters:: model_path (Union[str, Path, dict[str, Any]]) – Either the path to the model (as string or Path variable) or the already loaded state dict.
Return type:: SpanClassifier
Returns:: The loaded Flair model.

class flair.models.LanguageModel(dictionary, is_forward_lm, hidden_size, nlayers, embedding_size=100, nout=None, document_delimiter='\\n', dropout=0.1, recurrent_type='LSTM', has_decoder=True)View on GitHub #

Bases: Module

Container module with an encoder, a recurrent module, and a decoder.

init_weights()View on GitHub #

set_hidden(hidden)View on GitHub #

forward(input, hidden, ordered_sequence_lengths=None, decode=True)View on GitHub #

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

init_hidden(bsz)View on GitHub #

get_representation(strings, start_marker, end_marker, chars_per_chunk=512)View on GitHub #

get_output(text)View on GitHub #

repackage_hidden(h)View on GitHub #: Wraps hidden states in new Variables, to detach them from their history.

static initialize(matrix)View on GitHub #

classmethod load_language_model(model_file, has_decoder=True)View on GitHub #

classmethod load_checkpoint(model_file)View on GitHub #

save_checkpoint(file, optimizer, epoch, split, loss)View on GitHub #

save(file)View on GitHub #

generate_text(prefix='\\n', number_of_characters=1000, temperature=1.0, break_on_suffix=None)View on GitHub #

Return type:: tuple[str, float]

calculate_perplexity(text)View on GitHub #

Return type:: float

class flair.models.Lemmatizer(embeddings=None, label_type='lemma', rnn_input_size=50, rnn_hidden_size=256, rnn_layers=2, encode_characters=True, char_dict='common-chars-lemmatizer', max_sequence_length_dependent_on_input=True, max_sequence_length=20, use_attention=True, beam_size=1, start_symbol_for_encoding=True, end_symbol_for_encoding=True, bidirectional_encoding=True)View on GitHub #

Bases: Classifier[Sentence]

property label_type#: Each model predicts labels of a certain type.

words_to_char_indices(tokens, end_symbol=True, start_symbol=False, padding_in_front=False, seq_length=None)View on GitHub #

For a given list of strings this function creates index vectors that represent the characters of the strings.

Each string is represented by sequence_length (maximum string length + entries for special symbol) many indices representing characters in self.char_dict. One can manually set the vector length with the parameter seq_length, though the vector length is always at least maximum string length in the list.

Parameters:

seq_length – the maximum sequence length to use, if None the maximum is taken..
tokens (list[str]) – the texts of the toekens to encode
end_symbol – add self.end_index at the end of each representation
start_symbol – add self.start_index in front of each representation
padding_in_front – whether to fill up with self.dummy_index in front or in back of strings

forward_pass(sentences)View on GitHub #

decode(decoder_input_indices, initial_hidden_states, all_encoder_outputs)View on GitHub #

forward(encoder_input_indices, lengths, token_embedding_hidden)View on GitHub #

Define the computation performed at every call.

Should be overridden by all subclasses. :rtype: tuple[Tensor, Optional[Tensor]]

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

encode(sentences)View on GitHub #

encode_token(token)View on GitHub #

forward_loss(sentences)View on GitHub #

Performs a forward pass and returns a loss tensor for backpropagation.

Implement this to enable training.

Return type:: tuple[Tensor, int]

predict(sentences, mini_batch_size=16, return_probabilities_for_all_classes=False, verbose=False, label_name='predicted', return_loss=False, embedding_storage_mode='none')View on GitHub #

Predict lemmas of words for a given (list of) sentence(s).

Parameters:

sentences (Union[list[Sentence], Sentence]) – sentences to predict
label_name – label name used for predicted lemmas
mini_batch_size (int) – number of tokens that are send through the RNN simultaneously, assuming batching_in_rnn is set to True
embedding_storage_mode – default is ‘none’ which is always best. Only set to ‘cpu’ or ‘gpu’ if you wish to not only predict, but also keep the generated embeddings in CPU or GPU memory respectively.
return_loss – whether to compute and return loss. Setting it to True only makes sense if labels are provided
verbose (bool) – If True, lemmatized sentences will be printed in the console.
return_probabilities_for_all_classes (bool) – unused parameter.

evaluate(*args, **kwargs)View on GitHub #

Evaluates the model. Returns a Result object containing evaluation results and a loss value.

Implement this to enable evaluation.

Parameters:

data_points – The labeled data_points to evaluate.
gold_label_type – The label type indicating the gold labels
out_path – Optional output path to store predictions.
embedding_storage_mode – One of ‘none’, ‘cpu’ or ‘gpu’. ‘none’ means all embeddings are deleted and freshly recomputed, ‘cpu’ means all embeddings are stored on CPU, or ‘gpu’ means all embeddings are stored on GPU
mini_batch_size – The batch_size to use for predictions.
main_evaluation_metric – Specify which metric to highlight as main_score.
exclude_labels – Specify classes that won’t be considered in evaluation.
gold_label_dictionary – Specify which classes should be considered, all other classes will be taken as <unk>.
return_loss – Weather to additionally compute the loss on the data-points.
**kwargs – Arguments that will be ignored.

Return type:

Result

Returns:

The evaluation results.

class flair.models.TextPairClassifier(embeddings, label_type, embed_separately=False, **classifierargs)View on GitHub #

Bases: DefaultClassifier[DataPair[Sentence, Sentence], DataPair[Sentence, Sentence]]

Text Pair Classification Model for tasks such as Recognizing Textual Entailment, build upon TextClassifier.

The model takes document embeddings and puts resulting text representation(s) into a linear layer to get the actual class label. We provide two ways to embed the DataPairs: Either by embedding both DataPoints and concatenating the resulting vectors (“embed_separately=True”) or by concatenating the DataPoints and embedding the resulting vector (“embed_separately=False”).

property label_type#: Each model predicts labels of a certain type.

get_used_tokens(corpus, context_length=0, respect_document_boundaries=True)View on GitHub #

Return type:: Iterable[list[str]]

class flair.models.TextTripleClassifier(embeddings, label_type, embed_separately=False, **classifierargs)View on GitHub #

Bases: DefaultClassifier[DataTriple[Sentence, Sentence, Sentence], DataTriple[Sentence, Sentence, Sentence]]

Text Triple Classification Model for tasks such as Query-Ad Matching, build upon TextPairClassifier.

The model takes document embeddings and puts resulting text representation(s) into a linear layer to get the actual class label. We provide two ways to embed the DataPairs: Either by embedding both DataPoints and concatenating the resulting vectors (“embed_separately=True”) or by concatenating the DataPoints and embedding the resulting vector (“embed_separately=False”).

property label_type#: Each model predicts labels of a certain type.

get_used_tokens(corpus, context_length=0, respect_document_boundaries=True)View on GitHub #

Return type:: Iterable[list[str]]

class flair.models.TextPairRegressor(embeddings, label_type, embed_separately=False, dropout=0.0, locked_dropout=0.0, word_dropout=0.0, decoder=None)View on GitHub #

Bases: Model[DataPair[Sentence, Sentence]], ReduceTransformerVocabMixin

Text Pair Regression Model for tasks such as Semantic Textual Similarity Benchmark.

The model takes document embeddings and puts resulting text representation(s) into a linear layer to get the score. We provide two ways to embed the DataPairs: Either by embedding both DataPoints and concatenating the resulting vectors (“embed_separately=True”) or by concatenating the DataPoints and embedding the resulting vector (“embed_separately=False”).

property label_type#: Each model predicts labels of a certain type.

get_used_tokens(corpus, context_length=0, respect_document_boundaries=True)View on GitHub #

Return type:: Iterable[list[str]]

forward_loss(pairs)View on GitHub #

Performs a forward pass and returns a loss tensor for backpropagation.

Implement this to enable training.

Return type:: tuple[Tensor, int]

predict(pairs, mini_batch_size=32, verbose=False, label_name=None, embedding_storage_mode='none')View on GitHub #

Return type:: list[DataPair[Sentence, Sentence]]

evaluate(data_points, gold_label_type, out_path=None, embedding_storage_mode='none', mini_batch_size=32, main_evaluation_metric=('correlation', 'pearson'), exclude_labels=None, gold_label_dictionary=None, return_loss=True, **kwargs)View on GitHub #

Evaluates the model. Returns a Result object containing evaluation results and a loss value.

Implement this to enable evaluation.

Parameters:

data_points (Union[list[DataPair[Sentence, Sentence]], Dataset]) – The labeled data_points to evaluate.
gold_label_type (str) – The label type indicating the gold labels
out_path (Union[str, Path, None]) – Optional output path to store predictions.
embedding_storage_mode (Literal['none', 'cpu', 'gpu']) – One of ‘none’, ‘cpu’ or ‘gpu’. ‘none’ means all embeddings are deleted and freshly recomputed, ‘cpu’ means all embeddings are stored on CPU, or ‘gpu’ means all embeddings are stored on GPU
mini_batch_size (int) – The batch_size to use for predictions.
main_evaluation_metric (tuple[str, str]) – Specify which metric to highlight as main_score.
exclude_labels (Optional[list[str]]) – Specify classes that won’t be considered in evaluation.
gold_label_dictionary (Optional[Dictionary]) – Specify which classes should be considered, all other classes will be taken as <unk>.
return_loss (bool) – Weather to additionally compute the loss on the data-points.
**kwargs – Arguments that will be ignored.

Return type:

Result

Returns:

The evaluation results.

class flair.models.RelationClassifier(embeddings, label_dictionary, label_type, entity_label_types, entity_pair_labels=None, entity_threshold=None, cross_augmentation=True, encoding_strategy=<flair.models.relation_classifier_model.TypedEntityMarker object>, zero_tag_value='O', allow_unk_tag=True, **classifierargs)View on GitHub #

Bases: DefaultClassifier[EncodedSentence, EncodedSentence]

Relation Classifier to predict the relation between two entities.

Task#

Relation Classification (RC) is the task of identifying the semantic relation between two entities in a text. In contrast to (end-to-end) Relation Extraction (RE), RC requires pre-labelled entities.

Example:#

For the founded_by relation from ORG (head) to PER (tail) and the sentence “Larry Page and Sergey Brin founded Google .”, we extract the relations - founded_by(head=’Google’, tail=’Larry Page’) and - founded_by(head=’Google’, tail=’Sergey Brin’).

Architecture#

The Relation Classifier Model builds upon a text classifier. The model generates an encoded sentence for each entity pair in the cross product of all entities in the original sentence. In the encoded representation, the entities in the current entity pair are masked/marked with control tokens. (For an example, see the docstrings of different encoding strategies, e.g. TypedEntityMarker.) Then, for each encoded sentence, the model takes its document embedding and puts the resulting text representation(s) through a linear layer to get the class relation label.

The implemented encoding strategies are taken from this paper by Zhou et al.: https://arxiv.org/abs/2102.01373

Warning

Currently, the model has no multi-label support.

transform_sentence(sentences)View on GitHub #

Transforms sentences into encoded sentences specific to the RelationClassifier.

For more information on the internal sentence transformation procedure, see the flair.models.RelationClassifier architecture and the different flair.models.relation_classifier_model.EncodingStrategy variants docstrings.

Parameters:: sentences (Union[Sentence, list[Sentence]]) – sentences to transform
Return type:: list[EncodedSentence]
Returns:: A list of encoded sentences specific to the RelationClassifier

transform_dataset(dataset)View on GitHub #

Transforms a dataset into a dataset containing encoded sentences specific to the RelationClassifier.

The returned dataset is stored in memory. For more information on the internal sentence transformation procedure, see the RelationClassifier architecture and the different EncodingStrategy variants docstrings.

Parameters:: dataset (Dataset[Sentence]) – A dataset of sentences to transform
Return type:: FlairDatapointDataset[EncodedSentence]

Returns: A dataset of encoded sentences specific to the RelationClassifier

transform_corpus(corpus)View on GitHub #

Transforms a corpus into a corpus containing encoded sentences specific to the RelationClassifier.

The splits of the returned corpus are stored in memory. For more information on the internal sentence transformation procedure, see the RelationClassifier architecture and the different EncodingStrategy variants docstrings.

Parameters:: corpus (Corpus[Sentence]) – A corpus of sentences to transform
Return type:: Corpus[EncodedSentence]

Returns: A corpus of encoded sentences specific to the RelationClassifier

predict(sentences, mini_batch_size=32, return_probabilities_for_all_classes=False, verbose=False, label_name=None, return_loss=False, embedding_storage_mode='none')View on GitHub #

Predicts the class labels for the given sentence(s).

Standard Sentence objects and EncodedSentences specific to the RelationClassifier are allowed as input. The (relation) labels are directly added to the sentences.

Parameters:

sentences (Union[list[Sentence], list[EncodedSentence], Sentence, EncodedSentence]) – A list of (encoded) sentences.
mini_batch_size (int) – The mini batch size to use
return_probabilities_for_all_classes (bool) – Return probabilities for all classes instead of only best predicted
verbose (bool) – Set to display a progress bar
return_loss (bool) – Set to return loss
label_name (Optional[str]) – Set to change the predicted label type name
embedding_storage_mode (Literal['none', 'cpu', 'gpu']) – The default is ‘none’, which is always best. Only set to ‘cpu’ or ‘gpu’ if you wish to predict and keep the generated embeddings in CPU or GPU memory, respectively.

Return type:

Optional[tuple[Tensor, int]]

Returns: The loss and the total number of classes, if return_loss is set

property label_type: str#: Each model predicts labels of a certain type.

property zero_tag_value: str#

property allow_unk_tag: bool#

get_used_tokens(corpus, context_length=0, respect_document_boundaries=True)View on GitHub #

Return type:: Iterable[list[str]]

classmethod load(model_path)View on GitHub #

Loads a Flair model from the given file or state dictionary.

Parameters:: model_path (Union[str, Path, dict[str, Any]]) – Either the path to the model (as string or Path variable) or the already loaded state dict.
Return type:: RelationClassifier
Returns:: The loaded Flair model.

class flair.models.RelationExtractor(embeddings, label_type, entity_label_type, entity_pair_filters=None, pooling_operation='first_last', train_on_gold_pairs_only=False, **classifierargs)View on GitHub #

Bases: DefaultClassifier[Sentence, Relation]

property label_type#: Each model predicts labels of a certain type.

classmethod load(model_path)View on GitHub #

Loads a Flair model from the given file or state dictionary.

Parameters:: model_path (Union[str, Path, dict[str, Any]]) – Either the path to the model (as string or Path variable) or the already loaded state dict.
Return type:: RelationExtractor
Returns:: The loaded Flair model.

class flair.models.RegexpTagger(mapping)View on GitHub #

Bases: object

property registered_labels#

register_labels(mapping)View on GitHub #

Register a regexp -> label mapping.

Parameters:: mapping (Union[list[tuple[str, str]], tuple[str, str]]) – A list of tuples or a single tuple representing a mapping as regexp -> label

remove_labels(labels)View on GitHub #

Remove a registered regexp -> label mapping given by label.

Parameters:: labels (Union[list[str], str]) – A list of labels or a single label as strings.

predict(sentences)View on GitHub #

Predict the given sentences according to the registered mappings.

Return type:: list[Sentence]

class flair.models.SequenceTagger(embeddings, tag_dictionary, tag_type, use_rnn=True, rnn=None, rnn_type='LSTM', tag_format='BIOES', hidden_size=256, rnn_layers=1, bidirectional=True, use_crf=True, reproject_embeddings=True, dropout=0.0, word_dropout=0.05, locked_dropout=0.5, train_initial_hidden_state=False, loss_weights=None, init_from_state_dict=False, allow_unk_predictions=False)View on GitHub #

Bases: Classifier[Sentence]

The SequenceTagger is one of two main architectures in Flair used for sequence tagging.

Sequence tagging means classifying words in a sentence, for instance for part-of-speech tagging or named entity recognition. The SequenceTagger implements the “classic” model based on the LSTM-CRF architecture: words are first embedded using one or multiple flair.embeddings.TokenEmbeddings, these embeddings are then passed to the LSTM. Its hidden states for each input word are used to make the final prediction with a softmax classifier. For decoding, the SequenceTagger by default uses a CRF approach.

Alternatively, you can use the class flair.models.TokenClassifier for sequence tagging without a LSTM-CRF.

property label_type#: Each model predicts labels of a certain type.

static RNN(rnn_type, rnn_layers, hidden_size, bidirectional, rnn_input_dim)View on GitHub #

Static wrapper function returning an RNN instance from PyTorch.

Parameters:

rnn_type (str) – Type of RNN from torch.nn
rnn_layers (int) – number of layers to include
hidden_size (int) – hidden size of RNN cell
bidirectional (bool) – If True, RNN cell is bidirectional
rnn_input_dim (int) – Input dimension to RNN cell

Return type:

RNN

forward_loss(sentences)View on GitHub #

Conducts a forward pass through the SequenceTagger using labeled sentences and return the loss.

Parameters:: sentences (list[Sentence]) – A batch of labeled sentences.
Return type:: tuple[Tensor, int]
Returns:: A tuple consisting of the loss tensor and the number of tokens in the batch.

forward(sentence_tensor, lengths)View on GitHub #

Forward pass through the SequenceTagger.

Parameters:

sentence_tensor (Tensor) – A tensor representing the batch of sentences.
lengths (LongTensor) – A IntTensor representing the lengths of the respective sentences.

predict(sentences, mini_batch_size=32, return_probabilities_for_all_classes=False, verbose=False, label_name=None, return_loss=False, embedding_storage_mode='none', force_token_predictions=False)View on GitHub #

Call this method to predict labels for sentences.

Predictions are directly added to the Sentence objects that are passed to this method. This means that the predict() method does not return predictions. Rather, predictions are stored at each sentence and can be retrieved by calling flair.data.Sentence.get_labels() on each flair.data.Sentence.

Parameters:

sentences (Union[list[Sentence], Sentence]) – List of sentences in batch
mini_batch_size (int) – batch size for test data
return_probabilities_for_all_classes (bool) – Whether to return probabilities for all classes
verbose (bool) – whether to use progress bar
label_name (Optional[str]) – which label to predict
return_loss – whether to return loss value
embedding_storage_mode – determines where to store embeddings - can be “gpu”, “cpu” or None.
force_token_predictions (bool) – add labels per token instead of span labels, even if self.predict_spans is True

push_to_hub(repo_id, token=None, private=None, commit_message='Add new SequenceTagger model.')View on GitHub #

Uploads the Sequence Tagger model to a Hugging Face Hub repository.

Parameters:

repo_id (str) – A namespace (user or an organization) and a repo name separated by a /.
token (Optional[str]) – An authentication token (See https://huggingface.co/settings/token).
private (Optional[bool]) – Whether the repository is private.
commit_message (str) – Message to commit while pushing.

Returns: The url of the repository.

classmethod load(model_path)View on GitHub #

Loads a Flair model from the given file or state dictionary.

Parameters:: model_path (Union[str, Path, dict[str, Any]]) – Either the path to the model (as string or Path variable) or the already loaded state dict.
Return type:: SequenceTagger
Returns:: The loaded Flair model.

class flair.models.PrefixedSequenceTagger(*args, augmentation_strategy, **kwargs)View on GitHub #

Bases: SequenceTagger

classmethod load(model_path)View on GitHub #

Loads a Flair model from the given file or state dictionary.

Parameters:: model_path (Union[str, Path, dict[str, Any]]) – Either the path to the model (as string or Path variable) or the already loaded state dict.
Return type:: PrefixedSequenceTagger
Returns:: The loaded Flair model.

forward_loss(sentences)View on GitHub #

Conducts a forward pass through the SequenceTagger using labeled sentences and return the loss.

Parameters:: sentences (Union[list[Sentence], list[PrefixedSentence]]) – A batch of labeled sentences.
Return type:: tuple[Tensor, int]
Returns:: A tuple consisting of the loss tensor and the number of tokens in the batch.

predict(sentences, mini_batch_size=32, return_probabilities_for_all_classes=False, verbose=False, label_name=None, return_loss=False, embedding_storage_mode='none', force_token_predictions=False)View on GitHub #

Call this method to predict labels for sentences.

Predictions are directly added to the Sentence objects that are passed to this method. This means that the predict() method does not return predictions. Rather, predictions are stored at each sentence and can be retrieved by calling flair.data.Sentence.get_labels() on each flair.data.Sentence.

Parameters:

sentences (Union[list[Sentence], Sentence, list[PrefixedSentence], PrefixedSentence]) – List of sentences in batch
mini_batch_size (int) – batch size for test data
return_probabilities_for_all_classes (bool) – Whether to return probabilities for all classes
verbose (bool) – whether to use progress bar
label_name (Optional[str]) – which label to predict
return_loss – whether to return loss value
embedding_storage_mode – determines where to store embeddings - can be “gpu”, “cpu” or None.
force_token_predictions (bool) – add labels per token instead of span labels, even if self.predict_spans is True

augment_sentences(sentences, annotation_layers=None)View on GitHub #

Return type:: list[PrefixedSentence]

class flair.models.TokenClassifier(embeddings, label_dictionary, label_type, span_encoding='BIOES', **classifierargs)View on GitHub #

Bases: DefaultClassifier[Sentence, Token]

This is a simple class of models that tags individual words in text.

property label_type#: Each model predicts labels of a certain type.

classmethod load(model_path)View on GitHub #

Loads a Flair model from the given file or state dictionary.

Parameters:: model_path (Union[str, Path, dict[str, Any]]) – Either the path to the model (as string or Path variable) or the already loaded state dict.
Return type:: TokenClassifier
Returns:: The loaded Flair model.

class flair.models.WordTagger(embeddings, label_dictionary, label_type, span_encoding='BIOES', **classifierargs)View on GitHub #: Bases: TokenClassifier

Deprecated since version 0.12.2: The WordTagger was renamed to flair.models.TokenClassifier.

class flair.models.FewshotClassifierView on GitHub #

Bases: Classifier[Sentence], ABC

forward_loss(data_points)View on GitHub #

Performs a forward pass and returns a loss tensor for backpropagation.

Implement this to enable training.

Return type:: tuple[Tensor, int]

property tars_embeddings#

train(mode=True)View on GitHub #

Populate label similarity map based on cosine similarity before running epoch.

If the num_negative_labels_to_sample is set to an integer value then before starting each epoch the model would create a similarity measure between the label names based on cosine distances between their BERT encoded embeddings.

get_current_label_dictionary()View on GitHub #

get_current_label_type()View on GitHub #

is_current_task_multi_label()View on GitHub #

add_and_switch_to_new_task(task_name, label_dictionary, label_type, multi_label=True, force_switch=False)View on GitHub #

Adds a new task to an existing TARS model.

Sets necessary attributes and finally ‘switches’ to the new task. Parameters are similar to the constructor except for model choice, batch size and negative sampling. This method does not store the resultant model onto disk.

Parameters:

task_name (str) – a string depicting the name of the task
label_dictionary (Union[list, set, Dictionary, str]) – dictionary of the labels you want to predict
label_type (str) – string to identify the label type (‘ner’, ‘sentiment’, etc.)
multi_label (bool) – whether this task is a multi-label prediction problem
force_switch (bool) – if True, will overwrite existing task with same name

list_existing_tasks()View on GitHub #

Lists existing tasks in the loaded TARS model on the console.

Return type:: set[str]

switch_to_task(task_name)View on GitHub #: Switches to a task which was previously added.

property label_type#: Each model predicts labels of a certain type.

predict_zero_shot(sentences, candidate_label_set, multi_label=True)View on GitHub #

Make zero shot predictions from the TARS model.

Parameters:

sentences (Union[list[Sentence], Sentence]) – input sentence objects to classify
candidate_label_set (Union[list[str], set[str], str]) – set of candidate labels
multi_label (bool) – indicates whether multi-label or single class prediction. Defaults to True.

get_used_tokens(corpus, context_length=0, respect_document_boundaries=True)View on GitHub #

Return type:: Iterable[list[str]]

classmethod load(model_path)View on GitHub #

Loads a Flair model from the given file or state dictionary.

Parameters:: model_path (Union[str, Path, dict[str, Any]]) – Either the path to the model (as string or Path variable) or the already loaded state dict.
Return type:: FewshotClassifier
Returns:: The loaded Flair model.

class flair.models.TARSClassifier(task_name=None, label_dictionary=None, label_type=None, embeddings='bert-base-uncased', num_negative_labels_to_sample=2, prefix=True, **tagger_args)View on GitHub #

Bases: FewshotClassifier

TARS model for text classification.

In the backend, the model uses a BERT based binary text classifier which given a <label, text> pair predicts the probability of two classes “True”, and “False”. The input data is a usual Sentence object which is inflated by the model internally before pushing it through the transformer stack of BERT.

static_label_type = 'tars_label'#

LABEL_MATCH = 'YES'#

LABEL_NO_MATCH = 'NO'#

property tars_embeddings#

predict(sentences, mini_batch_size=32, return_probabilities_for_all_classes=False, verbose=False, label_name=None, return_loss=False, embedding_storage_mode='none', label_threshold=0.5, multi_label=None, force_label=False)View on GitHub #

Predict sentences on the Text Classification task.

Parameters:

return_probabilities_for_all_classes (bool) – if True, all classes will be added with their respective confidences.
sentences (Union[list[Sentence], Sentence]) – a Sentence or a List of Sentence
force_label (bool) – when multilabel is active, you can force to always get at least one prediction.
multi_label (Optional[bool]) – if True multiple labels can be predicted. Defaults to the setting of the configured task.
label_threshold (float) – when multi_label, specify the threshold when a class is considered as predicted.
mini_batch_size – size of the minibatch, usually bigger is more rapid but consume more memory, up to a point when it has no more effect.
all_tag_prob – True to compute the score for each tag on each token, otherwise only the score of the best tag is returned
verbose (bool) – set to True to display a progress bar
return_loss – set to True to also compute the loss
label_name (Optional[str]) – set this to change the name of the label type that is predicted
embedding_storage_mode – default is ‘none’ which doesn’t store the embeddings in RAM. Only set to ‘cpu’ or ‘gpu’ if you wish to not only predict, but also keep the generated embeddings in CPU or GPU memory respectively. ‘gpu’ to store embeddings in GPU memory.

classmethod load(model_path)View on GitHub #

Loads a Flair model from the given file or state dictionary.

Parameters:: model_path (Union[str, Path, dict[str, Any]]) – Either the path to the model (as string or Path variable) or the already loaded state dict.
Return type:: TARSClassifier
Returns:: The loaded Flair model.

class flair.models.TARSTagger(task_name=None, label_dictionary=None, label_type=None, embeddings='bert-base-uncased', num_negative_labels_to_sample=2, prefix=True, **tagger_args)View on GitHub #

Bases: FewshotClassifier

TARS model for sequence tagging.

In the backend, the model uses a BERT based 5-class sequence labeler which given a <label, text> pair predicts the probability for each word to belong to one of the BIOES classes. The input data is a usual Sentence object which is inflated by the model internally before pushing it through the transformer stack of BERT.

static_label_type = 'tars_label'#

property tars_embeddings#

predict(sentences, mini_batch_size=32, return_probabilities_for_all_classes=False, verbose=False, label_name=None, return_loss=False, embedding_storage_mode='none', most_probable_first=True)View on GitHub #

Predict sequence tags for Named Entity Recognition task.

Parameters:

sentences (Union[list[Sentence], Sentence]) – a Sentence or a List of Sentence
mini_batch_size – size of the minibatch, usually bigger is more rapid but consume more memory, up to a point when it has no more effect.
all_tag_prob – True to compute the score for each tag on each token, otherwise only the score of the best tag is returned
verbose (bool) – set to True to display a progress bar
return_loss – set to True to also compute the loss
label_name (Optional[str]) – set this to change the name of the label type that is predicted
embedding_storage_mode – default is ‘none’ which doesn’t store the embeddings in RAM. Only set to ‘cpu’ or ‘gpu’ if you wish to not only predict, but also keep the generated embeddings in CPU or GPU memory respectively. ‘gpu’ to store embeddings in GPU memory.
return_probabilities_for_all_classes (bool) – if True, all classes will be added with their respective confidences.
most_probable_first (bool) – if True, nested predictions will be removed, if False all predictions will be returned, including overlaps

classmethod load(model_path)View on GitHub #

Loads a Flair model from the given file or state dictionary.

Parameters:: model_path (Union[str, Path, dict[str, Any]]) – Either the path to the model (as string or Path variable) or the already loaded state dict.
Return type:: TARSTagger
Returns:: The loaded Flair model.

class flair.models.TextClassifier(embeddings, label_type, **classifierargs)View on GitHub #

Bases: DefaultClassifier[Sentence, Sentence]

Text Classification Model.

The model takes word embeddings, puts them into an RNN to obtain a text representation, and puts the text representation in the end into a linear layer to get the actual class label. The model can handle single and multi class data sets.

property label_type#: Each model predicts labels of a certain type.

classmethod load(model_path)View on GitHub #

Loads a Flair model from the given file or state dictionary.

Parameters:: model_path (Union[str, Path, dict[str, Any]]) – Either the path to the model (as string or Path variable) or the already loaded state dict.
Return type:: TextClassifier
Returns:: The loaded Flair model.

class flair.models.TextRegressor(document_embeddings, label_name='label')View on GitHub #

Bases: Model[Sentence], ReduceTransformerVocabMixin

property label_type#: Each model predicts labels of a certain type.

forward(*args)View on GitHub #

Define the computation performed at every call.

Should be overridden by all subclasses. :rtype: Tensor

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

forward_loss(sentences)View on GitHub #

Performs a forward pass and returns a loss tensor for backpropagation.

Implement this to enable training.

Return type:: tuple[Tensor, int]

predict(sentences, mini_batch_size=32, verbose=False, label_name=None, embedding_storage_mode='none')View on GitHub #

Return type:: list[Sentence]

forward_labels_and_loss(sentences)View on GitHub #

Return type:: tuple[Tensor, Tensor]

evaluate(data_points, gold_label_type, out_path=None, embedding_storage_mode='none', mini_batch_size=32, main_evaluation_metric=('micro avg', 'f1-score'), exclude_labels=None, gold_label_dictionary=None, return_loss=True, **kwargs)View on GitHub #

Evaluates the model. Returns a Result object containing evaluation results and a loss value.

Implement this to enable evaluation.

Parameters:

data_points (Union[list[Sentence], Dataset]) – The labeled data_points to evaluate.
gold_label_type (str) – The label type indicating the gold labels
out_path (Union[str, Path, None]) – Optional output path to store predictions.
embedding_storage_mode (Literal['none', 'cpu', 'gpu']) – One of ‘none’, ‘cpu’ or ‘gpu’. ‘none’ means all embeddings are deleted and freshly recomputed, ‘cpu’ means all embeddings are stored on CPU, or ‘gpu’ means all embeddings are stored on GPU
mini_batch_size (int) – The batch_size to use for predictions.
main_evaluation_metric (tuple[str, str]) – Specify which metric to highlight as main_score.
exclude_labels (Optional[list[str]]) – Specify classes that won’t be considered in evaluation.
gold_label_dictionary (Optional[Dictionary]) – Specify which classes should be considered, all other classes will be taken as <unk>.
return_loss (bool) – Weather to additionally compute the loss on the data-points.
**kwargs – Arguments that will be ignored.

Return type:

Result

Returns:

The evaluation results.

classmethod load(model_path)View on GitHub #

Loads a Flair model from the given file or state dictionary.

Parameters:: model_path (Union[str, Path, dict[str, Any]]) – Either the path to the model (as string or Path variable) or the already loaded state dict.
Return type:: TextRegressor
Returns:: The loaded Flair model.

get_used_tokens(corpus, context_length=0, respect_document_boundaries=True)View on GitHub #

Return type:: Iterable[list[str]]

class flair.models.MultitaskModel(models, task_ids=None, loss_factors=None, use_all_tasks=False)View on GitHub #

Bases: Classifier

Multitask Model class which acts as wrapper for creating custom multitask models.

Takes different tasks as input, parameter sharing is done by objects in flair, i.e. creating a Embedding Layer and passing it to two different Models, will result in a hard parameter-shared embedding layer. The abstract class takes care of calling the correct forward propagation and loss function of the respective model.

forward(*args)View on GitHub #

Define the computation performed at every call.

Should be overridden by all subclasses. :rtype: Tensor

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

forward_loss(sentences)View on GitHub #

Calls the respective forward loss of each model and sums them weighted by their loss factors.

Parameters:: sentences (Union[list[Sentence], Sentence]) – batch of sentences
Return type:: tuple[Tensor, int]

Returns: loss and sample count

predict(sentences, **predictargs)View on GitHub #

Uses the model to predict labels for a given set of data points.

The method does not directly return the predicted labels. Rather, labels are added as flair.data.Label objects to the respective data points. You can then access these predictions by calling flair.data.DataPoint.get_labels() on each data point that you passed through this method.

Parameters:

sentences – The data points for which the model should predict labels, most commonly Sentence objects.
mini_batch_size – The mini batch size to use. Setting this value higher typically makes predictions faster, but also costs more memory.
return_probabilities_for_all_classes – If set to True, the model will store probabilities for all classes instead of only the predicted class.
verbose – If set to True, will display a progress bar while predicting. By default, this parameter is set to False.
return_loss – Set this to True to return loss (only possible if gold labels are set for the sentences).
label_name – Optional parameter that if set, changes the identifier of the label type that is predicted. # noqa: E501
embedding_storage_mode – Default is ‘none’ which is always best. Only set to ‘cpu’ or ‘gpu’ if you wish to not only predict, but also keep the generated embeddings in CPU or GPU memory respectively. ‘gpu’ to store embeddings in GPU memory. # noqa: E501

static split_batch_to_task_ids(sentences, all_tasks=False)View on GitHub #

Splits a batch of sentences to its respective model.

If single sentence is assigned to several tasks (i.e. same corpus but different tasks), then the model assignment for this batch is randomly chosen.

Parameters:

sentences (Union[list[Sentence], Sentence]) – batch of sentences
all_tasks (bool) – use all tasks of each sentence. If deactivated, a random task will be sampled

Return type:

dict[str, list[int]]

Returns: Key-value pairs as (task_id, list of sentences ids in batch)

evaluate(data_points, gold_label_type, out_path=None, main_evaluation_metric=('micro avg', 'f1-score'), evaluate_all=True, **evalargs)View on GitHub #

Evaluates the model. Returns a Result object containing evaluation results and a loss value.

Parameters:

data_points – batch of sentences
gold_label_type (str) – if evaluate_all is False, specify the task to evaluate by the task_id.
out_path (Union[str, Path, None]) – if not None, predictions will be created and saved at the respective file.
main_evaluation_metric (tuple[str, str]) – Specify which metric to highlight as main_score
evaluate_all (bool) – choose if all tasks should be evaluated, or a single one, depending on gold_label_type
**evalargs – arguments propagated to flair.nn.Model.evaluate()

Return type:

Result

Returns: Tuple of Result object and loss value (float)

get_used_tokens(corpus, context_length=0, respect_document_boundaries=True)View on GitHub #

Return type:: Iterable[list[str]]

property label_type#: Each model predicts labels of a certain type.

classmethod load(model_path)View on GitHub #

Loads a Flair model from the given file or state dictionary.

Parameters:: model_path (Union[str, Path, dict[str, Any]]) – Either the path to the model (as string or Path variable) or the already loaded state dict.
Return type:: MultitaskModel
Returns:: The loaded Flair model.

Table of Contents

flair.models#

Task#

Example:#

Architecture#