Add model card (#1)

- Add model card (e2ce543eaf25f05396ae0c73fcd0f9cf28682e2b)


Co-authored-by: Marissa Gerchick <[email protected]>

README.md

@@ -0,0 +1,146 @@
+---
+language: en
+license: cc-by-nc-4.0
+tags:
+- dpr
+datasets:
+- nq_open
+---
+
+`dpr-reader-single-nq-base`
+
+# Table of Contents
+- [Model Details](#model-details)
+- [How To Get Started With the Model](#how-to-get-started-with-the-model)
+- [Uses](#uses)
+- [Risks, Limitations and Biases](#risks-limitations-and-biases)
+- [Training](#training)
+- [Evaluation](#evaluation-results)
+- [Environmental Impact](#environmental-impact)
+- [Technical Specifications](#technical-specifications)
+- [Citation Information](#citation-information)
+- [Model Card Authors](#model-card-authors)
+
+## Model Details
+
+**Model Description:** [Dense Passage Retrieval (DPR)](https://github.com/facebookresearch/DPR) is a set of tools and models for state-of-the-art open-domain Q&A research. `dpr-reader-single-nq-base` is the reader model trained using the [Natural Questions (NQ) dataset](https://huggingface.co/datasets/nq_open) ([Lee et al., 2019](https://aclanthology.org/P19-1612/); [Kwiatkowski et al., 2019](https://aclanthology.org/Q19-1026/)).
+
+- **Developed by:** See [GitHub repo](https://github.com/facebookresearch/DPR) for model developers  
+- **Model Type:** QA Reader Model
+- **Language(s):** [CC-BY-NC-4.0](https://github.com/facebookresearch/DPR/blob/main/LICENSE), also see [Code of Conduct](https://github.com/facebookresearch/DPR/blob/main/CODE_OF_CONDUCT.md)
+- **License:** English
+- **Related Models:** 
+  - [`dpr-ctx_encoder-single-nq-base`](https://huggingface.co/facebook/dpr-ctx_encoder-single-nq-base)
+  - [`dpr-question_encoder-single-nq-base`](https://huggingface.co/facebook/dpr-question_encoder-single-nq-base)
+  - [`dpr-ctx_encoder-multiset-base`](https://huggingface.co/facebook/dpr-ctx_encoder-multiset-base)
+  - [`dpr-question_encoder-multiset-base`](https://huggingface.co/facebook/dpr-question_encoder-multiset-base)
+  - [`dpr-reader-multiset-base`](https://huggingface.co/facebook/dpr-reader-multiset-base)
+- **Resources for more information:**
+  - [Research Paper](https://arxiv.org/abs/2004.04906)
+  - [GitHub Repo](https://github.com/facebookresearch/DPR)
+  - [Hugging Face DPR docs](https://huggingface.co/docs/transformers/main/en/model_doc/dpr)
+  - [BERT Base Uncased Model Card](https://huggingface.co/bert-base-uncased)
+  
+## How to Get Started with the Model 
+
+Use the code below to get started with the model. 
+
+```python
+from transformers import DPRReader, DPRReaderTokenizer
+
+tokenizer = DPRReaderTokenizer.from_pretrained("facebook/dpr-reader-single-nq-base")
+model = DPRReader.from_pretrained("facebook/dpr-reader-single-nq-base")
+encoded_inputs = tokenizer(
+    questions=["What is love ?"],
+    titles=["Haddaway"],
+    texts=["'What Is Love' is a song recorded by the artist Haddaway"],
+    return_tensors="pt",
+)
+outputs = model(**encoded_inputs)
+start_logits = outputs.start_logits
+end_logits = outputs.end_logits
+relevance_logits = outputs.relevance_logits
+```
+
+## Uses
+
+#### Direct Use
+
+`dpr-reader-single-nq-base`, [`dpr-ctx_encoder-single-nq-base`](https://huggingface.co/facebook/dpr-ctx_encoder-single-nq-base), and [`dpr-question_encoder-single-nq-base`](https://huggingface.co/facebook/dpr-question_encoder-single-nq-base) can be used for the task of open-domain question answering.
+
+#### Misuse and Out-of-scope Use
+
+The model should not be used to intentionally create hostile or alienating environments for people. In addition, the set of DPR models was not trained to be factual or true representations of people or events, and therefore using the models to generate such content is out-of-scope for the abilities of this model.
+
+## Risks, Limitations and Biases
+
+**CONTENT WARNING: Readers should be aware this section may contain content that is disturbing, offensive, and can propogate historical and current stereotypes.**
+
+Significant research has explored bias and fairness issues with language models (see, e.g., [Sheng et al., 2021](https://aclanthology.org/2021.acl-long.330.pdf) and [Bender et al., 2021](https://dl.acm.org/doi/pdf/10.1145/3442188.3445922)). Predictions generated by the model can include disturbing and harmful stereotypes across protected classes; identity characteristics; and sensitive, social, and occupational groups. 
+
+## Training
+
+#### Training Data
+
+This model was trained using the [Natural Questions (NQ) dataset](https://huggingface.co/datasets/nq_open) ([Lee et al., 2019](https://aclanthology.org/P19-1612/); [Kwiatkowski et al., 2019](https://aclanthology.org/Q19-1026/)). The model authors write that: 
+
+> [The dataset] was designed for end-to-end question answering. The questions were mined from real Google search queries and the answers were spans in Wikipedia articles identified by annotators.
+
+#### Training Procedure
+
+The training procedure is described in the [associated paper](https://arxiv.org/pdf/2004.04906.pdf): 
+
+> Given a collection of M text passages, the goal of our dense passage retriever (DPR) is to index all the passages in a low-dimensional and continuous space, such that it can retrieve efficiently the top k passages relevant to the input question for the reader at run-time.
+
+> Our dense passage retriever (DPR) uses a dense encoder EP(·) which maps any text passage to a d- dimensional real-valued vectors and builds an index for all the M passages that we will use for retrieval. At run-time, DPR applies a different encoder EQ(·) that maps the input question to a d-dimensional vector, and retrieves k passages of which vectors are the closest to the question vector.
+
+The authors report that for encoders, they used two independent BERT ([Devlin et al., 2019](https://aclanthology.org/N19-1423/)) networks (base, un-cased) and use FAISS ([Johnson et al., 2017](https://arxiv.org/abs/1702.08734)) during inference time to encode and index passages. See the paper for further details on training, including encoders, inference, positive and negative passages, and in-batch negatives.
+
+## Evaluation
+
+The following evaluation information is extracted from the [associated paper](https://arxiv.org/pdf/2004.04906.pdf).
+
+#### Testing Data, Factors and Metrics
+
+The model developers report the performance of the model on five QA datasets, using the top-k accuracy (k ∈ {20, 100}). The datasets were [NQ](https://huggingface.co/datasets/nq_open), [TriviaQA](https://huggingface.co/datasets/trivia_qa), [WebQuestions (WQ)](https://huggingface.co/datasets/web_questions), [CuratedTREC (TREC)](https://huggingface.co/datasets/trec), and [SQuAD v1.1](https://huggingface.co/datasets/squad).
+
+#### Results
+|      | Top 20 |           |    |      |       | Top 100|           |    |      |       |    
+|:----:|:------:|:---------:|:--:|:----:|:-----:|:------:|:---------:|:--:|:----:|:-----:|  
+|      | NQ     |  TriviaQA | WQ | TREC | SQuAD | NQ     |  TriviaQA | WQ | TREC | SQuAD |  
+|      | 78.4   |  79.4     |73.2| 79.8 | 63.2  | 85.4   |  85.0     |81.4| 89.1 | 77.2  |    
+
+## Environmental Impact
+
+Carbon emissions can be estimated using the [Machine Learning Impact calculator](https://mlco2.github.io/impact#compute) presented in [Lacoste et al. (2019)](https://arxiv.org/abs/1910.09700). We present the hardware type and based on the [associated paper](https://arxiv.org/abs/2004.04906).
+ 
+- **Hardware Type:** 8 32GB GPUs  
+- **Hours used:** Unknown  
+- **Cloud Provider:** Unknown
+- **Compute Region:** Unknown
+- **Carbon Emitted:** Unknown
+ 
+## Technical Specifications
+
+See the [associated paper](https://arxiv.org/abs/2004.04906) for details on the modeling architecture, objective, compute infrastructure, and training details.
+ 
+## Citation Information
+
+```bibtex
+@inproceedings{karpukhin-etal-2020-dense,
+    title = "Dense Passage Retrieval for Open-Domain Question Answering",
+    author = "Karpukhin, Vladimir and Oguz, Barlas and Min, Sewon and Lewis, Patrick and Wu, Ledell and Edunov, Sergey and Chen, Danqi and Yih, Wen-tau",
+    booktitle = "Proceedings of the 2020 Conference on Empirical Methods in Natural Language Processing (EMNLP)",
+    month = nov,
+    year = "2020",
+    address = "Online",
+    publisher = "Association for Computational Linguistics",
+    url = "https://www.aclweb.org/anthology/2020.emnlp-main.550",
+    doi = "10.18653/v1/2020.emnlp-main.550",
+    pages = "6769--6781",
+}
+```
+
+## Model Card Authors
+
+This model card was written by the team at Hugging Face.