Update README.md

README.md

@@ -1,199 +1,183 @@
 ---
-library_name: transformers
-tags: []
+language:
+- en
 ---
 
-# Model Card for Model ID
+<div align="center">
+  <img src="https://github.com/SapienzaNLP/relik/blob/main/relik.png?raw=true" height="150">
+  <img src="https://github.com/SapienzaNLP/relik/blob/main/Sapienza_Babelscape.png?raw=true" height="50">
+</div>
 
-<!-- Provide a quick summary of what the model is/does. -->
+<div align="center">
+  <h1>Retrieve, Read and LinK: Fast and Accurate Entity Linking and Relation Extraction on an Academic Budget</h1>
+</div>
 
+<div style="display:flex; justify-content: center; align-items: center; flex-direction: row;">
+    <a href="https://2024.aclweb.org/"><img src="http://img.shields.io/badge/ACL-2024-4b44ce.svg"></a> &nbsp; &nbsp; 
+    <a href="https://aclanthology.org/"><img src="http://img.shields.io/badge/paper-ACL--anthology-B31B1B.svg"></a> &nbsp; &nbsp; 
+    <a href="https://arxiv.org/abs/placeholder"><img src="https://img.shields.io/badge/arXiv-placeholder-b31b1b.svg"></a>
+</div>
+<div style="display:flex; justify-content: center; align-items: center; flex-direction: row;">
+    <a href="https://huggingface.co/collections/sapienzanlp/relik-retrieve-read-and-link-665d9e4a5c3ecba98c1bef19"><img src="https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Collection-FCD21D"></a> &nbsp; &nbsp;
+    <a href="https://github.com/SapienzaNLP/relik"><img src="https://img.shields.io/badge/GitHub-Repo-121013?logo=github&logoColor=white"></a> &nbsp; &nbsp;
+    <a href="https://github.com/SapienzaNLP/relik/releases"><img src="https://img.shields.io/github/v/release/SapienzaNLP/relik"></a>
+</div>
 
 
-## Model Details
+A blazing fast and lightweight Information Extraction model for **Entity Linking** and **Relation Extraction**.
 
-### Model Description
+## 🛠️ Installation
 
-<!-- Provide a longer summary of what this model is. -->
+Installation from PyPI
 
-This is the model card of a 🤗 transformers model that has been pushed on the Hub. This model card has been automatically generated.
+```bash
+pip install relik
+```
 
-- **Developed by:** [More Information Needed]
-- **Funded by [optional]:** [More Information Needed]
-- **Shared by [optional]:** [More Information Needed]
-- **Model type:** [More Information Needed]
-- **Language(s) (NLP):** [More Information Needed]
-- **License:** [More Information Needed]
-- **Finetuned from model [optional]:** [More Information Needed]
+<details>
+  <summary>Other installation options</summary>
 
-### Model Sources [optional]
+#### Install with optional dependencies
 
-<!-- Provide the basic links for the model. -->
+Install with all the optional dependencies.
 
-- **Repository:** [More Information Needed]
-- **Paper [optional]:** [More Information Needed]
-- **Demo [optional]:** [More Information Needed]
+```bash
+pip install relik[all]
+```
 
-## Uses
+Install with optional dependencies for training and evaluation.
 
-<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
+```bash
+pip install relik[train]
+```
 
