企业官网建设流程全解析

简介：面向粤语语言学与自然语言处理的pycantonese开源库完整资源包，适合作语言学研究、中文NLP方向的开发者、学术研究者及学习者使用。该库围绕粤语独特语法特点展开，提供汉字与Jyutping拼音转换、词语分割、停用词过滤、词性标注等核心工具，并能结合NLTK、spaCy进行情感分析、语义理解等高级任务，特别针对粤语多音字和缺乏明显词边界的难点给出可行方案。压缩包共294个文件，涵盖Python源码、RST/Markdown格式文档、CHA/TXT语料数据、HTML页面与字体资源等，大小约15.46MB，目录结构清晰，便于按模块调用和二次开发。目前已有689人浏览学习。通过该资源可以快速搭建粤语分析流程，掌握从原始文本到分词语料再到句法标注的完整链路，同时借助内置语料与脚本深入理解Jyutping体系，并将其应用到教学、词典工具或定制化NLP系统中，是粤语计算语言学领域难得的高价值参考资料。

1. 为什么处理粤语时，通用NLP工具会“翻车”

如果你试着把“我哋今日去茶餐廳食飯”丢给常见的普通话分词和拼音工具，结果通常很魔幻：分词把“茶餐廳”切成“茶/餐/厅”，注音更是直接把“食飯”标成普通话读音。原因不复杂，粤语书面语和普通话书面语在词汇、虚词、声调系统上差异太大，通用工具的词表和发音规则压根没有覆盖“哋”“嘅”“冇”这类字。这就是粤语NLP项目里最常见的翻车现场。

pycantonese 是一个面向粤语的 Python 库，它内置了粤语常用词典和粤语语料库，主要提供分词、粤拼（Jyutping）标注、词典查询这几项基本功。和通用 NLP 工具不一样，它的词表、读音映射、语料来源都围绕粤语本身设计，所以上面的句子交给它，能得到符合粤语习惯的切分和读音。它的定位不是一个大而全的平台，而是粤语文本处理链路里最该先补上的一块短板。

如果你在做粤语歌词字幕、粤语教学注音、语音合成前端标注，或者只是需要批量处理微博、论坛里的粤语文本，这个库是值得先花半天时间试跑的方向。这篇文章会从安装一路讲到接入生产管道，包括词典匹配的原理、多音字和异体字的坑、以及我自己遇到过的几次翻车经历。

2. 装上就能用：pycantonese 的最小运行环境与第一个分词任务

2.1 安装前先确认三件事

先别急着pip install，装之前花两分钟确认三件事，能省掉后面不少玄学问题。

第一是 Python 版本。pycantonese 属于典型的学术型小库，维护节奏不像商业库那么快，新版本语法特性基本不会用，但太老的 Python 又可能带不动它的依赖。我一般建议直接用 3.8 以上的版本，没必要在旧环境里折腾兼容性。第二是确认你当前在哪个虚拟环境里，别把包装进系统 Python，后面导入时才发现找不到模块。第三是心理预期：这个库首次导入时会初始化语料数据，不是一行代码秒出的那种轻量工具，第一次跑起来比普通库慢几秒是正常现象。

安装命令很简单：

pip install pycantonese python - <<'PY' import pycantonese as pc print("pycantonese 安装路径:", pc.__file__) PY

第二段脚本用来验证包能不能正常导入。如果能打印出安装路径，说明环境没问题；如果报ModuleNotFoundError，先检查虚拟环境是否激活，再用pip list看包到底装到哪了。Windows 用户如果终端打印中文乱码，可以把终端编码切到 UTF-8，或者在脚本开头加一句sys.stdout.reconfigure(encoding="utf-8")，这属于环境问题，不是库本身的问题。

2.2 最小分词脚本

安装验证通过之后，第一个可以直接抄的脚本就是分词。pycantonese 的分词器是经典的词典最大匹配思路：查内置粤语词典，能匹配到的最长词优先切出来，匹配不到的字就单独成词。这种方案对常用粤语词覆盖不错，但对新词、网络词会比较笨，这是后面避坑章节要讲的重点。

import pycantonese as pc text = "我哋今日去茶餐廳食飯" tokens = pc.segment(text) # segment() 返回的是字词列表，直接打印或按需取用 print(tokens)

