spaCy-PyThaiNLP

This package wraps the PyThaiNLP library to add Thai language support for spaCy.

Features

• Word Tokenization: Custom PyThaiNLPTokenizer preserving exact whitespace and token offsets, supporting custom dictionaries and engines (newmm, longest, attacut, etc.).
• Sentence Segmentation: Boundary detection preserving token integrity via PyThaiNLPSentencizer and engines like crfcut, whitespace, thaisum.
• Part-of-Speech Tagging: Supports Universal Dependencies tags (token.pos_) and fine-grained tags (token.tag_) across corpora (orchid_ud, pud, blackboard_ud, tdtb, tud, orchid).
• Named Entity Recognition: Flat NER (token.ents) and Nested NER (doc.spans) via PyThaiNLPNER.
• Dependency Parsing: Integration with PyThaiNLP's dependency parsers (esupar, etc.).
• Word Vectors: Word vector support via thai2fit_wv and other models.
• Text Normalization / Lemmatization: Thai text normalization via PyThaiNLPLemmatizer.
• Flexible Pipeline Architecture: Use the one-line spacy_pythainlp.load(), the blank model spacy_pythainlp.blank(), the all-in-one pythainlp pipe, or individual modular components.

Table of Contents

• Installation
• Quick Start
• Tokenizer & Custom Dictionaries
• Modular Components
• Usage Examples
  • Sentence Segmentation
  • Part-of-Speech Tagging
  • Named Entity Recognition
  • Dependency Parsing
  • Word Vectors
  • Lemmatization and Text Normalization
• All-in-One Configuration
• License

Installation

Prerequisites

• Python 3.9 or higher
• spaCy 3.0 or higher
• PyThaiNLP 3.1.0 or higher

Install via pip

pip install spacy-pythainlp

Quick Start

One-line Pipeline Loader

The easiest way to get started is with spacy_pythainlp.load():

import spacy_pythainlp

# Load Thai model with tokenizer, sentence segmentation, POS tagging, and NER
nlp = spacy_pythainlp.load()

doc = nlp("ผมเป็นคนไทย แต่มะลิอยากไปโรงเรียนส่วนผมจะไปไหน ผมอยากไปเที่ยว")

# Access sentences
for sent in doc.sents:
    print(sent.text)

# Access tokens and POS tags
for token in doc:
    print(f"{token.text}: {token.pos_} ({token.tag_})")

Standard spaCy Pipeline Setup

You can also add the pythainlp component to a blank model:

import spacy
import spacy_pythainlp

nlp = spacy.blank("th")
nlp.add_pipe("pythainlp")

doc = nlp("ผมเป็นคนไทย แต่มะลิอยากไปโรงเรียน")

Tokenizer & Custom Dictionaries

PyThaiNLPTokenizer preserves exact whitespace and character offsets, making doc.text identical to the input text.

import spacy
from spacy_pythainlp import PyThaiNLPTokenizer
from pythainlp.util import dict_trie

nlp = spacy.blank("th")

# Use a custom dictionary
custom_words = {"แอนตี้กราวิตี้", "ภาษาไทย"}
trie = dict_trie(dict_source=custom_words)

nlp.tokenizer = PyThaiNLPTokenizer(nlp.vocab, engine="newmm", custom_dict=trie)
doc = nlp("แอนตี้กราวิตี้และการประมวลผลภาษาไทย")

print([token.text for token in doc])

You can also create a blank model directly:

import spacy_pythainlp

nlp = spacy_pythainlp.blank("th", tokenize_engine="newmm")
doc = nlp("สวัสดีครับ วันนี้อากาศดี")

And in spaCy config files:

[nlp]
lang = "th"

[nlp.tokenizer]
@tokenizers = "pythainlp_tokenizer"
engine = "newmm"

Modular Components

Instead of enabling or disabling features in a single component, you can add individual modular components to any spaCy pipeline:

import spacy
import spacy_pythainlp

