Python实现粤语拼音标注(Jyutping)完整教程

问题

在香港工作的内地开发者，都会遇到一个具体的技术需求：

如何用Python对粤语文字进行拼音标注？

这个需求在 StackOverflow 和 CSDN 上几乎找不到完整答案。

环境信息

• Python: 3.9+
• FastAPI: 0.100+
• 依赖：fastapi, uvicorn, pydantic

完整实现

1. 粤拼词库

粤拼（Jyutping）是香港语言学学会制定的粤语拼音方案，核心是声母+韵母+声调。

import json
from typing import Optional

class JyutpingDictionary:
    def __init__(self, dict_path: str = "jyutping_dict.json"):
        with open(dict_path, "r", encoding="utf-8") as f:
            self.dict_data = json.load(f)

    def lookup(self, char: str) -> Optional[str]:
        """单字查询"""
        return self.dict_data.get(char, None)

    def annotate(self, text: str) -> list[dict]:
        """整句标注"""
        result = []
        for char in text:
            jyutping = self.lookup(char)
            result.append({
                "char": char,
                "jyutping": jyutping,
                "known": jyutping is not None
            })
        return result

# 初始化
dict_obj = JyutpingDictionary()

2. 完整粤拼词库（部分数据）

{
  "我": "ngo5",
  "你": "nei5",
  "佢": "keoi5",
  "哋": "di1",
  "唔": "m4",
  "知": "zi1",
  "道": "dou6",
  "香港": "hoeng1 gong2",
  "广州": "gwong2 zau1",
  "深圳": "sam1 zan3",
  "工作": "gung1 zok3",
  "MPF": "MPF"
}

3. FastAPI接口

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import List

app = FastAPI(title="粤语拼音标注API")

class AnnotationResult(BaseModel):
    char: str
    jyutping: Optional[str]
    known: bool

class AnnotateRequest(BaseModel):
    text: str

@app.post("/api/annotate", response_model=List[AnnotationResult])
def annotate_text(request: AnnotateRequest):
    """粤语拼音标注接口"""
    if not request.text:
        raise HTTPException(status_code=400, detail="text不能为空")

    dict_obj = JyutpingDictionary()
    result = dict_obj.annotate(request.text)
    return result

@app.get("/api/health")
def health_check():
    """健康检查"""
    return {"status": "ok", "message": "粤语拼音标注API运行正常"}

4. 运行方式

# 安装依赖
pip install fastapi uvicorn

# 启动服务
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

5. 接口测试

curl -X POST http://localhost:8000/api/annotate \
  -H "Content-Type: application/json" \
  -d '{"text": "我唔知你想去边度"}'

Response:

[
  {"char": "我", "jyutping": "ngo5", "known": true},
  {"char": "唔", "jyutping": "m4", "known": true},
  {"char": "知", "jyutping": "zi1", "known": true},
  {"char": "你", "jyutping": "nei5", "known": true},
  {"char": "想", "jyutping": "soeng2", "known": true},
  ...
]

常见错误处理

错误1：UnicodeEncodeError

# 错误写法
with open("dict.txt", "w") as f:
    f.write("我=ngo5")

# 正确写法：指定UTF-8编码
with open("dict.txt", "w", encoding="utf-8") as f:
    f.write("我=ngo5")

错误2：JSON解析失败

# 错误：文件不是标准JSON格式
# 正确：确保JSON格式正确
import json
with open("jyutping_dict.json", "r", encoding="utf-8") as f:
    data = json.load(f)

完整源码

完整源码和粤拼词库已开源至我的工具网站：

hk.datatrade.top

总结

本文实现了：

1. 粤拼词库的数据结构设计
2. 单字查询和整句标注的Python实现
3. FastAPI接口封装
4. 常见错误处理

适合有Python基础的开发者直接复用。

扩展阅读

• Jyutping官方方案：http://www.jyutping.org/
• 粤拼输入法推荐：RimeIME