question_answering

mindnlp.transformers.pipelines.question_answering.QuestionAnsweringPipeline

Bases: ChunkPipeline

Question Answering pipeline using any ModelForQuestionAnswering. See the question answering examples for more information.

Learn more about the basics of using a pipeline in the pipeline tutorial

This question answering pipeline can currently be loaded from [pipeline] using the following task identifier: "question-answering".

The models that this pipeline can use are models that have been fine-tuned on a question answering task. See the up-to-date list of available models on hf-mirror.com/models.

Source code in mindnlp/transformers/pipelines/question_answering.py

class QuestionAnsweringPipeline(ChunkPipeline):
    """
    Question Answering pipeline using any `ModelForQuestionAnswering`. See the [question answering
    examples](../task_summary#question-answering) for more information.

    Learn more about the basics of using a pipeline in the [pipeline tutorial](../pipeline_tutorial)

    This question answering pipeline can currently be loaded from [`pipeline`] using the following task identifier:
    `"question-answering"`.

    The models that this pipeline can use are models that have been fine-tuned on a question answering task. See the
    up-to-date list of available models on
    [hf-mirror.com/models](https://hf-mirror.com/models?filter=question-answering).
    """
    default_input_names = "question,context"
    handle_impossible_answer = False

    def __init__(
            self,
            model: "PreTrainedModel",
            tokenizer: PreTrainedTokenizer,
            modelcard: Optional['ModelCard'] = None,
            framework: Optional[str] = None,
            task: str = "",
            **kwargs,
    ):
        """
        Initializes a QuestionAnsweringPipeline object.

        Args:
            self (QuestionAnsweringPipeline): The QuestionAnsweringPipeline instance.
            model (PreTrainedModel): The pre-trained model to be used for question answering.
            tokenizer (PreTrainedTokenizer): The tokenizer associated with the pre-trained model.
            modelcard (Optional[ModelCard], optional): The model card providing details about the model. Defaults to None.
            framework (Optional[str], optional): The framework used for the model. Defaults to None.
            task (str): The specific task to be performed by the pipeline.
            **kwargs: Additional keyword arguments.

        Returns:
            None.

        Raises:
            None.
        """
        super().__init__(
            model=model,
            tokenizer=tokenizer,
            modelcard=modelcard,
            framework=framework,
            task=task,
            **kwargs,
        )

        self._args_parser = QuestionAnsweringArgumentHandler()

    @staticmethod
    def create_sample(
            question: Union[str, List[str]], context: Union[str, List[str]]
    ) -> Union[SquadExample, List[SquadExample]]:
        """
        QuestionAnsweringPipeline leverages the [`SquadExample`] internally. This helper method encapsulate all the
        logic for converting question(s) and context(s) to [`SquadExample`].

        We currently support extractive question answering.

        Arguments:
            question (`str` or `List[str]`): The question(s) asked.
            context (`str` or `List[str]`): The context(s) in which we will look for the answer.

        Returns:
            One or a list of [`SquadExample`]: The corresponding [`SquadExample`] grouping question and context.
        """
        if isinstance(question, list):
            return [SquadExample(None, q, c, None, None, None) for q, c in zip(question, context)]
        else:
            return SquadExample(None, question, context, None, None, None)

    def _sanitize_parameters(
            self,
            padding=None,
            topk=None,
            top_k=None,
            doc_stride=None,
            max_answer_len=None,
            max_seq_len=None,
            max_question_len=None,
            handle_impossible_answer=None,
            align_to_words=None,
            **kwargs,
    ):
        """
        Sanitizes the parameters for the QuestionAnsweringPipeline class.

        Args:
            self (QuestionAnsweringPipeline): An instance of the QuestionAnsweringPipeline class.
            padding (str, optional): The padding method to be used. Defaults to None.
            topk (int, optional): [DEPRECATED] The number of top answers to consider. Use top_k instead.
                Defaults to None.
            top_k (int, optional): The number of top answers to consider. Defaults to None.
            doc_stride (int, optional): The stride between chunks when splitting a long document into chunks.
                Defaults to None.
            max_answer_len (int, optional): The maximum length of the generated answer. Defaults to None.
            max_seq_len (int, optional): The maximum sequence length. Defaults to None.
            max_question_len (int, optional): The maximum length of the question. Defaults to None.
            handle_impossible_answer (bool, optional): Whether to handle impossible answers. Defaults to None.
            align_to_words (bool, optional): Whether to align the answer to whole words. Defaults to None.

        Returns:
            tuple: A tuple containing the preprocessed parameters, an empty dictionary, and the postprocessed parameters.

        Raises:
            ValueError: If top_k or max_answer_len is less than 1.
            UserWarning: If topk parameter is used instead of top_k, a warning is raised.
        """
        # Set defaults values
        preprocess_params = {}
        if padding is not None:
            preprocess_params["padding"] = padding
        if doc_stride is not None:
            preprocess_params["doc_stride"] = doc_stride
        if max_question_len is not None:
            preprocess_params["max_question_len"] = max_question_len
        if max_seq_len is not None:
            preprocess_params["max_seq_len"] = max_seq_len

        postprocess_params = {}
        if topk is not None and top_k is None:
            warnings.warn("topk parameter is deprecated, use top_k instead", UserWarning)
            top_k = topk
        if top_k is not None:
            if top_k < 1:
                raise ValueError(f"top_k parameter should be >= 1 (got {top_k})")
            postprocess_params["top_k"] = top_k
        if max_answer_len is not None:
            if max_answer_len < 1:
                raise ValueError(f"max_answer_len parameter should be >= 1 (got {max_answer_len}")
        if max_answer_len is not None:
            postprocess_params["max_answer_len"] = max_answer_len
        if handle_impossible_answer is not None:
            postprocess_params["handle_impossible_answer"] = handle_impossible_answer
        if align_to_words is not None:
            postprocess_params["align_to_words"] = align_to_words
        return preprocess_params, {}, postprocess_params

    def __call__(self, *args, **kwargs):
        """
        Answer the question(s) given as inputs by using the context(s).

        Args:
            args ([`SquadExample`] or a list of [`SquadExample`]):
                One or several [`SquadExample`] containing the question and context.
            X ([`SquadExample`] or a list of [`SquadExample`], *optional*):
                One or several [`SquadExample`] containing the question and context (will be treated the same way as if
                passed as the first positional argument).
            data ([`SquadExample`] or a list of [`SquadExample`], *optional*):
                One or several [`SquadExample`] containing the question and context (will be treated the same way as if
                passed as the first positional argument).
            question (`str` or `List[str]`):
                One or several question(s) (must be used in conjunction with the `context` argument).
            context (`str` or `List[str]`):
                One or several context(s) associated with the question(s) (must be used in conjunction with the
                `question` argument).
            topk (`int`, *optional*, defaults to 1):
                The number of answers to return (will be chosen by order of likelihood). Note that we return less than
                topk answers if there are not enough options available within the context.
            doc_stride (`int`, *optional*, defaults to 128):
                If the context is too long to fit with the question for the model, it will be split in several chunks
                with some overlap. This argument controls the size of that overlap.
            max_answer_len (`int`, *optional*, defaults to 15):
                The maximum length of predicted answers (e.g., only answers with a shorter length are considered).
            max_seq_len (`int`, *optional*, defaults to 384):
                The maximum length of the total sentence (context + question) in tokens of each chunk passed to the
                model. The context will be split in several chunks (using `doc_stride` as overlap) if needed.
            max_question_len (`int`, *optional*, defaults to 64):
                The maximum length of the question after tokenization. It will be truncated if needed.
            handle_impossible_answer (`bool`, *optional*, defaults to `False`):
                Whether or not we accept impossible as an answer.
            align_to_words (`bool`, *optional*, defaults to `True`):
                Attempts to align the answer to real words. Improves quality on space separated langages. Might hurt on
                non-space-separated languages (like Japanese or Chinese)

        Returns:
            A `dict` or a list of `dict`:
                Each result comes as a dictionary with the following keys:

                - **score** (`float`) -- The probability associated to the answer.
                - **start** (`int`) -- The character start index of the answer (in the tokenized version of the input).
                - **end** (`int`) -- The character end index of the answer (in the tokenized version of the input).
                - **answer** (`str`) -- The answer to the question.
        """
        # Convert inputs to features

        examples = self._args_parser(*args, **kwargs)
        if isinstance(examples, (list, tuple)) and len(examples) == 1:
            return super().__call__(examples[0], **kwargs)
        return super().__call__(examples, **kwargs)

    def preprocess(self, example, padding="do_not_pad", doc_stride=None, max_question_len=64, max_seq_len=None):
        '''
        The preprocess method performs preprocessing for a Question Answering task and yields processed features.

        Args:
            self (object): The instance of the QuestionAnsweringPipeline class.
            example (dict or SquadExample): The input example for the Question Answering task.
                This can be provided as a dictionary with keys: 'question' and 'context', or as a SquadExample object.
            padding (str): Determines the padding strategy.
                It can take the values 'do_not_pad' or other padding strategies supported by the tokenizer.
            doc_stride (int): The maximum distance between chunks of input context when splitting long contexts for processing.
                If not provided, it defaults to half of the max_seq_len or 128, whichever is smaller.
            max_question_len (int): The maximum length allowed for the input question.
                If the input question exceeds this length, it will be truncated.
            max_seq_len (int): The maximum length allowed for the input sequence.
                If not provided, it defaults to the minimum of the maximum length supported by the tokenizer and 384.

        Returns:
            None: This method yields processed features and does not return any value directly.

        Raises:
            ValueError: If the provided doc_stride is larger than max_seq_len.
        '''
        if isinstance(example, dict):
            example = SquadExample(None, example["question"], example["context"], None, None, None)

        if max_seq_len is None:
            max_seq_len = min(self.tokenizer.model_max_length, 384)
        if doc_stride is None:
            doc_stride = min(max_seq_len // 2, 128)

        if doc_stride > max_seq_len:
            raise ValueError(f"`doc_stride` ({doc_stride}) is larger than `max_seq_len` ({max_seq_len})")

        if not self.tokenizer.is_fast:
            features = squad_convert_examples_to_features(
                examples=[example],
                tokenizer=self.tokenizer,
                max_seq_length=max_seq_len,
                doc_stride=doc_stride,
                max_query_length=max_question_len,
                padding_strategy=PaddingStrategy.MAX_LENGTH,
                is_training=False,
                tqdm_enabled=False,
            )
        else:
            # Define the side we want to truncate / pad and the text/pair sorting
            question_first = self.tokenizer.padding_side == "right"

            encoded_inputs = self.tokenizer(
                text=example.question_text if question_first else example.context_text,
                text_pair=example.context_text if question_first else example.question_text,
                padding=padding,
                truncation="only_second" if question_first else "only_first",
                max_length=max_seq_len,
                stride=doc_stride,
                return_token_type_ids=True,
                return_overflowing_tokens=True,
                return_offsets_mapping=True,
                return_special_tokens_mask=True,
            )
            # When the input is too long, it's converted in a batch of inputs with overflowing tokens
            # and a stride of overlap between the inputs. If a batch of inputs is given, a special output
            # "overflow_to_sample_mapping" indicate which member of the encoded batch belong to which original batch sample.
            # Here we tokenize examples one-by-one so we don't need to use "overflow_to_sample_mapping".
            # "num_span" is the number of output samples generated from the overflowing tokens.
            num_spans = len(encoded_inputs["input_ids"])

            # p_mask: mask with 1 for token than cannot be in the answer (0 for token which can be in an answer)
            # We put 0 on the tokens from the context and 1 everywhere else (question and special tokens)
            p_mask = [
                [tok != 1 if question_first else 0 for tok in encoded_inputs.sequence_ids(span_id)]
                for span_id in range(num_spans)
            ]

            features = []
            for span_idx in range(num_spans):
                input_ids_span_idx = encoded_inputs["input_ids"][span_idx]
                attention_mask_span_idx = (
                    encoded_inputs["attention_mask"][span_idx] if "attention_mask" in encoded_inputs else None
                )
                token_type_ids_span_idx = (
                    encoded_inputs["token_type_ids"][span_idx] if "token_type_ids" in encoded_inputs else None
                )
                # keep the cls_token unmasked (some models use it to indicate unanswerable questions)
                if self.tokenizer.cls_token_id is not None:
                    cls_indices = np.nonzero(np.array(input_ids_span_idx) == self.tokenizer.cls_token_id)[0]
                    for cls_index in cls_indices:
                        p_mask[span_idx][cls_index] = 0
                submask = p_mask[span_idx]
                features.append(
                    SquadFeatures(
                        input_ids=input_ids_span_idx,
                        attention_mask=attention_mask_span_idx,
                        token_type_ids=token_type_ids_span_idx,
                        p_mask=submask,
                        encoding=encoded_inputs[span_idx],
                        # We don't use the rest of the values - and actually
                        # for Fast tokenizer we could totally avoid using SquadFeatures and SquadExample
                        cls_index=None,
                        token_to_orig_map={},
                        example_index=0,
                        unique_id=0,
                        paragraph_len=0,
                        token_is_max_context=0,
                        tokens=[],
                        start_position=0,
                        end_position=0,
                        is_impossible=False,
                        qas_id=None,
                    )
                )

        for i, feature in enumerate(features):
            fw_args = {}
            others = {}
            model_input_names = self.tokenizer.model_input_names + ["p_mask", "token_type_ids"]

            for k, v in feature.__dict__.items():
                if k in model_input_names:
                    tensor = mindspore.tensor(v)
                    if tensor.dtype == mindspore.int32:
                        tensor = tensor.long()
                    fw_args[k] = tensor.unsqueeze(0)
                else:
                    others[k] = v

            is_last = i == len(features) - 1
            yield {"example": example, "is_last": is_last, **fw_args, **others}

    def _forward(self, inputs):
        """
        Forward method for the QuestionAnsweringPipeline class.

        This method processes the input data and performs the forward pass through the model to
        generate predictions for question answering.

        Args:
            self (QuestionAnsweringPipeline): An instance of the QuestionAnsweringPipeline class.
            inputs (dict): A dictionary containing the input data for the model.

        Returns:
            None

        Raises:
            None
        """
        example = inputs["example"]
        model_inputs = {k: inputs[k] for k in self.tokenizer.model_input_names}
        output = self.model(**model_inputs)
        if isinstance(output, dict):
            return {"start": output["start_logits"], "end": output["end_logits"], "example": example, **inputs}
        else:
            start, end = output[:2]
            return {"start": start, "end": end, "example": example, **inputs}

    def postprocess(
            self,
            model_outputs,
            top_k=1,
            handle_impossible_answer=False,
            max_answer_len=15,
            align_to_words=True,
    ):
        """
        This method postprocess is a part of the class QuestionAnsweringPipeline.

        Args:
            self: Represents the instance of the class.
            model_outputs: A list of dictionaries representing the output from the model.
                Each dictionary contains keys 'start', 'end', 'example', 'p_mask', and 'attention_mask'.
            top_k: An integer specifying the maximum number of top answers to consider. Defaults to 1.
            handle_impossible_answer: A boolean indicating whether to handle impossible answer scenarios.
            max_answer_len: An integer defining the maximum length of the answer.
            align_to_words: A boolean flag indicating whether to align answers to words.

        Returns:
            This method does not return a value directly.
                If successful, it updates the answers list based on the processing logic.

        Raises:
            None.
        """
        min_null_score = 1000000  # large and positive
        answers = []
        for output in model_outputs:
            start_ = output["start"]
            end_ = output["end"]
            example = output["example"]
            p_mask = output["p_mask"]
            attention_mask = (
                output["attention_mask"].numpy() if output.get("attention_mask", None) is not None else None
            )

            starts, ends, scores, min_null_score = select_starts_ends(
                start_, end_, p_mask, attention_mask, min_null_score, top_k, handle_impossible_answer, max_answer_len
            )

            if not self.tokenizer.is_fast:
                char_to_word = np.array(example.char_to_word_offset)

                # Convert the answer (tokens) back to the original text
                # Score: score from the model
                # Start: Index of the first character of the answer in the context string
                # End: Index of the character following the last character of the answer in the context string
                # Answer: Plain text of the answer
                for s, e, score in zip(starts, ends, scores):
                    token_to_orig_map = output["token_to_orig_map"]
                    answers.append(
                        {
                            "score": score.item(),
                            "start": np.where(char_to_word == token_to_orig_map[s])[0][0].item(),
                            "end": np.where(char_to_word == token_to_orig_map[e])[0][-1].item(),
                            "answer": " ".join(example.doc_tokens[token_to_orig_map[s]: token_to_orig_map[e] + 1]),
                        }
                    )
            else:
                # Convert the answer (tokens) back to the original text
                # Score: score from the model
                # Start: Index of the first character of the answer in the context string
                # End: Index of the character following the last character of the answer in the context string
                # Answer: Plain text of the answer
                question_first = bool(self.tokenizer.padding_side == "right")
                enc = output["encoding"]

                # Encoding was *not* padded, input_ids *might*.
                # It doesn't make a difference unless we're padding on
                # the left hand side, since now we have different offsets
                # everywhere.
                if self.tokenizer.padding_side == "left":
                    offset = (output["input_ids"] == self.tokenizer.pad_token_id).numpy().sum()
                else:
                    offset = 0

                # Sometimes the max probability token is in the middle of a word so:
                # - we start by finding the right word containing the token with `token_to_word`
                # - then we convert this word in a character span with `word_to_chars`
                sequence_index = 1 if question_first else 0
                for s, e, score in zip(starts, ends, scores):
                    s = s - offset
                    e = e - offset

                    start_index, end_index = self.get_indices(enc, s, e, sequence_index, align_to_words)

                    answers.append(
                        {
                            "score": score.item(),
                            "start": start_index,
                            "end": end_index,
                            "answer": example.context_text[start_index:end_index],
                        }
                    )

        if handle_impossible_answer:
            answers.append({"score": min_null_score, "start": 0, "end": 0, "answer": ""})
        answers = sorted(answers, key=lambda x: x["score"], reverse=True)[:top_k]
        if len(answers) == 1:
            return answers[0]
        return answers

    def get_indices(
            self, enc: "tokenizers.Encoding", s: int, e: int, sequence_index: int, align_to_words: bool
    ) -> Tuple[int, int]:
        """
        This method retrieves the start and end character indices corresponding to the specified token indices
        within a given sequence.

        Args:
            self: The instance of the QuestionAnsweringPipeline class.
            enc (tokenizers.Encoding): An instance of the tokenizers.Encoding class containing the encoded tokens.
            s (int): The start token index within the encoded sequence.
            e (int): The end token index within the encoded sequence.
            sequence_index (int): The index of the sequence within the encoding to consider.
            align_to_words (bool): A flag indicating whether to align the indices to words within the encoding.

        Returns:
            Tuple[int, int]: A tuple containing the start and end character indices within the specified sequence.

        Raises:
            Exception: If an error occurs during the process of retrieving the character indices, an Exception is raised.
                This may occur if the token-to-word or word-to-chars mappings are not available or encounter an
                unexpected issue.
        """
        if align_to_words:
            try:
                start_word = enc.token_to_word(s)
                end_word = enc.token_to_word(e)
                start_index = enc.word_to_chars(start_word, sequence_index=sequence_index)[0]
                end_index = enc.word_to_chars(end_word, sequence_index=sequence_index)[1]
            except Exception:
                # Some tokenizers don't really handle words. Keep to offsets then.
                start_index = enc.offsets[s][0]
                end_index = enc.offsets[e][1]
        else:
            start_index = enc.offsets[s][0]
            end_index = enc.offsets[e][1]
        return start_index, end_index

    def span_to_answer(self, text: str, start: int, end: int) -> Dict[str, Union[str, int]]:
        """
        When decoding from token probabilities, this method maps token indexes to actual word in the initial context.

        Args:
            text (`str`): The actual context to extract the answer from.
            start (`int`): The answer starting token index.
            end (`int`): The answer end token index.

        Returns:
            Dictionary like `{'answer': str, 'start': int, 'end': int}`
        """
        words = []
        token_idx = char_start_idx = char_end_idx = chars_idx = 0

        for word in enumerate(text.split(" ")):
            token = self.tokenizer.tokenize(word)

            # Append words if they are in the span
            if start <= token_idx <= end:
                if token_idx == start:
                    char_start_idx = chars_idx

                if token_idx == end:
                    char_end_idx = chars_idx + len(word)

                words += [word]

            # Stop if we went over the end of the answer
            if token_idx > end:
                break

            # Append the subtokenization length to the running index
            token_idx += len(token)
            chars_idx += len(word) + 1

        # Join text with spaces
        return {
            "answer": " ".join(words),
            "start": max(0, char_start_idx),
            "end": min(len(text), char_end_idx),
        }

mindnlp.transformers.pipelines.question_answering.QuestionAnsweringPipeline.__call__(*args, **kwargs)

Answer the question(s) given as inputs by using the context(s).

PARAMETER	DESCRIPTION
args	One or several [SquadExample] containing the question and context. TYPE: [`SquadExample`] or a list of [`SquadExample`] DEFAULT: ()
X	One or several [SquadExample] containing the question and context (will be treated the same way as if passed as the first positional argument). TYPE: [`SquadExample`] or a list of [`SquadExample`], *optional*
data	One or several [SquadExample] containing the question and context (will be treated the same way as if passed as the first positional argument). TYPE: [`SquadExample`] or a list of [`SquadExample`], *optional*
question	One or several question(s) (must be used in conjunction with the context argument). TYPE: `str` or `List[str]`
context	One or several context(s) associated with the question(s) (must be used in conjunction with the question argument). TYPE: `str` or `List[str]`
topk	The number of answers to return (will be chosen by order of likelihood). Note that we return less than topk answers if there are not enough options available within the context. TYPE: `int`, *optional*, defaults to 1
doc_stride	If the context is too long to fit with the question for the model, it will be split in several chunks with some overlap. This argument controls the size of that overlap. TYPE: `int`, *optional*, defaults to 128
max_answer_len	The maximum length of predicted answers (e.g., only answers with a shorter length are considered). TYPE: `int`, *optional*, defaults to 15
max_seq_len	The maximum length of the total sentence (context + question) in tokens of each chunk passed to the model. The context will be split in several chunks (using doc_stride as overlap) if needed. TYPE: `int`, *optional*, defaults to 384
max_question_len	The maximum length of the question after tokenization. It will be truncated if needed. TYPE: `int`, *optional*, defaults to 64
handle_impossible_answer	Whether or not we accept impossible as an answer. TYPE: `bool`, *optional*, defaults to `False`
align_to_words	Attempts to align the answer to real words. Improves quality on space separated langages. Might hurt on non-space-separated languages (like Japanese or Chinese) TYPE: `bool`, *optional*, defaults to `True`

RETURNS	DESCRIPTION
	A dict or a list of dict: Each result comes as a dictionary with the following keys: score (float) -- The probability associated to the answer. start (int) -- The character start index of the answer (in the tokenized version of the input). end (int) -- The character end index of the answer (in the tokenized version of the input). answer (str) -- The answer to the question.

Source code in mindnlp/transformers/pipelines/question_answering.py

def __call__(self, *args, **kwargs):
    """
    Answer the question(s) given as inputs by using the context(s).

    Args:
        args ([`SquadExample`] or a list of [`SquadExample`]):
            One or several [`SquadExample`] containing the question and context.
        X ([`SquadExample`] or a list of [`SquadExample`], *optional*):
            One or several [`SquadExample`] containing the question and context (will be treated the same way as if
            passed as the first positional argument).
        data ([`SquadExample`] or a list of [`SquadExample`], *optional*):
            One or several [`SquadExample`] containing the question and context (will be treated the same way as if
            passed as the first positional argument).
        question (`str` or `List[str]`):
            One or several question(s) (must be used in conjunction with the `context` argument).
        context (`str` or `List[str]`):
            One or several context(s) associated with the question(s) (must be used in conjunction with the
            `question` argument).
        topk (`int`, *optional*, defaults to 1):
            The number of answers to return (will be chosen by order of likelihood). Note that we return less than
            topk answers if there are not enough options available within the context.
        doc_stride (`int`, *optional*, defaults to 128):
            If the context is too long to fit with the question for the model, it will be split in several chunks
            with some overlap. This argument controls the size of that overlap.
        max_answer_len (`int`, *optional*, defaults to 15):
            The maximum length of predicted answers (e.g., only answers with a shorter length are considered).
        max_seq_len (`int`, *optional*, defaults to 384):
            The maximum length of the total sentence (context + question) in tokens of each chunk passed to the
            model. The context will be split in several chunks (using `doc_stride` as overlap) if needed.
        max_question_len (`int`, *optional*, defaults to 64):
            The maximum length of the question after tokenization. It will be truncated if needed.
        handle_impossible_answer (`bool`, *optional*, defaults to `False`):
            Whether or not we accept impossible as an answer.
        align_to_words (`bool`, *optional*, defaults to `True`):
            Attempts to align the answer to real words. Improves quality on space separated langages. Might hurt on
            non-space-separated languages (like Japanese or Chinese)

    Returns:
        A `dict` or a list of `dict`:
            Each result comes as a dictionary with the following keys:

            - **score** (`float`) -- The probability associated to the answer.
            - **start** (`int`) -- The character start index of the answer (in the tokenized version of the input).
            - **end** (`int`) -- The character end index of the answer (in the tokenized version of the input).
            - **answer** (`str`) -- The answer to the question.
    """
    # Convert inputs to features

    examples = self._args_parser(*args, **kwargs)
    if isinstance(examples, (list, tuple)) and len(examples) == 1:
        return super().__call__(examples[0], **kwargs)
    return super().__call__(examples, **kwargs)

mindnlp.transformers.pipelines.question_answering.QuestionAnsweringPipeline.__init__(model, tokenizer, modelcard=None, framework=None, task='', **kwargs)

Initializes a QuestionAnsweringPipeline object.

PARAMETER	DESCRIPTION
self	The QuestionAnsweringPipeline instance. TYPE: QuestionAnsweringPipeline
model	The pre-trained model to be used for question answering. TYPE: PreTrainedModel
tokenizer	The tokenizer associated with the pre-trained model. TYPE: PreTrainedTokenizer
modelcard	The model card providing details about the model. Defaults to None. TYPE: Optional[ModelCard] DEFAULT: None
framework	The framework used for the model. Defaults to None. TYPE: Optional[str] DEFAULT: None
task	The specific task to be performed by the pipeline. TYPE: str DEFAULT: ''
**kwargs	Additional keyword arguments. DEFAULT: {}

RETURNS	DESCRIPTION
	None.

Source code in mindnlp/transformers/pipelines/question_answering.py

def __init__(
        self,
        model: "PreTrainedModel",
        tokenizer: PreTrainedTokenizer,
        modelcard: Optional['ModelCard'] = None,
        framework: Optional[str] = None,
        task: str = "",
        **kwargs,
):
    """
    Initializes a QuestionAnsweringPipeline object.

    Args:
        self (QuestionAnsweringPipeline): The QuestionAnsweringPipeline instance.
        model (PreTrainedModel): The pre-trained model to be used for question answering.
        tokenizer (PreTrainedTokenizer): The tokenizer associated with the pre-trained model.
        modelcard (Optional[ModelCard], optional): The model card providing details about the model. Defaults to None.
        framework (Optional[str], optional): The framework used for the model. Defaults to None.
        task (str): The specific task to be performed by the pipeline.
        **kwargs: Additional keyword arguments.

    Returns:
        None.

    Raises:
        None.
    """
    super().__init__(
        model=model,
        tokenizer=tokenizer,
        modelcard=modelcard,
        framework=framework,
        task=task,
        **kwargs,
    )

    self._args_parser = QuestionAnsweringArgumentHandler()

mindnlp.transformers.pipelines.question_answering.QuestionAnsweringPipeline.create_sample(question, context) staticmethod

QuestionAnsweringPipeline leverages the [SquadExample] internally. This helper method encapsulate all the logic for converting question(s) and context(s) to [SquadExample].

We currently support extractive question answering.

PARAMETER	DESCRIPTION
question	The question(s) asked. TYPE: `str` or `List[str]`
context	The context(s) in which we will look for the answer. TYPE: `str` or `List[str]`

RETURNS	DESCRIPTION
Union[SquadExample, List[SquadExample]]	One or a list of [SquadExample]: The corresponding [SquadExample] grouping question and context.

Source code in mindnlp/transformers/pipelines/question_answering.py

@staticmethod
def create_sample(
        question: Union[str, List[str]], context: Union[str, List[str]]
) -> Union[SquadExample, List[SquadExample]]:
    """
    QuestionAnsweringPipeline leverages the [`SquadExample`] internally. This helper method encapsulate all the
    logic for converting question(s) and context(s) to [`SquadExample`].

    We currently support extractive question answering.

    Arguments:
        question (`str` or `List[str]`): The question(s) asked.
        context (`str` or `List[str]`): The context(s) in which we will look for the answer.

    Returns:
        One or a list of [`SquadExample`]: The corresponding [`SquadExample`] grouping question and context.
    """
    if isinstance(question, list):
        return [SquadExample(None, q, c, None, None, None) for q, c in zip(question, context)]
    else:
        return SquadExample(None, question, context, None, None, None)

mindnlp.transformers.pipelines.question_answering.QuestionAnsweringPipeline.get_indices(enc, s, e, sequence_index, align_to_words)

This method retrieves the start and end character indices corresponding to the specified token indices within a given sequence.

PARAMETER	DESCRIPTION
self	The instance of the QuestionAnsweringPipeline class.
enc	An instance of the tokenizers.Encoding class containing the encoded tokens. TYPE: Encoding
s	The start token index within the encoded sequence. TYPE: int
e	The end token index within the encoded sequence. TYPE: int
sequence_index	The index of the sequence within the encoding to consider. TYPE: int
align_to_words	A flag indicating whether to align the indices to words within the encoding. TYPE: bool

RETURNS	DESCRIPTION
Tuple[int, int]	Tuple[int, int]: A tuple containing the start and end character indices within the specified sequence.

RAISES	DESCRIPTION
Exception	If an error occurs during the process of retrieving the character indices, an Exception is raised. This may occur if the token-to-word or word-to-chars mappings are not available or encounter an unexpected issue.

Source code in mindnlp/transformers/pipelines/question_answering.py

def get_indices(
        self, enc: "tokenizers.Encoding", s: int, e: int, sequence_index: int, align_to_words: bool
) -> Tuple[int, int]:
    """
    This method retrieves the start and end character indices corresponding to the specified token indices
    within a given sequence.

    Args:
        self: The instance of the QuestionAnsweringPipeline class.
        enc (tokenizers.Encoding): An instance of the tokenizers.Encoding class containing the encoded tokens.
        s (int): The start token index within the encoded sequence.
        e (int): The end token index within the encoded sequence.
        sequence_index (int): The index of the sequence within the encoding to consider.
        align_to_words (bool): A flag indicating whether to align the indices to words within the encoding.

    Returns:
        Tuple[int, int]: A tuple containing the start and end character indices within the specified sequence.

    Raises:
        Exception: If an error occurs during the process of retrieving the character indices, an Exception is raised.
            This may occur if the token-to-word or word-to-chars mappings are not available or encounter an
            unexpected issue.
    """
    if align_to_words:
        try:
            start_word = enc.token_to_word(s)
            end_word = enc.token_to_word(e)
            start_index = enc.word_to_chars(start_word, sequence_index=sequence_index)[0]
            end_index = enc.word_to_chars(end_word, sequence_index=sequence_index)[1]
        except Exception:
            # Some tokenizers don't really handle words. Keep to offsets then.
            start_index = enc.offsets[s][0]
            end_index = enc.offsets[e][1]
    else:
        start_index = enc.offsets[s][0]
        end_index = enc.offsets[e][1]
    return start_index, end_index

mindnlp.transformers.pipelines.question_answering.QuestionAnsweringPipeline.postprocess(model_outputs, top_k=1, handle_impossible_answer=False, max_answer_len=15, align_to_words=True)

This method postprocess is a part of the class QuestionAnsweringPipeline.

PARAMETER	DESCRIPTION
self	Represents the instance of the class.
model_outputs	A list of dictionaries representing the output from the model. Each dictionary contains keys 'start', 'end', 'example', 'p_mask', and 'attention_mask'.
top_k	An integer specifying the maximum number of top answers to consider. Defaults to 1. DEFAULT: 1
handle_impossible_answer	A boolean indicating whether to handle impossible answer scenarios. DEFAULT: False
max_answer_len	An integer defining the maximum length of the answer. DEFAULT: 15
align_to_words	A boolean flag indicating whether to align answers to words. DEFAULT: True

RETURNS	DESCRIPTION
	This method does not return a value directly. If successful, it updates the answers list based on the processing logic.

Source code in mindnlp/transformers/pipelines/question_answering.py

def postprocess(
        self,
        model_outputs,
        top_k=1,
        handle_impossible_answer=False,
        max_answer_len=15,
        align_to_words=True,
):
    """
    This method postprocess is a part of the class QuestionAnsweringPipeline.

    Args:
        self: Represents the instance of the class.
        model_outputs: A list of dictionaries representing the output from the model.
            Each dictionary contains keys 'start', 'end', 'example', 'p_mask', and 'attention_mask'.
        top_k: An integer specifying the maximum number of top answers to consider. Defaults to 1.
        handle_impossible_answer: A boolean indicating whether to handle impossible answer scenarios.
        max_answer_len: An integer defining the maximum length of the answer.
        align_to_words: A boolean flag indicating whether to align answers to words.

    Returns:
        This method does not return a value directly.
            If successful, it updates the answers list based on the processing logic.

    Raises:
        None.
    """
    min_null_score = 1000000  # large and positive
    answers = []
    for output in model_outputs:
        start_ = output["start"]
        end_ = output["end"]
        example = output["example"]
        p_mask = output["p_mask"]
        attention_mask = (
            output["attention_mask"].numpy() if output.get("attention_mask", None) is not None else None
        )

        starts, ends, scores, min_null_score = select_starts_ends(
            start_, end_, p_mask, attention_mask, min_null_score, top_k, handle_impossible_answer, max_answer_len
        )

        if not self.tokenizer.is_fast:
            char_to_word = np.array(example.char_to_word_offset)

            # Convert the answer (tokens) back to the original text
            # Score: score from the model
            # Start: Index of the first character of the answer in the context string
            # End: Index of the character following the last character of the answer in the context string
            # Answer: Plain text of the answer
            for s, e, score in zip(starts, ends, scores):
                token_to_orig_map = output["token_to_orig_map"]
                answers.append(
                    {
                        "score": score.item(),
                        "start": np.where(char_to_word == token_to_orig_map[s])[0][0].item(),
                        "end": np.where(char_to_word == token_to_orig_map[e])[0][-1].item(),
                        "answer": " ".join(example.doc_tokens[token_to_orig_map[s]: token_to_orig_map[e] + 1]),
                    }
                )
        else:
            # Convert the answer (tokens) back to the original text
            # Score: score from the model
            # Start: Index of the first character of the answer in the context string
            # End: Index of the character following the last character of the answer in the context string
            # Answer: Plain text of the answer
            question_first = bool(self.tokenizer.padding_side == "right")
            enc = output["encoding"]

            # Encoding was *not* padded, input_ids *might*.
            # It doesn't make a difference unless we're padding on
            # the left hand side, since now we have different offsets
            # everywhere.
            if self.tokenizer.padding_side == "left":
                offset = (output["input_ids"] == self.tokenizer.pad_token_id).numpy().sum()
            else:
                offset = 0

            # Sometimes the max probability token is in the middle of a word so:
            # - we start by finding the right word containing the token with `token_to_word`
            # - then we convert this word in a character span with `word_to_chars`
            sequence_index = 1 if question_first else 0
            for s, e, score in zip(starts, ends, scores):
                s = s - offset
                e = e - offset

                start_index, end_index = self.get_indices(enc, s, e, sequence_index, align_to_words)

                answers.append(
                    {
                        "score": score.item(),
                        "start": start_index,
                        "end": end_index,
                        "answer": example.context_text[start_index:end_index],
                    }
                )

    if handle_impossible_answer:
        answers.append({"score": min_null_score, "start": 0, "end": 0, "answer": ""})
    answers = sorted(answers, key=lambda x: x["score"], reverse=True)[:top_k]
    if len(answers) == 1:
        return answers[0]
    return answers

mindnlp.transformers.pipelines.question_answering.QuestionAnsweringPipeline.preprocess(example, padding='do_not_pad', doc_stride=None, max_question_len=64, max_seq_len=None)

The preprocess method performs preprocessing for a Question Answering task and yields processed features.

PARAMETER	DESCRIPTION
self	The instance of the QuestionAnsweringPipeline class. TYPE: object
example	The input example for the Question Answering task. This can be provided as a dictionary with keys: 'question' and 'context', or as a SquadExample object. TYPE: dict or SquadExample
padding	Determines the padding strategy. It can take the values 'do_not_pad' or other padding strategies supported by the tokenizer. TYPE: str DEFAULT: 'do_not_pad'
doc_stride	The maximum distance between chunks of input context when splitting long contexts for processing. If not provided, it defaults to half of the max_seq_len or 128, whichever is smaller. TYPE: int DEFAULT: None
max_question_len	The maximum length allowed for the input question. If the input question exceeds this length, it will be truncated. TYPE: int DEFAULT: 64
max_seq_len	The maximum length allowed for the input sequence. If not provided, it defaults to the minimum of the maximum length supported by the tokenizer and 384. TYPE: int DEFAULT: None

RETURNS	DESCRIPTION
None	This method yields processed features and does not return any value directly.

RAISES	DESCRIPTION
ValueError	If the provided doc_stride is larger than max_seq_len.

Source code in mindnlp/transformers/pipelines/question_answering.py

def preprocess(self, example, padding="do_not_pad", doc_stride=None, max_question_len=64, max_seq_len=None):
    '''
    The preprocess method performs preprocessing for a Question Answering task and yields processed features.

    Args:
        self (object): The instance of the QuestionAnsweringPipeline class.
        example (dict or SquadExample): The input example for the Question Answering task.
            This can be provided as a dictionary with keys: 'question' and 'context', or as a SquadExample object.
        padding (str): Determines the padding strategy.
            It can take the values 'do_not_pad' or other padding strategies supported by the tokenizer.
        doc_stride (int): The maximum distance between chunks of input context when splitting long contexts for processing.
            If not provided, it defaults to half of the max_seq_len or 128, whichever is smaller.
        max_question_len (int): The maximum length allowed for the input question.
            If the input question exceeds this length, it will be truncated.
        max_seq_len (int): The maximum length allowed for the input sequence.
            If not provided, it defaults to the minimum of the maximum length supported by the tokenizer and 384.

    Returns:
        None: This method yields processed features and does not return any value directly.

    Raises:
        ValueError: If the provided doc_stride is larger than max_seq_len.
    '''
    if isinstance(example, dict):
        example = SquadExample(None, example["question"], example["context"], None, None, None)

    if max_seq_len is None:
        max_seq_len = min(self.tokenizer.model_max_length, 384)
    if doc_stride is None:
        doc_stride = min(max_seq_len // 2, 128)

    if doc_stride > max_seq_len:
        raise ValueError(f"`doc_stride` ({doc_stride}) is larger than `max_seq_len` ({max_seq_len})")

    if not self.tokenizer.is_fast:
        features = squad_convert_examples_to_features(
            examples=[example],
            tokenizer=self.tokenizer,
            max_seq_length=max_seq_len,
            doc_stride=doc_stride,
            max_query_length=max_question_len,
            padding_strategy=PaddingStrategy.MAX_LENGTH,
            is_training=False,
            tqdm_enabled=False,
        )
    else:
        # Define the side we want to truncate / pad and the text/pair sorting
        question_first = self.tokenizer.padding_side == "right"

        encoded_inputs = self.tokenizer(
            text=example.question_text if question_first else example.context_text,
            text_pair=example.context_text if question_first else example.question_text,
            padding=padding,
            truncation="only_second" if question_first else "only_first",
            max_length=max_seq_len,
            stride=doc_stride,
            return_token_type_ids=True,
            return_overflowing_tokens=True,
            return_offsets_mapping=True,
            return_special_tokens_mask=True,
        )
        # When the input is too long, it's converted in a batch of inputs with overflowing tokens
        # and a stride of overlap between the inputs. If a batch of inputs is given, a special output
        # "overflow_to_sample_mapping" indicate which member of the encoded batch belong to which original batch sample.
        # Here we tokenize examples one-by-one so we don't need to use "overflow_to_sample_mapping".
        # "num_span" is the number of output samples generated from the overflowing tokens.
        num_spans = len(encoded_inputs["input_ids"])

        # p_mask: mask with 1 for token than cannot be in the answer (0 for token which can be in an answer)
        # We put 0 on the tokens from the context and 1 everywhere else (question and special tokens)
        p_mask = [
            [tok != 1 if question_first else 0 for tok in encoded_inputs.sequence_ids(span_id)]
            for span_id in range(num_spans)
        ]

        features = []
        for span_idx in range(num_spans):
            input_ids_span_idx = encoded_inputs["input_ids"][span_idx]
            attention_mask_span_idx = (
                encoded_inputs["attention_mask"][span_idx] if "attention_mask" in encoded_inputs else None
            )
            token_type_ids_span_idx = (
                encoded_inputs["token_type_ids"][span_idx] if "token_type_ids" in encoded_inputs else None
            )
            # keep the cls_token unmasked (some models use it to indicate unanswerable questions)
            if self.tokenizer.cls_token_id is not None:
                cls_indices = np.nonzero(np.array(input_ids_span_idx) == self.tokenizer.cls_token_id)[0]
                for cls_index in cls_indices:
                    p_mask[span_idx][cls_index] = 0
            submask = p_mask[span_idx]
            features.append(
                SquadFeatures(
                    input_ids=input_ids_span_idx,
                    attention_mask=attention_mask_span_idx,
                    token_type_ids=token_type_ids_span_idx,
                    p_mask=submask,
                    encoding=encoded_inputs[span_idx],
                    # We don't use the rest of the values - and actually
                    # for Fast tokenizer we could totally avoid using SquadFeatures and SquadExample
                    cls_index=None,
                    token_to_orig_map={},
                    example_index=0,
                    unique_id=0,
                    paragraph_len=0,
                    token_is_max_context=0,
                    tokens=[],
                    start_position=0,
                    end_position=0,
                    is_impossible=False,
                    qas_id=None,
                )
            )

    for i, feature in enumerate(features):
        fw_args = {}
        others = {}
        model_input_names = self.tokenizer.model_input_names + ["p_mask", "token_type_ids"]

        for k, v in feature.__dict__.items():
            if k in model_input_names:
                tensor = mindspore.tensor(v)
                if tensor.dtype == mindspore.int32:
                    tensor = tensor.long()
                fw_args[k] = tensor.unsqueeze(0)
            else:
                others[k] = v

        is_last = i == len(features) - 1
        yield {"example": example, "is_last": is_last, **fw_args, **others}

mindnlp.transformers.pipelines.question_answering.QuestionAnsweringPipeline.span_to_answer(text, start, end)

When decoding from token probabilities, this method maps token indexes to actual word in the initial context.

PARAMETER	DESCRIPTION
text	The actual context to extract the answer from. TYPE: `str`
start	The answer starting token index. TYPE: `int`
end	The answer end token index. TYPE: `int`

RETURNS	DESCRIPTION
Dict[str, Union[str, int]]	Dictionary like {'answer': str, 'start': int, 'end': int}

Source code in mindnlp/transformers/pipelines/question_answering.py

def span_to_answer(self, text: str, start: int, end: int) -> Dict[str, Union[str, int]]:
    """
    When decoding from token probabilities, this method maps token indexes to actual word in the initial context.

    Args:
        text (`str`): The actual context to extract the answer from.
        start (`int`): The answer starting token index.
        end (`int`): The answer end token index.

    Returns:
        Dictionary like `{'answer': str, 'start': int, 'end': int}`
    """
    words = []
    token_idx = char_start_idx = char_end_idx = chars_idx = 0

    for word in enumerate(text.split(" ")):
        token = self.tokenizer.tokenize(word)

        # Append words if they are in the span
        if start <= token_idx <= end:
            if token_idx == start:
                char_start_idx = chars_idx

            if token_idx == end:
                char_end_idx = chars_idx + len(word)

            words += [word]

        # Stop if we went over the end of the answer
        if token_idx > end:
            break

        # Append the subtokenization length to the running index
        token_idx += len(token)
        chars_idx += len(word) + 1

    # Join text with spaces
    return {
        "answer": " ".join(words),
        "start": max(0, char_start_idx),
        "end": min(len(text), char_end_idx),
    }