Add check for evaluation + metrics

app.py

@@ -8,6 +8,7 @@ from compliance_checks import (
     IntendedPurposeCheck,
     GeneralLimitationsCheck,
     ComputationalRequirementsCheck,
+    EvaluationCheck,
 )
 
 hf_writer = gr.HuggingFaceDatasetSaver(
@@ -23,6 +24,7 @@ checks = [
     IntendedPurposeCheck(),
     GeneralLimitationsCheck(),
     ComputationalRequirementsCheck(),
+    EvaluationCheck(),
 ]
 suite = ComplianceSuite(checks=checks)
 

bloom_card.py

@@ -1,147 +0,0 @@
-bloom_card = """\
-# Model Details  
-
-BLOOM is an autoregressive Large Language Model (LLM), trained to continue text from a prompt on vast amounts of text data using industrial-scale computational resources. As such, it is able to output coherent text in 46 languages and 13 programming languages that is hardly distinguishable from text written by humans. BLOOM can also be instructed to perform text tasks it hasn't been explicitly trained for, by casting them as text generation tasks.
-
-## Basics
-*This section provides information about the model type, version, license, funders, release date, developers, and contact information.*
-*It is useful for anyone who wants to reference the model.*
-  
-**Developed by:** BigScience ([website](https://bigscience.huggingface.co))
-
-*All collaborators are either volunteers or have an agreement with their employer. (Further breakdown of participants forthcoming.)*
-    
-**Model Type:** Transformer-based Language Model
-
-**Checkpoints format:** `transformers` (Megatron-DeepSpeed format available [here](https://huggingface.co/bigscience/bloom-optimizer-states))
-
-**Version:** 1.0.0
-
-**Languages:** Multiple; see [training data](#training-data)
-
-**License:** RAIL License v1.0 ([link](https://huggingface.co/spaces/bigscience/license) / [article and FAQ](https://bigscience.huggingface.co/blog/the-bigscience-rail-license))
-
-**Release Date Estimate:** Monday, 11.July.2022
-
-**Send Questions to:** bigscience-contact@googlegroups.com
-
-**Cite as:** BigScience, _BigScience Language Open-science Open-access Multilingual (BLOOM) Language Model_. International, May 2021-May 2022
-
-**Funded by:** 
-    
-* The French government.
-
-* Hugging Face ([website](https://huggingface.co)).
-
-* Organizations of contributors.  *(Further breakdown of organizations forthcoming.)*
-
-## Intended Use
-
-This model is being created in order to enable public research on large language models (LLMs). LLMs are intended to be used for language generation or as a pretrained base model that can be further fine-tuned for specific tasks. Use cases below are not exhaustive.
-
-### Direct Use
-
--   Text generation
-
--   Exploring characteristics of language generated by a language model
-
-    -   Examples: Cloze tests, counterfactuals, generations with reframings
-
-### Downstream Use
-
--   Tasks that leverage language models include: Information Extraction, Question Answering, Summarization
-
-### Out-of-Scope Use
-
-Using the model in [high-stakes](#high-stakes) settings is out of scope for this model.  The model is not designed for [critical decisions](#critical-decisions) nor uses with any material consequences on an individual's livelihood or wellbeing. The model outputs content that appears factual but may not be correct.  
-
-Out-of-scope Uses Include:
-
--   Usage in biomedical domains, political and legal domains, or finance domains
-
--   Usage for evaluating or scoring individuals, such as for employment, education, or credit
-
--   Applying the model for critical automatic decisions, generating factual content, creating reliable summaries, or generating predictions that must be correct
-
-#### Misuse
-
-Intentionally using the model for harm, violating [human rights](#human-rights), or other kinds of malicious activities, is a misuse of this model. This includes:
-
--   Spam generation
-
--   Disinformation and influence operations
-
--   Disparagement and defamation
-
--   Harassment and abuse
-  
--   [Deception](#deception)
-
--   Unconsented impersonation and imitation
-
--   Unconsented surveillance 
-
--   Generating content without attribution to the model, as specified in the [RAIL License, Use Restrictions](https://huggingface.co/spaces/bigscience/license)
-
-## Bias, Risks, and Limitations
-*This section identifies foreseeable harms and misunderstandings.*
-    
-Model may:
-
--   Overrepresent some viewpoints and underrepresent others
-
--   Contain stereotypes
-  
--   Contain [personal information](#personal-data-and-information)
-
--   Generate:
-
-    -   Hateful, abusive, or violent language
-
-    -   Discriminatory or prejudicial language
-
-    -   Content that may not be appropriate for all settings, including sexual content
-
--   Make errors, including producing incorrect information as if it were factual
-
--   Generate irrelevant or repetitive outputs
-
--   Induce users into attributing human traits to it, such as sentience or consciousness
-
-## Technical Specifications
-*This section includes details about the model objective and architecture, and the compute infrastructure.*
-*It is useful for people interested in model development.*
-
-### Compute infrastructure
-Jean Zay Public Supercomputer, provided by the French government (see [announcement](https://www.enseignementsup-recherche.gouv.fr/fr/signature-du-marche-d-acquisition-de-l-un-des-supercalculateurs-les-plus-puissants-d-europe-46733)).
-
-#### Hardware
-
-* 384 A100 80GB GPUs (48 nodes)
-    
-* Additional 32 A100 80GB GPUs (4 nodes) in reserve
-
-* 8 GPUs per node Using NVLink 4 inter-gpu connects, 4 OmniPath links
-
-* CPU: AMD
-
-* CPU memory: 512GB per node
-
-* GPU memory: 640GB per node
-
-* Inter-node connect: Omni-Path Architecture (OPA)
-
-* NCCL-communications network: a fully dedicated subnet
-
-* Disc IO network: shared network with other types of nodes
-
-#### Software
-
-* Megatron-DeepSpeed ([Github link](https://github.com/bigscience-workshop/Megatron-DeepSpeed))
-
-* DeepSpeed ([Github link](https://github.com/microsoft/DeepSpeed))
-
-* PyTorch (pytorch-1.11 w/ CUDA-11.5; see [Github link](https://github.com/pytorch/pytorch))
-
-* apex ([Github link](https://github.com/NVIDIA/apex))
-"""

compliance_checks/__init__.py

@@ -13,4 +13,8 @@ from compliance_checks.general_limitations import (
 
 from compliance_checks.computational_requirements import (
     ComputationalRequirementsCheck, ComputationalRequirementsResult,
-)
+)
+
+from compliance_checks.evaluation import (
+    EvaluationCheck, EvaluationResult,
+)

compliance_checks/evaluation.py

@@ -0,0 +1,95 @@
+from compliance_checks.base import ComplianceResult, ComplianceCheck, walk_to_next_heading
+from bs4 import BeautifulSoup
+
+
+class EvaluationResult(ComplianceResult):
+    name = "Evaluation and Metrics"
+
+    def __init__(
+            self,
+            *args,
+            **kwargs,
+    ):
+        super().__init__(*args, **kwargs)
+
+    def __eq__(self, other):
+        if isinstance(other, EvaluationResult):
+            if super().__eq__(other):
+                try:
+                    return True
+                except AssertionError:
+                    return False
+        else:
+            return False
+
+    def to_string(self):
+        if self.status:
+            return """\
+            It looks like this model card has some documentation for how the model was evaluated! We look for this by \
+            searching for headings that say things like:
+            - Evaluation
+            - Evaluation results
+            - Benchmarks
+            - Results
+            """
+        else:
+            return """\
+            We weren't able to find a section in this model card that reports the evaluation process, but it's easy to \
+            add one! You can add the following section to the model card and, once you fill in the \
+            `[More Information Needed]` sections, the "Evaluation and Metrics" check should pass 🤗
+            
+            ```md
+            ## Evaluation
+            
+            <!-- This section describes the evaluation protocols and provides the results. -->
+            
+            ### Testing Data, Factors & Metrics
+            
+            #### Testing Data
+            
+            <!-- This should link to a Data Card if possible. -->
+            
+            [More Information Needed]
+            
+            #### Factors
+            
+            <!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
+            
+            [More Information Needed]
+            
+            #### Metrics
+            
+            <!-- These are the evaluation metrics being used, ideally with a description of why. -->
+            
+            [More Information Needed]
+            
+            ### Results
+            
+            [More Information Needed]
+            
+            #### Summary
+            
+            [More Information Needed]
+            ```
+            """
+
+
+class EvaluationCheck(ComplianceCheck):
+    name = "Evaluation and Metrics"
+
+    def run_check(self, card: BeautifulSoup):
+        combos = [
+            ("h1", "Evaluation"), ("h2", "Evaluation"),
+            ("h2", "Evaluation results"), ("h2", "Evaluation Results"),
+            ("h2", "Benchmarks"),
+            ("h2", "Results"),
+        ]
+
+        for hX, heading in combos:
+            purpose_check = walk_to_next_heading(card, hX, heading)
+            if purpose_check:
+                return EvaluationResult(
+                    status=True,
+                )
+
+        return EvaluationResult()

tests/conftest.py

@@ -2,45 +2,42 @@ from os import listdir
 from os.path import isfile, join
 from pathlib import Path
 
-
-# TODO: I have the option of maybe making a check for accuracy/metrics?
-
 # Note, some of these are marked as FALSE instead of TRUE because the
 # information is hidden somewhere non-standard, e.g. described in prose
 
 # Intended Purpose, General Limitations, Computational Requirements
 expected_check_results = {
-    "albert-base-v2": [True, True, False],
-    "bert-base-cased": [True, True, False],
-    "bert-base-multilingual-cased": [True, True, False],
-    "bert-base-uncased": [True, True, False],
-    "big-science___bloom": [True, True, True],
-    "cl-tohoku___bert-base-japanese-whole-word-masking": [False, False, False],
-    "distilbert-base-cased-distilled-squad": [True, True, True],
-    "distilbert-base-uncased": [True, True, False],
-    "distilbert-base-uncased-finetuned-sst-2-english": [True, True, False],
-    "distilroberta-base": [True, True, False],
-    "emilyalsentzer___Bio_ClinicalBERT": [False, False, False],
-    "facebook___bart-large-mnli": [False, False, False],
-    "google___electra-base-discriminator": [False, False, False],
-    "gpt2": [True, True, False],
-    "Helsinki-NLP___opus-mt-en-es": [False, False, False],
-    "jonatasgrosman___wav2vec2-large-xlsr-53-english": [False, False, False],
-    "microsoft___layoutlmv3-base": [False, False, False],
-    "openai___clip-vit-base-patch32": [True, True, False],
-    "openai___clip-vit-large-patch14": [True, True, False],
-    "philschmid___bart-large-cnn-samsum": [False, False, False],
-    "prajjwal1___bert-tiny": [False, False, False],
-    "roberta-base": [True, True, False],
-    "roberta-large": [True, True, False],
-    "runwayml___stable-diffusion-v1-5": [True, True, False],
-    "sentence-transformers___all-MiniLM-L6-v2": [True, False, False],
-    "StanfordAIMI___stanford-deidentifier-base": [False, False, False],
-    "t5-base": [True, False, False],
-    "t5-small": [True, False, False],
-    "xlm-roberta-base": [True, True, False],
-    "xlm-roberta-large": [True, True, False],
-    "yiyanghkust___finbert-tone": [False, False, False],
+    "albert-base-v2": [True, True, False, True],
+    "bert-base-cased": [True, True, False, True],
+    "bert-base-multilingual-cased": [True, True, False, False],
+    "bert-base-uncased": [True, True, False, True],
+    "big-science___bloom": [True, True, True, True],
+    "cl-tohoku___bert-base-japanese-whole-word-masking": [False, False, False, False],
+    "distilbert-base-cased-distilled-squad": [True, True, True, True],
+    "distilbert-base-uncased": [True, True, False, True],
+    "distilbert-base-uncased-finetuned-sst-2-english": [True, True, False, False],
+    "distilroberta-base": [True, True, False, True],
+    "emilyalsentzer___Bio_ClinicalBERT": [False, False, False, False],
+    "facebook___bart-large-mnli": [False, False, False, False],
+    "google___electra-base-discriminator": [False, False, False, False],
+    "gpt2": [True, True, False, True],
+    "Helsinki-NLP___opus-mt-en-es": [False, False, False, True],
+    "jonatasgrosman___wav2vec2-large-xlsr-53-english": [False, False, False, True],
+    "microsoft___layoutlmv3-base": [False, False, False, False],
+    "openai___clip-vit-base-patch32": [True, True, False, False],
+    "openai___clip-vit-large-patch14": [True, True, False, False],
+    "philschmid___bart-large-cnn-samsum": [False, False, False, True],
+    "prajjwal1___bert-tiny": [False, False, False, False],
+    "roberta-base": [True, True, False, True],
+    "roberta-large": [True, True, False, True],
+    "runwayml___stable-diffusion-v1-5": [True, True, False, True],
+    "sentence-transformers___all-MiniLM-L6-v2": [True, False, False, True],
+    "StanfordAIMI___stanford-deidentifier-base": [False, False, False, False],
+    "t5-base": [True, False, False, True],
+    "t5-small": [True, False, False, True],
+    "xlm-roberta-base": [True, True, False, False],
+    "xlm-roberta-large": [True, True, False, False],
+    "yiyanghkust___finbert-tone": [False, False, False, False],
 }
 
 
@@ -49,18 +46,9 @@ def pytest_generate_tests(metafunc):
         files = [f"cards/{f}" for f in listdir("cards") if isfile(join("cards", f))]
         cards = [Path(f).read_text() for f in files]
         model_ids = [f.replace("cards/", "").replace(".md", "") for f in files]
-
-        # TODO: IMPORTANT – remove the default [False, False, False]
-        expected_results = [expected_check_results.get(m, [False, False, False]) for m, c in zip(model_ids, cards)]
+        expected_results = [expected_check_results.get(m) for m, c in zip(model_ids, cards)]
 
         metafunc.parametrize(
             ["real_model_card", "expected_check_results"],
             list(map(list, zip(cards, expected_results)))
         )
-
-    # rows = read_csvrows()
-    # if 'row' in metafunc.fixturenames:
-    #     metafunc.parametrize('row', rows)
-    # if 'col' in metafunc.fixturenames:
-    #     metafunc.parametrize('col', list(itertools.chain(*rows)))
-

tests/test_compliance_checks.py

@@ -6,6 +6,7 @@ from compliance_checks import (
     IntendedPurposeCheck,
     GeneralLimitationsCheck,
     ComputationalRequirementsCheck,
+    EvaluationCheck,
 )
 
 
@@ -60,7 +61,8 @@ def test_end_to_end_compliance_suite(real_model_card, expected_check_results):
     suite = ComplianceSuite(checks=[
         IntendedPurposeCheck(),
         GeneralLimitationsCheck(),
-        ComputationalRequirementsCheck()
+        ComputationalRequirementsCheck(),
+        EvaluationCheck(),
     ])
 
     results = suite.run(real_model_card)

tests/test_evaluation_check.py

@@ -0,0 +1,131 @@
+import pytest
+
+import markdown
+from bs4 import BeautifulSoup
+from compliance_checks.evaluation import (
+    EvaluationCheck, EvaluationResult,
+)
+
+empty_template = """\
+## Evaluation
+
+<!-- This section describes the evaluation protocols and provides the results. -->
+
+### Testing Data, Factors & Metrics
+
+#### Testing Data
+
+<!-- This should link to a Data Card if possible. -->
+
+[More Information Needed]
+
+#### Factors
+
+<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
+
+[More Information Needed]
+
+#### Metrics
+
+<!-- These are the evaluation metrics being used, ideally with a description of why. -->
+
+[More Information Needed]
+
+### Results
+
+[More Information Needed]
+
+#### Summary
+
+"""
+model_card_template = """\
+## Evaluation
+
+Some info...
+
+### Testing Data, Factors & Metrics
+
+#### Testing Data
+
+Some information here
+
+#### Factors
+
+Etc...
+
+#### Metrics
+
+There are some metrics listed out here
+
+### Results
+
+And some results
+
+#### Summary
+
+Summarizing everything up!
+"""
+albert = """\
+# ALBERT Base v2
+
+## Evaluation results
+
+When fine-tuned on downstream tasks, the ALBERT models achieve the following results:
+"""
+helsinki = """\
+### eng-spa
+
+## Benchmarks
+
+| testset               | BLEU  | chr-F |
+|-----------------------|-------|-------|
+| newssyscomb2009-engspa.eng.spa 	| 31.0 	| 0.583 |
+| news-test2008-engspa.eng.spa 	| 29.7 	| 0.564 |
+| newstest2009-engspa.eng.spa 	| 30.2 	| 0.578 |
+| newstest2010-engspa.eng.spa 	| 36.9 	| 0.620 |
+| newstest2011-engspa.eng.spa 	| 38.2 	| 0.619 |
+| newstest2012-engspa.eng.spa 	| 39.0 	| 0.625 |
+| newstest2013-engspa.eng.spa 	| 35.0 	| 0.598 |
+| Tatoeba-test.eng.spa 	| 54.9 	| 0.721 |
+"""
+phil = """\
+## Results
+
+| key | value |
+| --- | ----- |
+| eval_rouge1 | 42.621 |
+| eval_rouge2 | 21.9825 |
+| eval_rougeL | 33.034 |
+| eval_rougeLsum | 39.6783 |
+"""
+runway = """\
+## Evaluation Results 
+Evaluations with different classifier-free guidance scales (1.5, 2.0, 3.0, 4.0,
+"""
+
+success_result = EvaluationResult(
+    status=True
+)
+
+
+@pytest.mark.parametrize("card", [
+    model_card_template,
+    albert,
+    helsinki,
+    phil,
+    runway,
+])
+def test_run_checks(card):
+    model_card_html = markdown.markdown(card)
+    card_soup = BeautifulSoup(model_card_html, features="html.parser")
+
+    results = EvaluationCheck().run_check(card_soup)
+
+    assert results == success_result
+
+
+def test_fail_on_empty_template():
+    model_card_html = markdown.markdown(empty_template)
+    card_soup = BeautifulSoup(model_card_html, features="html.parser")
+    results = EvaluationCheck().run_check(card_soup)
+    assert results == EvaluationResult()