sapienzanlp/usea-preprocessing repository overview

This is the official repository for the paper Universal Semantic Annotator: the First Unified API for WSD, SRL and Semantic Parsing⁠, which will be presented at LREC 2022 by Riccardo Orlando⁠, Simone Conia⁠, Stefano Faralli⁠, and Roberto Navigli⁠.

⁠Cite this work

If you use USeA or any part of this work, please consider citing the paper as follows:

@inproceedings{orlando-etal-2022-usea,
    title      = "{U}niversal {S}emantic {A}nnotator: the First Unified {API} for {WSD}, {SRL} and {S}emantic {P}arsing",
    author     = "Orlando, Riccardo and Conia, Simone and Faralli, Stefano and Navigli, Roberto",
    booktitle  = "Proceedings of the 13th Language Resources and Evaluation Conference (LREC 2022)",
    month      = june,
    year       = "2022",
    address    = "Marseille, France",
    publisher  = "European Language Resources Association"
}

⁠Abstract

⁠Description

Universal Semantic Annotator (USeA) is the first unified API for three primary tasks in Natural Language Understanding (NLU):

• Word Sense Disambiguation (WSD): the task of assigning the most appropriate sense to a word in context;
• Semantic Role Labeling (SRL): the task of extracting the predicate-argument structures within a sentence;
• Semantic Parsing (Abstract Meaning Representation, AMR): the task of representing a text in a structured semantic graph.

The main motivations behind USeA are manifold: i) the creation of an easy-to-use tool and service for the automatic annotation of explicit semantic knowledge in 100 languages, ii) enabling the use of explicit semantics in multilingual and cross-lingual real-world applications, iii) the democratization of state-of-the-art systems that would otherwise require expert knowledge of the field for their development and implementation, and last but not least iv) fostering further research in NLU and other fields on the interplay between semantics and other modalities, e.g., computer vision, speech recognition, video understanding.

⁠Image Description

This repo is for the Docker image of the USeA preprocessing module. This image takes care of:

1. Receiving an HTTP/S request to process an input text;
2. Processing the input text (tokenization, pos tagging, lemmatization);
3. Returning the preprocessed text.

⁠How to use

⁠How to start a usea-preprocessing container

Make sure you have installed docker⁠ before proceeding, then run the following command:

docker run --name usea-preprocessing -p 22001:80 sapienzanlp/usea-preprocessing:1.0.0

If you want to run the container in the background, simply use the flag -d as follows:

docker run -d --name usea-preprocessing -p 22001:80 sapienzanlp/usea-preprocessing1.0.0

If everything went well, the container will become available at localhost:22001/api/preprocessing. You can check that everything is fine with the following Python script:

import requests
import json

text = "The quick brown fox jumps over the lazy dog."
response = requests.post(
    "http://localhost:22001/api/preprocessing", json={"text": text}
)
print(json.dumps(response.json(), indent=2))

⁠Stopping the container

Simply run:

docker stop usea-preprocessing

If you also want to remove the container:

docker stop usea-preprocessing
docker rm usea-preprocessing

⁠ENV Variables

There are few environment variables that can be passed to the docker container:

⁠TIMEOUT

Workers silent for more than this many seconds are killed and restarted. It is useful when loading multiple languages because it takes time to download all the preprocessing models. By default, TIMEOUT="500"

docker run --name usea-preprocessing -e TIMEOUT="1200" -p 22001:80 sapienzanlp/usea-preprocessing1.0.0

⁠WORKERS_PER_CORE

This image will check how many CPU cores are available in the current server running your container.

It will set the number of workers to the number of CPU cores multiplied by this value. By default, WORKERS_PER_CORE="1".

You can set it like:

docker run --name usea-preprocessing -e WORKERS_PER_CORE="3" -p 22001:80 sapienzanlp/usea-preprocessing1.0.0

If you used the value 3 in a server with 2 CPU cores, it would run 6 worker processes.

You can use floating point values too.

So, for example, if you have a big server (let's say, with 8 CPU cores) running several applications, and you have a FastAPI application that you know won't need high performance. And you don't want to waste server resources. You could make it use 0.5 workers per CPU core. For example:

docker run --name usea-preprocessing -e WORKERS_PER_CORE="0.5" -p 22001:80 sapienzanlp/usea-preprocessing1.0.0

In a server with 8 CPU cores, this would make it start only 4 worker processes.

⁠MAX_WORKERS

Can be used to limit the number of simultaneous process. By default, MAX_WORKERS="1".

docker run --name usea-preprocessing -e MAX_WORKERS="1" -p 22001:80 sapienzanlp/usea-preprocessing1.0.0

⁠LOG_LEVEL

The log level for Gunicorn.

One of:

• debug
• info
• warning
• error
• critical

By default, LOG_LEVEL="info".

docker run --name usea-preprocessing -e LOG_LEVEL="info" -p 22001:80 sapienzanlp/usea-preprocessing1.0.0

⁠FastAPI docs

http://127.0.0.1/docs

⁠Acknowledgements

The authors gratefully acknowledge the support of the European Language Grid project No. 825627 (Universal Semantic Annotator, USeA)⁠ under the European Union’s Horizon 2020 research and innovation programme.

⁠License

This work is under the Attribution-NonCommercial 4.0 International (CC BY-NC 4.0) license.