Underthesea documentation

Vietnamese NLP Toolkit

Underthesea - Vietnamese NLP Toolkit

https://img.shields.io/pypi/v/underthesea.svg https://img.shields.io/pypi/pyversions/underthesea.svg https://img.shields.io/badge/license-GNU%20General%20Public%20License%20v3-brightgreen.svg https://img.shields.io/travis/undertheseanlp/underthesea.svg Documentation Status https://img.shields.io/badge/chat-on%20facebook-green.svg

https://raw.githubusercontent.com/undertheseanlp/underthesea/master/logo.jpg

underthesea is a suite of open source Python modules, data sets and tutorials supporting research and development in Vietnamese Natural Language Processing.

💫 Version 1.3.0 out now! Underthesea meet deep learning!

Free software GNU General Public License v3
Live demo undertheseanlp.com
Colab notebooks latest / stable
Documentation Underthesea Documentation
Facebook Underthesea Page
Youtube Underthesea NLP Channel

Installation

To install underthesea, simply:

$ pip install underthesea
✨🍰✨

Satisfaction, guaranteed.

Usage

1. Sentence Segmentation

Usage

>>> # -*- coding: utf-8 -*-
>>> from underthesea import sent_tokenize
>>> text = 'Taylor cho biết lúc đầu cô cảm thấy ngại với cô bạn thân Amanda nhưng rồi mọi thứ trôi qua nhanh chóng. Amanda cũng thoải mái với mối quan hệ này.'

>>> sent_tokenize(text)
[
    "Taylor cho biết lúc đầu cô cảm thấy ngại với cô bạn thân Amanda nhưng rồi mọi thứ trôi qua nhanh chóng.",
    "Amanda cũng thoải mái với mối quan hệ này."
]

2. Word Segmentation

Usage

>>> # -*- coding: utf-8 -*-
>>> from underthesea import word_tokenize
>>> sentence = 'Chàng trai 9X Quảng Trị khởi nghiệp từ nấm sò'

>>> word_tokenize(sentence)
['Chàng trai', '9X', 'Quảng Trị', 'khởi nghiệp', 'từ', 'nấm', 'sò']

>>> word_tokenize(sentence, format="text")
'Chàng_trai 9X Quảng_Trị khởi_nghiệp từ nấm sò'

3. POS Tagging

Usage

>>> # -*- coding: utf-8 -*-
>>> from underthesea import pos_tag
>>> pos_tag('Chợ thịt chó nổi tiếng ở Sài Gòn bị truy quét')
[('Chợ', 'N'),
 ('thịt', 'N'),
 ('chó', 'N'),
 ('nổi tiếng', 'A'),
 ('ở', 'E'),
 ('Sài Gòn', 'Np'),
 ('bị', 'V'),
 ('truy quét', 'V')]

4. Chunking

Usage

>>> # -*- coding: utf-8 -*-
>>> from underthesea import chunk
>>> text = 'Bác sĩ bây giờ có thể thản nhiên báo tin bệnh nhân bị ung thư?'
>>> chunk(text)
[('Bác sĩ', 'N', 'B-NP'),
 ('bây giờ', 'P', 'I-NP'),
 ('có thể', 'R', 'B-VP'),
 ('thản nhiên', 'V', 'I-VP'),
 ('báo tin', 'N', 'B-NP'),
 ('bệnh nhân', 'N', 'I-NP'),
 ('bị', 'V', 'B-VP'),
 ('ung thư', 'N', 'I-VP'),
 ('?', 'CH', 'O')]

5. Dependency Parsing

Usage

>>> # -*- coding: utf-8 -*-
>>> from underthesea import dependency_parse
>>> text = 'Tối 29/11, Việt Nam thêm 2 ca mắc Covid-19'
>>> dependency_parse(text)
[('Tối', 5, 'obl:tmod'),
 ('29/11', 1, 'flat:date'),
 (',', 1, 'punct'),
 ('Việt Nam', 5, 'nsubj'),
 ('thêm', 0, 'root'),
 ('2', 7, 'nummod'),
 ('ca', 5, 'obj'),
 ('mắc', 7, 'nmod'),
 ('Covid-19', 8, 'nummod')]

6. Named Entity Recognition

Usage

