pyabsa

PyABSA: A Modularized Framework for Reproducible Aspect-based Sentiment Analysis

PyABSA is a modular, reproducible framework for Aspect-based Sentiment Analysis (ABSA) — from research to production. It unifies training/evaluation/inference across ABSA subtasks, ships with ready-to-use checkpoints, and offers dataset tooling and metric visualization.

• 📄 Paper: CIKM 2023 [ACM DL]
• 📚 Docs: https://pyabsa.readthedocs.io/
• 🧪 Examples: examples-v2/
• 🧰 Dataset hub: ABSADatasets
• 🌐 Online demos: see links below

Getting Started

Welcome to PyABSA! This guide will walk you through the initial steps to get you up and running with the framework.

Prerequisites

Make sure you have Python 3.8 or later installed on your system. You can check your Python version by running:

python --version

Installation

For a straightforward installation, you can use pip:

pip install -U pyabsa

This command installs the core components of PyABSA. For more advanced features like text augmentation and visualization, you may need to install additional dependencies.

Your First Code

After installation, you can start using PyABSA with just a few lines of code. Here’s a simple example to get you started:

from pyabsa import AspectTermExtraction as ATEPC

# Initialize the aspect extractor
aspect_extractor = ATEPC.AspectExtractor('multilingual', auto_device=True)

# Perform aspect extraction on a sample sentence
result = aspect_extractor.predict(
    ['I love this movie, it is so great!'],
    save_result=True,
    print_result=True
)

Features at a Glance

• Unified API for training / evaluation / inference across ABSA tasks
• Model Zoo with available_checkpoints() and auto-download
• Visualization for evaluation metrics
• Human-in-the-loop dataset annotation helpers
• Text augmentation for classification & adversarial defense
• Automatic device selection; simple CPU/GPU switching

See the Introduction for the full feature list.

Supported Tasks

Task	What it does	Python API entry	Demo
APC (Aspect Polarity Classification)	Classify sentiment for a given aspect	pyabsa.AspectPolarityClassification	Multilingual APC (HF Space)
ATEPC (Aspect Term Extraction & Polarity Classification)	Extract aspect terms and their sentiment	pyabsa.AspectTermExtraction	ATEPC (HF Space)
ASTE (Aspect Sentiment Triplet Extraction)	Extract (aspect, opinion, sentiment) triplets	pyabsa.AspectSentimentTripletExtraction	Triplet Extraction (HF Space)
ASQP / ACOS	Extract (aspect, category, opinion, sentiment) quadruples	pyabsa.AspectCategoryOpinionSentimentTripletExtraction	Quadruple Extraction (HF Space)
Others	Text classification, adversarial defense, etc.	pyabsa.TextClassification, pyabsa.TextAdversarialDefense, ...	–

Full list and

tutorials: Supported Tasks · Tutorials

Installation

PyPI (recommended):

pip install -U pyabsa

From source (latest mainline):

git clone https://github.com/yangheng95/PyABSA --depth=1
cd PyABSA
python setup.py install

Requirements: Python >= 3.8; PyTorch and Transformers will be installed as dependencies. For advanced/optional dependencies (augmentation, visualization, demos), see the Installation guide.

Quickstart

1) Extract aspect terms and classify their sentiments (ATEPC)

from pyabsa import AspectTermExtraction as ATEPC, available_checkpoints

# View available checkpoints (local + remote)
print(available_checkpoints())

aspect_extractor = ATEPC.AspectExtractor(
    'multilingual',
    auto_device=True,  # False -> force CPU
    cal_perplexity=True
)

# Single instance
aspect_extractor.predict(
    ['I love this movie, it is so great!'],
    save_result=True,
    print_result=True,
    ignore_error=True
)

# Batch inference from a built-in dataset
inference_source = ATEPC.ATEPCDatasetList.Restaurant16
result = aspect_extractor.batch_predict(
    target_file=inference_source,
    save_result=True,
    print_result=True,
    pred_sentiment=True
)
print(result)

2) Aspect-based sentiment classification (APC)

from pyabsa import AspectPolarityClassification as APC, available_checkpoints

print(available_checkpoints(show_ckpts=True))

classifier = APC.SentimentClassifier(
    'multilingual',
    auto_device=True,
    cal_perplexity=True
)

classifier.predict(
    ['I love this movie, it is so great!'],
    save_result=True,
    print_result=True,
    ignore_error=True
)

inference_source = APC.APCDatasetList.Laptop14
apc_result = classifier.batch_predict(
    target_file=inference_source,
    save_result=True,
    print_result=True,
    pred_sentiment=True
)
print(apc_result)

More examples (training, evaluation, visualization, deployment): see examples-v2/ and Tutorials.

Model Zoo & Checkpoints

• List all available checkpoints:

  from pyabsa import available_checkpoints
  print(available_checkpoints())
  

• PyABSA resolves checkpoints across local/remote registries and auto-downloads when needed. See the docs for * CheckpointManager* and API Reference.

Datasets

• Public & community-contributed datasets: ABSADatasets
• To prepare your own datasets (format, semi-automatic annotation, naming conventions), see Integrated Datasets and Notice in the docs.
• You can also use built-in dataset enums (e.g., APC.APCDatasetList.Laptop14, ATEPC.ATEPCDatasetList.Restaurant16) to run quick experiments.

Documentation

• Overview & features: Introduction
• Installation & optional components: Installation
• Task tutorials (train/infer/deploy): Tutorials
• API Reference: API Reference

Roadmap (indicative)

• Python 3.13 compatibility verification and wheels
• Extended dataset templates & validators
• Streamlined model registry and checkpoint metadata
• Better Hugging Face integration (Spaces & model cards)
• Optional plugins: advanced augmentation, evaluation dashboards

Have a suggestion? Please open a GitHub Discussion or Issue.

Known Limitations

• v2 introduced breaking API changes; older scripts may need updates.
• Some checkpoints require a one-time download at first use.
• GPU is optional but recommended for training and large-scale inference.
• Certain advanced features have extra dependencies; see the Installation guide.

Citation

If you use PyABSA in your research or products, please cite:

CIKM 2023

@inproceedings{YangZL23,
    author = {Heng Yang and Chen Zhang and Ke Li},
    title = {PyABSA: A Modularized Framework for Reproducible Aspect-based Sentiment Analysis},
    booktitle = {Proceedings of the 32nd ACM International Conference on Information and Knowledge Management (CIKM 2023)},
    pages = {5117--5122},
    year = {2023},
    doi = {10.1145/3583780.3614752}
}

arXiv 2022 (optional)

@article{YangL22,
    author = {Heng Yang and Ke Li},
    title = {PyABSA: Open Framework for Aspect-based Sentiment Analysis},
    journal = {CoRR},
    volume = {abs/2208.01368},
    year = {2022},
    doi = {10.48550/arXiv.2208.01368}
}

Contributing

Contributions are welcome! You can:

• Share custom datasets via ABSADatasets
• Integrate your models (with or without PyABSA base—we can help adapt)
• Report bugs, improve messages & docs, or add example scripts
• Propose features or refactors

Guidelines

• Use Python 3.8+; please run at least one GPU and one CPU pass for examples before submitting.
• Keep changes reproducible (seeds, configs) and scoped.
• In PR description, summarize motivation and impact.

Community and Support

Join our community to stay updated, ask questions, and contribute to the project.

• GitHub Discussions: For questions, feature requests, and discussions.
• Issue Tracker: To report bugs and track issues.
• Contributing: We welcome contributions! Please see our contributing guidelines for more details.

License

MIT License © PyABSA contributors