pycantonese：专为粤语设计的语言学驱动NLP工具库

简介本资源是面向Python开发者与计算语言学研究者的粤语NLP专用工具库pycantonese专为解决粤语文本处理中词切分难、音译不统一、词性标注缺标准等核心问题而设计适用于粤语语音分析、教学辅助、信息抽取及学术研究等场景。压缩包共294个文件含36个核心Python源码实现Jyutping转换、词分割、停用词过滤与POS标注、58个CHA格式粤语语料CHILDES儿童语言数据库标准格式、38个HTML文档含API参考与教程、30个TXT词典与配置文件以及字体、样式、构建配置等辅助资源整体15.46MB结构完整、开箱即用。已有691人学习下载资源提供从基础音译到高级句法分析的全链路支持包含可直接调用的工具函数、标准化粤语语料样本及清晰的模块化代码组织是开展粤语自然语言处理实践与研究的可靠起点。1. pycantonese 是什么一个专为粤语“量身定制”的 Python 工具箱不是通用 NLP 库的“粤语皮肤”你有没有试过用中文分词工具处理一句粤语“我哋而家食紧叉烧饭。”结果可能是“我 / 哋 / 而 / 家 / 食 / 紧 / 叉 / 烧 / 饭”——错得离谱“叉烧”是固定词不该拆“食紧”是现在进行时标记“正在吃”但标准中文分词器根本没见过“食紧”这个词“我哋”在粤语里就是“我们”可“哋”字在简体中文语料里几乎不出现模型直接懵掉。这就像拿一把只标了“普通话尺寸”的裁缝尺硬去量一件广式旗袍——布料、剪裁、扣子位置全不一样再精准的尺子也量不准。pycantonese 就是那把专为粤语打制的“岭南尺”它不试图把粤语塞进普通话 NLP 的模具里而是从音系Jyutping、词汇粤语停用词表、语法粤语特有的助词、体标记、书写习惯繁体为主、夹杂粤语特有字如“咗”“啲”“嘅”出发提供一整套真正懂粤语的计算语言学基础能力。它不是“Python 版粤语版 jieba”而是一套扎根于粤语语言学事实的、可复现、可验证、可教学的开源工具集。搞懂它你就拿到了打开粤语数字人文、方言保护、本地化语音/文本系统的第一把真实钥匙。2. 为什么需要 pycantonese当普通话 NLP 遇上粤语不是“差一点”而是“差一套规则”2.1 粤语不是普通话的“方言变体”而是独立的语言系统很多人下意识觉得“粤语不就是带口音的中文” 这个认知偏差正是所有粤语 NLP 翻车的起点。从语言学角度看粤语和普通话的差异远超“北京话 vs 上海话”。它们在音系、词汇、语法、历史演变路径上都存在系统性断裂音系鸿沟普通话有 4 个声调粤语有 6–9 个常用 6 个且调值完全不同。比如“诗”si1、“史”si2、“试”si3在粤语里靠声调严格区分意义而普通话仅靠声母/韵母区分“shi”一个读音对应多个字。没有 Jyutping 这样的标准化拼音方案连最基础的语音对齐、TTS 合成都无从谈起。词汇断层粤语日常高频词大量游离于普通话词典之外。“埋单”“执输”“甩辘”“着数”“黐线”……这些词在《现代汉语词典》里查不到在通用中文语料库中出现频次趋近于零。强行用 jieba 或 HanLP 分词结果就是满屏“未登录词”。语法特区粤语有普通话完全缺失的语法范畴。例如体标记系统“紧”进行体食紧、“咗”完成体食咗、“过”经验体食过、“住”持续体企住——它们不是简单副词而是必须依附动词、影响句法结构的核心功能词代词与复数标记“我哋”我们、“你哋”你们、“佢哋”他们“哋”是强制性复数标记不能省略句末语气词爆炸“啦”“喎”“啫”“啩”“咩”……每个都携带精细的情态、疑问、强调、缓和等语用信息直接影响情感分析和对话系统判断。提示这不是“加几个粤语词”的小修补问题。当你发现一个 NLP 流水线在处理粤语时分词错误率超 40%、POS 标注准确率跌到 55%、命名实体识别NER几乎失效——问题根源不在模型参数而在整个预处理链条的底层假设崩塌了它默认输入是符合普通话分布规律的文本。2.2 pycantonese 如何“重建底层假设”从语言学事实出发的四大支柱pycantonese 不是堆砌算法而是用语言学知识为计算过程“打地基”。它的核心能力全部锚定在可验证的粤语语言学共识上2.2.1 Jyutping粤语音系的“唯一身份证”Jyutping粤拼是香港语言学学会制定的粤语罗马化方案被学术界、教育界、输入法厂商广泛采用。pycantonese 内置完整 Jyutping 转换引擎支持汉字 → Jyutpingpycantonese.characters_to_jyutping(你好) → [(nei5, hou2)]Jyutping → 音节结构解析声母j, 韵母yu, 声调5多音字消歧结合上下文词性与常见搭配import pycantonese # 输入繁体/简体混合粤语自动转标准粤拼 result pycantonese.characters_to_jyutping(我哋而家食紧叉烧饭) print(result) # 输出: [(ngo5, dei6), (ji4, gaa1), (sik6, gan2), (caa1, siu1), (faan6)]这段代码背后是数十年粤语音系研究成果的结晶每个字的粤语读音不是靠“猜”而是查权威字典如《广州话正音字典》、经语言学家校验的确定映射。没有这一步所有基于语音的下游任务ASR、TTS、声调识别都是空中楼阁。2.2.2 粤语分词不靠统计靠“语法词典规则”三重校验pycantonese 的分词器word_segmentation拒绝“黑盒统计”。它融合核心词典收录逾 2 万条粤语高频词、固定搭配、习语如“拍拖”“落雨”“打风”“食得咸鱼抵得渴”语法模式库识别粤语特有构词法如“动词紧/咗/住”食紧、食咗、企住、“形容词啲”好多啲、细啲、“名词仔/女”阿仔、阿女规则引擎处理连读变调、口语缩略“係咪”→“係”“咪”、夹杂英文“email”“WiFi”不拆。它不追求“最大概率切分”而追求“语言学上合法的切分”。例如原句通用中文分词错误pycantonese 分词正确语言学依据“佢哋睇紧部新出嘅剧。”佢 / 哋 / 睇 / 紧 / 部 / 新 / 出 / 嘅 / 剧佢哋 / 睇紧 / 部 / 新出嘅 / 剧“睇紧”是不可分割的进行体结构“新出嘅”是“新出”“嘅”构成的定语结构非“新/出/嘅”三字独立2.2.3 粤语停用词与词性标注让机器读懂粤语的“语法心跳”通用中文停用词表如哈工大停用词表对粤语基本无效——它删掉“的”“了”“在”却保留“嘅”“咗”“紧”而这恰恰是粤语语法骨架。pycantonese 提供粤语专用停用词表包含 300 个高频虚词、助词、语气词“嘅”“咗”“紧”“啩”“啦”“喎”“啫”“咩”“点解”“边度”可按需启用/禁用粤语 POS 标注器基于粤语树库Cantonese Treebank训练标签集适配粤语语法如VX表示趋向动词“入去”“出嚟”AS表示体标记“紧”“咗”UH表示语气词。# 对分词结果做词性标注 seg pycantonese.word_segmentation(我哋而家食紧叉烧饭) pos_tags pycantonese.pos_tag(seg) print(pos_tags) # 输出: [(我哋, PRON), (而家, ADV), (食紧, VX), (叉烧, N), (饭, N)] # 注意食紧 被整体标为 VX趋向动词/体标记而非拆成 食(V) 紧(AS)这个标注结果直接服务于句法分析、依存关系抽取、问答系统中的谓词识别——它让机器第一次能“看见”粤语动词后那个决定句子时态的灵魂标记。2.2.4 开放、可验证、可教学一切基于公开语料与学术共识pycantonese 的所有数据源均明确标注出处Jyutping 映射来自《粤语审音配词字库》香港中文大学分词词典整合自《广州话词典》《香港粤语词典》及公开粤语语料库如 HKCanCorPOS 标签体系遵循 Universal Dependencies (UD) 粤语树库规范所有代码、文档、测试用例开源每行关键逻辑都有语言学文献引用如 Li Thompson, 1981 对粤语体标记的经典分析。这意味着你不是在调用一个“神秘 API”而是在使用一套可追溯、可质疑、可改进的语言学计算框架。学生能对照教材验证结果研究者能定位误差源头工程师能理解每个参数背后的语言学含义——这才是专业级工具该有的样子。3. pycantonese 和其他工具的区别不是“更好用”而是“根本不在同一赛道”3.1 常见误区与易混概念初学者最容易踩的五个坑易混点 1pycantonese ≈ “粤语版 jieba”为什么混两者都提供分词功能名字里都有“分词”二字。怎么区分jieba 是纯统计驱动的中文分词器依赖大规模中文语料训练其词典、模型、规则全部针对普通话设计pycantonese 的分词是语言学规则主导粤语词典支撑少量统计校准核心目标是保证语法合法性而非追求 F1 分数。它甚至不提供“训练新模型”的接口——因为粤语分词的瓶颈从来不是数据量而是语言学知识建模。易混点 2pycantonese 可以直接替代 spaCy / Stanza 做粤语 NLP为什么混spaCy/Stanza 是主流 NLP 框架用户自然想“找个粤语模型加载进去”。怎么区分spaCy/Stanza 的粤语模型如有本质是将通用架构套用在粤语语料上其 tokenization、POS、NER 标签集仍是通用框架的简化版无法表达粤语特有范畴如体标记 AS、语气词 UH。pycantonese 不是“另一个 NLP 框架”而是粤语语言学能力的原子化封装——你可以把它当作 spaCy 的上游预处理器先用 pycantonese 分词标 AS/UH再喂给 spaCy但它本身不提供 pipeline、ner、dependency parser 等高层抽象。易混点 3有了 Jyutping 字典自己写个转换脚本就够了为什么混Jyutping 看似只是“汉字→拼音”的映射表。怎么区分真实场景中一个字在不同粤语词里读音可能不同多音字需结合上下文消歧如“行”在“行走”中读haang4但在“银行”中读hong4粤语存在大量口语字、异体字“啲”“嘅”“咗”“冇”、非标准写法“唔该”常写作“唔该”或“唔該”。pycantonese 的characters_to_jyutping内置了上下文感知的消歧逻辑和异体字归一化远超静态字典查询。易混点 4pycantonese 粤语 NLP 全栈解决方案为什么混标题里有 “NLP”用户期待“开箱即用”。怎么区分pycantonese刻意保持“小而专”它不做深度学习模型、不提供预训练 BERT、不集成 TTS/ASR 引擎。它的使命是解决 NLP 流水线中最底层、最易被忽视、却最致命的环节——让输入文本变成语言学上可解释、可操作的符号序列。它输出的是[(word, pos), ...]和[(char, jyutping), ...]而不是“情感得分”或“实体列表”。易混点 5用 pycantonese 处理简体粤语如内地网友写的粤语效果一样好为什么混简体字和繁体字一一对应似乎不影响。怎么区分粤语书面语存在大量简繁不对应的特有字“嘅”所有格在简体环境下常被误写为“的”语义完全错乱“咗”完成体被写成“了”丢失粤语语法特征“啲”一些被写成“些”或“滴”“冇”没有被写成“没有”或“毛”。pycantonese 的词典和规则库默认面向规范繁体粤语文本。处理简体混排文本前必须先做“粤语正字归一化”如将“的”替换为“嘅”“了”替换为“咗”而这一步本身就需要语言学知识——pycantonese 不提供此功能但它的设计清晰划出了这条边界它处理“已归一化的粤语文本”而非“待清洗的网络口语”。注意pycantonese 的文档首页就写着“This library assumes input text is in standard written Cantonese (primarily traditional Chinese characters). It does not perform text normalization or OCR correction.” —— 它坦诚告诉你它的能力边界这比那些号称“全能”却处处翻车的工具更值得信赖。4. pycantonese 的核心能力详解不只是分词而是粤语计算的“语法基石”4.1 Jyutping 深度解析从拼音到音系结构的穿透式理解pycantonese 的 Jyutping 功能远不止“查字典”。它把每个粤拼字符串解构成可编程的音系单元为语音技术提供精确控制4.1.1 声母、韵母、声调的结构化解析import pycantonese # 解析单个粤拼 syllable pycantonese.parse_jyutping(nei5) print(syllable.initial) # n 声母 print(syllable.final) # ei 韵母 print(syllable.tone) # 5 声调数字 # 批量解析处理多音字 words [你好, 你好呀] for word in words: jyutpings pycantonese.characters_to_jyutping(word) print(f{word} → {jyutpings}) # 输出: # 你好 → [(nei5, hou2)] # 你好呀 → [(nei5, hou2, aa3)] # 呀 是语气词独立音节这个parse_jyutping接口的意义在于它把语音信息从字符串变成了结构化对象。你可以轻松实现声调统计分析某文本中第 6 声调出现频率韵母聚类找出押韵的粤语诗句声母混淆模拟为语音识别错误建模生成同音字表辅助粤语输入法开发。4.1.2 多音字上下文消歧语言学规则驱动的智能选择粤语多音字极多如“行”“长”“发”“落”单纯查表会出错。pycantonese 在characters_to_jyutping中嵌入轻量级消歧逻辑# 同一个字在不同词中读音不同 print(pycantonese.characters_to_jyutping(行走)) # [(haang4, zau2)] print(pycantonese.characters_to_jyutping(银行)) # [(ng4, haang4)] print(pycantonese.characters_to_jyutping(长处)) # [(coeng4, cyu3)] print(pycantonese.characters_to_jyutping(长大)) # [(zoeng2, daai6)]其消歧依据是词性与构词法“行走”是动词“行”取移动义读haang4“银行”是名词“行”取“商行”义读haang4此处为特例实际读hong4pycantonese 词典已收录此特读“长处”中“长”为形容词长久读coeng4“长大”中“长”为动词生长读zoeng2。这种规则虽不如深度学习模型复杂但透明、可控、可调试——当结果出错时你能立刻定位是哪条规则没覆盖而不是面对一个黑盒梯度更新。4.2 粤语分词在“词典派”与“统计派”之间走出第三条路pycantonese 的分词器 (word_segmentation) 是其最受赞誉的功能它巧妙平衡了规则刚性与语境柔性4.2.1 三级匹配策略确保核心词不被切碎分词过程按优先级执行专有名词/固定搭配优先匹配从最长词开始扫描如“香港特别行政区” “香港” “香”确保“港铁”“TVB”“麦当劳”不被拆语法模式二次校验对初步切分结果应用粤语构词规则过滤。例如检测到“食”后紧跟“紧”则强制合并为“食紧”检测到“新”后是“出嘅”则合并为“新出嘅”剩余字符回退分词对未匹配部分使用小型粤语词典进行最大匹配MM。# 展示三级策略如何协同工作 text 港铁宣布新出嘅列车服务今早开始运行 seg pycantonese.word_segmentation(text) print(seg) # 输出: [港铁, 宣布, 新出嘅, 列车, 服务, 今早, 开始, 运行] # 关键点新出嘅 未被拆成 新/出/嘅港铁 作为专有名词整体保留4.2.2 可配置的分词粒度满足不同下游任务需求pycantonese 允许开发者根据任务调整分词“粗细”modedefault平衡精度与召回推荐用于一般文本分析modefine启用更多短语切分如将“叉烧饭”切为“叉烧”“饭”便于菜品实体识别modecoarse倾向保留长词如“而家食紧”整体视为一个时间-动作复合单位适合句法分析。# 不同模式对比 text 我哋而家食紧叉烧饭 print(default:, pycantonese.word_segmentation(text, modedefault)) # [我哋, 而家, 食紧, 叉烧饭] print(fine:, pycantonese.word_segmentation(text, modefine)) # [我哋, 而家, 食紧, 叉烧, 饭] print(coarse:, pycantonese.word_segmentation(text, modecoarse)) # [我哋而家食紧叉烧饭] # 极端情况演示用这种灵活性源于其模块化设计分词器本身不固化“什么是词”而是提供可插拔的规则集与词典源——这是通用分词器难以提供的深度控制权。4.3 粤语词性标注POS让机器识别粤语的“语法角色”pycantonese 的pos_tag函数返回的不仅是词性标签更是粤语语法结构的显式编码4.3.1 粤语专属标签集直击语法要害其 POS 标签集基于 UD 粤语树库包含普通话 NLP 工具忽略的关键类别标签含义粤语例词普通话对应难点ASAspect Marker (体标记)咗、紧、住、过普通话“了”“着”“过”功能混杂且常省略UHInterjection / Sentence-final Particle (语气词)啦、喎、啫、啩、咩普通话无系统性语气词体系通用 POS 标注器常标为INTJ或PART丢失语用信息VXDirectional Verb (趋向动词)入去、出嚟、返转头普通话“进去”“出来”是词粤语“入去”是动词趋向补语语法地位不同DTDeterminer (限定词)呢、嗰、呢啲、嗰啲普通话“这”“那”后不强制加“些”粤语“呢啲”“嗰啲”是固定搭配# 标注结果展示粤语语法结构 text 佢哋今朝食咗叉烧饭啦 seg pycantonese.word_segmentation(text) pos pycantonese.pos_tag(seg) for word, tag in zip(seg, pos): print(f{word:8} {tag}) # 输出: # 佢哋 PRON # 今朝 ADV # 食咗 VX ← 注意食咗 整体标为 VX完成体标记非 VAS # 叉烧饭 N # 啦 UH ← 语气词承载感叹、提醒等语用功能这个VX标签直接告诉下游任务“食咗”是一个不可分割的语法单位其语义是“完成”而非“吃”“了”。这对构建粤语时态感知的问答系统至关重要。4.3.2 与通用框架的协作做 spaCy 的“粤语增强插件”pycantonese 不排斥主流框架而是作为其能力补充import spacy import pycantonese # 加载 spaCy 粤语模型假设有 nlp spacy.load(zh_cantonese_core_web_sm) # 先用 pycantonese 做粤语特有预处理 raw_text 我哋而家食紧叉烧饭。 seg pycantonese.word_segmentation(raw_text) # 得到 [我哋, 而家, 食紧, 叉烧饭] pos_tags pycantonese.pos_tag(seg) # 得到 [(我哋,PRON), (而家,ADV), ...] # 构造 spaCy 可接受的 Doc 对象需额外步骤 # 此处示意将 pycantonese 的输出注入 spaCy pipeline提升其对体标记、语气词的识别鲁棒性这种协作模式避免了重复造轮子又弥补了通用框架的方言短板——这才是务实的工程实践。5. 什么时候该用 pycantonese什么时候该绕道走一份来自血泪经验的边界指南5.1 你该用 pycantonese 的 4 个典型场景附真实项目教训场景 1构建粤语数字人文数据库要求检索结果语言学可信项目背景某高校语言学实验室启动“粤语俗语百年变迁”项目需从旧报纸、口述史录音文字稿中批量提取“体标记”咗/紧/住/过和“语气词”啦/喎/啫的使用频次并按年代、地域、语境分类。翻车现场初期用通用中文 NLP 工具处理“食咗”被拆成“食”和“咗”两个独立 token“咗”被标为PART小品词导致所有“完成体”统计全部丢失“啦”被当作无意义停用词过滤语气词分析归零。pycantonese 救场# 从原始文本中精准捕获体标记与语气词 def extract_cantonese_grammar(text): seg pycantonese.word_segmentation(text) pos pycantonese.pos_tag(seg) aspects [word for word, tag in zip(seg, pos) if tag AS] # 直接抓 AS 标签 particles [word for word, tag in zip(seg, pos) if tag UH] # 直接抓 UH 标签 return aspects, particles aspects, particles extract_cantonese_grammar(佢哋今朝食咗叉烧饭啦) print(体标记:, aspects) # [食咗] print(语气词:, particles) # [啦]教训总结当你的研究问题直接指向粤语特有语法范畴体、语气、代词复数标记时pycantonese 不是“加分项”而是保底项。它的标签集就是为你的问题量身定制的答案格式。场景 2开发粤语客服机器人需准确理解用户意图中的时态与情态项目背景某跨境电商平台上线粤语客服用户提问如“我嘅订单而家到边度”“呢单货几时先至收得到”“上次嘅退货仲未处理好啊”——其中“而家”“先至”“仲未”“啊”携带关键时态现在/将来/持续否定和情态催促/抱怨/确认。翻车现场用通用 NLU 模型如 Rasa直接训练模型将“而家”识别为普通时间名词无法关联到“当前状态查询”意图将“啊”当作噪音过滤丢失用户情绪强度信号对“先至”才这种粤语特有焦点标记完全无感。pycantonese 救场# 提取时态与情态线索作为 NLU 模型的强特征 def get_grammar_features(text): features {} seg pycantonese.word_segmentation(text) pos pycantonese.pos_tag(seg) # 体标记指示动作状态 features[aspect] [tag for _, tag in zip(seg, pos) if tag in [AS, VX]] # 语气词指示情态强度 features[particle] [word for word, tag in zip(seg, pos) if tag UH] # 时间副词粤语特有表达 time_words [而家, 依家, 即刻, 阵间, 先至, 终归, 始终] features[time_word] [w for w in seg if w in time_words] return features print(get_grammar_features(我嘅订单而家到边度)) # {aspect: [], particle: [], time_word: [而家]} print(get_grammar_features(上次嘅退货仲未处理好啊)) # {aspect: [], particle: [啊], time_word: [仲未]} # 仲未 是粤语特有持续否定时间副词教训总结在资源有限数据少、算力弱的垂直场景用 pycantonese 提取高价值语言学特征比盲目堆大模型更有效。它把模糊的“语感”转化成可枚举、可统计、可输入模型的离散特征。场景 3为粤语语音合成TTS系统提供精准音素与声调标注项目背景某语音技术公司开发粤语 TTS需将文本“我哋而家食紧叉烧饭”转换为音素序列ngo5 dei6 ji4 gaa1 sik6 gan2 caa1 siu1 faan6并确保“食紧”作为一个音节sik6 gan2非sik6gan2传递给声学模型。翻车现场用通用中文 TTS 流程先分词再查拼音“食紧”被拆成两字查得sik6gan2但粤语中“食紧”连读时“紧”字声调会发生变调常变为低平调独立标注gan2导致合成语音生硬、不自然。pycantonese 救场# pycantonese 保证“食紧”作为整体单元获取粤拼 text 我哋而家食紧叉烧饭 seg pycantonese.word_segmentation(text) # [我哋, 而家, 食紧, 叉烧饭] jyutpings [] for word in seg: # 对每个分词结果整体查粤拼 jp_list pycantonese.characters_to_jyutping(word) jyutpings.extend(jp_list) print( .join(jyutpings)) # ngo5 dei6 ji4 gaa1 sik6 gan2 caa1 siu1 faan6 # 关键sik6 gan2 是连续两个音节TTS 引擎可据此建模连读变调教训总结语音技术对文本预处理的精度要求是毫秒级的。pycantonese 的分词与粤拼绑定确保了音系信息与词汇边界的严格对齐——这是任何“后处理拼接”方案都无法替代的底层保障。场景 4教学与科普向学生/公众可视化粤语语法结构项目背景某语言学导师制作粤语语法互动课件需动态演示“体标记”如何改变句子含义“食”吃→“食紧”正在吃→“食咗”已吃→“食过”曾吃过。翻车现场用 PPT 手动画箭头学生难以建立“紧/咗/过”与“进行/完成/经验”之间的映射用通用分词器演示“食紧”被拆开教学逻辑断裂。pycantonese 救场# 生成教学可视化数据 def show_aspect_change(verb): base pycantonese.characters_to_jyutping(verb)[0] # 如 sik6 aspects { base: f{verb} ({base}), progressive: f{verb}紧 ({base} gan2), perfect: f{verb}咗 ({base} zo2), experiential: f{verb}过 ({base} gwo3) } return aspects print(show_aspect_change(食)) # {base: 食 (sik6), progressive: 食紧 (sik6 gan2), perfect: 食咗 (sik6 zo2), experiential: 食过 (sik6 gwo3)}教训总结pycantonese 的确定性、可解释性、与语言学理论的高度一致使它成为绝佳的教学脚手架。它把抽象的语法概念变成了学生可点击、可验证、可修改的代码实例。5.2 你该绕道走的 3 个明确信号别硬扛信号 1你的文本是未经清洗的社交媒体口语充斥简体字、拼音、表情包、错别字如“我今天好累啊想食叉烧but钱包空空…”pycantonese 的设计前提规范繁体粤语在此完全失效。此时应优先做简繁转换用 OpenCC粤语正字归一化将“的”→“嘅”“了”→“咗”“些”→“啲”拼音/英文词隔离“but”不参与粤语分词这些前置清洗pycantonese 不提供也不该由它承担。信号 2你需要端到端的深度学习模型如粤语 BERT、粤语机器翻译pyc本文还有配套的精品资源点击获取