PyABSA：用于可复现方面级情感分析的模块化框架

PyABSA 是一个 模块化、可复现 的 方面级情感分析（ABSA） 框架——从研究到生产。它统一了 ABSA 各子任务的训练、评估和推理，附带开箱即用的检查点，并提供数据集工具和指标可视化功能。

• 📄 论文: CIKM 2023 [ACM DL]
• 📚 文档: https://pyabsa.readthedocs.io/
• 🧪 示例: examples-v2/
• 🧰 数据集中心: ABSADatasets
• 🌐 在线演示: 见下方链接

---

快速入门

欢迎使用 PyABSA！本指南将引导您完成框架的初始设置和使用步骤。

前提条件

请确保您的系统已安装 Python 3.8 或更高版本。您可以通过运行以下命令检查 Python 版本：

python --version

安装

要进行简单安装，您可以使用 pip：

pip install -U pyabsa

此命令将安装 PyABSA 的核心组件。如需使用文本增强和可视化等高级功能，可能需要安装额外的依赖项。

第一段代码

安装完成后，只需几行代码即可开始使用 PyABSA。以下是一个简单的示例：

from pyabsa import AspectTermExtraction as ATEPC

# 初始化方面提取器
aspect_extractor = ATEPC.AspectExtractor('multilingual', auto_device=True)

# 对示例句子进行方面提取
result = aspect_extractor.predict(
    ['我喜欢这部电影，太棒了！'],
    save_result=True,
    print_result=True
)

---

功能概览

• 面向 ABSA 各任务的 统一 API，用于训练、评估和推理
• 包含 available_checkpoints() 和自动下载功能的 模型库
• 用于评估指标的 可视化工具
• 支持 人机协作 的数据标注辅助工具
• 用于分类及对抗防御的 文本增强功能
• 自动设备选择；轻松切换 CPU/GPU

更多功能详情，请参阅 简介。

---

支持的任务

任务	功能描述	Python API 入口	演示
APC（方面极性分类）	对给定方面的情感进行分类	pyabsa.AspectPolarityClassification	多语言 APC（HF Space）
ATEPC（方面术语提取与极性分类）	提取方面术语及其情感	pyabsa.AspectTermExtraction	ATEPC（HF Space）
ASTE（方面情感三元组提取）	提取 (方面, 观点, 情感) 三元组	pyabsa.AspectSentimentTripletExtraction	三元组提取（HF Space）
ASQP / ACOS	提取 (方面, 类别, 观点, 情感) 四元组	pyabsa.AspectCategoryOpinionSentimentTripletExtraction	四元组提取（HF Space）
其他	文本分类、对抗防御等	pyabsa.TextClassification, pyabsa.TextAdversarialDefense, ...	–

完整列表及教程：支持的任务 · 教程

---

安装

通过 PyPI（推荐）：

pip install -U pyabsa

从源码安装（最新主分支）：

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

要求: Python >= 3.8；PyTorch 和 Transformers 将作为依赖项自动安装。有关高级或可选依赖项（增强、可视化、演示），请参阅 安装指南。

---

快速入门

1) 提取方面术语并分类其情感 (ATEPC)

from pyabsa import AspectTermExtraction as ATEPC, available_checkpoints

# 查看可用检查点（本地 + 远程）
print(available_checkpoints())

aspect_extractor = ATEPC.AspectExtractor(
    'multilingual',
    auto_device=True,  # False -> 强制使用 CPU
    cal_perplexity=True
)

# 单个实例
aspect_extractor.predict(
    ['我喜欢这部电影，太棒了！'],
    save_result=True,
    print_result=True,
    ignore_error=True
)