输出大致是["我哋", "今日", "去", "茶餐廳", "食飯"]，其中“茶餐廳”会作为一个整体切出来，这正是通用工具做不到的地方。这里要注意两点：segment()的入参是字符串，不是列表；返回结果是普通列表，可以直接for遍历，也可以" ".join(tokens)拼成空格分隔的文本。如果拿到的切分结果和你预期的词边界不一样，先别急着怀疑库，看是不是文本里混入了全角空格或不可见字符。

提示：segment()不认识的字会切成单字。这不是报错，是词典匹配的正常表现，后面用自定义词典补。

2.3 从“能跑”到“能用”：看返回结构与空结果

很多人的第一个疑惑是：为什么单字能切对，整句却切得和我想的不一样。这源于词典最大匹配的固有特性：切分结果依赖匹配顺序和词典覆盖，同一个词放在不同上下文里，边界可能变化。我一般会写一段小脚本批量验证边界场景：

texts = ["我哋", "今日", "去茶餐廳", "食飯", "茶餐廳今日好多人"] for line in texts: print(line, "->", pc.segment(line))

这段代码不是为了跑通，而是让你观察“茶餐廳”在不同位置是否都被整体切出。如果大部分都切对了，说明词典覆盖正常；如果同一个词在句子中间被切开，通常是因为前后字组成了词典里的另一个更长词，属于匹配优先级问题。生产环境里我习惯把这类文本单独抽出来，维护进一个“强制成词”的覆盖列表，而不是反过来怀疑分词器坏了。

跑完这几个用例，你对这个库的脾气就基本有数了：它擅长粤语常用词，但对上下文语义不敏感。明白这一点，后面接语音合成或歌词注音时，就知道哪些地方要加后处理。

3. 用 pycantonese 标粤拼：词典匹配的工作原理与三个必调参数

3.1 为什么普通话拼音工具标不了粤语

把粤语文本丢给普通话拼音工具，基本等于让一个只懂普通话发音的人去读广东话，结果当然是按普通话字音硬读。粤语和普通话的声调系统完全不是一回事：粤拼有六个声调（部分分析方案还细分阴入、中入、阳入），有入声韵尾 -p/-t/-k，还有普通话里根本不存在的声母和韵母组合。更重要的是，粤语有一批常用字在普通话里根本不是同一套用法，比如“佢”（他）、“冇”（没有）、“係”（是）、“嘅”（的），这些字在普通话拼音工具里可能压根没有对应读音。

我曾经帮某开发者调试一个粤语语音合成前端，他图省事直接用了普通话的拼音转换接口，结果“唔該”被标成了普通话的“wú gāi”，合成出来的音频完全没法听。这个教训很直接：粤语文本处理第一步就应该锁定粤语专用工具，普通话工具在这个场景里没有平替空间。

3.2 先分词再注音：两行代码拿逐字粤拼

pycantonese 的读音查询接口是按“词”而不是按整句工作的，所以标准化流程是：先segment()分词，再对每个词查粤拼。这里分享一个可以直接跑的最小脚本：

import pycantonese as pc text = "佢哋好鍾意食蛋撻" for token in pc.segment(text): jp = pc.jyutping(token) print(f"{token} : {jp}")

jyutping()的输入是单个词，输出结构在不同版本里略有差异：有的版本返回包含(字, 读音)元组的列表，有的版本直接返回字典。这个差异让不少初学者栽过跟头，所以我一般会写一层兼容函数，把不同返回结构统一成字符串：

import pycantonese as pc def first_reading(result): # 有的版本返回 [('字', 'zyut6'), ('詞', 'ci4')] 这种列表 # 有的版本返回 {'字': 'zyut6'} 这种字典 if isinstance(result, dict): return " ".join(result.values()) if isinstance(result, list): return " ".join(pair[1] for pair in result) return str(result) text = "佢哋好鍾意食蛋撻" for token in pc.segment(text): print(token, first_reading(pc.jyutping(token)))

