诗泉 chinese-poetry-api：37 万首古诗词装进一个 Docker，一条命令自建诗词 API

教程 2026-09-08 21:40

想做一个古诗词小程序、背诗机器人，或者给 AI 应用补一点真正的中国文学底子，最容易低估的往往不是界面，而是数据：数据从哪来？格式怎么统一？作者、朝代、体裁怎么关联？全文搜索怎么做？简繁体怎么兼容？这些“还没开始写功能”的事，足够把一个小项目拖进数据清洗的泥潭。

最近留意到一个很实在的开源项目——chinese-poetry-api（中文名“诗泉”）。它把近 40 万首中国古诗词整理成一个开箱即用的 API 服务：不用自己爬网页、不用设计表结构、不用先搭一套搜索系统，起个容器直接调接口就能拿到诗。

它到底是什么

诗泉是一个用 Go 语言编写的高性能中国古诗词 API 服务，数据源自经典的开源 chinese-poetry 数据集（仓库里用 Git Submodule 管理）。

几个关键事实（GitHub 实时数据，2026 年 9 月 8 日）：

仓库 palemoky/chinese-poetry-api，创建于 2025 年 12 月
2,810 stars / 357 forks，主力语言 Go，最近一次提交在 2026 年 9 月初
最新版 v0.6.0（2026 年 7 月发布），Docker 镜像约 17 MB
许可证 GPL-3.0（这点后面要单独提醒）

我对它的在线服务做了一次实测，/api/stats 返回的真实数据是：

{"data":{"poems":371313,"authors":13577,"dynasties":11,"types":17}}

——37 万首诗词、1.3 万位作者、11 个朝代、17 种体裁。这个量级意味着它不是“随机返回几首名诗”的演示玩具，而是一套能支撑检索、筛选和内容生成的数据底座。

覆盖面：不只是唐诗宋词

按体裁和朝代都做了自动分类，包括：

体裁：唐诗、宋词、元曲、诗经、楚辞、乐府诗、五代词、论语、四书五经，以及五言/七言绝句、五言/七言律诗等
朝代：先秦、两汉、魏晋、南北朝、隋、唐、五代、宋、元、清

其中光七言绝句和七言律诗合计就超过 15 万首，五言绝句和五言律诗也超过 9 万首。

真正好用的几个能力

1. 按朝代、作者、体裁随意叠加筛选

# 唐代诗词
curl "http://localhost:1279/api/v1/poems?dynasty=唐"

# 李白的五言绝句（支持分页）
curl "http://localhost:1279/api/v1/poems?author=李白&page=2&page_size=50"

做“诗人主页”“朝代专题”“每日推荐”这类功能，不用把数据全捞回来自己过滤。

2. 全文搜索：不只搜标题

用户记得“床前明月光”却不一定记得《静夜思》，也可能只记得诗里有个“月”。项目支持按标题、内容、作者分别检索，这对搜索框、聊天机器人和 AI 检索增强（RAG）来说，比“先下载 JSON 再造轮子”省事太多。

3. 随机来一首，还能带条件

# 随机一首
curl "https://poetry.palemoky.com/api/poems/random"

# 随机李白的五言绝句
curl "https://poetry.palemoky.com/api/poems/random?author=李白&type=五言绝句"

# 飞花令：随机抽一首含“春”的作品
curl "https://poetry.palemoky.com/api/poems/random?char=春"

实测第二条接口，返回的是李白《越女词五首三》：“耶溪采莲女，见客櫂歌回。笑入荷花去，佯羞不出来。”筛选条件可以自由叠加，一个“今日读什么”的产品原型到这里其实已经能跑起来了。

4. 简繁体共用一套接口

同一个库同时存简体与繁体，加个参数就切换：

curl "https://poetry.palemoky.com/api/poems/random?lang=zh-Hant"

实测返回的是关汉卿《感天动地窦娥冤・乔牌儿》的繁体原文。官方称简繁转换优化到约 300ns/op。做港澳台或海外中文用户、想加繁体阅读模式，不用再复制一套库。

5. REST 与 GraphQL 双协议

普通页面和小程序用 REST 足够直接；复杂前端或后台想一次只取需要的字段，可以走 GraphQL（端点 /graphql），不用为接口风格重做数据层。

一条命令跑起来

docker run -d -p 1279:1279 palemoky/chinese-poetry-api:latest

然后健康检查：curl http://localhost:1279/api/v1/health。容器首次启动会自动下载诗词数据库，不用手动导入几十万条数据；镜像支持 amd64 / arm64 多架构，群晖、NAS、树莓派都能跑。

常用环境变量：PORT（默认 1279）、TZ（建议 Asia/Shanghai）、RATE_LIMIT_RPS（默认 10）、RATE_LIMIT_BURST（默认 20）。内置 IP 限流，非法查询参数会返回 400 而不是悄悄忽略——准备公开部署的话，这些是真正能少踩坑的边界。

也可以从源码构建，仓库提供完整的 Makefile（make build、make process-data、make run-server）。

三个实测踩坑提醒

接口前缀不一样。自建服务是 /api/v1/poems，而官方在线版是 /api/poems。我实测在线版调 /api/v1/poems/search 直接返回 NOT_FOUND，照抄文档时留意。
搜索关键词有长度限制。实测搜索单字“月”会返回 q must be at least 3 characters，做飞花令要改用 /poems/random?char=春 这条路。
许可证是 GPL-3.0。个人项目、学习、自部署都没问题；但如果要做闭源商业产品分发，GPL 的传染性需要提前评估，别等要上线了才发现。

适合谁用

古诗词小程序 / 学习 App：作者页、朝代页、背诵抽查、每日一句
AI 应用与聊天机器人：给对话接上可靠的诗词检索，别再让大模型凭记忆“背诗”然后一本正经地编
内容创作者工具：输入主题或情绪，随机取诗句做标题灵感、配图文案、视频开场
开发练手：接口结构清晰，REST 和 GraphQL 都有，数据也够丰富，很适合做一份像样的作品

一点感想

很多开源项目给你一份数据文件，接下来怎么查、怎么搜、怎么部署还要自己补。诗泉的价值在于把“数据集”往前推了一步，变成了可调用、可部署、可扩展的服务。对开发者来说这个差别很大：你不用先花一周清洗古诗词数据才能验证想法，可以先调一个接口，让第一首诗出现在页面上，再决定这到底是个背诗工具、一个 AI 助手，还是一个把古典文学带回日常生活的小入口。

顺带一提，如果家里有孩子正在背古诗、学文言，拿它自己搭一个“每日一句”的小页面，比买 App 有意思得多——数据都是现成的。