pysentimiento：用于情感分析和社会NLP任务的Python工具包

一个基于Transformer的SocialNLP任务库。

目前支持以下功能：

任务	语言
情感分析	西班牙语、英语、意大利语、葡萄牙语
仇恨言论检测	西班牙语、英语、意大利语、葡萄牙语
反讽检测	西班牙语、英语、意大利语、葡萄牙语
情感分析	西班牙语、英语、意大利语、葡萄牙语
命名实体识别与词性标注	西班牙语、英语
上下文感知的仇恨言论检测	西班牙语
针对性情感分析	西班牙语

只需运行 pip install pysentimiento 即可开始使用：

快速入门

from pysentimiento import create_analyzer
analyzer = create_analyzer(task="sentiment", lang="es")

analyzer.predict("Qué gran jugador es Messi")
# 返回 AnalyzerOutput(output=POS, probas={POS: 0.998, NEG: 0.002, NEU: 0.000})
analyzer.predict("Esto es pésimo")
# 返回 AnalyzerOutput(output=NEG, probas={NEG: 0.999, POS: 0.001, NEU: 0.000})
analyzer.predict("Qué es esto?")
# 返回 AnalyzerOutput(output=NEU, probas={NEU: 0.993, NEG: 0.005, POS: 0.002})

analyzer.predict("jejeje no te creo mucho")
# AnalyzerOutput(output=NEG, probas={NEG: 0.587, NEU: 0.408, POS: 0.005})
"""
英语中的情感分析
"""

emotion_analyzer = create_analyzer(task="emotion", lang="en")

emotion_analyzer.predict("yayyy")
# 返回 AnalyzerOutput(output=joy, probas={joy: 0.723, others: 0.198, surprise: 0.038, disgust: 0.011, sadness: 0.011, fear: 0.010, anger: 0.009})
emotion_analyzer.predict("fuck off")
# 返回 AnalyzerOutput(output=anger, probas={anger: 0.798, surprise: 0.055, fear: 0.040, disgust: 0.036, joy: 0.028, others: 0.023, sadness: 0.019})

"""
仇恨言论（厌女症与种族主义）
"""
hate_speech_analyzer = create_analyzer(task="hate_speech", lang="es")

hate_speech_analyzer.predict("Esto es una mierda pero no es odio")
# 返回 AnalyzerOutput(output=[], probas={hateful: 0.022, targeted: 0.009, aggressive: 0.018})
hate_speech_analyzer.predict("Esto es odio porque los inmigrantes deben ser aniquilados")
# 返回 AnalyzerOutput(output=['hateful'], probas={hateful: 0.835, targeted: 0.008, aggressive: 0.476})

hate_speech_analyzer.predict("Vaya guarra barata y de poca monta es XXXX!")
# 返回 AnalyzerOutput(output=['hateful', 'targeted', 'aggressive'], probas={hateful: 0.987, targeted: 0.978, aggressive: 0.969})

更多关于支持的任务和语言的详细信息，以及每个经过基准测试的模型的性能报告，请参阅 TASKS。

此外，还可以查看这些包含如何使用 pysentimiento 的示例笔记本：

• 西班牙语 + 英语
• 意大利语
• 葡萄牙语
• 上下文感知的仇恨言论——西班牙语

预处理

pysentimiento 提供了一个专为基于Transformer的模型进行推文分类而设计的推文预处理器。

from pysentimiento.preprocessing import preprocess_tweet

# 将用户句柄和URL替换为特殊标记
preprocess_tweet("@perezjotaeme debería cambiar esto http://bit.ly/sarasa") # "@usuario debería cambiar esto url"

# 缩短重复字符
preprocess_tweet("no entiendo naaaaaaaadaaaaaaaa", shorten=2) # "no entiendo naadaa"

# 规范化笑声表达
preprocess_tweet("jajajajaajjajaajajaja no lo puedo creer ajajaj") # "jaja no lo puedo creer jaja"

# 处理标签
preprocess_tweet("esto es #UnaGenialidad")
# "esto es una genialidad"

# 处理表情符号
preprocess_tweet("🎉🎉", lang="en")
# 'emoji party popper emoji emoji party popper emoji'

开发者指南

0. 克隆并安装

git clone https://github.com/pysentimiento/pysentimiento
pip install poetry
poetry shell
poetry install

1. 运行脚本训练模型

有关如何训练您自己的模型的更多信息，请参阅 TRAIN.md。

注意：您需要访问数据集，而这些数据集目前尚未公开。请发送电子邮件给我们以获取访问权限。

2. 将模型上传到Hugging Face Model Hub