这段代码就是典型的“面向返回结构编程”。初学者最容易犯的错是把整句直接传给jyutping()，得到的结果要么为空要么结构混乱。正确姿势永远是先分词、再逐词查询。实际项目里如果需要控制输出格式，比如只要第一个读音，可以在first_reading()里加split()[0]；如果要做逐字对齐，就保留列表结构，不转成字符串。

3.3 多音字与字形归一：把“中”读对的三步配置

粤拼查询本质是查词典，所以它没有上下文消歧能力。最典型的例子是“中”字，在“中間”里读zung1，在“中意”里读zung3，但词典查询只会按词条返回，如果词库里没有“中意”这个完整词条，就会退回到默认读音。这不是 bug，是词典匹配方案的天然边界。

要解决多音字问题，我一般会维护一个项目级优先读音表：

PRIORITY = { "中意": [("中", "zung3"), ("意", "ji3")], "中間": [("中", "zung1"), ("間", "gaan1")], "係": [("係", "hai6")], } def resolve_reading(word): # 优先查项目自定义表，查不到再走库默认查询 if word in PRIORITY: return PRIORITY[word] return pycantonese.jyutping(word)

这段代码看起来简单，但它是粤语注音管道里最容易出效果的一个环节。优先表的意义不是替代词典，而是把你业务里真正关心的多音词钉死，避免批量跑完后出现成片的错音。

除了多音字，还有一类问题也常被忽略：粤语文本里的异体字和香港字。最常见的如“裏”“裡”“里”三套写法、“臺”“台”混用，如果文本不统一，词典查询时一个都匹配不上。我写过一个很简单的归一化函数，在分词之前先把字形统一到词典收录的写法：

NORM = {"裡": "裏", "裏": "裏", "臺": "台", "爲": "為"} def normalize(text): for k, v in NORM.items(): text = text.replace(k, v) return text

注意，归一化要放在segment()之前做，否则分词边界会因为异体字被打乱。这一步处理完，再跑分词和读音查询，空结果率通常会明显下降。“中意”这类多音词的优先表 + 字形归一化，是我做任何粤语文本标注任务都会先配好的两个前置环节。

3.4 批量文本注音：缓存让速度提升两个量级

当你从几行示例代码切换到几千行的真实语料时，第一个遇到的性能问题就是重复查询。一句歌词里“嘅”可能出现五六次，每次都重新查一遍词典，纯属浪费。解决方案是用functools.lru_cache包一层缓存：

from functools import lru_cache import pycantonese as pc @lru_cache(maxsize=2048) def jyutping_cached(word): return pc.jyutping(word) def annotate(text): tokens = pc.segment(text) return [(word, jyutping_cached(word)) for word in tokens] print(annotate("佢哋好鍾意食蛋撻"))

缓存命中率在歌词、字幕这类重复度高的语料里非常可观。maxsize我一般设 2048 到 8192 之间，太小了频繁淘汰，太大了内存白白占用。这里要说清楚一个边界：lru_cache只是进程内缓存，不跨进程共享。如果你用多进程并行处理大量文本，每个进程还是各自查一遍，不会因为缓存而节省整体耗时。

注意：jyutping_cached()的入参必须是单个词，不要把整句传进去。整句缓存不仅命中率低，还会让词典查询找不到结果。

4. 从粤拼到 IPA：自建转换层的实践比想象中简单

4.1 什么时候需要 IPA

粤拼（Jyutping）是罗马字母拼写方案，适合人读和程序处理，但语音合成、音系对比、语料库标注这些场景往往要求国际音标（IPA）。比如你拿粤拼文本去驱动一个基于 IPA 的语音合成前端，或者做方言音系对比分析，都需要把zyut6这类拼写转成对应的音标符号。

这里有个常见误区，很多人以为一定有现成工具一键转换，实际工程里我很少找到完全满意的方案。pycantonese 的重点放在词语切分和读音查询上；要从粤拼到 IPA，我更倾向于在 pycantonese 的输出结果上自建一层几十行的规则，这比四处找转换库更可控，也更容易针对自己的音系方案调整。

4.2 最小映射表：先按最长键匹配，再处理声调

粤拼到 IPA 的转换可以拆成两步：声母韵母的字母组合映射，加声调符号映射。最容易翻车的坑是字母组合的匹配顺序，比如aa必须优先于a被匹配，否则长元音会被拆成两个短音。我的做法是把映射表按键长度排序，先查长键：