-### Direct Use
+Install with optional dependencies for [FAISS](https://github.com/facebookresearch/faiss)
 
-<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
+FAISS PyPI package is only available for CPU. For GPU, install it from source or use the conda package.
 
-[More Information Needed]
+For CPU:
 
-### Downstream Use [optional]
+```bash
+pip install relik[faiss]
+```
 
-<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
+For GPU:
 
-[More Information Needed]
+```bash
+conda create -n relik python=3.10
+conda activate relik
 
-### Out-of-Scope Use
+# install pytorch
+conda install -y pytorch=2.1.0 pytorch-cuda=12.1 -c pytorch -c nvidia
 
-<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
+# GPU
+conda install -y -c pytorch -c nvidia faiss-gpu=1.8.0
+# or GPU with NVIDIA RAFT
+conda install -y -c pytorch -c nvidia -c rapidsai -c conda-forge faiss-gpu-raft=1.8.0
 
-[More Information Needed]
+pip install relik
+```
 
-## Bias, Risks, and Limitations
+Install with optional dependencies for serving the models with
+[FastAPI](https://fastapi.tiangolo.com/) and [Ray](https://docs.ray.io/en/latest/serve/quickstart.html).
 
-<!-- This section is meant to convey both technical and sociotechnical limitations. -->
+```bash
+pip install relik[serve]
+```
 
-[More Information Needed]
+#### Installation from source
 
-### Recommendations
+```bash
+git clone https://github.com/SapienzaNLP/relik.git
+cd relik
+pip install -e .[all]
+```
 
-<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
+</details>
 
-Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. More information needed for further recommendations.
+## 🚀 Quick Start
 
-## How to Get Started with the Model
+[//]: # (Write a short description of the model and how to use it with the `from_pretrained` method.)
 
-Use the code below to get started with the model.
+ReLiK is a lightweight and fast model for **Entity Linking** and **Relation Extraction**.
+It is composed of two main components: a retriever and a reader.
+The retriever is responsible for retrieving relevant documents from a large collection,
+while the reader is responsible for extracting entities and relations from the retrieved documents.
+ReLiK can be used with the `from_pretrained` method to load a pre-trained pipeline.
 
-[More Information Needed]
+Here is an example of how to use ReLiK for **Relation Extraction**:
 
-## Training Details
+```python
+from relik import Relik
+from relik.inference.data.objects import RelikOutput
 
-### Training Data
+relik = Relik.from_pretrained("sapienzanlp/relik-relation-extraction-nyt-large")
+relik_out: RelikOutput = relik("Michael Jordan was one of the best players in the NBA.")
+```
 
-<!-- This should link to a Dataset Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->
 
-[More Information Needed]
-
-### Training Procedure
-
-<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
-
-#### Preprocessing [optional]
-
-[More Information Needed]
-
-
-#### Training Hyperparameters
-
-- **Training regime:** [More Information Needed] <!--fp32, fp16 mixed precision, bf16 mixed precision, bf16 non-mixed precision, fp16 non-mixed precision, fp8 mixed precision -->
-
-#### Speeds, Sizes, Times [optional]
-
-<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
-
-[More Information Needed]
-
-## Evaluation
-
-<!-- This section describes the evaluation protocols and provides the results. -->
-
-### Testing Data, Factors & Metrics
-
-#### Testing Data
-
-<!-- This should link to a Dataset 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 Examination [optional]
-
-<!-- Relevant interpretability work for the model goes here -->
-
-[More Information Needed]
-
-## Environmental Impact
-
-<!-- Total emissions (in grams of CO2eq) and additional considerations, such as electricity usage, go here. Edit the suggested text below accordingly -->
-
-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).
-
-- **Hardware Type:** [More Information Needed]
-- **Hours used:** [More Information Needed]
-- **Cloud Provider:** [More Information Needed]
-- **Compute Region:** [More Information Needed]
-- **Carbon Emitted:** [More Information Needed]
-
-## Technical Specifications [optional]
-
-### Model Architecture and Objective
-
-[More Information Needed]
-
-### Compute Infrastructure
-
-[More Information Needed]
-
-#### Hardware
-
-[More Information Needed]
-
-#### Software
-
-[More Information Needed]
-
-## Citation [optional]
-
-<!-- If there is a paper or blog post introducing the model, the APA and Bibtex information for that should go in this section. -->
-
-**BibTeX:**
-
-[More Information Needed]
-
-**APA:**
-
-[More Information Needed]
-
-## Glossary [optional]
-
-<!-- If relevant, include terms and calculations in this section that can help readers understand the model or model card. -->
-
-[More Information Needed]
-
-## More Information [optional]
-
-[More Information Needed]
-
-## Model Card Authors [optional]
-
-[More Information Needed]
-
-## Model Card Contact
-
-[More Information Needed]
+    RelikOutput(
+      text='Michael Jordan was one of the best players in the NBA.', 
+      tokens=Michael Jordan was one of the best players in the NBA., 
+      id=0, 
+      spans=[
+        Span(start=0, end=14, label='--NME--', text='Michael Jordan'), 
+        Span(start=50, end=53, label='--NME--', text='NBA')
+      ], 
+      triplets=[
+        Triplets(
+          subject=Span(start=0, end=14, label='--NME--', text='Michael Jordan'), 
+          label='company', 
+          object=Span(start=50, end=53, label='--NME--', text='NBA'), 
+          confidence=1.0
+          )
+      ], 
+      candidates=Candidates(
+        span=[], 
+        triplet=[
+                  [
+                    [
+                      {"text": "company", "id": 4, "metadata": {"definition": "company of this person"}}, 
+                      {"text": "nationality", "id": 10, "metadata": {"definition": "nationality of this person or entity"}}, 
+                      {"text": "child", "id": 17, "metadata": {"definition": "child of this person"}}, 
+                      {"text": "founded by", "id": 0, "metadata": {"definition": "founder or co-founder of this organization, religion or place"}}, 
+                      {"text": "residence", "id": 18, "metadata": {"definition": "place where this person has lived"}},
+                      ...
+                  ]
+              ]
+          ]
+      ),
+    )
+
+
+## 📊 Performance
+
+The following table shows the results (Micro F1) of ReLiK Large on the NYT dataset:
+
+| Model                                    | NYT | NYT (Pretr) | AIT (m:s) |
+|------------------------------------------|------|-------|------------|
+| REBEL                                    | 93.1 | 93.4  | 01:45      |
+| UiE                                      | 93.5 | --    | --      |
+| USM                                      | 94.0 | 94.1  | --      |
+| ➡️ [ReLiK<sub>Large<sub>](https://huggingface.co/sapienzanlp/relik-relation-extraction-nyt-large) | **95.0** | **94.9**  | 00:30      |
+
+
+## 🤖 Models
+
+Models can be found on [🤗 Hugging Face](https://huggingface.co/collections/sapienzanlp/relik-retrieve-read-and-link-665d9e4a5c3ecba98c1bef19).
+
+## 💽 Cite this work
+
+If you use any part of this work, please consider citing the paper as follows:
+
+```bibtex
+@inproceedings{orlando-etal-2024-relik,
+    title     = "Retrieve, Read and LinK: Fast and Accurate Entity Linking and Relation Extraction on an Academic Budget",
+    author    = "Orlando, Riccardo and Huguet Cabot, Pere-Llu{\'\i}s and Barba, Edoardo and Navigli, Roberto",
+    booktitle = "Findings of the Association for Computational Linguistics: ACL 2024",
+    month     = aug,
+    year      = "2024",
+    address   = "Bangkok, Thailand",
+    publisher = "Association for Computational Linguistics",
+}
+```