Documentation for the RESTful API
Semantic Role Labeling Annotation with the Model API
To encourage the integration of Semantic Role Labeling into downstream applications,
the Model API offers a simple solution for out-of-the-box role labeling by providing
an interface to a full end-to-end state-of-the-art pretrained model
(Conia et al., 2021).
Semantic Role Labeling
Returns Semantic Role Labeling annotations for a given sentence. In particular, it identifies and
disambiguates the predicates in a sentence, and, for each predicate, it identifies and labels its arguments.
Method
POST
URL
https://verbatlas.org/api/model
Request body
Name |
Type |
Description |
documents |
List<Document> |
A list of documents to disambiguate.
|
Document
Name |
Type |
Description |
text |
String |
The document to disambiguate.
|
lang |
String |
Language of the document.
|
Example
Request body
curl -X 'POST' \
'https://verbatlas.org/api/model' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '[
{"text":"The quick brown fox jumps over the lazy dog.", "lang":"EN"},
{"text":"I walked along the river bank.", "lang":"EN"}
]'
Response
[
{
"tokens": [
{
"index": 0,
"rawText": "The"
},
{
"index": 1,
"rawText": "quick"
},
{
"index": 2,
"rawText": "brown"
},
{
"index": 3,
"rawText": "fox"
},
{
"index": 4,
"rawText": "jumps"
},
{
"index": 5,
"rawText": "over"
},
{
"index": 6,
"rawText": "the"
},
{
"index": 7,
"rawText": "lazy"
},
{
"index": 8,
"rawText": "dog"
},
{
"index": 9,
"rawText": "."
}
],
"annotations": [
{
"tokenIndex": 4,
"verbatlas": {
"frameName": "JUMP",
"roles": [
{
"role": "Theme",
"score": 1,
"span": [
0,
4
]
},
{
"role": "Destination",
"score": 1,
"span": [
5,
9
]
}
]
},
"englishPropbank": {
"frameName": "jump.03",
"roles": [
{
"role": "ARG0",
"score": 1,
"span": [
0,
4
]
},
{
"role": "ARG1",
"score": 1,
"span": [
5,
9
]
}
]
},
"chinesePropbank": {
"frameName": "ç¬.03",
"roles": [
{
"role": "A0",
"score": 1,
"span": [
0,
4
]
},
{
"role": "DIR",
"score": 1,
"span": [
5,
9
]
}
]
},
"germanPropbank": {
"frameName": "springen.1",
"roles": [
{
"role": "A0",
"score": 1,
"span": [
0,
4
]
},
{
"role": "A1",
"score": 1,
"span": [
5,
9
]
}
]
},
"pdtVallex": {
"frameName": "v-w7190f1",
"roles": []
},
"spanishAncora": {
"frameName": "asomar.d1",
"roles": [
{
"role": "arg0-exp",
"score": 1,
"span": [
0,
4
]
},
{
"role": "arg3-ori",
"score": 1,
"span": [
5,
6
]
},
{
"role": "arg1-tem",
"score": 1,
"span": [
6,
9
]
}
]
},
"catalanAncora": {
"frameName": "baixar.b1",
"roles": [
{
"role": "arg0-exp",
"score": 1,
"span": [
0,
4
]
},
{
"role": "arg3-ori",
"score": 1,
"span": [
5,
6
]
},
{
"role": "argM-loc",
"score": 1,
"span": [
6,
9
]
}
]
}
}
]
},
{
"tokens": [
{
"index": 0,
"rawText": "I"
},
{
"index": 1,
"rawText": "walked"
},
{
"index": 2,
"rawText": "along"
},
{
"index": 3,
"rawText": "the"
},
{
"index": 4,
"rawText": "river"
},
{
"index": 5,
"rawText": "bank"
},
{
"index": 6,
"rawText": "."
}
],
"annotations": [
{
"tokenIndex": 1,
"verbatlas": {
"frameName": "GO-FORWARD",
"roles": [
{
"role": "Agent",
"score": 1,
"span": [
0,
1
]
},
{
"role": "Location",
"score": 1,
"span": [
2,
6
]
}
]
},
"englishPropbank": {
"frameName": "walk.01",
"roles": [
{
"role": "ARG0",
"score": 1,
"span": [
0,
1
]
},
{
"role": "ARGM-DIR",
"score": 1,
"span": [
2,
6
]
}
]
},
"chinesePropbank": {
"frameName": "èµ°è·¯.01",
"roles": [
{
"role": "A0",
"score": 1,
"span": [
0,
1
]
},
{
"role": "LOC",
"score": 1,
"span": [
2,
6
]
}
]
},
"germanPropbank": {
"frameName": "wehen.1",
"roles": [
{
"role": "A0",
"score": 1,
"span": [
0,
1
]
},
{
"role": "A2",
"score": 1,
"span": [
2,
6
]
}
]
},
"pdtVallex": {
"frameName": "v-w9161f2",
"roles": []
},
"spanishAncora": {
"frameName": "caminar.d1",
"roles": [
{
"role": "arg0-agt",
"score": 1,
"span": [
0,
1
]
},
{
"role": "argM-loc",
"score": 1,
"span": [
2,
6
]
}
]
},
"catalanAncora": {
"frameName": "caminar.d1",
"roles": [
{
"role": "arg0-agt",
"score": 1,
"span": [
0,
1
]
},
{
"role": "argM-loc",
"score": 1,
"span": [
2,
6
]
}
]
}
}
]
}
]
Supported languages
Online
The Web interface of InVeRo-XL supports the following 12 languages.
- AR: Arabic
- CA: Catalan
- CS: Czech
- DE: German
- EN: English
- ES: Spanish
- FR: French
- IT: Italian
- NL: Dutch
- RU: Russian
- PT: Portuguese
- ZH: Chinese
Offline
The offline version of InVeRo-XL supports the following 45 languages. Download InVeRo-XL here.
- AF: Afrikaans
- AR: Arabic
- BG: Bulgarian
- CA: Catalan
- CS: Czech
- DA: Danish
- DE: German
- EL: Greek
- EN: English
- ES: Spanish
- ET: Estonian
- EU: Basque
- FA: Persian
- FI: Finnish
- FR: French
- GA: Irish
- HE: Hebrew
- HI: Hindi
- HR: Croatian
- HU: Hungarian
- HY: Armenian
- ID: Indonesian
- IT: Italian
- JA: Japanese
- KO: Korean
- LT: Lithuanian
- LV: Latvian
- MR: Marathi
- NL: Dutch
- NB: Norwegian
- PL: Polish
- PT: Portuguese
- RO: Romanian
- RU: Russian
- SK: Slovak
- SL: Slovenian
- SR: Serbian
- SV: Swedish
- TA: Tamil
- TE: Telugu
- TR: Turkish
- UK: Ukrainian
- UR: Urdu
- VI: Vietnamese
- ZH: Chinese
Using InVeRo-XL Offline
Where to download? Download InVeRo-XL here.
Available Docker images
We release different types of Docker images depending on the annotation style
you want to use and also depending on the hardware you have (i.e. CPU or GPU). In particular:
- invero-xl-span-[cpu|cuda] is the configuration that performs cross-lingual span-based SRL and is the one used by InVeRo-XL's Web server;
- invero-xl-dependency-[cpu|cuda] is an alternative configuration built to perform cross-lingual dependency-based SRL.
Requirements
In order to run InVeRo-XL offline, you need to install Docker. Please refer to its official documentation
to install it on your system.
How to launch your local instance of InVeRo-XL
To run a local instance of InVeRo-XL, users are required to perform a one-time setup to load one of the available images.
Let's say that we want to load invero-xl-span-cpu:
#!/bin/bash
docker load -i invero-xl-span-cpu-2.0.0.tar
After that, InVeRo-XL can be started by running the following commands:
#!/bin/bash
PORT=12345
LANGUAGES="EN FR IT ZH"
docker run \
--name invero-xl-span-cpu \
-p $PORT:80 \
-e LANGUAGES=$LANGUAGES \
invero-xl-span-cpu:2.0.0
This will run an invero-xl-span instance on CPU on port number 12345 loading the preprocessing
models for English, French, Italian and Chinese.
Running InVeRo-XL on your GPU
If you need GPU support, you can load the cuda version of an image, for example invero-xl-span-cuda.
Before using a cuda image, you have to load it, just like the CPU image:
#!/bin/bash
docker load -i invero-xl-span-cuda-2.0.0.tar
Then you can launch InVeRo-XL through the docker run command, with an
additional flag,
--gpus, for example:
#!/bin/bash
PORT=12345
LANGUAGES="EN FR IT ZH"
docker run \
--name invero-xl-span-cuda \
--gpus all \
-p $PORT:80 \
-e LANGUAGES=$LANGUAGES \
invero-xl-span-cuda:2.0.0
For more info about how to enable GPU support in Docker you can refer to the
official documentation.
Usage
InVeRo-XL exposes an end-point named /api/model. The endpoint accepts POST requests with a JSON body, containing a list of documents.
For each document, two parameters must be specified:
- text: a mandatory field that contains the text of the document
- lang: an optional field that indicates the language of the document. If omitted, InVeRo-XL will fasttext to detect the text language
Each request to the Model API returns a JSON response containing a list of output objects, one for each input document, containing
the automatic annotations according to each of the 7 linguistic inventories.
Let's try with a simple example. We want to disambiguate the words in the following sentence "The quick brown fox jumps over the lazy dog.":
curl -X 'POST' \
'http://127.0.0.1/api/model' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '[
{"text":"The quick brown fox jumps over the lazy dog.", "lang":"EN"},
]'
If everything went right, the output should be similar to:
[
{
"tokens": [
{
"index": 0,
"rawText": "The"
},
{
"index": 1,
"rawText": "quick"
},
{
"index": 2,
"rawText": "brown"
},
{
"index": 3,
"rawText": "fox"
},
{
"index": 4,
"rawText": "jumps"
},
{
"index": 5,
"rawText": "over"
},
{
"index": 6,
"rawText": "the"
},
{
"index": 7,
"rawText": "lazy"
},
{
"index": 8,
"rawText": "dog"
},
{
"index": 9,
"rawText": "."
}
],
"annotations": [
{
"tokenIndex": 4,
"verbatlas": {
"frameName": "JUMP",
"roles": [
{
"role": "Theme",
"score": 1,
"span": [
0,
4
]
},
{
"role": "Destination",
"score": 1,
"span": [
5,
9
]
}
]
},
"englishPropbank": {
"frameName": "jump.03",
"roles": [
{
"role": "ARG0",
"score": 1,
"span": [
0,
4
]
},
{
"role": "ARG1",
"score": 1,
"span": [
5,
9
]
}
]
},
"chinesePropbank": {
"frameName": "ç¬.03",
"roles": [
{
"role": "A0",
"score": 1,
"span": [
0,
4
]
},
{
"role": "DIR",
"score": 1,
"span": [
5,
9
]
}
]
},
"germanPropbank": {
"frameName": "springen.1",
"roles": [
{
"role": "A0",
"score": 1,
"span": [
0,
4
]
},
{
"role": "A1",
"score": 1,
"span": [
5,
9
]
}
]
},
"pdtVallex": {
"frameName": "v-w7190f1",
"roles": []
},
"spanishAncora": {
"frameName": "asomar.d1",
"roles": [
{
"role": "arg0-exp",
"score": 1,
"span": [
0,
4
]
},
{
"role": "arg3-ori",
"score": 1,
"span": [
5,
6
]
},
{
"role": "arg1-tem",
"score": 1,
"span": [
6,
9
]
}
]
},
"catalanAncora": {
"frameName": "baixar.b1",
"roles": [
{
"role": "arg0-exp",
"score": 1,
"span": [
0,
4
]
},
{
"role": "arg3-ori",
"score": 1,
"span": [
5,
6
]
},
{
"role": "argM-loc",
"score": 1,
"span": [
6,
9
]
}
]
}
}
]
}
]
Environment Variables
There are a few environment variables that can be passed to the docker container:
LANGUAGES
A list of languages, separated by whitespaces. This list indicates the preprocessing models to load with InVeRo-XL.
The SRL model of InVeRo-XL supports more tha 40 languages (see the
list of supported languages),
but each language requires loading its own preprocessing model. We suggest loading only those languages you need
so as to reduce the memory footprint of InVeRo-XL.
Default value
LANGUAGES="EN"
Example
Launching InVeRo-XL to disambiguate text in English, French and Italian.
docker run --name {$CONTAINER_NAME} -e LANGUAGES="EN FR IT" {$IMAGE_NAME}
TIMEOUT
When loading many languages, InVeRo-XL has to download multiple preprocessing models which may require a long time. If your container
crashes, try to increase this value.
Default value
TIMEOUT="500"
Example
Setting the TIMEOUT value to 1200.
docker run --name {$CONTAINER_NAME} -e TIMEOUT="1200" {$IMAGE_NAME}
MAX_WORKERS
Can be used to limit the number of simultaneously running processes (instances of InVeRo-XL).
Default value
MAX_WORKERS=1
Example
Setting the number of InVeRo-XL instances to 4
docker run --name {$CONTAINER_NAME} -e MAX_WORKERS="4" {$IMAGE_NAME}
WORKERS_PER_CORE
InVeRo-XL checks 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.
Default value
WORKERS_PER_CORE=1
Example
docker run --name {$CONTAINER_NAME} -e WORKERS_PER_CORE="3" {$IMAGE_NAME}
If you set the value to 3 in a server with 2 CPU cores, it will run 6 worker processes.
docker run --name {$CONTAINER_NAME} -e WORKERS_PER_CORE="0.5" {$IMAGE_NAME}
LOG_LEVEL
The log level for Gunicorn.
Supported values
debug
info
warning
error
critical
Default value
LOG_LEVEL="info"
Example
docker run --name {$CONTAINER_NAME} -e LOG_LEVEL="info" {$IMAGE_NAME}
FastAPI docs
Auto-generated interactive documentation for the API (thanks to FastAPI).
http://127.0.0.1:PORT/docs
where PORT is the port number you specify when starting up InVeRo-XL.
Semantic Information with the Resource API
The Resource API provides a RESTful interface to easily link predicate-level information, e.g.,
predicate lemmas and/or predicate senses, to VerbAtlas specific features, e.g., frames and semantic roles.
Predicate Information
Given a predicate (a lemma, a WordNet sense key, a WordNet synset ID or a BabelNet synset ID),
it returns the corresponding VerbAtlas frame(s).
Method
GET or POST
URL
/api/verbatlas/predicate?lemma=lemma
/api/verbatlas/predicate?wordnetSenseKey=wordnetSenseKey
/api/verbatlas/predicate?wordnetID=wordnetID
/api/verbatlas/predicate?babelnetID=babelnetID
Parameters
Name |
Type |
Description |
lemma |
String |
A predicate lemma, e.g., eat, drink, write, read...
|
wordnetSenseKey |
String |
A WordNet sense key, e.g., eat%2:34:00::
|
wordnetID |
String |
A WordNet synset ID, e.g., wn:01168468v.
|
babelnetID |
String |
A BabelNet synset ID, e.g., bn:00087460v
|
Request example
https://verbatlas.org/api/verbatlas/predicate?lemma=eat
Response
{
"bn:00085841v": {
"va_frame_id": "va:0139f",
"va_frame_name": "CORRODE_WEAR-AWAY_SCRATCH"
},
"bn:00085692v": {
"va_frame_id": "va:0135f",
"va_frame_name": "CONSUME_SPEND"
},
"bn:00087461v": {
"va_frame_id": "va:0051f",
"va_frame_name": "EAT_BITE"
},
"bn:00087460v": {
"va_frame_id": "va:0051f",
"va_frame_name": "EAT_BITE"
},
"bn:00087462v": {
"va_frame_id": "va:0051f",
"va_frame_name": "EAT_BITE"
},
"bn:00087463v": {
"va_frame_id": "va:0115f",
"va_frame_name": "EXPERIENCE-MENTAL-STATE"
}
}
Request example
Given a VerbAtlas frame ID, e.g. va:0001f, it returns all the predicates that belong to the given VerbAtlas frame.
Method
GET or POST
URL
/api/verbatlas/frame?verbatlasFrameID=verbatlasFrameID
Parameters
Name |
Type |
Description |
verbatlasFrameID |
String |
A VerbAtlas frame ID, e.g., va:0001f
|
Request Example
https://verbatlas.org/api/verbatlas/frame?verbatlasFrameID=va:0001f
Response
{
"predicate_argument_structure": [
"Agent",
"Theme",
"Beneficiary",
"Attribute"
],
"babelnet_synset_ids": [
"bn:00082138v",
"bn:00082200v",
"bn:00082203v",
"bn:00089416v",
"bn:00093787v",
"bn:00094745v",
"bn:00095007v"
],
"wordnet_synset_ids": [
"wn:00668099v",
"wn:00719231v",
"wn:00668805v",
"wn:00669099v",
"wn:00670179v",
"wn:00669630v",
"wn:02457585v"
]
}
PropBank to VerbAtlas: predicate sense mapping
Given a PropBank predicate sense (e.g. eat.01) it returns the corresponding VerbAtlas frame
(e.g. va:0051f/EAT_BITE).
Method
GET or POST
URL
/api/verbatlas/align/sense?propbankSenseID=propbankSenseID
Paremeters
Name |
Type |
Description |
propbankSenseID |
String |
A PropBank sense, e.g. eat.01
|
Request Example
https://verbatlas.org/api/verbatlas/align/sense?propbankSenseID=eat.01
Response
{
"va_frame_id": "va:0051f",
"va_frame_name": "EAT_BITE"
}
PropBank to VerbAtlas: semantic roles mapping
Given a PropBank predicate sense (e.g. eat.01) it
returns the mapping from its PropBank semantic roles to the corresponding VerbAtlas semantic roles.
Method
GET or POST
URL
/api/verbatlas/align/roles?propbankSenseID=propbankSenseID
Parameters
Name |
Type |
Description |
propbankSenseID |
String |
A PropBank sense, e.g. eat.01
|
Request Example
https://verbatlas.org/api/verbatlas/align/roles?propbankSenseID=eat.01
Response
{
"A0": "Agent",
"A1": "Patient"
}
Citation
If you use InVeRo-XL, please cite InVeRo-XL: Making Cross-Lingual Semantic Role Labeling Accessible with Intelligible Verbs and Roles:
@inproceedings{conia-etal-2021-invero-xl,
title = {{InVeRo-XL}: Making Cross-Lingual {S}emantic {R}ole {L}abeling Accessible with {I}ntelligible {V}erbs and {R}oles},
author = {Conia, Simone and Orlando, Riccardo and Brignone, Fabrizio and Cecconi, Francesco and Navigli, Roberto},
booktitle = {Proceedings of EMNLP},
year = {2021},
month = {nov},
address = {Punta Cana, Dominican Republic},
url = {https://aclanthology.org/2021.emnlp-demo.36/},
}
License
InVeRo-XL is licensed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0)
Acknowledgements
This project is part of the Universal Semantic Annotator (USeA)
project funded by the European Language Grid (ELG), Project Number 825627.