1. 从一张 Excel 名单说起汉字转拼音到底难在哪先明确一件事Python 汉字批量转拼音指的是把中文文本姓名、地址、商品名、标签批量转换成拼音串常见输出形态有三种——全拼zhangsan、带声调全拼zhāngsān、首字母缩写zs。能做的事包括给通讯录生成拼音索引、给数据库补一列拼音字段、给搜索做拼音模糊匹配、给文件名做规范化。适合谁手头有一批中文数据、又不想一个个手敲拼音的人尤其是做后台、数据清洗、运营工具的同学。我最早遇到这个需求是帮朋友处理一份三千多行的员工名单。姓名转拼音看着简单真做起来坑不少多音字“单”“仇”“解”当姓氏时读音完全不同、声调要不要保留、首字母缩写怎么取、批量文件怎么读怎么写。手动敲不仅慢还容易错重复性极高。后来用pypinyin写了个脚本一次跑完还能复用。这篇就按工程化落地的思路来先给可复制的脚本骨架再讲多音字、声调、首字母缩写这些常见需求怎么配最后附一组能直接跑的验证命令。中间会用到 TaoToken 来管理模型调用相关的密钥与配置方便你把“脚本 模型辅助”这套流程固定下来。下面直接开干。2. 前置准备pypinyin 安装与 TaoToken 配置2.1 依赖清单核心就一个库pypinyin。批量处理文件再加pandas和openpyxl读写 Excel。如果你要顺带用大模型做多音字兜底判断再装openai或requests。pip install pypinyin pandas openpyxl requests版本上pypinyin建议 0.51 以上多音字词典更全。装完可以快速验证python -c import pypinyin; print(pypinyin.__version__)2.2 TaoToken 是什么为什么这里要用它TaoToken 是一个面向开发者的模型调用与密钥管理平台能做什么简单说它把模型对话、API Key 管理、编码计划Coding Plan这些能力集中到一处适合需要长期跑脚本、又要调用模型的场景。适合谁像我这样脚本里偶尔要“问一下模型”判断多音字、或者做文本清洗的人。它的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 这个不加 UTM。你需要先去控制台生成一个 API Key脚本里通过环境变量读取别硬编码进代码。# Linux / macOS export TAOTOKEN_API_KEY你的key # Windows PowerShell setx TAOTOKEN_API_KEY 你的key注意密钥只放环境变量或本地配置文件别提交到 Git。这是所有批量脚本的基本纪律。2.3 目录结构建议批量处理最怕文件乱。建议这样组织pinyin_project/ ├── input/ # 待处理的中文文件 ├── output/ # 转换结果 ├── config.py # 配置项 └── convert.py # 主脚本输入输出分离跑错了也不会覆盖原文件这是踩过坑之后的习惯。3. 可复制脚本pypinyin 批量转换骨架3.1 基础转换函数先写最核心的转换函数支持三种输出模式。pypinyin的style参数控制声调NORMAL不带声调TONE带声调符号TONE3用数字标声调。from pypinyin import pinyin, Style def to_pinyin(text, modenormal): mode: normal 全拼无声调 / tone 全拼带声调 / initials 首字母缩写 if not text or not isinstance(text, str): return if mode normal: style Style.NORMAL elif mode tone: style Style.TONE elif mode initials: style Style.FIRST_LETTER else: raise ValueError(f未知模式: {mode}) result pinyin(text, stylestyle, errorsignore) return .join([item[0] for item in result]) # 快速自测 print(to_pinyin(张三)) # zhangsan print(to_pinyin(张三, tone)) # zhāngsān print(to_pinyin(张三, initials)) # zserrorsignore表示遇到非汉字数字、英文、符号直接跳过避免报错。如果你希望保留原字符改成errorslambda x: x。3.2 多音字处理自定义词典多音字是最大的坑。比如“单”作姓氏读 shàn默认会转成 dān。pypinyin支持加载自定义词典优先级高于内置词典。from pypinyin import load_phrases_dict # 自定义多音字词典key 是词value 是每个字的读音列表 load_phrases_dict({ 单田芳: [[shàn], [tián], [fāng]], 解晓东: [[xiè], [xiǎo], [dōng]], 仇士良: [[qiú], [shì], [liáng]], }) print(to_pinyin(单田芳)) # shantianfang - 加载后应为 shantianfang 的 shàn 版本实测下来姓氏类多音字最好单独维护一个词典文件用 JSON 存脚本启动时加载import json from pypinyin import load_phrases_dict def load_custom_dict(pathcustom_dict.json): with open(path, r, encodingutf-8) as f: data json.load(f) # 转成 pypinyin 需要的格式 phrases {k: [[c] for c in v] for k, v in data.items()} load_phrases_dict(phrases) # custom_dict.json 示例 # {单田芳: [shàn, tián, fāng], 解晓东: [xiè, xiǎo, dōng]}3.3 批量文件输入输出用 pandas 读 Excel 或 CSV对指定列做转换再写回新文件。这是最通用的批量骨架。import pandas as pd from pathlib import Path def batch_convert(input_file, output_file, column, modenormal): df pd.read_excel(input_file) if input_file.suffix in (.xlsx, .xls) else pd.read_csv(input_file) if column not in df.columns: raise KeyError(f列 {column} 不存在现有列: {list(df.columns)}) df[f{column}_pinyin] df[column].apply(lambda x: to_pinyin(x, mode)) df.to_excel(output_file, indexFalse) if output_file.suffix in (.xlsx, .xls) else df.to_csv(output_file, indexFalse) print(f完成: {input_file.name} - {output_file.name}, 共 {len(df)} 行) if __name__ __main__: input_dir Path(input) output_dir Path(output) output_dir.mkdir(exist_okTrue) for f in input_dir.glob(*.xlsx): batch_convert(f, output_dir / f.name, column姓名, modenormal)跑之前确认输入文件里有一列叫“姓名”没有就改column参数。输出会多出一列姓名_pinyin原数据不动。3.4 用 TaoToken 做多音字兜底可选内置词典覆盖不到的生僻姓名可以让模型判断。这里用 TaoToken 的 API 地址密钥从环境变量读。import os import requests def model_pinyin_hint(word): api_key os.getenv(TAOTOKEN_API_KEY) if not api_key: return None url https://taotoken.net/api/v1/chat/completions headers {Authorization: fBearer {api_key}, Content-Type: application/json} payload { model: gpt-4o-mini, messages: [{role: user, content: f请给出“{word}”作为人名的拼音只返回拼音不要解释。}], } try: resp requests.post(url, jsonpayload, headersheaders, timeout10) resp.raise_for_status() return resp.json()[choices][0][message][content].strip() except Exception as e: print(f模型调用失败回退到 pypinyin: {e}) return None这段是兜底逻辑模型能答就用模型的答不了或超时就回退到pypinyin。别把模型当主力它慢且贵只用来处理词典覆盖不到的少数情况。4. 验证请求与成功结果4.1 单函数验证先跑最小验证确认三种模式都对python -c from pypinyin import pinyin, Style print(.join([x[0] for x in pinyin(重庆, styleStyle.NORMAL)])) print(.join([x[0] for x in pinyin(重庆, styleStyle.TONE)])) print(.join([x[0] for x in pinyin(重庆, styleStyle.FIRST_LETTER)])) 预期输出chongqing chóngqìng cq注意“重庆”的“重”读 chóng 不是 zhòngpypinyin内置词典能正确处理这就是用库而不是自己查表的价值。4.2 批量脚本验证准备一个测试 Excel两列姓名、部门。跑脚本python convert.py成功时终端会打印完成: test.xlsx - test.xlsx, 共 5 行打开output/test.xlsx应该看到新增的姓名_pinyin列值类似 zhangsan、lisi、wangwu。如果某行是空的检查原单元格是不是空值或纯符号。4.3 模型兜底验证设置好TAOTOKEN_API_KEY后单独测一下兜底函数python -c from convert import model_pinyin_hint print(model_pinyin_hint(单田芳)) 能返回拼音串就说明 TaoToken 这条链路通了。返回 None 说明密钥没读到或网络异常脚本会自动回退不影响主流程。5. 本篇常见错误排查5.1 ModuleNotFoundError: No module named pypinyin没装库或者装到了别的 Python 环境。先确认当前解释器which python python -m pip install pypinyin用python -m pip而不是裸pip能避免装错环境。虚拟环境里跑脚本时确保激活了对应环境。5.2 多音字转错比如“单”转成 dan内置词典没覆盖这个姓氏。解决办法是加载自定义词典见 3.2 节。注意load_phrases_dict要在调用pinyin之前执行且词典 key 是完整词不是单字。5.3 输出文件里拼音列全是 NaN多半是原列有空值或者列名写错了。to_pinyin对空值返回空字符串不会变 NaN如果整列 NaN检查column参数是否和 Excel 表头完全一致包括空格。用print(df.columns.tolist())打印实际列名核对。5.4 模型调用返回 401密钥没读到。检查环境变量echo $TAOTOKEN_API_KEYWindows 下setx设置后要重开终端才生效。另外确认请求头是Bearer加空格再加 key少空格会 401。5.5 处理大文件时内存爆掉几千行没问题几十万行要分块。用 pandas 的chunksizefor chunk in pd.read_excel(input_file, chunksize10000): chunk[pinyin] chunk[姓名].apply(to_pinyin) # 追加写入或者直接用 CSV 流式读写比 Excel 省内存。6. 把脚本固定下来密钥、文档与长期编码脚本能跑通只是第一步要长期复用得把密钥管理和接入文档固定住。TaoToken 的 API Key 在控制台生成接入文档里有完整的请求格式和参数说明照着配就行。如果你只是偶尔验证模型输出用模型对话页面手动测几条更省事如果像我一样要长期跑批量任务、甚至接进编码流程Coding Plan 更适合能把调用额度和密钥统一管起来。具体入口生成和管理密钥https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite查看接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite手动验证模型输出https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite长期编码与 Agent 场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite最后给个实用技巧把custom_dict.json和脚本一起放进 Git每次遇到新的多音字姓名就往词典里加一条跑得越多越准。这比每次临时改代码靠谱得多。脚本骨架已经给全剩下的就是拿你自己的数据跑一遍看输出对不对。 Python 汉字批量转拼音：用 pypinyin 配 TaoToken 搭一套可复用脚本
1. 从一张 Excel 名单说起汉字转拼音到底难在哪先明确一件事Python 汉字批量转拼音指的是把中文文本姓名、地址、商品名、标签批量转换成拼音串常见输出形态有三种——全拼zhangsan、带声调全拼zhāngsān、首字母缩写zs。能做的事包括给通讯录生成拼音索引、给数据库补一列拼音字段、给搜索做拼音模糊匹配、给文件名做规范化。适合谁手头有一批中文数据、又不想一个个手敲拼音的人尤其是做后台、数据清洗、运营工具的同学。我最早遇到这个需求是帮朋友处理一份三千多行的员工名单。姓名转拼音看着简单真做起来坑不少多音字“单”“仇”“解”当姓氏时读音完全不同、声调要不要保留、首字母缩写怎么取、批量文件怎么读怎么写。手动敲不仅慢还容易错重复性极高。后来用pypinyin写了个脚本一次跑完还能复用。这篇就按工程化落地的思路来先给可复制的脚本骨架再讲多音字、声调、首字母缩写这些常见需求怎么配最后附一组能直接跑的验证命令。中间会用到 TaoToken 来管理模型调用相关的密钥与配置方便你把“脚本 模型辅助”这套流程固定下来。下面直接开干。2. 前置准备pypinyin 安装与 TaoToken 配置2.1 依赖清单核心就一个库pypinyin。批量处理文件再加pandas和openpyxl读写 Excel。如果你要顺带用大模型做多音字兜底判断再装openai或requests。pip install pypinyin pandas openpyxl requests版本上pypinyin建议 0.51 以上多音字词典更全。装完可以快速验证python -c import pypinyin; print(pypinyin.__version__)2.2 TaoToken 是什么为什么这里要用它TaoToken 是一个面向开发者的模型调用与密钥管理平台能做什么简单说它把模型对话、API Key 管理、编码计划Coding Plan这些能力集中到一处适合需要长期跑脚本、又要调用模型的场景。适合谁像我这样脚本里偶尔要“问一下模型”判断多音字、或者做文本清洗的人。它的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 这个不加 UTM。你需要先去控制台生成一个 API Key脚本里通过环境变量读取别硬编码进代码。# Linux / macOS export TAOTOKEN_API_KEY你的key # Windows PowerShell setx TAOTOKEN_API_KEY 你的key注意密钥只放环境变量或本地配置文件别提交到 Git。这是所有批量脚本的基本纪律。2.3 目录结构建议批量处理最怕文件乱。建议这样组织pinyin_project/ ├── input/ # 待处理的中文文件 ├── output/ # 转换结果 ├── config.py # 配置项 └── convert.py # 主脚本输入输出分离跑错了也不会覆盖原文件这是踩过坑之后的习惯。3. 可复制脚本pypinyin 批量转换骨架3.1 基础转换函数先写最核心的转换函数支持三种输出模式。pypinyin的style参数控制声调NORMAL不带声调TONE带声调符号TONE3用数字标声调。from pypinyin import pinyin, Style def to_pinyin(text, modenormal): mode: normal 全拼无声调 / tone 全拼带声调 / initials 首字母缩写 if not text or not isinstance(text, str): return if mode normal: style Style.NORMAL elif mode tone: style Style.TONE elif mode initials: style Style.FIRST_LETTER else: raise ValueError(f未知模式: {mode}) result pinyin(text, stylestyle, errorsignore) return .join([item[0] for item in result]) # 快速自测 print(to_pinyin(张三)) # zhangsan print(to_pinyin(张三, tone)) # zhāngsān print(to_pinyin(张三, initials)) # zserrorsignore表示遇到非汉字数字、英文、符号直接跳过避免报错。如果你希望保留原字符改成errorslambda x: x。3.2 多音字处理自定义词典多音字是最大的坑。比如“单”作姓氏读 shàn默认会转成 dān。pypinyin支持加载自定义词典优先级高于内置词典。from pypinyin import load_phrases_dict # 自定义多音字词典key 是词value 是每个字的读音列表 load_phrases_dict({ 单田芳: [[shàn], [tián], [fāng]], 解晓东: [[xiè], [xiǎo], [dōng]], 仇士良: [[qiú], [shì], [liáng]], }) print(to_pinyin(单田芳)) # shantianfang - 加载后应为 shantianfang 的 shàn 版本实测下来姓氏类多音字最好单独维护一个词典文件用 JSON 存脚本启动时加载import json from pypinyin import load_phrases_dict def load_custom_dict(pathcustom_dict.json): with open(path, r, encodingutf-8) as f: data json.load(f) # 转成 pypinyin 需要的格式 phrases {k: [[c] for c in v] for k, v in data.items()} load_phrases_dict(phrases) # custom_dict.json 示例 # {单田芳: [shàn, tián, fāng], 解晓东: [xiè, xiǎo, dōng]}3.3 批量文件输入输出用 pandas 读 Excel 或 CSV对指定列做转换再写回新文件。这是最通用的批量骨架。import pandas as pd from pathlib import Path def batch_convert(input_file, output_file, column, modenormal): df pd.read_excel(input_file) if input_file.suffix in (.xlsx, .xls) else pd.read_csv(input_file) if column not in df.columns: raise KeyError(f列 {column} 不存在现有列: {list(df.columns)}) df[f{column}_pinyin] df[column].apply(lambda x: to_pinyin(x, mode)) df.to_excel(output_file, indexFalse) if output_file.suffix in (.xlsx, .xls) else df.to_csv(output_file, indexFalse) print(f完成: {input_file.name} - {output_file.name}, 共 {len(df)} 行) if __name__ __main__: input_dir Path(input) output_dir Path(output) output_dir.mkdir(exist_okTrue) for f in input_dir.glob(*.xlsx): batch_convert(f, output_dir / f.name, column姓名, modenormal)跑之前确认输入文件里有一列叫“姓名”没有就改column参数。输出会多出一列姓名_pinyin原数据不动。3.4 用 TaoToken 做多音字兜底可选内置词典覆盖不到的生僻姓名可以让模型判断。这里用 TaoToken 的 API 地址密钥从环境变量读。import os import requests def model_pinyin_hint(word): api_key os.getenv(TAOTOKEN_API_KEY) if not api_key: return None url https://taotoken.net/api/v1/chat/completions headers {Authorization: fBearer {api_key}, Content-Type: application/json} payload { model: gpt-4o-mini, messages: [{role: user, content: f请给出“{word}”作为人名的拼音只返回拼音不要解释。}], } try: resp requests.post(url, jsonpayload, headersheaders, timeout10) resp.raise_for_status() return resp.json()[choices][0][message][content].strip() except Exception as e: print(f模型调用失败回退到 pypinyin: {e}) return None这段是兜底逻辑模型能答就用模型的答不了或超时就回退到pypinyin。别把模型当主力它慢且贵只用来处理词典覆盖不到的少数情况。4. 验证请求与成功结果4.1 单函数验证先跑最小验证确认三种模式都对python -c from pypinyin import pinyin, Style print(.join([x[0] for x in pinyin(重庆, styleStyle.NORMAL)])) print(.join([x[0] for x in pinyin(重庆, styleStyle.TONE)])) print(.join([x[0] for x in pinyin(重庆, styleStyle.FIRST_LETTER)])) 预期输出chongqing chóngqìng cq注意“重庆”的“重”读 chóng 不是 zhòngpypinyin内置词典能正确处理这就是用库而不是自己查表的价值。4.2 批量脚本验证准备一个测试 Excel两列姓名、部门。跑脚本python convert.py成功时终端会打印完成: test.xlsx - test.xlsx, 共 5 行打开output/test.xlsx应该看到新增的姓名_pinyin列值类似 zhangsan、lisi、wangwu。如果某行是空的检查原单元格是不是空值或纯符号。4.3 模型兜底验证设置好TAOTOKEN_API_KEY后单独测一下兜底函数python -c from convert import model_pinyin_hint print(model_pinyin_hint(单田芳)) 能返回拼音串就说明 TaoToken 这条链路通了。返回 None 说明密钥没读到或网络异常脚本会自动回退不影响主流程。5. 本篇常见错误排查5.1 ModuleNotFoundError: No module named pypinyin没装库或者装到了别的 Python 环境。先确认当前解释器which python python -m pip install pypinyin用python -m pip而不是裸pip能避免装错环境。虚拟环境里跑脚本时确保激活了对应环境。5.2 多音字转错比如“单”转成 dan内置词典没覆盖这个姓氏。解决办法是加载自定义词典见 3.2 节。注意load_phrases_dict要在调用pinyin之前执行且词典 key 是完整词不是单字。5.3 输出文件里拼音列全是 NaN多半是原列有空值或者列名写错了。to_pinyin对空值返回空字符串不会变 NaN如果整列 NaN检查column参数是否和 Excel 表头完全一致包括空格。用print(df.columns.tolist())打印实际列名核对。5.4 模型调用返回 401密钥没读到。检查环境变量echo $TAOTOKEN_API_KEYWindows 下setx设置后要重开终端才生效。另外确认请求头是Bearer加空格再加 key少空格会 401。5.5 处理大文件时内存爆掉几千行没问题几十万行要分块。用 pandas 的chunksizefor chunk in pd.read_excel(input_file, chunksize10000): chunk[pinyin] chunk[姓名].apply(to_pinyin) # 追加写入或者直接用 CSV 流式读写比 Excel 省内存。6. 把脚本固定下来密钥、文档与长期编码脚本能跑通只是第一步要长期复用得把密钥管理和接入文档固定住。TaoToken 的 API Key 在控制台生成接入文档里有完整的请求格式和参数说明照着配就行。如果你只是偶尔验证模型输出用模型对话页面手动测几条更省事如果像我一样要长期跑批量任务、甚至接进编码流程Coding Plan 更适合能把调用额度和密钥统一管起来。具体入口生成和管理密钥https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite查看接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite手动验证模型输出https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite长期编码与 Agent 场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite最后给个实用技巧把custom_dict.json和脚本一起放进 Git每次遇到新的多音字姓名就往词典里加一条跑得越多越准。这比每次临时改代码靠谱得多。脚本骨架已经给全剩下的就是拿你自己的数据跑一遍看输出对不对。