chinese-poetry-api README

The project's README from github.com/palemoky/chinese-poetry-api. As one markdown file: README.md.

chinese-poetry

中国古诗词 API 服务

Docker Image Docker Image Size pre-commit License

基于 Go 语言的高性能中国古诗词 API 服务，支持 REST 和 GraphQL 接口，提供简体/繁体中文、爬虫练习场等功能。

在线版：https://poetry.palemoky.com

palemoky%2Fchinese-poetry-api | Trendshift

特性

快速开始

使用 Docker（推荐）

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

完整配置参见 docker-compose.yml。

使用 Makefile

make help          # 查看所有可用命令
make build         # 构建项目
make process-data  # 处理数据
make run-server    # 启动服务

克隆仓库

本项目使用 Git Submodules 管理诗词数据，推荐使用以下命令快速克隆：

# 完整克隆（包含 submodules）
git clone --recurse-submodules --depth=1 https://github.com/palemoky/chinese-poetry-api.git

如果已经克隆了仓库，可以单独更新 submodules：

git submodule update --init --depth 1

API 使用

多语言支持

所有接口支持 lang 参数切换简繁体：

参数值 说明
zh-Hans 简体中文（默认）
zh-Hant 繁体中文

REST API

# 健康检查
curl "http://localhost:1279/api/v1/health"

# 统计信息
curl "http://localhost:1279/api/v1/stats"

# 简体中文（默认）
curl "http://localhost:1279/api/v1/poems"

# 繁体中文
curl "http://localhost:1279/api/v1/poems?lang=zh-Hant"

# 诗词列表（带过滤，与 /poems/random 使用同一组参数）
curl "http://localhost:1279/api/v1/poems?dynasty=唐"
curl "http://localhost:1279/api/v1/poems?author=李白&page=2&page_size=50"
curl "http://localhost:1279/api/v1/poems?dynasty_id=1&type_id=11&type_id=12" # 多个 type_id 为「或」关系

# 游标翻页：把上一页 pagination.next_cursor 的值回传给 after。
curl "http://localhost:1279/api/v1/poems?page_size=50&after=cG9lbTo0MjA"

# 搜索诗词
curl "http://localhost:1279/api/v1/poems/search?q=静夜思"

# 随机诗词
curl "http://localhost:1279/api/v1/poems/random"

# 随机诗词（带过滤）
curl "http://localhost:1279/api/v1/poems/random?author=李白"
curl "http://localhost:1279/api/v1/poems/random?type=五言绝句"
curl "http://localhost:1279/api/v1/poems/random?char=春" # 飞花令等单字场景
curl "http://localhost:1279/api/v1/poems/random?author=李白&type=五言绝句"
curl "http://localhost:1279/api/v1/poems/random?author=李白&type=五言绝句&dynasty=唐"
curl "http://localhost:1279/api/v1/poems/random?author=李白&dynasty=唐&type=五言绝句&type=七言绝句&type=五言律诗"

# 作者列表
curl "http://localhost:1279/api/v1/authors?page=1&page_size=20"

# 作者详情
curl "http://localhost:1279/api/v1/authors/1"

# 朝代列表
curl "http://localhost:1279/api/v1/dynasties"

# 朝代详情
curl "http://localhost:1279/api/v1/dynasties/1"

# 诗词体裁列表
curl "http://localhost:1279/api/v1/types"

# 诗词体裁详情
curl "http://localhost:1279/api/v1/types/10"

GraphQL API

端点：http://localhost:1279/graphql

# 繁体中文查询
query {
  poems(lang: ZH_HANT, pageSize: 10) {
    edges {
      node {
        title
        content
        author {
          name
        }
      }
    }
    totalCount
  }
}

# 搜索诗词
query {
  searchPoems(query: "静夜思", searchType: TITLE) {
    edges {
      node {
        title
        author {
          name
        }
      }
    }
  }
}

