Update README.md

README.md

@@ -7,4 +7,336 @@ tags:
 pipeline_tag: token-classification
 base_model:
 - team-lucid/deberta-v3-small-korean
----
+---
+
+
+
+## Intro 
+
+
+![image/png](https://cdn-uploads.huggingface.co/production/uploads/64993e268242893df52102a8/cZo8s2oHN8N37iU006XZC.png)
+
+
+
+GLiNER is a Named Entity Recognition (NER) model capable of identifying any entity type using a bidirectional transformer encoders (BERT-like). It provides a practical alternative to traditional NER models, which are limited to predefined entities, and Large Language Models (LLMs) that, despite their flexibility, are costly and large for resource-constrained scenarios.
+
+This particular version utilize bi-encoder architecture, where textual encoder is [team-lucid/DeBERTa v3 small](team-lucid/deberta-v3-small-korean) and entity label encoder is sentence transformer - [BAAI/bge-m3](https://huggingface.co/BAAI/bge-m3).
+
+Such architecture brings several advantages over uni-encoder GLiNER:
+
+- An unlimited amount of entities can be recognized at a single time;
+- Faster inference if entity embeddings are preprocessed;
+- Better generalization to unseen entities;
+
+However, it has some drawbacks such as a lack of inter-label interactions that make it hard for the model to disambiguate semantically similar but contextually different entities.
+
+
+- Paper: [https://arxiv.org/abs/2311.08526](https://arxiv.org/abs/2311.08526)
+- Repository: [https://github.com/urchade/GLiNER](https://github.com/urchade/GLiNER)
+- Service: https://github.com/henrikalbihn/gliner-as-a-service
+
+--- 
+## Installation & Usage
+
+Install or update the gliner package:
+
+```bash
+pip install gliner>=0.2.16
+pip install python-mecab-ko
+```
+
+Once you've downloaded the GLiNER library, you can import the GLiNER class. You can then load this model using `GLiNER.from_pretrained` and predict entities with `predict_entities`.
+
+```python
+from gliner import GLiNER
+
+model = GLiNER.from_pretrained("lots-o/gliner-bi-ko-small-v1")
+
+text = """크리스토퍼 놀란(Christopher Nolan) 은 영국의 영화 감독, 각본가, 영화 프로듀서이다. 그의 대표작으로는 2008년 개봉한 《다크 나이트》 시리즈가 있으며, 특히 《다크 나이트》(2008)의 감독으로 가장 유명하다. 이 영화는 배트맨 캐릭터를 중심으로 한 슈퍼히어로 영화로, 히스 레저의 조커 역할이 큰 인기를 끌었다. 또한, 2010년에 개봉한 《인셉션》(2010)은 복잡한 시간과 꿈의 개념을 다룬 SF 영화로, 영화 제작 방식과 스토리 전개에서 혁신적인 접근을 선보였다. 크리스토퍼 놀란은 시간 여행과 다차원적 이야기를 탐구하는 영화들을 통해 현대 영화계에서 중요한 감독으로 자리매김했다.
+"""
+
+labels = [
+    "영화/소설 작품명",
+    "사람 이름",
+    "캐릭터 이름",
+    "직업명",
+    "날짜_연(년)",
+    "날짜_일",
+    "날짜_달(월)",
+    "국가"
+]
+
+entities = model.predict_entities(text, labels, threshold=0.2)
+
+for entity in entities:
+    print(entity["text"], "=>", entity["label"])
+```
+
+```
+크리스토퍼 놀란 => 사람 이름
+Christopher Nolan => 사람 이름
+영국 => 국가
+영화 감독 => 직업명
+각본가 => 직업명
+영화 프로듀서 => 직업명
+2008년 => 날짜_연(년)
+다크 나이트 => 영화/소설 작품명
+다크 나이트 => 영화/소설 작품명
+2008 => 날짜_연(년)
+감독 => 직업명
+배트맨 => 캐릭터 이름
+히스 레저 => 사람 이름
+조커 => 캐릭터 이름
+2010년 => 날짜_연(년)
+인셉션 => 영화/소설 작품명
+2010 => 날짜_연(년)
+크리스토퍼 놀란 => 사람 이름
+감독 => 직업명
+```
+
+If you have a large amount of entities and want to pre-embed them, please, refer to the following code snippet:
+
+```python
+labels = ["your entities"]
+texts = ["your texts"]
+
+entity_embeddings = model.encode_labels(labels, batch_size = 8)
+
+outputs = model.batch_predict_with_embeds(texts, entity_embeddings, labels)
+```
+
+
+---
+
+## Dataset 
+- [국립국어원 모두의 말뭉치](https://kli.korean.go.kr/corpus/main/requestMain.do?lang=ko) 
+- [한국어 중첩 개체명 말뭉치(Korean Nested Named Entity Corpus)](https://github.com/korean-named-entity/konne)
+
+[TTA 150](https://www.korean.go.kr/front/reportData/reportDataView.do?mn_id=207&searchOrder=date&report_seq=1078&pageIndex=1)
+
+```python
+entity_type_mapping = {
+    "PS": {
+        "PS_NAME": "인물_사람",
+        "PS_CHARACTER": "인물_가상 캐릭터",
+        "PS_PET": "인물_반려동물",
+    },
+    "FD": {
+        "FD_SCIENCE": "학문 분야_과학",
+        "FD_SOCIAL_SCIENCE": "학문 분야_사회과학",
+        "FD_MEDICINE": "학문 분야_의학",
+        "FD_ART": "학문 분야_예술",
+        "FD_HUMANITIES": "학문 분야_인문학",
+        "FD_OTHERS": "학문 분야_기타",
+    },
+    "TR": {
+        "TR_SCIENCE": "이론_과학",
+        "TR_SOCIAL_SCIENCE": "이론_사회과학",
+        "TR_MEDICINE": "이론_의학",
+        "TR_ART": "이론_예술",
+        "TR_HUMANITIES": "이론_철학/언어/역사",
+        "TR_OTHERS": "이론_기타",
+    },
+    "AF": {
+        "AF_BUILDING": "인공물_건축물/토목건설물",
+        "AF_CULTURAL_ASSET": "인공물_문화재",
+        "AF_ROAD": "인공물_도로/철로",
+        "AF_TRANSPORT": "인공물_교통수단/운송수단",
+        "AF_MUSICAL_INSTRUMENT": "인공물_악기",
+        "AF_WEAPON": "인공물_무기",
+        "AFA_DOCUMENT": "인공물_도서/서적 작품명",
+        "AFA_PERFORMANCE": "인공물_춤/공연/연극 작품명",
+        "AFA_VIDEO": "인공물_영화/TV 프로그램",
+        "AFA_ART_CRAFT": "인공물_미술/조형 작품명",
+        "AFA_MUSIC": "인공물_음악 작품명",
+        "AFW_SERVICE_PRODUCTS": "인공물_서비스 상품",
+        "AFW_OTHER_PRODUCTS": "인공물_기타 상품",
+    },
+    "OG": {
+        "OGG_ECONOMY": "기관_경제",
+        "OGG_EDUCATION": "기관_교육",
+        "OGG_MILITARY": "기관_군사",
+        "OGG_MEDIA": "기관_미디어",
+        "OGG_SPORTS": "기관_스포츠",
+        "OGG_ART": "기관_예술",
+        "OGG_MEDICINE": "기관_의료",
+        "OGG_RELIGION": "기관_종교",
+        "OGG_SCIENCE": "기관_과학",
+        "OGG_LIBRARY": "기관_도서관",
+        "OGG_LAW": "기관_법률",
+        "OGG_POLITICS": "기관_정부/공공",
+        "OGG_FOOD": "기관_음식 업체",
+        "OGG_HOTEL": "기관_숙박 업체",
+        "OGG_OTHERS": "기관_기타",
+    },
+    "LC": {
+        "LCP_COUNTRY": "장소_국가",
+        "LCP_PROVINCE": "장소_도/주 지역",
+        "LCP_COUNTY": "장소_세부 행정구역",
+        "LCP_CITY": "장소_도시",
+        "LCP_CAPITALCITY": "장소_수도",
+        "LCG_RIVER": "장소_강/호수",
+        "LCG_OCEAN": "장소_바다",
+        "LCG_BAY": "장소_반도/만",
+        "LCG_MOUNTAIN": "장소_산/산맥",
+        "LCG_ISLAND": "장소_섬",
+        "LCG_CONTINENT": "장소_대륙",
+        "LC_SPACE": "장소_천체",
+        "LC_OTHERS": "장소_기타",
+    },
+    "CV": {
+        "CV_CULTURE": "문명_문명/문화",
+        "CV_TRIBE": "문명_민족/종족",
+        "CV_LANGUAGE": "문명_언어",
+        "CV_POLICY": "문명_제도/정책",
+        "CV_LAW": "문명_법/법률",
+        "CV_CURRENCY": "문명_통화",
+        "CV_TAX": "문명_조세",
+        "CV_FUNDS": "문명_연금/기금",
+        "CV_ART": "문명_예술",
+        "CV_SPORTS": "문명_스포츠",
+        "CV_SPORTS_POSITION": "문명_스포츠 포지션",
+        "CV_SPORTS_INST": "문명_스포츠 용품/도구",
+        "CV_PRIZE": "문명_상/훈장",
+        "CV_RELATION": "문명_가족/친족 관계",
+        "CV_OCCUPATION": "문명_직업",
+        "CV_POSITION": "문명_직위/직책",
+        "CV_FOOD": "문명_음식",
+        "CV_DRINK": "문명_음료/술",
+        "CV_FOOD_STYLE": "문명_음식 유형",
+        "CV_CLOTHING": "문명_의복/섬유",
+        "CV_BUILDING_TYPE": "문명_건축 양식",
+    },
+    "DT": {
+        "DT_DURATION": "날짜_기간",
+        "DT_DAY": "날짜_일",
+        "DT_WEEK": "날짜_주(주차)",
+        "DT_MONTH": "날짜_달(월)",
+        "DT_YEAR": "날짜_연(년)",
+        "DT_SEASON": "날짜_계절",
+        "DT_GEOAGE": "날짜_지질시대",
+        "DT_DYNASTY": "날짜_왕조시대",
+        "DT_OTHERS": "날짜_기타",
+    },
+    "TI": {
+        "TI_DURATION": "시간_기간",
+        "TI_HOUR": "시간_시각(시)",
+        "TI_MINUTE": "시간_분",
+        "TI_SECOND": "시간_초",
+        "TI_OTHERS": "시간_기타",
+    },
+    "QT": {
+        "QT_AGE": "수량_나이",
+        "QT_SIZE": "수량_넓이/면적",
+        "QT_LENGTH": "수량_길이/거리",
+        "QT_COUNT": "수량_수량/빈도",
+        "QT_MAN_COUNT": "수량_인원수",
+        "QT_WEIGHT": "수량_무게",
+        "QT_PERCENTAGE": "수량_백분율",
+        "QT_SPEED": "수량_속도",
+        "QT_TEMPERATURE": "수량_온도",
+        "QT_VOLUME": "수량_부피",
+        "QT_ORDER": "수량_순서",
+        "QT_PRICE": "수량_금액",
+        "QT_PHONE": "수량_전화번호",
+        "QT_SPORTS": "수량_스포츠 수량",
+        "QT_CHANNEL": "수량_채널 번호",
+        "QT_ALBUM": "수량_앨범 수량",
+        "QT_ADDRESS": "수량_주소 관련 숫자",
+        "QT_OTHERS": "수량_기타 수량",
+    },
+    "EV": {
+        "EV_ACTIVITY": "사건_사회운동/선언",
+        "EV_WAR_REVOLUTION": "사건_전쟁/혁명",
+        "EV_SPORTS": "사건_스포츠 행사",
+        "EV_FESTIVAL": "사건_축제/영화제",
+        "EV_OTHERS": "사건_기타",
+    },
+    "AM": {
+        "AM_INSECT": "동물_곤충",
+        "AM_BIRD": "동물_조류",
+        "AM_FISH": "동물_어류",
+        "AM_MAMMALIA": "동물_포유류",
+        "AM_AMPHIBIA": "동물_양서류",
+        "AM_REPTILIA": "동물_파충류",
+        "AM_TYPE": "동물_분류명",
+        "AM_PART": "동물_부위명",
+        "AM_OTHERS": "동물_기타",
+    },
+    "PT": {
+        "PT_FRUIT": "식물_과일/열매",
+        "PT_FLOWER": "식물_꽃",
+        "PT_TREE": "식물_나무",
+        "PT_GRASS": "식물_풀",
+        "PT_TYPE": "식물_분류명",
+        "PT_PART": "식물_부위명",
+        "PT_OTHERS": "식물_기타",
+    },
+    "MT": {
+        "MT_ELEMENT": "물질_원소",
+        "MT_METAL": "물질_금속",
+        "MT_ROCK": "물질_암석",
+        "MT_CHEMICAL": "물질_화학",
+    },
+    "TM": {
+        "TM_COLOR": "용어_색깔",
+        "TM_DIRECTION": "용어_방향",
+        "TM_CLIMATE": "용어_기후 지역",
+        "TM_SHAPE": "용어_모양/형태",
+        "TM_CELL_TISSUE_ORGAN": "용어_세포/조직/기관",
+        "TMM_DISEASE": "용어_증상/질병",
+        "TMM_DRUG": "용어_약품",
+        "TMI_HW": "용어_IT 하드웨어",
+        "TMI_SW": "용어_IT 소프트웨어",
+        "TMI_SITE": "용어_URL 주소",
+        "TMI_EMAIL": "용어_이메일 주소",
+        "TMI_MODEL": "용어_제품 모델명",
+        "TMI_SERVICE": "용어_IT 서비스",
+        "TMI_PROJECT": "용어_프로젝트",
+        "TMIG_GENRE": "용어_게임 장르",
+        "TM_SPORTS": "용어_스포츠",
+    },
+}
+```
+## Evaluation
+
+
+Evaluate with the [konne dev set](https://github.com/korean-named-entity/konne) :
+The evaluation results presented in the table below, except for the values I provided, were derived from the following source: [taeminlee/gliner_ko.](https://huggingface.co/taeminlee/gliner_ko)
+
+|             Model              | Precision(P) | Recall(R) |     F1     | 
+| :----------------------------: | :----------: | :-------: | :--------: | 
+| gliner-bi-ko-small-v1 (t=0.5)  |    81.53%    |  74.16%   |   77.67%   | 
+| gliner-bi-ko-xlarge-v1 (t=0.5) |  **84.73%**  |  77.71%   | **81.07%** | 
+|       Gliner-ko (t=0.5)        |    72.51%    |  79.82%   |   75.99%   | 
+|    Gliner Large-v2 (t=0.5)     |    34.33%    |  19.50%   |   24.87%   | 
+|      Gliner Multi (t=0.5)      |    40.94%    |  34.18%   |   37.26%   | 
+|             Pororo             |    70.25%    |  57.94%   |   63.50%   |
+
+
+
+--- 
+
+## Citation
+```bibtex
+@misc{gliner_bi_ko_small_v1,
+  title={gliner-bi-ko-small-v1},
+  author={Gihwan Kim},
+  year={2025},
+  url={https://huggingface.co/lots-o/gliner-bi-ko-small-v1}
+  publisher={Hugging Face}
+}
+
+```
+
+```bibtex
+@misc{zaratiana2023gliner,
+      title={GLiNER: Generalist Model for Named Entity Recognition using Bidirectional Transformer}, 
+      author={Urchade Zaratiana and Nadi Tomeh and Pierre Holat and Thierry Charnois},
+      year={2023},
+      eprint={2311.08526},
+      archivePrefix={arXiv},
+      primaryClass={cs.CL}
+}
+```
+