# 示例映射，展示思路，实际音系方案请按你的标注体系调整 JYUTPING_MAP = { "aa": "aː", "a": "ɐ", "i": "iː", "u": "uː", "e": "ɛː", "o": "ɔː", "oe": "œː", "yu": "yː", "ng": "ŋ", } def jyutping_to_ipa(syllable): # 先去掉末尾的声调数字，单独处理 tone = syllable[-1] if syllable[-1].isdigit() else "" body = syllable[:-1] if tone else syllable # 按键长度降序匹配，保证 aa 优先于 a result = "" i = 0 while i < len(body): matched = False for key in sorted(JYUTPING_MAP, key=len, reverse=True): if body.startswith(key, i): result += JYUTPING_MAP[key] i += len(key) matched = True break if not matched: result += body[i] i += 1 if tone: result += f"^{tone}" # 声调用上标数字表示，工程上最直观 return result print(jyutping_to_ipa("zyut6")) # 输出形如 zyːt^6 的结果

这段代码的核心逻辑是两层：声调先拆走，避免数字影响字母匹配；字母部分用降序匹配保证多字母组合优先命中。真实使用中，你还需要把声母表（比如z、c、s、gw、kw）和韵尾（p、t、k、m、n、ng）也加进映射表，逐个音位补全。这个表听起来工作量大，实际也就几十行，一次配好，后面所有文本都能复用。

4.3 变调：规则之外的事交给后处理

IPA 转换最怕的是只按词典音标转，完全忽略变调。粤语口语里有不少常见变调现象，比如“女”在“女仔”一词里受后字影响可能改变调值，“唔該”在句末语气场景下也常有语调漂移。词典里存的是单字本调，不是口语实际调值，所以拼音转 IPA 的管道必须预留一层后处理。

我的做法是维护一张“上下文变调覆盖表”，在转换成 IPA 之前先查这张表：

TONE_OVERRIDE = { "女仔": [("女", "neoi5"), ("仔", "zai2")], "唔該": [("唔", "m4"), ("該", "goi1")], } def apply_tone_override(word): return TONE_OVERRIDE.get(word, None)

注意，这张表的作用域是“项目相关”。歌词注音项目只需要覆盖歌词里出现的口语词，语音合成项目则需要根据合成引擎的韵律模型决定要不要改调。这种后处理方案无法一劳永逸，但它在工程上是可控的：词典给基础读音，覆盖表处理异常场景，两者互不干扰。

5. 避坑指南：5 个让 pycantonese 不好用的真实原因

5.1 生僻字与网络新词查不到读音

现象：批量标注时，某些字返回None或空列表，比如网络新词、古字、香港本地造字。

原因：pycantonese 的词表来自其内置语料和词典，覆盖面以常用粤语词为主。新词和生僻字不在词表里，查询自然落空。

解决：建一个项目级后备音表。常见做法是手写一个FALLBACK = {"字": "jyut6"}字典，在词典查询返回空时兜底：

FALLBACK = {"嗰": "go2", "啲": "di1"} def safe_jyutping(word): result = pycantonese.jyutping(word) if not result: return FALLBACK.get(word, "") return result

后备表不需要大，只维护你真实语料里出现的缺失项，每补一个都能立刻看到效果。跑完一批文本后，我会把空结果单独导出来做一次人工核对，再决定哪些进后备表。

5.2 分词结果和 jieba 差很多，别急着换工具

现象：同一句粤语，pycantonese 切出来的词和 jieba 默认词表切出来完全不同，比如“我哋”被 jieba 切成了“我/哋”。

原因：jieba 的默认词典面向普通话书面语，“我哋”“茶餐廳”“食飯”这些粤语词不在其词表里，被拆碎是正常现象。

解决：粤语场景优先用 pycantonese 的分词结果。如果你需要在一个管道里同时处理普通话和粤语，不要直接换回 jieba，而是让文本先走一遍语言判断，粤语文本走 pycantonese。混合场景下给 jieba 加粤语自定义词表也可以，但要清楚这是你的工程改造，不是 jieba 开箱即用的能力。