>>> # -*- coding: utf-8 -*-
>>> from underthesea import ner
>>> text = 'Chưa tiết lộ lịch trình tới Việt Nam của Tổng thống Mỹ Donald Trump'
>>> ner(text)
[('Chưa', 'R', 'O', 'O'),
 ('tiết lộ', 'V', 'B-VP', 'O'),
 ('lịch trình', 'V', 'B-VP', 'O'),
 ('tới', 'E', 'B-PP', 'O'),
 ('Việt Nam', 'Np', 'B-NP', 'B-LOC'),
 ('của', 'E', 'B-PP', 'O'),
 ('Tổng thống', 'N', 'B-NP', 'O'),
 ('Mỹ', 'Np', 'B-NP', 'B-LOC'),
 ('Donald', 'Np', 'B-NP', 'B-PER'),
 ('Trump', 'Np', 'B-NP', 'I-PER')]

7. Text Classification

Download models

$ underthesea download-model TC_GENERAL
$ underthesea download-model TC_BANK

Usage

>>> # -*- coding: utf-8 -*-
>>> from underthesea import classify

>>> classify('HLV đầu tiên ở Premier League bị sa thải sau 4 vòng đấu')
['The thao']
>>> classify('Hội đồng tư vấn kinh doanh Asean vinh danh giải thưởng quốc tế')
['Kinh doanh']

>> classify('Lãi suất từ BIDV rất ưu đãi', domain='bank')
['INTEREST_RATE']

8. Sentiment Analysis

Download models

$ underthesea download-model SA_GENERAL
$ underthesea download-model SA_BANK

Usage

>>> # -*- coding: utf-8 -*-
>>> from underthesea import sentiment

>>> sentiment('hàng kém chất lg,chăn đắp lên dính lông lá khắp người. thất vọng')
negative
>>> sentiment('Sản phẩm hơi nhỏ so với tưởng tượng nhưng chất lượng tốt, đóng gói cẩn thận.')
positive

>>> sentiment('Đky qua đường link ở bài viết này từ thứ 6 mà giờ chưa thấy ai lhe hết', domain='bank')
['CUSTOMER_SUPPORT#negative']
>>> sentiment('Xem lại vẫn thấy xúc động và tự hào về BIDV của mình', domain='bank')
['TRADEMARK#positive']

9. Vietnamese NLP Resources

List resources

$ underthesea list-data
| Name         | Type        | License   |   Year | Directory             |
|--------------+-------------+-----------+--------+-----------------------|
| UTS2017-BANK | Categorized | Open      |   2017 | datasets/UTS2017-BANK |
| VNESES       | Plaintext   | Open      |   2012 | datasets/LTA          |
| VNTQ_BIG     | Plaintext   | Open      |   2012 | datasets/LTA          |
| VNTQ_SMALL   | Plaintext   | Open      |   2012 | datasets/LTA          |
| VNTC         | Categorized | Open      |   2007 | datasets/VNTC         |

$ underthesea list-data --all

Download resources

$ underthesea download-data VNTC
100%|██████████| 74846806/74846806 [00:09<00:00, 8243779.16B/s]
Resource VNTC is downloaded in ~/.underthesea/datasets/VNTC folder

Up Coming Features

  • Machine Translation
  • Text to Speech
  • Automatic Speech Recognition

Contributing

Do you want to contribute with underthesea development? Great! Please read more details at CONTRIBUTING.rst.

AUTHORS

Original Authors

Awesome Contributors

Thanks

Thanks to all the wonderful folks who have contributed to schedule over the years

History

6.1.3 (2023-02-25)

6.1.2 (2023-02-15)

6.1.1 (2023-02-10)

6.1.0 (2023-02-08)

6.0.3 (2023-01-25)

6.0.2 (2023-01-17)

Full Changelog: https://github.com/undertheseanlp/underthesea/compare/v6.0.1…v6.0.2

6.0.1 (2023-01-08)

6.0.0 (2023-01-01)

  • Happy New Year 2023! Let’s bump up the version! (GH-616)

1.4.1 (2022-12-17)

  • Create underthesea app (GH-607)
  • Add viet2ipa module (GH-437)
  • Training NER model with VLSP2016 dataset using BERT (GH-437)
  • Remove unidecode as a dependency (GH-569)

1.3.5 (2022-10-31)

  • Add Text Normalization module (GH-534)
  • Release underthesea_core version 0.0.5a2 (GH-550)
  • Support GLIBC_2.17 (GH-530)
  • Update resources path (GH-540)
  • Fix function word_tokenize (GH-528)

1.3.4 (2022-01-08)

  • Demo chatbot with rasa (GH-513)
  • Lite version of underthesea (GH-505)
  • Increase word_tokenize speed 1.5 times (GH-185)
  • Add build for windows (GH-185)

1.3.3 (2021-09-02)

  • Update torch and transformer dependency (GH-403)

1.3.2 (2021-08-04)

  • Publish two ABSA open datasets (GH-417)
  • Migrate from travis-ci to github actions (GH-410)
  • Update ParserTrainer (GH-392)
  • Add pipeline folder (GH-351)

