简介：pycantonese是一个面向Python开发者的粤语语言学与自然语言处理工具库，专门解决粤语文本中的Jyutping拼音转换、词语切分、词性标注与停用词过滤等核心问题，适用于粤语语料分析、语音教学、情感分析和信息提取等场景。资源包内含294个文件，压缩包总大小15.46MB，文件类型丰富，以py源码、html在线文档、rst说明、txt语料以及woff字体等为主，既提供了可直接调用的库代码，也附带完整的API文档、使用示例和语言学语料素材，便于开发者快速上手和深入扩展。目前已有689人学习下载。该工具将复杂的粤语处理流程封装为简洁接口，支持与NLTK、spaCy等主流NLP框架配合使用，能够显著降低粤语NLP任务的开发门槛，无论是从事方言研究的学者，还是构建粤语应用的工程师，都能从中获得高效、可复用的技术支撑。 做中文NLP的人，多半默认一个前提：中文就是普通话。分词用jieba跑一段，词向量用预训练模型跑一版，仿佛“中文”在NLP世界里从来不需要加限定词。但一旦你的文本里有“我哋今日去咗街”这种句子，这一整套流水线基本就卡住了——切分乱、词性错、连做个字转拼音都尴尬到没法看。
所以我第一次看到pycantonese这个库的时候，第一反应是：终于有人把粤语从笼统的“中文NLP”里单拎出来认真做了。它不是花架子，而是把粤语语料、粤拼转换、分词、词性标注这些基础功能打包成了一个Python库，方便做粤语语言学研究、粤语语料分析，以及各种粤语NLP落地项目的人直接调用。这篇文章我不打算照抄官方文档，而是从实际使用和踩坑的角度，把pycantonese能干什么、怎么装、怎么用、有哪些坑，一次性讲透，适合正在入门NLP、或者需要处理粤语文本的Python开发者参考。
1. 粤语NLP为什么需要单独一套工具：通用中文模型的天然短板
1.1 粤语和普通话的语法词汇差异，直接决定模型效果
粤语虽然属于汉语方言，但在NLP语境里，它几乎可以当作一门独立语言来看待。词汇层面，“食饭”“倾偈”“得闲”分别对应普通话的“吃饭”“聊天”“有空”；语法层面，粤语的“我大过你”（我比你大）这种比较句式，和普通话语序完全不同；语气助词“喇”“㗎”“咩”在粤语里高频出现，但在普通话文本里几乎见不到。
这些差异带来的结果是：基于普通话语料训练出来的分词模型和词性标注模型，放到粤语口语文本上，准确率会肉眼可见地下降。常见的情况有两种，一种是“我哋”这种粤语特色词，被通用分词器切成“我”和“哋”两个无意义单元，下游任务跟着错；另一种是“俾”“喺”“咗”这类高频功能词，根本不在通用模型的词表里，模型只能瞎猜。
1.2 pycantonese的定位：语料、拼音、分词一体化
pycantonese是一个开源Python库，目标很直接：给粤语研究者和开发者提供一套开箱即用的基础工具。它内置了香港粤语标注语料库（HKCAC），支持粤拼和耶鲁拼音转换，能做粤语分词和词性标注，还可以与NLTK无缝衔接。说白了，它想把“粤语NLP分析”这件事的起点成本降下来，让你不需要先去吭哧吭哧找语料、清洗数据、训练拼音模型，装完库直接就能干活。
用一句话概括：如果普通话NLP的基础设施是jieba加哈工大LTP，那粤语NLP的基础设施里，pycantonese是绕不开的那块地基。
2. 安装与第一印象：一条pip命令背后的资源准备
2.1 安装命令与版本选择
安装本身没什么特别，标准做法：
pip install pycantonese建议在Python 3.8以上的环境里安装，这既是对依赖库兼容性的考虑，也避免老版本Python在使用类型注解和异步下载时出现莫名其妙的问题。如果你平时做NLP项目已经习惯用conda管理环境，可以新建一个干净环境再装：
conda create -n pycantonese python=3.10 -y conda activate pycantonese pip install pycantonese2.2 首次运行会触发语料下载，很多人卡在这一步
装完库不等于所有数据都在本地。pycantonese的部分功能，尤其是语料库访问，会在第一次调用时才从远程拉取数据。整个下载过程是异步的，所以首次运行时需要稍微等一会儿。
这里有个常见的误解：有人以为安装失败，因为import之后没有立刻看到语料目录。其实资源解压后默认存在用户目录下的某个隐藏文件夹里，具体位置可以参考库的包内路径。想稳妥一点，可以提前手动确认网络能连通项目托管地址，避免在公司代理环境下出现SSL证书校验失败这类问题。
我见过很多人在这一步打退堂鼓，但我实际体验下来，语料文件的大小在几十MB量级，正常网络环境下等待时间完全可以接受。下载完成后，离线使用也没问题，只有当你要访问在线更新或重新初始化数据时才需要再次联网。
3. 逐项拆解核心功能：语料库、分词、粤拼与繁简转换
3.1 内置语料库：香港粤语标注语料（HKCAC）
pycantonese最值钱的家底，是它自带的香港粤语标注语料库。通过一行代码就能加载：
import pycantonese as pc corpus = pc.hkcancor()这个语料库里包含大量真实的粤语口语转写文本，每一条都做了分词、词性标注，并且标注了对应的粤拼。拿到语料对象之后，可以按词条、按词性过滤，也可以直接遍历带标注的标记序列：
for token in corpus.tokens(): print(token)每个token通常是(word, tag, jyutping)这种结构，也就是词语本身、词性标签、粤拼读音三件套。这意味着做音韵研究、词频统计、词性分布分析的时候，你不需要再另外找一份带拼音的词表去对齐，语料库已经帮你对齐好了。
3.2 分词：粤语分词的颗粒度比普通话更难把握
分词是NLP的基础工序，粤语分词比普通话麻烦得多。因为粤语书面语没有统一规范，同一个词在不同场景下可能写作“唔使”“唔使喇”或“唔使啦”，切分边界经常模糊。pycantonese提供的分词接口很简洁：
result = pc.segment("我哋今日去咗街") print(result)返回结果是分词后的列表。它和jieba最大的不同在于，pycantonese的分词行为更贴近粤语语料库的标注习惯，而不是普通话的通用词表。对于“去咗”这种“动词+体貌助词”结构，它会尽量遵循语法单元而不是无脑按单字切，这在做文本挖掘时能省下不少清洗时间。
不过要注意，分词往往跟领域有关。pycantonese的模型和语料以香港粤语口语为主，处理广州粤语书面语或者海外粤语社区文本时，表现会有波动。所以我在项目中通常把它作为第一层切分工具，根据具体文本再叠加自定义词典或后处理规则。
3.3 粤拼与耶鲁拼音转换：整词、逐字都能查
粤语拼音系统有好几套，pycantonese主要支持粤拼和耶鲁拼音。最常见的用法是给一个词返回拼音列表：
pc.jyutping("你好")输出类似：
['nei5', 'hou2']也有按单字查全部读音的场景，比如人名、地名，或者遇到多音字想确认所有可能读音：
pc.char_to_jyutping("中")返回结果会把“中”字的多个读音列出来，带声调数字标记。熟悉粤拼的人知道，数字代表声调，1到6分别对应不同调类。这个功能在语言学研究里特别实用，比如统计一段文本的字频、音调分布，或者做粤语古诗朗读辅助工具，都能直接用。
如果你只熟悉耶鲁拼音，也可以切到对应接口。两种拼音体系各有适用场景，粤拼是目前学界和词典用得多的方案，耶鲁拼音则在一些老教材和海外场景出现率较高。一个库同时支持两套，免去了自己写映射表的工作。
3.4 繁简转换与字符集处理
粤语文本经常是繁体字为主，但也混着简体、异体字和特殊语气字。pycantonese提供了简单的繁简转换能力，虽然它没有OpenCC那么全面，但对于语料库里出现的字词基本够用。更重要的是，它处理粤语特殊字符时比通用转换工具稳得多，不会把“嘅”“啲”“唔”这种字强行转成简体而丢失语义。
在我实际做语料清洗时，通常搭配规则是：先用pycantonese做基础繁简统一，再用OpenCC处理大规模简体繁体转换，最后人工校验一小部分粤语专用字。这个组合在效率和准确率上比较均衡。
4. 和NLTK结合：把粤语处理嵌入标准NLP工作流
4.1 为什么NLTK集成是关键一步
很多刚开始做NLP的人会问：pycantonese自己不是能分词、能标词性吗，为什么还要提NLTK？原因在于，NLP项目的完整链路远不只是分词和词性标注，还包括停用词过滤、n-gram统计、搭配分析、文本分类、情感分析这些后续步骤。NLTK提供了这些通用组件，但它本身不支持粤语。pycantonese恰好补上了这一环，两者结合就等于“NLTK的生态 + 粤语的语料资源”。
使用层面，pycantonese可以直接提供符合NLTK语料库格式的数据接口，让NLTK的文本处理函数无缝对接粤语数据。这意味着，跑普通话文本那套统计方法，几乎不需要改代码就能用在粤语上。
4.2 快速搭建一条NLTK流水线示例
下面这段代码演示了典型的结合方式：加载粤语语料、过滤词性、统计频率。
import pycantonese as pc from nltk import FreqDist from nltk.corpus import stopwords corpus = pc.hkcancor() tokens = [word for word, tag, jyutping in corpus.tagged_tokens()] # 简单过滤：只保留名词和动词，做频率统计 filtered = [word for word, tag, _ in corpus.tagged_tokens() if tag.startswith("N") or tag.startswith("V")] freq = FreqDist(filtered) print(freq.most_common(20))这里FreqDist是NLTK自带的频率统计工具，在普通话文本分析里很常见。换成粤语数据之后，整个调用方式没有任何异样，原因就是pycantonese在设计时就考虑了与NLTK的兼容。
4.3 自己动手扩展词典和停用词表
NLTK默认的停用词表是英文的，完全不适用于粤语。需要在流水线里加上粤语停用词过滤时，建议自己维护一份高频功能词表，比如“嘅、咁、唔、係、喺、呢、嗰、喇、㗎”这类虚词。频率统计结果中真正有分析价值的通常是实词，不把虚词滤掉，前几名全是语气助词，图表也看不下去。
5. 实战拆解：用pycantonese处理一段粤语新闻评论
5.1 场景设计
假设我在做一个大湾区舆情分析的小项目，需要从一段粤语新闻评论里提取：主要人物、高频话题词、句子对应的粤拼发音。这种需求在真实的语音合成、舆情监测、方言文本挖掘里很常见，正好覆盖pycantonese的几个核心功能。
输入文本示例：
今日政府公布咗新一轮嘅交通措施，市民反应好热烈。有人话措施太急，冇时间适应。5.2 完整处理代码
import pycantonese as pc text = "今日政府公布咗新一轮嘅交通措施，市民反应好热烈。有人话措施太急，冇时间适应。" # 1. 分词 words = pc.segment(text) print("分词结果：", words) # 2. 对每个词取粤拼，并尝试获取词性标签 for word in words: jyutping_list = pc.jyutping(word) print(f"{word} -> {' '.join(jyutping_list)}") # 3. 加载语料，做全语料级别的词性对比 corpus = pc.hkcancor() tagged = corpus.tagged_tokens()运行之后，分词结果会呈现“政府”“公布咗”“交通措施”这类语义单元，而不是把“告咗”拆开。这说明库对粤语体貌助词的识别是有效的。拼音部分，“政府”会对应zing2 fu2，声调符号清晰标注。
5.3 把结果存储成结构化数据
实际项目中，处理完文本之后通常要落库或导出。我习惯把分词、拼音、词性整理成表格形式：
import csv rows = [] for word in pc.segment(text): jyutping = " ".join(pc.jyutping(word)) rows.append([word, jyutping]) with open("cantonese_result.csv", "w", newline="", encoding="utf-8") as f: writer = csv.writer(f) writer.writerow(["word", "jyutping"]) writer.writerows(rows)这样后面做Excel透视表或者加载到Pandas里分析都很顺手。
5.4 从语料库获取词性标注的补充方法
如果你希望得到更精确的词性，可以直接从HKCAC语料里搜索对应词条。虽然不能覆盖所有开放文本，但对于常见词，语料库里的标注可以作为参考基准。我通常在项目中把两种结果合并：分词器输出的词条作为主结果，语料库词典标注作为补充判断。
6. 踩坑记录与性能优化建议
6.1 分词结果在不同环境的可复现性
用pycantonese时遇到过一个问题：同一段文本在不同机器上分词结果不完全一致。原因大概率是语料库版本不一致。项目在更新语料的同时，分词策略可能会有细微调整，所以如果团队协作做粤语NLP项目，最好把pycantonese的版本号固定到requirements.txt里，甚至把语料包快照保存下来，否则复现实验时比较痛苦。
6.2 粤拼输出带声调数字，别直接当字符串匹配
pycantonese返回的粤拼是带数字声调的格式，比如nei5、hou2。如果你要做文本匹配或者语音合成的前置处理，记得把声调数字和拼音主体分开。一个简单的做法：
import re def split_tone(syllable): match = re.match(r"([a-z]+)([1-6]?)$", syllable) if match: return match.group(1), match.group(2) return syllable, ""这个函数可以把“nei5”拆成(“nei”, “5”)，方便做韵律分析。很多人在这一步偷懒，直接把带声调拼音塞给合成引擎，结果音素解析直接报错。
6.3 批量处理时的性能优化
pycantonese的分词和拼音转换，单条短文本响应很快，但如果要处理几万条评论，逐个调用就会显得吃力。我的建议有两个：一是增加缓存层，对重复出现的高频词直接缓存拼音结果；二是做批量预处理时用多进程，分词本身是CPU密集型操作，Python的GIL在单线程下会限制性能。
另外，我习惯先把所有文本按标点切分成短句，再调用pycantonese处理，而不是一次性传很长的段落。原因是长文本可能包含分词算法没见过的人名、机构名，切成短句后错误会被限制在小范围内，后续修正成本低很多。
6.4 不要拿普通话NLP的评价标准来苛求它
pycantonese的分词准确率、词性标注覆盖率，和jieba在普通话上的成熟度不是一个量级，这点必须有心理预期。粤语的NLP资源本来就少，这个库的价值在于它填补了“从无到有”的空白，而不是“从有到精”。如果项目需要高精度粤语分析，更合理的路线是先用pycantonese跑基础标注，再人工抽一部分数据做校验，或者基于它的输出训练一个领域专属的小模型。
我在实际项目中，当前策略就是用pycantonese处理粤语特有的语法特征，再用通用中文模型兜底处理粤语文本里的官话词汇，两者结合之后整体效果明显好于单独使用任何一方。这也算是我自己摸出来的一条折中路径，分享出来供参考。
本文还有配套的精品资源，点击获取