nlp = spacy_pythainlp.blank("th")

# Add only sentence segmentation
nlp.add_pipe("pythainlp_sentencizer", config={"engine": "crfcut"})

# Add only POS tagging
nlp.add_pipe("pythainlp_tagger", config={"corpus": "orchid_ud"})

# Add only NER
nlp.add_pipe("pythainlp_ner", config={"engine": "thainer"})

# Add only lemmatization / text normalization
nlp.add_pipe("pythainlp_lemmatizer", config={"normalize_text": True})

doc = nlp("วันที่ 15 กันยายน 2564 ทดสอบระบบที่กรุงเทพ")

Available component factories:

• "pythainlp_sentencizer": Sentence segmentation
• "pythainlp_tagger": Part-of-speech tagging
• "pythainlp_ner": Named entity recognition
• "pythainlp_parser": Dependency parsing
• "pythainlp_vectors": Word vectors
• "pythainlp_lemmatizer": Lemmatization and text normalization
• "pythainlp": All-in-one component (backward compatible)

Usage Examples

Sentence Segmentation

import spacy_pythainlp

nlp = spacy_pythainlp.load(sent=True, pos=False, ner=False)

doc = nlp("ผมเป็นคนไทย แต่มะลิอยากไปโรงเรียนส่วนผมจะไปไหน ผมอยากไปเที่ยว")

for i, sent in enumerate(doc.sents, 1):
    print(f"Sentence {i}: {sent.text}")

Part-of-Speech Tagging

import spacy_pythainlp

nlp = spacy_pythainlp.load(pos=True, pos_corpus="orchid_ud")

doc = nlp("ผมเป็นคนไทย")

for token in doc:
    print(f"{token.text}: UPOS={token.pos_}, TAG={token.tag_}")

Named Entity Recognition

import spacy_pythainlp

nlp = spacy_pythainlp.load(ner=True, ner_engine="thainer")

doc = nlp("วันที่ 15 กันยายน 2564 ทดสอบระบบที่กรุงเทพ")

for ent in doc.ents:
    print(f"{ent.text}: {ent.label_}")

Dependency Parsing

import spacy_pythainlp

nlp = spacy_pythainlp.load(dependency_parsing=True, dependency_parsing_engine="esupar")

doc = nlp("ผมเป็นคนไทย")

for token in doc:
    print(f"{token.text}: {token.dep_} <- {token.head.text}")

Word Vectors

import spacy_pythainlp

nlp = spacy_pythainlp.load(word_vector=True, word_vector_model="thai2fit_wv")

doc = nlp("แมว สุนัข")

token1 = doc[0]  # แมว
token2 = doc[1]  # สุนัข
print(f"Similarity: {token1.similarity(token2)}")

Lemmatization and Text Normalization

import spacy
import spacy_pythainlp

nlp = spacy_pythainlp.blank("th")
nlp.add_pipe("pythainlp_lemmatizer")

doc = nlp("สระ  เ เ ม ว")
for token in doc:
    print(f"{token.text} -> lemma: {token.lemma_}, norm: {token.norm_}")

All-in-One Configuration

You can customize the pythainlp pipeline component with config:

nlp.add_pipe(
    "pythainlp",
    config={
        "pos_engine": "perceptron",
        "pos": True,
        "pos_corpus": "orchid_ud",
        "sent_engine": "crfcut",
        "sent": True,
        "ner_engine": "thainer",
        "ner": True,
        "tokenize_engine": "newmm",
        "tokenize": False,
        "dependency_parsing": False,
        "dependency_parsing_engine": "esupar",
        "dependency_parsing_model": None,
        "word_vector": True,
        "word_vector_model": "thai2fit_wv"
    }
)

Configuration Options

Resources

• PyThaiNLP Documentation
• spaCy Documentation
• GitHub Repository
• Issue Tracker

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

   Copyright 2016-2026 PyThaiNLP Project

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.