# 统计信息
query {
  statistics {
    totalPoems
    totalAuthors
    poemsByDynasty {
      dynasty {
        name
      }
      count
    }
  }
}

搜索功能

类型 说明 示例
all 全文搜索（默认） ?q=月
title 标题搜索 ?q=静夜思&type=title
content 内容搜索 ?q=床前明月光&type=content
author 作者搜索 ?q=李白&type=author

数据集

本项目基于 chinese-poetry 数据集，使用的是修正了错字、朝代与作者等问题的 palemoky/chinese-poetry（fix-typo 分支），包含：

分类 数量 分类 数量 分类 数量 分类 数量
五言绝句 16,860 七言绝句 82,744 五言律诗 59,681 七言律诗 68,696
乐府诗 6,714 五代词 543 宋词 21,347 元曲 10,904
诗经 305 楚辞 65 论语 20 四书五经 14
其他 76,077 
pie title 收录数据分布概览 (忽略极小值)
"七绝/七律" : 151440
"五绝/五律" : 76541
"宋词/五代词" : 21890
"元曲" : 10904
"乐府诗" : 6714
"其他" : 76077

致谢

chinese-poetry-api (palemoky/chinese-poetry-api)

Searching Database…

3.4K ·GitHub
Chinese-poetry-api
Что это такое?Быстрый API-сервис для классической китайской поэзии, написанный на Go: отдаёт и REST, и GraphQL на наборе данных почти из 400 000 стихотворений — танские стихи, сунские_ci, юаньские цюй и не только.
Это библиотека, которую я подключаю, или отдельный сервер, который я разворачиваю?Это отдельный сервер, который вы разворачиваете сами (через Docker или сборку Go), а не библиотека для импорта в свой код.
Как его запустить?Склонируйте репозиторий вместе с Git-сабмодулями, чтобы подтянуть данные со стихами, затем запустите через Docker Compose (рекомендуется, конфиг в docker-compose.yml) либо соберите и запустите с помощью прилагаемого Makefile.
Данные со стихами нужно скачивать отдельно?Да, сами стихи лежат в отдельном репозитории-сабмодуле (это форк chinese-poetry с исправленными опечатками), поэтому клонировать нужно с сабмодулями или, если вы уже склонировали без них, выполнить submodule update.
Есть ли ограничения на то, сколько запросов я могу делать?Да, там есть встроенное ограничение частоты запросов по IP, специально чтобы защитить публичный API от злоупотреблений.
Docker-образ работает на ARM-серверах или только на x86?Docker-образ мультиархитектурный: поддерживаются и amd64, и arm64.
Насколько большая база стихов?Около 400 000 записей: 82 744 семисловных цзюэцзюй, 68 696 семисловных люйши, 21 347 сунских ци, 10 904 юаньских цюй, плюс «Шицзин», «Чуцы» и другое.
Какие виды поиска поддерживает API?По умолчанию — полнотекстовый поиск (?q=月), а через параметр type доступны отдельные режимы поиска по названию, содержимому и автору.
Можно получать результаты и на упрощённом, и на традиционном китайском?Да, каждый эндпоинт принимает параметр lang (zh-Hans или zh-Hant) для переключения между упрощённым и традиционным китайским; оба хранятся в одной базе.
Насколько быстрое преобразование между упрощённым и традиционным написанием?Конвертация оптимизирована под многопоточность и выполняется примерно за 300 нс на операцию, с использованием библиотеки gocc.
What are similar projects?tyk, zincsearch, typesense, pansou, reaction, dgraph, cube, claude-relay-service
Which topics is it in?rate-limiting, full-text-search, arm64, chinese-language, graphql, dataset, search, i18n, docker-compose, rest-api, backend, gplv3
Creator
palemoky
Size
12.9 MB
Stars
3.4K
Updated
CommitOct 07Releasev0.6.0Jul 04
Age
10mo
Commits · 90 Days