简介：汉语词典数据库收录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?q=keyword&limit=20，拼音检索GET /api/pinyin?q=zhongwen&limit=20。精确查询返回单个词条的全部字段，包括解释、拼音、例句；模糊搜索返回匹配词条列表，按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="汉语词典查询服务", version="1.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_model=WordResponse) async def lookup_word(word: str): row = await db.fetch_one("SELECT * FROM word WHERE word = $1", word) if not row: raise HTTPException(status_code=404, detail="词条不存在") examples = await db.fetch_all("SELECT example_text FROM example WHERE word_id = $1", row["id"]) return WordResponse(word=row["word"], pinyin=row["pinyin"], explanation=row["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_buffers=1GB -c max_connections=200 -c effective_cache_size=3GB api: build: . depends_on: - db environment: DATABASE_URL: postgresql://dict_user:dict_password@db: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，但词库里明明有这个词。原因：用户输入的「裏」是 U+88CF，词库里的「裡」是 U+88E1，两个 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?q=zhong&limit=8，接口返回以zhong开头的拼音对应词条，按frequency排序，效果就是输入法式的联想体验。需要注意的坑：拼音联想查询要设置最短输入长度，建议不低于 2 个字符，否则返回结果太多且没有区分度。我还会在接口加一个match_mode参数，prefix表示前缀匹配，fuzzy表示编辑距离模糊匹配，后者用pg_trgm的相似度函数实现，前端可以根据输入长度自动切换模式。
7.2 集成到分词与命名实体识别流程：词库动态更新策略
词典接口不仅可以人查，也可以机器查。我把这个服务接入了某跨平台系统的分词模块，当分词器遇到无法识别的组合词时，回调词典服务的模糊搜索接口，把候选词返回给分词模块做合并。这个方法能解决领域新词问题，比如某公司内部产品名越来越多，靠固定的分词词典永远跟不上更新节奏。更新策略上，我维护了一张user_word表，记录用户自定义词条，查询时优先合并该表的结果。接口层加一个POST /api/word写入接口，配合固定 token 做鉴权，普通调用方没有写权限。
7.3 性能验收清单：推荐压测工具与验收指标
上线前建议做一轮简单的压测，工具用wrk或locust都行。验收指标我通常会卡三条：并发 50 时平均响应时间小于 50ms，P99 小于 200ms；精确查询成功率百分百，模糊搜索在限流条件下不报 5xx；数据库 CPU 使用率在压测峰值时不超过 70%。压测时要注意先预热缓存，否则首轮请求全部穿透到数据库，数据会虚高。另一个习惯是压测后检查连接池的实际使用峰值，如果接近max_size说明并发容量已经到顶，需要扩容或者调大连接数。
这套服务我从本地 SQLite 起步，逐步演进到 PostgreSQL 加 FastAPI 的线上架构，中间经历过数据重复、编码陷阱、死锁、索引失效，最后沉淀下来的是这套方案和这份避坑清单。希望帮到你，愿你的词典数据不再是一堆没人敢动的 JSON 文件，而是一个随时可查、可调、可扩展的正式服务。
本文还有配套的精品资源，点击获取