请参阅 huggingface 文档中的“模型共享与上传”说明。

许可证

pysentimiento 是一个开源库。但是，请注意，模型是使用第三方数据集训练的，并受其各自许可证的约束，其中许多仅限于非商业用途。

1. TASS数据集许可证（西班牙语情感分析、西班牙语和英语情感分析的许可证）

2. SEMEval 2017数据集许可证（英语情感分析）

3. LinCE数据集（命名实体识别与词性标注的许可证）

建议与错误修复

请使用仓库的问题跟踪器来指出错误并提出建议（新模型、使用其他数据集、支持其他语言等）。

引用

如果您在工作中使用了 pysentimiento，请引用这篇论文。

@misc{perez2021pysentimiento,
      title={pysentimiento: A Python Toolkit for Opinion Mining and Social NLP tasks}, 
      author={Juan Manuel Pérez and Mariela Rajngewerc and Juan Carlos Giudici and Damián A. Furman and Franco Luque and Laura Alonso Alemany and María Vanina Martínez},
      year={2023},
      eprint={2106.09462},a
      archivePrefix={arXiv},
      primaryClass={cs.CL}
}

此外，请同时引用您所使用的特定模型的相关预训练模型和数据集。详细信息请参阅 REFERENCES。

pysentimiento 快速上手指南

pysentimiento 是一个基于 Transformer 的 Python 工具包，专为社交网络自然语言处理（SocialNLP）任务设计。它支持情感分析、仇恨言论检测、反讽识别、情绪分析及命名实体识别等任务，覆盖西班牙语、英语、意大利语和葡萄牙语。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：建议 Python 3.7 及以上
• 前置依赖：无需额外安装深度学习框架，pysentimiento 会自动处理相关依赖（如 transformers, torch 等）。

安装步骤

使用 pip 直接安装：

pip install pysentimiento

提示：国内开发者若遇到下载速度慢的问题，可使用清华或阿里镜像源加速安装：

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

基本使用

1. 情感分析 (Sentiment Analysis)

以下示例演示如何对西班牙语文本进行情感分析（支持正向 POS、负向 NEG、中性 NEU）：

from pysentimiento import create_analyzer

# 创建西班牙语情感分析器
analyzer = create_analyzer(task="sentiment", lang="es")

# 预测示例
result = analyzer.predict("Qué gran jugador es Messi")
print(result.output) 
# 输出: POS

result = analyzer.predict("Esto es pésimo")
print(result.output) 
# 输出: NEG

# 查看具体概率分布
print(result.probas)
# 输出: {'NEG': 0.999, 'POS': 0.001, 'NEU': 0.000}

2. 情绪分析 (Emotion Analysis)

支持英语等多语言的情绪分类（如 joy, anger, sadness 等）：

# 创建英语情绪分析器
emotion_analyzer = create_analyzer(task="emotion", lang="en")

result = emotion_analyzer.predict("yayyy")
print(result.output) 
# 输出: joy

result = emotion_analyzer.predict("fuck off")
print(result.output) 
# 输出: anger

3. 仇恨言论检测 (Hate Speech Detection)

检测文本是否包含仇恨、针对性攻击或侵略性内容：

# 创建西班牙语仇恨言论检测器
hate_speech_analyzer = create_analyzer(task="hate_speech", lang="es")

result = hate_speech_analyzer.predict("Esto es odio porque los inmigrantes deben ser aniquilados")
print(result.output) 
# 输出: ['hateful']

print(result.probas)
# 输出: {'hateful': 0.835, 'targeted': 0.008, 'aggressive': 0.476}

4. 推文预处理 (可选)

针对社交媒体文本（如 Twitter），提供了专门的预处理函数，可处理用户提及、URL、重复字符、表情符号等：

from pysentimiento.preprocessing import preprocess_tweet

# 替换用户提及和 URL
text = preprocess_tweet("@perezjotaeme debería cambiar esto http://bit.ly/sarasa")
# 结果: "@usuario debería cambiar esto url"

# 缩短重复字符
text = preprocess_tweet("no entiendo naaaaaaaadaaaaaaaa", shorten=2)
# 结果: "no entiendo naadaa"

# 规范化笑声
text = preprocess_tweet("jajajajaajjajaajajaja no lo puedo creer")
# 结果: "jaja no lo puedo creer jaja"

# 处理标签和表情
text = preprocess_tweet("esto es #UnaGenialidad")
# 结果: "esto es una genialidad"

更多支持的任务（如反讽检测、NER、POS tagging）及语言组合，请参考官方文档或直接在 create_analyzer 中更改 task 和 lang 参数尝试。