简介汉语词典数据库收录21104个汉字与符号覆盖标点、数学符号等字段含带声调与无声调拼音、笔画数、偏旁、页面链接及详情文本面向中文文本处理、汉字学习工具或词典类应用开发者可用于快速获得结构化汉语数据。压缩包共33个文件以JSON数据为主28个附JavaScript脚本、README说明等整体约33.36MB。数据文件提供完整版、按区间分片版、精简版、纯汉字表及拼音对照表等多种形态兼顾完整性、体积与检索效率完整版适合整体分析分片版便于增量更新与差异对比精简版省去详情信息以减小体积纯汉字表便于词频统计拼音对照表可辅助注音处理。已有513人学习/下载。配套脚本与清晰目录结构可按需选取全量或分片数据在个人项目中有效缩短汉语数据整理与结构化时间适合中文NLP、辞书研究及前端字典场景直接复用资源仅限个人学习使用禁止商用。1. 汉语词典数据库HTTP接口为什么值得自己动手做一套做 NLP 项目、做汉语学习工具、做古籍校对系统几乎都绕不开一个尴尬的现状市面上能直接用的汉语词典数据库要么闭源收费要么结构混乱、字段对不上要么干脆就是一个巨大的 JSON 文件让你自己解析连个像样的查询接口都没有。chinese-dictionary这个方向解决的正是这个痛点把一本或多本汉语词典的结构化数据整理成统一的数据库再暴露出一套 HTTP 接口让任何语言写的程序都能通过简单的 GET 请求查到词语解释、拼音、例句甚至异形词信息。它适合正在做中文分词、语义检索、词义消歧的开发者也适合想给自家产品配一个轻量词典查询服务的人。我最早被这个标题吸引是因为手里有一个某高校的语料标注项目需要批量查询五千多个词的词性和释义。当时直接读 JSON 文件单线程跑一次要四五个小时而且数据结构三天两头变维护成本极高。后来换成了落库加 HTTP 接口的方案查询耗时从秒级降到毫秒级前端和脚本都能用同一套 API整个流程才真正稳定下来。这篇文章就沿着「数据库怎么设计 → HTTP 接口怎么搭 → 参数怎么调 → 哪些坑必须躲」这条线把我验证过的方案完整讲一遍。2. 先搞懂数据从哪来词典数据的三种来源与格式取舍2.1 开源词典数据的常见形态JSON、TXT 还是 SQLite做汉语词典数据库的第一步不是写代码而是先把源数据的格式摸清楚。我接触过的公开词典数据大概有三种形态每种都有自己的脾气。第一种是结构良好的 JSON 文件比如一些开源汉英词典导出的数据每条记录包含词语、拼音、解释、标签等字段这种最友好解析简单直接就能映射到表结构。第二种是纯文本格式通常是一行一个词条用制表符或特定分隔符切开字段不固定某些词条有例句某些没有解析时需要写兼容逻辑。第三种是现成的 SQLite 文件别人已经整理好了但表结构往往不符合你的需求字段命名混乱甚至存在重复词条需要清洗。我自己的经验是除非源数据本身就是你从权威词典方合法获取的结构化导出文件否则不要轻信任何声称「全量、干净、无重复」的现成数据库。曾经拿到过一个号称收录六十万词条的某词典导出包落库后发现重复词条超过四万还有大量解释字段为空的残次记录。所以无论来源是什么第一步永远是数据体检统计总条数、检查必填字段的空值率、抽查词条内容是否完整。这一步花掉的半小时能省下后面排错的一整天。2.2 选择存储引擎SQLite 用于本地PostgreSQL 用于服务化存储引擎的选择直接决定后续 HTTP 接口的性能上限。如果词典数据只做本地查询、单机使用SQLite 是最省事的方案单文件、零配置、事务安全支持全文搜索的 FTS5 扩展也够用而且把 .db 文件直接分发给别人就能复用。我通常把 SQLite 版本作为开发期的主力迭代快、好调试。但如果要把词典服务部署到服务器上、支持多用户并发查询SQLite 的写锁和并发瓶颈会很快成为问题这时候就需要迁到 PostgreSQL 或者 MySQL。PostgreSQL 的优势在于支持 GIN 索引、中文分词扩展、JSONB 字段对多条件组合查询和全文检索的支持远超 SQLite。实际线上项目中我用的是 PostgreSQL 加pg_trgm扩展做模糊匹配配合zhparser做中文分词查询带「落霞与孤鹜齐飞」这种整句也能快速返回相关词条。选型理由很简单数据量在百万级以下SQLite 完全够用数据量在百万级以上或者需要并发读PostgreSQL 更稳妥。不要一开始就上重型数据库词典数据的读取场景远多于写入单机性能瓶颈通常不在存储引擎而在索引设计。2.3 数据清洗脚本统一拼音、繁简、多音字字段拿到源数据后必须做一轮清洗否则接口查出来的结果会对用户造成误导。最常见的坑是拼音字段格式不统一有的带声调zhōng wén有的带数字zhong1 wen2有的干脆没标。我的做法是统一转成带声调的格式并且额外存一份不带声调、不带空格的纯字母字段专门用来做模糊查询和拼音匹配。还有繁简体的问题同一个词条在源数据里可能既有简体又有繁体最好拆成word_simplified和word_traditional两个字段查询时自动映射。多音字的处理比较微妙比如「行」在「行走」里读xíng在「行列」里读háng。源数据里如果只有一个拼音字段通常只记录最常见的读音这对词典查询是能接受的但对 TTS 或语音合成场景就不够。我的方案是单独建一张polyphone表记录词语级别的读音覆盖查询时先查该表查不到再回落到默认读音。数据清洗脚本一般用 Python 写配合opencc做繁简转换、pypinyin做拼音标注脚本跑完后输出一份清洗报告列出空值率、重复率、异常字符百分比方便自己判断数据是否达标。3. 数据库表结构设计五张表把词典数据拆得明明白白3.1 核心词条表word 表的字段设计与索引策略词条表是整个数据库的心脏字段设计要兼顾查询效率和数据完整性。我常用的结构是id自增主键、word存简体词形、word_traditional存繁体、pinyin存带声调拼音、pinyin_plain存无调拼音、explanation存 JSON 格式的解释列表、frequency存词频权重、source存数据来源标识、created_at和updated_at记录时间。解释字段用 JSON 而不是单独建表是因为一个词条的解释条目数量不固定而且不同来源的解释结构差异大JSON 的灵活性远高于强行拆表。索引设计上word字段必须建唯一索引因为词典查询绝大多数是精确匹配。pinyin_plain字段建普通索引支持拼音查询。word字段还需要建一个前缀索引或 trigram 索引用来支持「以某字开头」或「包含某字」的模糊查询。PostgreSQL 下我会用CREATE EXTENSION pg_trgm然后建 GIN 索引SQLite 下就用默认的 B-tree 索引配合LIKE查询。实测下来五十万词条的量级精确查询在 5ms 以内模糊查询在 30ms 左右完全够用。CREATE TABLE word ( id BIGSERIAL PRIMARY KEY, word VARCHAR(64) NOT NULL, word_traditional VARCHAR(64), pinyin VARCHAR(128), pinyin_plain VARCHAR(128), explanation JSONB NOT NULL DEFAULT [], frequency INTEGER DEFAULT 0, source VARCHAR(32), created_at TIMESTAMP DEFAULT now(), updated_at TIMESTAMP DEFAULT now() ); CREATE UNIQUE INDEX idx_word_unique ON word(word); CREATE INDEX idx_word_prefix ON word USING gin (word gin_trgm_ops); CREATE INDEX idx_pinyin_plain ON word(pinyin_plain);3.2 例句、分词、异形词关系表为什么不能全塞进一个 JSON词条主表搞定之后还有三类数据需要单独建表例句、分词信息、异形词映射。例句如果直接塞进word表的 JSON 字段里查询「包含某词的所有例句」就会变成全表扫描性能不可接受。我单独建了example表字段为id、word_id外键、example_text、example_source并在word_id上建索引。分词信息表word_segment记录一个词条被拆分成的最小语义单元比如「中华人民共和国」拆成「中华」「人民」「共和国」用于搜索引擎的召回优化。异形词表variant的意义在于处理繁体、异体、港台用语的映射比如「计算机」和「电脑」不是异形词但「裏」和「里」就是。这张表记录standard_word_id和variant_word两个字段查询时先规范化输入再映射到标准词条。曾经遇到过一个翻车案例用户搜索「裏」返回空结果因为词库里只有繁体词条裡而异形词映射表没建全。建了variant表之后这类问题从根上解决前提是映射数据要尽量全这个只能靠积累。3.3 全文检索与拼音检索索引让 HTTP 接口支持模糊搜如果接口只支持精确查询使用价值会大打折扣用户输入「春晓」时你可能只能返回李白那首诗。所以必须提前设计好全文检索方案。PostgreSQL 里我用zhparser做中文分词配置然后建一个生成列search_vector把word、explanation拼接后转成 tsvector再建 GIN 索引。查询时用plainto_tsquery解析用户输入匹配度高的结果排在前面。拼音检索相对简单pinyin_plain字段已经存了无调拼音查询时把用户输入也转成无调拼音做 LIKE 匹配即可。要注意一个细节中文全文检索的tsvector不能直接用默认配置默认配置会把中文按单字切分查「中国」会匹配所有包含「中」和「国」的单字记录噪声巨大。用zhparser后按词组切分查询精度明显提升。SQLite 下我用的 FTS5 同样支持自定义分词器但社区方案不如 PostgreSQL 成熟所以如果项目对模糊搜索要求高我会直接选 PostgreSQL而不是在 SQLite 上折腾。4. 搭建 HTTP 接口从 HTTP 裸接口到 FastAPI 的完整实现4.1 接口路径设计精确查询、模糊搜索、拼音检索三条路由HTTP 接口的路径设计要尽量贴合使用场景我一般暴露三条核心路由精确查询GET /api/word/{word}模糊搜索GET /api/search?qkeywordlimit20拼音检索GET /api/pinyin?qzhongwenlimit20。精确查询返回单个词条的全部字段包括解释、拼音、例句模糊搜索返回匹配词条列表按frequency字段降序排列拼音检索接收无调拼音或带调拼音统一转成pinyin_plain格式后再查库。设计上还有一个容易忽略的点HTTP 响应格式需要统一。我前后换过两版第一版每个接口返回的 JSON 结构都不一样前端解析逻辑写得非常痛苦。后来统一成{ code: 0, message: ok, data: {...} }的格式code非 0 表示业务错误比如词条不存在返回code: 40401参数错误返回code: 40001。这个统一格式对调用方非常友好也方便后期加限流和日志。4.2 用 FastAPI 实现查询接口参数校验与响应序列化FastAPI 是我目前的首选框架理由很直接自带 OpenAPI 文档、请求参数类型校验、异步支持而且性能在 Python 生态里属于第一梯队。下面这段代码实现了精确查询和拼音检索两个接口核心逻辑是先从参数取出关键词然后调用查询函数最后统一返回。注意拼音检索时要把带调拼音转成无调拼音这一步在接口层做而不是在 SQL 里做是为了让pinyin_plain索引能命中。from fastapi import FastAPI, HTTPException, Query from pydantic import BaseModel from typing import Optional import re app FastAPI(title汉语词典查询服务, version1.0.0) class WordResponse(BaseModel): word: str pinyin: str explanation: list examples: list def normalize_pinyin(pinyin: str) - str: tone_map {ā: a, á: a, ǎ: a, à: a, ē: e, é: e, ě: e, è: e, ī: i, í: i, ǐ: i, ì: i, ō: o, ó: o, ǒ: o, ò: o, ū: u, ú: u, ǔ: u, ù: u} result [] for ch in pinyin: if ch in tone_map: result.append(tone_map[ch]) elif ch.isalpha(): result.append(ch) return .join(result) app.get(/api/word/{word}, response_modelWordResponse) async def lookup_word(word: str): row await db.fetch_one(SELECT * FROM word WHERE word $1, word) if not row: raise HTTPException(status_code404, detail词条不存在) examples await db.fetch_all(SELECT example_text FROM example WHERE word_id $1, row[id]) return WordResponse(wordrow[word], pinyinrow[pinyin], explanationrow[explanation], examples[e[example_text] for e in examples])逻辑说明normalize_pinyin函数把带声调拼音转成无调拼音用户输入zhōngwén也能命中zhongwen索引。参数校验交给 FastAPI 的路由声明完成比如路径参数{word}自动处理 URL 编码问题。实际部署时还要加一个Query参数用于控制返回条数limit默认 20、最大 100防止有人一口气拉走全库数据。4.3 连接池与缓存层让查询响应稳定在 10ms 以内数据库连接池是接口稳定性的基础。Python 的asyncpg连接池默认最大连接数 10高并发时不够用。我把最小连接数设为 5、最大设为 50并开启statement_cache_size到 100避免每次查询都重新解析 SQL。查询结果缓存是另一个关键优化用redis或内存缓存cachetools都行我习惯用后者零依赖直接加一个 LRU 缓存装饰器。缓存键的设计要小心精确查询用word:{word}模糊搜索用search:{q}:{limit}拼音检索用pinyin:{normalized}。缓存过期时间默认 24 小时因为词典数据很少变动更新词库后手动清缓存即可。加了缓存后接口响应时间从平均 25ms 降到 4ms 左右而且数据库的连接数压力大幅减小。如果你部署在 Docker 容器里内存缓存一定要设置最大条目数否则内存被缓存的查询结果吃满后进程会 OOM这是我在生产环境踩过的真实的坑。5. 部署与参数调优Docker 编排、索引失效与性能瓶颈排查5.1 用 Docker Compose 跑起数据库和接口服务的完整配置部署环节我推荐直接上 Docker Compose一条命令就能把 PostgreSQL 和 FastAPI 服务拉起来环境一致性有保证。下面这段配置里db服务负责数据库api服务负责 HTTP 接口两个容器通过内部网络通信。需要注意的关键参数是 PostgreSQL 的shared_buffers和max_connections默认值偏保守根据服务器内存和预估并发量调整。另一个容易忽略的是持久化卷pgdata必须挂到宿主机路径否则容器重建后数据全丢这个后悔药是没有的。version: 3.8 services: db: image: postgres:15 environment: POSTGRES_USER: dict_user POSTGRES_PASSWORD: dict_password POSTGRES_DB: chinese_dict volumes: - ./pgdata:/var/lib/postgresql/data ports: - 5432:5432 command: postgres -c shared_buffers1GB -c max_connections200 -c effective_cache_size3GB api: build: . depends_on: - db environment: DATABASE_URL: postgresql://dict_user:dict_passworddb:5432/chinese_dict ports: - 8000:8000 command: uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4启动命令是docker compose up -d --build首次启动后检查两个容器的日志docker compose ps看状态docker compose logs api看接口服务是否报连接数据库错误。端口映射对外只暴露 8000数据库端口 5432 只允许内网访问生产环境一定要加防火墙规则否则数据库直接裸奔在公网上数据安全问题会被无限放大。5.2 索引失效的三种常见场景函数包裹、隐式类型转换、LIKE 前缀索引这东西建了不等于能用查询语句写得不对索引照样失效。最常见的失效场景是查询字段被函数包裹比如WHERE lower(word) lower(中国)PostgreSQL 无法对lower(word)使用普通 B-tree 索引。解决办法是改成WHERE word 中国 COLLATE C或者在表上建表达式索引CREATE INDEX ON word (lower(word))。第二种是隐式类型转换比如word字段是VARCHAR查询传参却是整数或某种自定义类型PostgreSQL 会放弃索引走全表扫描。第三种是LIKE %关键词%这种前导通配符的查询对普通 B-tree 索引无效只能用 trigram 或 GIN 索引。排查方法很简单执行EXPLAIN ANALYZE SELECT ...看到Seq Scan而不是Index Scan就说明索引没命中。我总结的常规操作是索引失效先看查询条件的字段类型和是否包裹了函数再看EXPLAIN结果最后考虑要不要建表达式索引。5.3 线上排查经验慢查询、连接耗尽、504 超时线上服务跑起来之后最常遇到的问题有三个。慢查询是最先遇到的通常是模糊搜索扫了全表现象是接口偶尔返回超过 1 秒紧急处理办法是先用EXPLAIN定位如果是因为索引没建补索引如果是因为查询条件太宽松比如搜索「一」这个词那就加frequency字段做排序过滤限制低价值结果。连接耗尽的现象是数据库日志疯狂报sorry, too many clients already原因通常是应用层连接池没做好或者某个批处理脚本反复创建新连接不释放。解决路径是统一用asyncpg连接池设置合理的min_size和max_size并且禁止在代码里直接create_connection。504 超时多半出在接口前面的网关层默认超时时间太短大查询被网关掐断。遇到这种情况我会先确认是不是查询真的需要这么久如果是全量导出类查询就单独走异步任务而不是挂在 HTTP 同步接口上。6. 避坑指南数据源、编码、并发三个维度的血泪经验6.1 词条重复同一词语在不同来源里解释不一致现象查询「苹果」返回两条记录一条解释是水果另一条解释是手机品牌而且词频权重都很高排序随机。原因合并多个词典来源时没有做词条去重或者不同来源的词性标注体系不同。解决落库前先按word做聚合生成canonical_id多条记录合并到一条记录上解释字段里保留来源标签比如{source: source_a, text: ...}。合并规则要明确优先保留权威来源其余来源作为补充解释。不要简单地去重丢数据因为不同来源的解释可能互为补充。6.2 编码问题繁体词条的 Unicode 规范化导致接口查不到现象用户复制了一个繁体词条「裏」来查询接口返回 404但词库里明明有这个词。原因用户输入的「裏」是 U88CF词库里的「裡」是 U88E1两个 Unicode 码点不同但视觉上几乎一样属于 CJK 兼容字形的典型问题。解决落库前对所有中文文本做 NFC 规范化查询时对用户输入也做同样的规范化。Python 里用unicodedata.normalize(NFC, text)PostgreSQL 里用normalize(text, NFC)。规范化之后需要重建索引因为它改变了字段的实际存储值。6.3 并发写入死锁批量导入词库时两条事务相互等待现象跑批量导入脚本时数据库日志报deadlock detected导入进程挂起。原因多个事务插入词条时A 事务先插了「中华」再插「人民」B 事务先插「人民」再插「中华」两个事务各自持有一把锁又等对方的锁形成死锁。解决批量导入时按词条首字母排序后再分批插入或者把隔离级别降为READ COMMITTED并给每条插入语句加ON CONFLICT DO NOTHING。如果数据量极大我建议干脆关掉事务自动提交每五千条词条手动COMMIT一次这样即使中途失败回滚代价也可控。7. 进阶用法把词典服务变成离线全文检索与词频推荐的底座7.1 用 HTTP 接口支撑前端拼音输入法和模糊联想接口搭好之后最常见的进阶用法是给前端输入框做拼音联想和模糊匹配。用户在搜索框输入zhong时前端实时调用GET /api/pinyin?qzhonglimit8接口返回以zhong开头的拼音对应词条按frequency排序效果就是输入法式的联想体验。需要注意的坑拼音联想查询要设置最短输入长度建议不低于 2 个字符否则返回结果太多且没有区分度。我还会在接口加一个match_mode参数prefix表示前缀匹配fuzzy表示编辑距离模糊匹配后者用pg_trgm的相似度函数实现前端可以根据输入长度自动切换模式。7.2 集成到分词与命名实体识别流程词库动态更新策略词典接口不仅可以人查也可以机器查。我把这个服务接入了某跨平台系统的分词模块当分词器遇到无法识别的组合词时回调词典服务的模糊搜索接口把候选词返回给分词模块做合并。这个方法能解决领域新词问题比如某公司内部产品名越来越多靠固定的分词词典永远跟不上更新节奏。更新策略上我维护了一张user_word表记录用户自定义词条查询时优先合并该表的结果。接口层加一个POST /api/word写入接口配合固定 token 做鉴权普通调用方没有写权限。7.3 性能验收清单推荐压测工具与验收指标上线前建议做一轮简单的压测工具用wrk或locust都行。验收指标我通常会卡三条并发 50 时平均响应时间小于 50msP99 小于 200ms精确查询成功率百分百模糊搜索在限流条件下不报 5xx数据库 CPU 使用率在压测峰值时不超过 70%。压测时要注意先预热缓存否则首轮请求全部穿透到数据库数据会虚高。另一个习惯是压测后检查连接池的实际使用峰值如果接近max_size说明并发容量已经到顶需要扩容或者调大连接数。这套服务我从本地 SQLite 起步逐步演进到 PostgreSQL 加 FastAPI 的线上架构中间经历过数据重复、编码陷阱、死锁、索引失效最后沉淀下来的是这套方案和这份避坑清单。希望帮到你愿你的词典数据不再是一堆没人敢动的 JSON 文件而是一个随时可查、可调、可扩展的正式服务。本文还有配套的精品资源点击获取
简介汉语词典数据库收录21104个汉字与符号覆盖标点、数学符号等字段含带声调与无声调拼音、笔画数、偏旁、页面链接及详情文本面向中文文本处理、汉字学习工具或词典类应用开发者可用于快速获得结构化汉语数据。压缩包共33个文件以JSON数据为主28个附JavaScript脚本、README说明等整体约33.36MB。数据文件提供完整版、按区间分片版、精简版、纯汉字表及拼音对照表等多种形态兼顾完整性、体积与检索效率完整版适合整体分析分片版便于增量更新与差异对比精简版省去详情信息以减小体积纯汉字表便于词频统计拼音对照表可辅助注音处理。已有513人学习/下载。配套脚本与清晰目录结构可按需选取全量或分片数据在个人项目中有效缩短汉语数据整理与结构化时间适合中文NLP、辞书研究及前端字典场景直接复用资源仅限个人学习使用禁止商用。1. 汉语词典数据库HTTP接口为什么值得自己动手做一套做 NLP 项目、做汉语学习工具、做古籍校对系统几乎都绕不开一个尴尬的现状市面上能直接用的汉语词典数据库要么闭源收费要么结构混乱、字段对不上要么干脆就是一个巨大的 JSON 文件让你自己解析连个像样的查询接口都没有。chinese-dictionary这个方向解决的正是这个痛点把一本或多本汉语词典的结构化数据整理成统一的数据库再暴露出一套 HTTP 接口让任何语言写的程序都能通过简单的 GET 请求查到词语解释、拼音、例句甚至异形词信息。它适合正在做中文分词、语义检索、词义消歧的开发者也适合想给自家产品配一个轻量词典查询服务的人。我最早被这个标题吸引是因为手里有一个某高校的语料标注项目需要批量查询五千多个词的词性和释义。当时直接读 JSON 文件单线程跑一次要四五个小时而且数据结构三天两头变维护成本极高。后来换成了落库加 HTTP 接口的方案查询耗时从秒级降到毫秒级前端和脚本都能用同一套 API整个流程才真正稳定下来。这篇文章就沿着「数据库怎么设计 → HTTP 接口怎么搭 → 参数怎么调 → 哪些坑必须躲」这条线把我验证过的方案完整讲一遍。2. 先搞懂数据从哪来词典数据的三种来源与格式取舍2.1 开源词典数据的常见形态JSON、TXT 还是 SQLite做汉语词典数据库的第一步不是写代码而是先把源数据的格式摸清楚。我接触过的公开词典数据大概有三种形态每种都有自己的脾气。第一种是结构良好的 JSON 文件比如一些开源汉英词典导出的数据每条记录包含词语、拼音、解释、标签等字段这种最友好解析简单直接就能映射到表结构。第二种是纯文本格式通常是一行一个词条用制表符或特定分隔符切开字段不固定某些词条有例句某些没有解析时需要写兼容逻辑。第三种是现成的 SQLite 文件别人已经整理好了但表结构往往不符合你的需求字段命名混乱甚至存在重复词条需要清洗。我自己的经验是除非源数据本身就是你从权威词典方合法获取的结构化导出文件否则不要轻信任何声称「全量、干净、无重复」的现成数据库。曾经拿到过一个号称收录六十万词条的某词典导出包落库后发现重复词条超过四万还有大量解释字段为空的残次记录。所以无论来源是什么第一步永远是数据体检统计总条数、检查必填字段的空值率、抽查词条内容是否完整。这一步花掉的半小时能省下后面排错的一整天。2.2 选择存储引擎SQLite 用于本地PostgreSQL 用于服务化存储引擎的选择直接决定后续 HTTP 接口的性能上限。如果词典数据只做本地查询、单机使用SQLite 是最省事的方案单文件、零配置、事务安全支持全文搜索的 FTS5 扩展也够用而且把 .db 文件直接分发给别人就能复用。我通常把 SQLite 版本作为开发期的主力迭代快、好调试。但如果要把词典服务部署到服务器上、支持多用户并发查询SQLite 的写锁和并发瓶颈会很快成为问题这时候就需要迁到 PostgreSQL 或者 MySQL。PostgreSQL 的优势在于支持 GIN 索引、中文分词扩展、JSONB 字段对多条件组合查询和全文检索的支持远超 SQLite。实际线上项目中我用的是 PostgreSQL 加pg_trgm扩展做模糊匹配配合zhparser做中文分词查询带「落霞与孤鹜齐飞」这种整句也能快速返回相关词条。选型理由很简单数据量在百万级以下SQLite 完全够用数据量在百万级以上或者需要并发读PostgreSQL 更稳妥。不要一开始就上重型数据库词典数据的读取场景远多于写入单机性能瓶颈通常不在存储引擎而在索引设计。2.3 数据清洗脚本统一拼音、繁简、多音字字段拿到源数据后必须做一轮清洗否则接口查出来的结果会对用户造成误导。最常见的坑是拼音字段格式不统一有的带声调zhōng wén有的带数字zhong1 wen2有的干脆没标。我的做法是统一转成带声调的格式并且额外存一份不带声调、不带空格的纯字母字段专门用来做模糊查询和拼音匹配。还有繁简体的问题同一个词条在源数据里可能既有简体又有繁体最好拆成word_simplified和word_traditional两个字段查询时自动映射。多音字的处理比较微妙比如「行」在「行走」里读xíng在「行列」里读háng。源数据里如果只有一个拼音字段通常只记录最常见的读音这对词典查询是能接受的但对 TTS 或语音合成场景就不够。我的方案是单独建一张polyphone表记录词语级别的读音覆盖查询时先查该表查不到再回落到默认读音。数据清洗脚本一般用 Python 写配合opencc做繁简转换、pypinyin做拼音标注脚本跑完后输出一份清洗报告列出空值率、重复率、异常字符百分比方便自己判断数据是否达标。3. 数据库表结构设计五张表把词典数据拆得明明白白3.1 核心词条表word 表的字段设计与索引策略词条表是整个数据库的心脏字段设计要兼顾查询效率和数据完整性。我常用的结构是id自增主键、word存简体词形、word_traditional存繁体、pinyin存带声调拼音、pinyin_plain存无调拼音、explanation存 JSON 格式的解释列表、frequency存词频权重、source存数据来源标识、created_at和updated_at记录时间。解释字段用 JSON 而不是单独建表是因为一个词条的解释条目数量不固定而且不同来源的解释结构差异大JSON 的灵活性远高于强行拆表。索引设计上word字段必须建唯一索引因为词典查询绝大多数是精确匹配。pinyin_plain字段建普通索引支持拼音查询。word字段还需要建一个前缀索引或 trigram 索引用来支持「以某字开头」或「包含某字」的模糊查询。PostgreSQL 下我会用CREATE EXTENSION pg_trgm然后建 GIN 索引SQLite 下就用默认的 B-tree 索引配合LIKE查询。实测下来五十万词条的量级精确查询在 5ms 以内模糊查询在 30ms 左右完全够用。CREATE TABLE word ( id BIGSERIAL PRIMARY KEY, word VARCHAR(64) NOT NULL, word_traditional VARCHAR(64), pinyin VARCHAR(128), pinyin_plain VARCHAR(128), explanation JSONB NOT NULL DEFAULT [], frequency INTEGER DEFAULT 0, source VARCHAR(32), created_at TIMESTAMP DEFAULT now(), updated_at TIMESTAMP DEFAULT now() ); CREATE UNIQUE INDEX idx_word_unique ON word(word); CREATE INDEX idx_word_prefix ON word USING gin (word gin_trgm_ops); CREATE INDEX idx_pinyin_plain ON word(pinyin_plain);3.2 例句、分词、异形词关系表为什么不能全塞进一个 JSON词条主表搞定之后还有三类数据需要单独建表例句、分词信息、异形词映射。例句如果直接塞进word表的 JSON 字段里查询「包含某词的所有例句」就会变成全表扫描性能不可接受。我单独建了example表字段为id、word_id外键、example_text、example_source并在word_id上建索引。分词信息表word_segment记录一个词条被拆分成的最小语义单元比如「中华人民共和国」拆成「中华」「人民」「共和国」用于搜索引擎的召回优化。异形词表variant的意义在于处理繁体、异体、港台用语的映射比如「计算机」和「电脑」不是异形词但「裏」和「里」就是。这张表记录standard_word_id和variant_word两个字段查询时先规范化输入再映射到标准词条。曾经遇到过一个翻车案例用户搜索「裏」返回空结果因为词库里只有繁体词条裡而异形词映射表没建全。建了variant表之后这类问题从根上解决前提是映射数据要尽量全这个只能靠积累。3.3 全文检索与拼音检索索引让 HTTP 接口支持模糊搜如果接口只支持精确查询使用价值会大打折扣用户输入「春晓」时你可能只能返回李白那首诗。所以必须提前设计好全文检索方案。PostgreSQL 里我用zhparser做中文分词配置然后建一个生成列search_vector把word、explanation拼接后转成 tsvector再建 GIN 索引。查询时用plainto_tsquery解析用户输入匹配度高的结果排在前面。拼音检索相对简单pinyin_plain字段已经存了无调拼音查询时把用户输入也转成无调拼音做 LIKE 匹配即可。要注意一个细节中文全文检索的tsvector不能直接用默认配置默认配置会把中文按单字切分查「中国」会匹配所有包含「中」和「国」的单字记录噪声巨大。用zhparser后按词组切分查询精度明显提升。SQLite 下我用的 FTS5 同样支持自定义分词器但社区方案不如 PostgreSQL 成熟所以如果项目对模糊搜索要求高我会直接选 PostgreSQL而不是在 SQLite 上折腾。4. 搭建 HTTP 接口从 HTTP 裸接口到 FastAPI 的完整实现4.1 接口路径设计精确查询、模糊搜索、拼音检索三条路由HTTP 接口的路径设计要尽量贴合使用场景我一般暴露三条核心路由精确查询GET /api/word/{word}模糊搜索GET /api/search?qkeywordlimit20拼音检索GET /api/pinyin?qzhongwenlimit20。精确查询返回单个词条的全部字段包括解释、拼音、例句模糊搜索返回匹配词条列表按frequency字段降序排列拼音检索接收无调拼音或带调拼音统一转成pinyin_plain格式后再查库。设计上还有一个容易忽略的点HTTP 响应格式需要统一。我前后换过两版第一版每个接口返回的 JSON 结构都不一样前端解析逻辑写得非常痛苦。后来统一成{ code: 0, message: ok, data: {...} }的格式code非 0 表示业务错误比如词条不存在返回code: 40401参数错误返回code: 40001。这个统一格式对调用方非常友好也方便后期加限流和日志。4.2 用 FastAPI 实现查询接口参数校验与响应序列化FastAPI 是我目前的首选框架理由很直接自带 OpenAPI 文档、请求参数类型校验、异步支持而且性能在 Python 生态里属于第一梯队。下面这段代码实现了精确查询和拼音检索两个接口核心逻辑是先从参数取出关键词然后调用查询函数最后统一返回。注意拼音检索时要把带调拼音转成无调拼音这一步在接口层做而不是在 SQL 里做是为了让pinyin_plain索引能命中。from fastapi import FastAPI, HTTPException, Query from pydantic import BaseModel from typing import Optional import re app FastAPI(title汉语词典查询服务, version1.0.0) class WordResponse(BaseModel): word: str pinyin: str explanation: list examples: list def normalize_pinyin(pinyin: str) - str: tone_map {ā: a, á: a, ǎ: a, à: a, ē: e, é: e, ě: e, è: e, ī: i, í: i, ǐ: i, ì: i, ō: o, ó: o, ǒ: o, ò: o, ū: u, ú: u, ǔ: u, ù: u} result [] for ch in pinyin: if ch in tone_map: result.append(tone_map[ch]) elif ch.isalpha(): result.append(ch) return .join(result) app.get(/api/word/{word}, response_modelWordResponse) async def lookup_word(word: str): row await db.fetch_one(SELECT * FROM word WHERE word $1, word) if not row: raise HTTPException(status_code404, detail词条不存在) examples await db.fetch_all(SELECT example_text FROM example WHERE word_id $1, row[id]) return WordResponse(wordrow[word], pinyinrow[pinyin], explanationrow[explanation], examples[e[example_text] for e in examples])逻辑说明normalize_pinyin函数把带声调拼音转成无调拼音用户输入zhōngwén也能命中zhongwen索引。参数校验交给 FastAPI 的路由声明完成比如路径参数{word}自动处理 URL 编码问题。实际部署时还要加一个Query参数用于控制返回条数limit默认 20、最大 100防止有人一口气拉走全库数据。4.3 连接池与缓存层让查询响应稳定在 10ms 以内数据库连接池是接口稳定性的基础。Python 的asyncpg连接池默认最大连接数 10高并发时不够用。我把最小连接数设为 5、最大设为 50并开启statement_cache_size到 100避免每次查询都重新解析 SQL。查询结果缓存是另一个关键优化用redis或内存缓存cachetools都行我习惯用后者零依赖直接加一个 LRU 缓存装饰器。缓存键的设计要小心精确查询用word:{word}模糊搜索用search:{q}:{limit}拼音检索用pinyin:{normalized}。缓存过期时间默认 24 小时因为词典数据很少变动更新词库后手动清缓存即可。加了缓存后接口响应时间从平均 25ms 降到 4ms 左右而且数据库的连接数压力大幅减小。如果你部署在 Docker 容器里内存缓存一定要设置最大条目数否则内存被缓存的查询结果吃满后进程会 OOM这是我在生产环境踩过的真实的坑。5. 部署与参数调优Docker 编排、索引失效与性能瓶颈排查5.1 用 Docker Compose 跑起数据库和接口服务的完整配置部署环节我推荐直接上 Docker Compose一条命令就能把 PostgreSQL 和 FastAPI 服务拉起来环境一致性有保证。下面这段配置里db服务负责数据库api服务负责 HTTP 接口两个容器通过内部网络通信。需要注意的关键参数是 PostgreSQL 的shared_buffers和max_connections默认值偏保守根据服务器内存和预估并发量调整。另一个容易忽略的是持久化卷pgdata必须挂到宿主机路径否则容器重建后数据全丢这个后悔药是没有的。version: 3.8 services: db: image: postgres:15 environment: POSTGRES_USER: dict_user POSTGRES_PASSWORD: dict_password POSTGRES_DB: chinese_dict volumes: - ./pgdata:/var/lib/postgresql/data ports: - 5432:5432 command: postgres -c shared_buffers1GB -c max_connections200 -c effective_cache_size3GB api: build: . depends_on: - db environment: DATABASE_URL: postgresql://dict_user:dict_passworddb:5432/chinese_dict ports: - 8000:8000 command: uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4启动命令是docker compose up -d --build首次启动后检查两个容器的日志docker compose ps看状态docker compose logs api看接口服务是否报连接数据库错误。端口映射对外只暴露 8000数据库端口 5432 只允许内网访问生产环境一定要加防火墙规则否则数据库直接裸奔在公网上数据安全问题会被无限放大。5.2 索引失效的三种常见场景函数包裹、隐式类型转换、LIKE 前缀索引这东西建了不等于能用查询语句写得不对索引照样失效。最常见的失效场景是查询字段被函数包裹比如WHERE lower(word) lower(中国)PostgreSQL 无法对lower(word)使用普通 B-tree 索引。解决办法是改成WHERE word 中国 COLLATE C或者在表上建表达式索引CREATE INDEX ON word (lower(word))。第二种是隐式类型转换比如word字段是VARCHAR查询传参却是整数或某种自定义类型PostgreSQL 会放弃索引走全表扫描。第三种是LIKE %关键词%这种前导通配符的查询对普通 B-tree 索引无效只能用 trigram 或 GIN 索引。排查方法很简单执行EXPLAIN ANALYZE SELECT ...看到Seq Scan而不是Index Scan就说明索引没命中。我总结的常规操作是索引失效先看查询条件的字段类型和是否包裹了函数再看EXPLAIN结果最后考虑要不要建表达式索引。5.3 线上排查经验慢查询、连接耗尽、504 超时线上服务跑起来之后最常遇到的问题有三个。慢查询是最先遇到的通常是模糊搜索扫了全表现象是接口偶尔返回超过 1 秒紧急处理办法是先用EXPLAIN定位如果是因为索引没建补索引如果是因为查询条件太宽松比如搜索「一」这个词那就加frequency字段做排序过滤限制低价值结果。连接耗尽的现象是数据库日志疯狂报sorry, too many clients already原因通常是应用层连接池没做好或者某个批处理脚本反复创建新连接不释放。解决路径是统一用asyncpg连接池设置合理的min_size和max_size并且禁止在代码里直接create_connection。504 超时多半出在接口前面的网关层默认超时时间太短大查询被网关掐断。遇到这种情况我会先确认是不是查询真的需要这么久如果是全量导出类查询就单独走异步任务而不是挂在 HTTP 同步接口上。6. 避坑指南数据源、编码、并发三个维度的血泪经验6.1 词条重复同一词语在不同来源里解释不一致现象查询「苹果」返回两条记录一条解释是水果另一条解释是手机品牌而且词频权重都很高排序随机。原因合并多个词典来源时没有做词条去重或者不同来源的词性标注体系不同。解决落库前先按word做聚合生成canonical_id多条记录合并到一条记录上解释字段里保留来源标签比如{source: source_a, text: ...}。合并规则要明确优先保留权威来源其余来源作为补充解释。不要简单地去重丢数据因为不同来源的解释可能互为补充。6.2 编码问题繁体词条的 Unicode 规范化导致接口查不到现象用户复制了一个繁体词条「裏」来查询接口返回 404但词库里明明有这个词。原因用户输入的「裏」是 U88CF词库里的「裡」是 U88E1两个 Unicode 码点不同但视觉上几乎一样属于 CJK 兼容字形的典型问题。解决落库前对所有中文文本做 NFC 规范化查询时对用户输入也做同样的规范化。Python 里用unicodedata.normalize(NFC, text)PostgreSQL 里用normalize(text, NFC)。规范化之后需要重建索引因为它改变了字段的实际存储值。6.3 并发写入死锁批量导入词库时两条事务相互等待现象跑批量导入脚本时数据库日志报deadlock detected导入进程挂起。原因多个事务插入词条时A 事务先插了「中华」再插「人民」B 事务先插「人民」再插「中华」两个事务各自持有一把锁又等对方的锁形成死锁。解决批量导入时按词条首字母排序后再分批插入或者把隔离级别降为READ COMMITTED并给每条插入语句加ON CONFLICT DO NOTHING。如果数据量极大我建议干脆关掉事务自动提交每五千条词条手动COMMIT一次这样即使中途失败回滚代价也可控。7. 进阶用法把词典服务变成离线全文检索与词频推荐的底座7.1 用 HTTP 接口支撑前端拼音输入法和模糊联想接口搭好之后最常见的进阶用法是给前端输入框做拼音联想和模糊匹配。用户在搜索框输入zhong时前端实时调用GET /api/pinyin?qzhonglimit8接口返回以zhong开头的拼音对应词条按frequency排序效果就是输入法式的联想体验。需要注意的坑拼音联想查询要设置最短输入长度建议不低于 2 个字符否则返回结果太多且没有区分度。我还会在接口加一个match_mode参数prefix表示前缀匹配fuzzy表示编辑距离模糊匹配后者用pg_trgm的相似度函数实现前端可以根据输入长度自动切换模式。7.2 集成到分词与命名实体识别流程词库动态更新策略词典接口不仅可以人查也可以机器查。我把这个服务接入了某跨平台系统的分词模块当分词器遇到无法识别的组合词时回调词典服务的模糊搜索接口把候选词返回给分词模块做合并。这个方法能解决领域新词问题比如某公司内部产品名越来越多靠固定的分词词典永远跟不上更新节奏。更新策略上我维护了一张user_word表记录用户自定义词条查询时优先合并该表的结果。接口层加一个POST /api/word写入接口配合固定 token 做鉴权普通调用方没有写权限。7.3 性能验收清单推荐压测工具与验收指标上线前建议做一轮简单的压测工具用wrk或locust都行。验收指标我通常会卡三条并发 50 时平均响应时间小于 50msP99 小于 200ms精确查询成功率百分百模糊搜索在限流条件下不报 5xx数据库 CPU 使用率在压测峰值时不超过 70%。压测时要注意先预热缓存否则首轮请求全部穿透到数据库数据会虚高。另一个习惯是压测后检查连接池的实际使用峰值如果接近max_size说明并发容量已经到顶需要扩容或者调大连接数。这套服务我从本地 SQLite 起步逐步演进到 PostgreSQL 加 FastAPI 的线上架构中间经历过数据重复、编码陷阱、死锁、索引失效最后沉淀下来的是这套方案和这份避坑清单。希望帮到你愿你的词典数据不再是一堆没人敢动的 JSON 文件而是一个随时可查、可调、可扩展的正式服务。本文还有配套的精品资源点击获取
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