# 使用内置数据集进行批量推理
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) 基于方面的情感分类 (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(
    ['我爱这部电影，太棒了！'],
    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)

更多示例（训练、评估、可视化、部署）：请参阅 examples-v2/ 和 教程。

---

模型库与检查点

• 列出所有可用的检查点：

  from pyabsa import available_checkpoints
  print(available_checkpoints())
  

• PyABSA 会跨本地和远程注册表解析检查点，并在需要时自动下载。有关详细信息，请参阅文档中的 * CheckpointManager* 和 API 参考。

---

数据集

• 公开及社区贡献的数据集：ABSADatasets
• 如需准备您自己的数据集（格式、半自动标注、命名规范），请参阅文档中的 集成数据集 和 注意事项。
• 您也可以使用内置的数据集枚举（例如 APC.APCDatasetList.Laptop14、ATEPC.ATEPCDatasetList.Restaurant16） 来快速进行实验。

---

文档

• 概述与功能：简介
• 安装与可选组件：安装
• 任务教程（训练/推理/部署）：教程
• API 参考：API 参考

---

路线图（参考）

• 验证 Python 3.13 兼容性并生成轮子包
• 扩展数据集模板与验证器
• 简化模型注册表和检查点元数据
• 改进与 Hugging Face 的集成（Spaces 和模型卡片）
• 可选插件：高级数据增强、评估仪表板

您有建议吗？请在 GitHub 上发起讨论或提交问题。

---

已知限制

• v2 引入了破坏性 API 更改；旧脚本可能需要更新。
• 部分检查点首次使用时需要一次性下载。
• GPU 是可选的，但建议用于训练和大规模推理。
• 某些高级功能具有额外依赖项；请参阅安装指南。

---

引用

如果您在研究或产品中使用 PyABSA，请引用以下文献：

CIKM 2023

@inproceedings{YangZL23,
    author = {Heng Yang and Chen Zhang and Ke Li},
    title = {PyABSA：用于可重复方面情感分析的模块化框架},
    booktitle = {第32届 ACM 国际信息与知识管理会议论文集（CIKM 2023）},
    pages = {5117--5122},
    year = {2023},
    doi = {10.1145/3583780.3614752}
}

arXiv 2022（可选）

@article{YangL22,
    author = {Heng Yang and Ke Li},
    title = {PyABSA：面向方面情感分析的开源框架},
    journal = {CoRR},
    volume = {abs/2208.01368},
    year = {2022},
    doi = {10.48550/arXiv.2208.01368}
}

---

贡献

欢迎您的贡献！您可以：

• 通过 ABSADatasets 分享自定义数据集
• 集成您的模型（无论是否基于 PyABSA——我们可以帮助适配）
• 报告 bug、改进提示信息和文档，或添加示例脚本
• 提出新功能或重构建议

指南

• 使用 Python 3.8 及以上版本；提交前请至少在 GPU 和 CPU 上各运行一次示例。
• 保持更改的可重复性（种子、配置）并明确范围。
• 在 PR 描述中总结动机和影响。

---

社区与支持

加入我们的社区，以获取最新动态、提问并为项目做出贡献。

• GitHub 讨论区：用于提问、功能请求和讨论。
• 问题跟踪器：用于报告 bug 和跟踪问题。
• 贡献：我们欢迎您的贡献！更多详情请参阅我们的贡献指南。

---

许可证

MIT 许可证 © PyABSA 贡献者

---

PyABSA 快速上手指南

PyABSA 是一个模块化、可复现的**方面级情感分析（ABSA）**框架，支持从研究到生产的全流程。它统一了训练、评估和推理接口，并提供开箱即用的预训练模型。

1. 环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：3.8 或更高版本
  • 检查命令：python --version
• 硬件建议：
  • 推理：CPU 即可运行，但推荐使用 GPU 以获得更快响应。
  • 训练：强烈建议使用 NVIDIA GPU。
• 依赖项：安装时会自动安装 PyTorch 和 Transformers 等核心依赖。

国内加速提示：若下载依赖较慢，建议在 pip 命令后添加清华或阿里镜像源（见下文安装步骤）。

2. 安装步骤

方式一：通过 PyPI 安装（推荐）

使用 pip 直接安装最新稳定版。

标准安装：

pip install -U pyabsa

使用国内镜像源加速（推荐中国开发者）：

pip install -U pyabsa -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：从源码安装（获取最新特性）

如果您需要体验最新的开发版功能：

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

3. 基本使用

安装完成后，只需几行代码即可进行方面词提取和情感分类（ATEPC 任务）。以下示例展示了如何加载多语言模型并对句子进行预测。

最简单的使用示例

from pyabsa import AspectTermExtraction as ATEPC

# 1. 初始化方面提取器
# 'multilingual': 使用多语言预训练模型
# auto_device=True: 自动检测并使用 GPU，若无 GPU 则使用 CPU
aspect_extractor = ATEPC.AspectExtractor('multilingual', auto_device=True)

# 2. 执行预测
# 首次运行时会自动下载模型checkpoint
result = aspect_extractor.predict(
    ['I love this movie, it is so great!'],
    save_result=True,   # 保存结果到本地
    print_result=True   # 在控制台打印结果
)

进阶：批量推理

如果您已有数据集文件或想使用内置数据集进行批量测试：

from pyabsa import AspectTermExtraction as ATEPC

aspect_extractor = ATEPC.AspectExtractor('multilingual', auto_device=True)

# 使用内置的 Restaurant16 数据集进行批量预测
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)

其他支持任务

PyABSA 还支持多种 ABSA 子任务，调用方式类似：

• 方面情感分类 (APC): from pyabsa import AspectPolarityClassification as APC
• 方面情感三元组提取 (ASTE): from pyabsa import AspectSentimentTripletExtraction
• 四元组提取 (ASQP/ACOS): from pyabsa import AspectCategoryOpinionSentimentTripletExtraction

更多详细教程、训练脚本及可视化功能，请访问官方文档：https://pyabsa.readthedocs.io/