linhdpostdata/poetrylab-api

Poetrylab API

镜像概述和主要用途

Poetrylab API是一个RESTful API服务，专注于诗歌文本分析，提供两种核心分析功能：诗节韵律分析（scansion）和跨行连续检查（enjambment）。用户可通过POST请求访问/analysis端点提交诗歌文本，获取结构化分析结果。此外，/ui端点提供交互式API文档界面，便于测试和使用。

核心功能和特性

• 诗节韵律分析（scansion）：提取诗歌的音节、重音位置、韵律模式等信息，支持配置rhyme_analysis参数以获取诗节结构信息（如诗节类型、押韵方式等）。
• 跨行连续检查（enjambment）：识别诗歌中的跨行连续现象，返回所在诗行及具体类型（如连接词相关的跨行连续）。
• API文档界面：通过/ui端点提供交互式文档，支持在线测试API功能。
• RESTful设计：仅支持POST方法访问/analysis端点，符合REST规范。

使用场景和适用范围

• 诗歌研究与文学分析：帮助学者、学生分析诗歌的韵律结构和形式特征。
• 教育领域：辅助诗歌教学，直观展示诗歌的韵律和结构特点。
• 内容创作：为诗人或文学创作者提供结构化的诗歌分析工具，优化作品形式。

使用方法和配置说明

访问端点

• 分析端点：/analysis（仅支持POST方法）
• 文档界面：/ui（GET方法，提供交互式API文档）

请求示例

提交诗歌文本至/analysis端点，需指定分析方法（scansion或enjambment）。以下为示例诗歌：

La cebolla es 
cerrada y pobre:
escarcha de tus días
y de mis noches.
Hambre y 
hielo negro y 
grande y redonda.

响应示例

enjambment分析结果

json
{
  "enjambment": {
    "4": {
      "type": "sirrematic_relation_words_conjunction",
      "on": [
        "CONJ",
        "NOUN"
      ]
    },
    "5": {
      "type": "sirrematic_relation_words_conjunction",
      "on": [
        "CONJ",
        "ADJ"
      ]
    }
  }
}

scansion分析结果（部分）

json
{
  "scansion": [
    {
      "tokens": [
        {
          "word": [
            {
              "syllable": "La",
              "is_stressed": false,
              "is_word_end": true
            }
          ],
          "stress_position": 0
        },
        {
          "word": [
            {
              "syllable": "ce",
              "is_stressed": false
            },
            {
              "syllable": "bo",
              "is_stressed": true
            },
            {
              "syllable": "lla",
              "is_stressed": false,
              "has_synalepha": true,
              "is_word_end": true
            }
          ],
          "stress_position": -2
        },
        ...
      ],
      "phonological_groups": [...],
      "rhythm": {
        "stress": "--++-",
        "type": "pattern",
        "length": 5,
        "length_range": {
          "min_length": 5,
          "max_length": 6
        }
      }      
    },
    ...
  ]
}

若设置rhyme_analysis: True，输出将包含诗节结构信息：

json
"structure": "septilla",
"rhyme": "-",
"ending": "",
"ending_stress": 0,
"rhyme_type": "",
"rhyme_relaxation": null

部署指南

Docker部署

构建镜像

bash
docker build --tag linhdpostdata/poetrylab-api .

运行容器

bash
docker run -p "5000:5000" linhdpostdata/poetrylab-api

容器启动后，API服务将在http://localhost:5000可用，文档界面可通过http://localhost:5000/ui访问。

开发环境

安装开发模式依赖并启动服务：

bash
pip install -e .
connexion run poetrylab_api/openapi.yml

测试

安装开发模式依赖后执行测试：

bash
pip install -e .
python setup.py test

注意事项

• 详细的scansion输出解释可参考rantanplan文档：https://rantanplan.readthedocs.io/en/latest/readme.html
• 稳定版本镜像已发布至Docker Hub，可直接使用linhdpostdata/poetrylab-api镜像。