1.3.1 (2021-01-11)

  • Compatible with newer version of scikit-learn (GH-313)
  • Retrain classification and sentiment models with latest version of scikit-learn (GH-381)
  • Add ClassifierTrainer (from languageflow) (GH-381)
  • Add 3 new datasets (GH-351)
  • [Funny Update] Change underthesea’s avatar (GH-371)
  • [CI] Add Stale App: Automatically close stale Issues and Pull Requests that tend to accumulate during a project (GH-351)

1.3.0 (2020-12-11)

  • Remove languageflow dependency (GH-364)
  • Remove tabulate dependency (GH-364)
  • Remove scores in text classification and sentiment section (GH-351)
  • Add information of dependency_parse module in info function (GH-351)
  • Try to use Github Actions (GH-353)
  • Dependency Parsing (GH-157)

1.2.3 (2020-11-28)

  • Refactor config for resources (GH-300)
  • Thêm API xử lý dữ liệu (GH-299)

1.2.2 (2020-11-04)

  • Remove nltk strict version (GH-308)
  • Add word_hyphen rule (GH-290)
  • Sanity check python version (GH-320)
  • Handle exception case in sentiment module (GH-321)
  • Cập nhật quản lý resources từ languageflow (GH-295)
  • Loại bỏ languageflow trong quá trình cài đặt (GH-295)
  • Cập nhật phiên bản fasttext (GH-304)

1.1.16 (2019-06-15)

  • Bumping up version of the languageflow dependency (GH-231)
  • Update phiên bản scikit-learn 0.20.2 (GH-229)
  • Cập nhật lại các dependencies (GH-241)
  • Cập nhật mô hình trên bộ dữ liệu VNTC (GH-246)
  • Cập nhật mô hình trên bộ dữ liệu UTS2017_BANK_TC (GH-243)
  • Cập nhật mô hình trên bộ dữ liệu UTS2017_BANK_SA (GH-244)
  • Lỗi với các câu sentiment ở demo (GH-236)
  • Thống nhất cách đặt tên và quản lý model (GH-225)

1.1.12 (2019-03-13)

  • Add sentence segmentation feature

1.1.9 (2019-01-01)

  • Improve speed of word_tokenize function
  • Only support python 3.6+
  • Use flake8 for style guide enforcement

1.1.8 (2018-06-20)

  • Fix word_tokenize error when text contains tab (t) character
  • Fix regex_tokenize with url

1.1.7 (2018-04-12)

  • Rename word_sent function to word_tokenize
  • Refactor version control in setup.py file and __init__.py file
  • Update documentation badge url