5.3 多音字只回单一读音，上下文救不了

现象：“中意”读成了zung1 ji3，实际粤语口语应该读zung3 ji3。

原因：词典查询按词条匹配，词库里没有收录“中意”或者没有为它标注多音，于是退回到默认读音。

解决：不要指望加参数，直接用优先级覆盖表。把“中意”这类词钉死在PRIORITY字典里，查询前先查优先表。这是我在第 3 章讲过的方法，也是所有多音字问题最直接有效的路径。批量跑完后，我会按出现频次抽检多音字，优先表本身也需要跟着语料迭代。

5.4 繁简与异体字导致查询失败

现象：文本里写的是“裏”，词典查不到；改成“裡”或“里”就能查到。

原因：词表收录的是某一套字形写法，异体字不在其中。粤语文本里“裏/裡”“臺/台”“爲/為”混用很常见，不归一化就会频繁落空。

解决：在分词和注音前做一步字形归一化。把常用异体字统一到你选定的一套写法，再进管道。我这里有一条血泪经验：归一化映射表要放在所有处理的最前面，千万不要放在分词之后，否则边界已经乱了，后面对齐全是错的。

5.5 首次运行慢、内存占用高

现象：脚本启动后第一次调用segment()或jyutping()时卡住几秒，第二次就快了。

原因：首次调用要加载语料库和词典到内存，初始化成本高。

解决：把加载步骤放到程序启动阶段，用“预热”解决线上首次请求的卡顿。做法很简单，程序启动后主动先跑一次空分词，让语料库完成加载：

import pycantonese as pc # 预热：启动阶段主动触发一次词典加载 pc.segment("我哋") # 后续业务调用不会再触发加载 tokens = pc.segment("今日去茶餐廳")

如果是在 Web 服务里用，这个预热要放在 Worker 启动函数里，而不是放在请求处理函数里。放在请求里，第一个用户就要替你承担这几秒的初始化延迟。

6. 进阶：把它接进歌词字幕标注管道，顺便救回多音字

把前面的技巧串起来，就是一个可以直接放进项目的歌词或字幕注音管道。我平时做这类任务时，会把管道封装成纯函数，输入一行文本，输出逐词注音结果，方便单测也方便复用：

import re from functools import lru_cache import pycantonese as pc PRIORITY = { "中意": [("中", "zung3"), ("意", "ji3")], "唔該": [("唔", "m4"), ("該", "goi1")], } @lru_cache(maxsize=4096) def lookup(word): if word in PRIORITY: return PRIORITY[word] return pycantonese.jyutping(word) def annotate_line(line): # 去除歌词常见的标点，只保留正文 cleaned = re.sub(r"[，。！？、\s]+", "", line) words = pc.segment(cleaned) return [(word, lookup(word)) for word in words] for line in ["佢哋好鍾意食蛋撻", "唔該要一杯凍奶茶"]: print(line, "=>", annotate_line(line))

这个管道的核心设计是三层结构：分词负责切词，优先表负责钉死多音字，缓存负责扛批量。每一层都可以单独测试和替换，比如某天你换了一个更大的粤语词典，分词层和缓存层不受影响。它的边界也很清楚：只处理正文文本，不负责分离歌词里的时间轴和歌曲信息，那些需要在管道外面单独解析。

如果跑出来的注音要用于语音合成前端，还有一个额外动作：把结果按“字”而不是按“词”对齐，因为合成引擎通常需要逐字读音。此时只要把列表里的二元组展开成单字级对应即可，逻辑不复杂，但必须确认分词结果里每个字都被覆盖到，漏字的话后面韵律标注全是错位。

说句实话，这种管道跑通不难，难的是后续维护。我之前做一个模拟粤语字幕项目，第一批批量注音出来错误率不到百分之几，我以为没问题，直到测试用户反馈“中意”读成了“中间”的意思，才发现多音字错音是批量跑完后最刺眼的硬伤。从那以后我养成一个习惯：每次批量注音完，按字频从高到低抽 20 条人工扫一遍，再决定要不要补优先表。词典会漏，规则会错，但人工抽检能把翻车概率压到可接受的水平。希望这个思路帮到你。

本文还有配套的精品资源，点击获取