1.1.6 (2017-12-26)

  • New feature: aspect sentiment analysis
  • Integrate with languageflow 1.1.6
  • Fix bug tokenize string with ‘=’ (#159)

1.1.5 (2017-10-12)

  • New feature: named entity recognition
  • Refactor and update model for word_sent, pos_tag, chunking

1.1.4 (2017-09-12)

  • New feature: text classification
  • [bug] Fix Text error
  • [doc] Add facebook link

1.1.3 (2017-08-30)

1.1.2 (2017-08-22)

  • Add dictionary

1.1.1 (2017-07-05)

  • Support Python 3
  • Refactor feature_engineering code

1.1.0 (2017-05-30)

  • Add chunking feature
  • Add pos_tag feature
  • Add word_sent feature, fix performance
  • Add Corpus class
  • Add Transformer classes
  • Integrated with dictionary of Ho Ngoc Duc
  • Add travis-CI, auto build with PyPI

1.0.0 (2017-03-01)

  • First release on PyPI.
  • First release on Readthedocs

The API Documentation / Guide

If you are looking for information on a specific function, class, or method, this part of the documentation is for you.

Developer Interface

word_tokenize

underthesea.word_tokenize(sentence, format=None, use_token_normalize=True, fixed_words=[])[source]

Vietnamese word segmentation

Parameters:
  • sentence (str) – raw sentence
  • format (str, optional) – format option. Defaults to None. use format=`text` for text format
  • use_token_normalize (bool) – True if use token_normalize
  • fixed_words (list) – list of fixed words
Returns:

word tokens
Return type:

list of str

Examples

>>> # -*- coding: utf-8 -*-
>>> from underthesea import word_tokenize
>>> sentence = "Bác sĩ bây giờ có thể thản nhiên báo tin bệnh nhân bị ung thư"

>>> word_tokenize(sentence)
["Bác sĩ", "bây giờ", "có thể", "thản nhiên", "báo tin", "bệnh nhân", "bị", "ung thư"]

>>> word_tokenize(sentence, format="text")
"Bác_sĩ bây_giờ có_thể thản_nhiên báo_tin bệnh_nhân bị ung_thư"

pos_tag

underthesea.pos_tag(sentence, format=None)[source]

Vietnamese POS tagging

Parameters:sentence ({unicode, str}) – Raw sentence
Returns:tokens – tagged sentence
Return type:list of tuple with word, pos tag

Examples

>>> # -*- coding: utf-8 -*-
>>> from underthesea import pos_tag
>>> sentence = "Chợ thịt chó nổi tiếng ở TPHCM bị truy quét"
>>> pos_tag(sentence)
[('Chợ', 'N'),
('thịt', 'N'),
('chó', 'N'),
('nổi tiếng', 'A'),
('ở', 'E'),
('TPHCM', 'Np'),
('bị', 'V'),
('truy quét', 'V')]

chunking

underthesea.chunk(sentence, format=None)[source]

Vietnamese chunking

Parameters:sentence ({unicode, str}) – raw sentence
Returns:tokens – tagged sentence
Return type:list of tuple with word, pos tag, chunking tag

Examples

>>> # -*- coding: utf-8 -*-
>>> from underthesea import chunk
>>> sentence = "Nghi vấn 4 thi thể Triều Tiên trôi dạt bờ biển Nhật Bản"
>>> chunk(sentence)
[('Nghi vấn', 'N', 'B-NP'),
('4', 'M', 'B-NP'),
('thi thể', 'N', 'B-NP'),
('Triều Tiên', 'Np', 'B-NP'),
('trôi dạt', 'V', 'B-VP'),
('bờ biển', 'N', 'B-NP'),
('Nhật Bản', 'Np', 'B-NP')]

ner

underthesea.ner(sentence, format=None, deep=False)[source]

Location and classify named entities in text

Parameters:sentence ({unicode, str}) – raw sentence
Returns:tokens
Return type:list of tuple with word, pos tag, chunking tag, ner tag tagged sentence

Examples

>>> # -*- coding: utf-8 -*-
>>> from underthesea import ner
>>> sentence = "Ông Putin ca ngợi những thành tựu vĩ đại của Liên Xô"
>>> ner(sentence)
[('Ông', 'Nc', 'B-NP', 'O'),
('Putin', 'Np', 'B-NP', 'B-PER'),
('ca ngợi', 'V', 'B-VP', 'O'),
('những', 'L', 'B-NP', 'O'),
('thành tựu', 'N', 'B-NP', 'O'),
('vĩ đại', 'A', 'B-AP', 'O'),
('của', 'E', 'B-PP', 'O'),
('Liên Xô', 'Np', 'B-NP', 'B-LOC')]

classify

Install dependencies and download default model

$ pip install Cython
$ pip install future scipy numpy scikit-learn
$ pip install -U fasttext --no-cache-dir --no-deps --force-reinstall
$ underthesea data
underthesea.classify(X, domain=None)[source]

Text classification

Parameters:
  • X ({unicode, str}) – raw sentence
  • domain ({None, 'bank'}) –
    domain of text
    • None: general domain
    • bank: bank domain
Returns:

tokens – categories of sentence
Return type:

list

sentiment

Install dependencies

$ pip install future scipy numpy scikit-learn==0.19.2 joblib
underthesea.sentiment(X, domain='general')[source]

Sentiment Analysis

Parameters:
  • X (str) – raw sentence
  • domain (str) – domain of text (bank or general). Default: general
Returns:

  • Text (Text of input sentence)
  • Labels (Sentiment of sentence)

Examples

>>> from underthesea import sentiment
>>> sentence = "Chuyen tiền k nhận Dc tiên"
>>> sentiment(sentence, domain='bank')
[MONEY_TRANSFER#negative (1.0)]

viet2ipa

underthesea.pipeline.ipa.viet2ipa(text: str, *args, **kwargs)[source]

Generate ipa of the syllable

Vietnamese syllabic structure (Anh & Trang 2022)

syllable = onset + rhyme + tone

rhyme = medial + nuclear vowel + (coda)

Parameters:
  • text (str) – represents syllable
  • dialect (str) – Either the string “north” or “south”. Default: north
  • eight (boolean) – If true, use eight tone format, else use six tone format. Default: False
  • tone (str) – Either the string “ipa” or “number”. Default: number
Returns:

A string. Represents ipa of the syllable

Examples

>>> # -*- coding: utf-8 -*-
>>> from underthesea.pipeline.ipa import viet2ipa
>>> viet2ipa("trồng")
tɕoŋ³²

Indices and tables