所有功能已完成，运行OK
This commit is contained in:
JimmysAIPG
385
README.md
Normal file
385
README.md
Normal file
@@ -0,0 +1,385 @@
|
||||
# 古诗词阅读网站
|
||||
|
||||
基于大模型分类的中国古诗词阅读管理系统
|
||||
|
||||
## 系统架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ 古诗词阅读网站 │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ Frontend (原生 JS + CSS) │ Backend (FastAPI + SQLite)│
|
||||
│ - 多类别组合筛选 │ - RESTful API │
|
||||
│ - 阅读标记管理 │ - SQLite 数据库 │
|
||||
│ - 标签云浏览 │ - 分类查询 │
|
||||
│ - 进度统计 │ - 批量导入 │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ classify_pois.py (LLM 分类脚本) │
|
||||
│ - 20 维分类标签体系 │
|
||||
│ - 繁体转简体支持 │
|
||||
│ - 实时去重 + 持久化 │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## 核心功能
|
||||
|
||||
### 1. 20 维分类标签体系
|
||||
|
||||
| 维度分类 | 标签数量 | 示例 |
|
||||
|---------|---------|------|
|
||||
| **季节时序** | 39 | 春、夏、秋、冬、24 节气、时辰 |
|
||||
| **题材类型** | 17 | 山水田园、边塞征战、咏史怀古等 |
|
||||
| **情感心境** | 31 | 情感基调 11 种 + 具体情感 20 种 |
|
||||
| **景物意象** | 77 | 自然、植物、动物、建筑、色彩、声音 |
|
||||
| **哲理思想** | 7 | 儒家、道家、佛家、人生感悟等 |
|
||||
| **艺术手法** | 18 | 写作手法、修辞手法 |
|
||||
| **人物社会** | 33 | 人生阶段、社会身份、地理方位、节日 |
|
||||
|
||||
### 2. 繁体转简体支持
|
||||
|
||||
- ✅ 自动识别繁体中文诗词
|
||||
- ✅ LLM 自动转换为简体中文
|
||||
- ✅ 保留原始繁体版本（可选）
|
||||
- ✅ 基于简体内容去重（繁简同一首诗不会重复）
|
||||
- ✅ 所有分类标签统一使用简体
|
||||
|
||||
**输入示例（繁体）：**
|
||||
```json
|
||||
{
|
||||
"title": "山居秋暝",
|
||||
"author": "王維",
|
||||
"paragraphs": ["空山新雨後，天氣晚來秋。", "明月鬆間照，清泉石上流。"]
|
||||
}
|
||||
```
|
||||
|
||||
**输出示例（简体）：**
|
||||
```json
|
||||
{
|
||||
"title": "山居秋暝",
|
||||
"author": "王维",
|
||||
"paragraphs": ["空山新雨后，天气晚来秋。", "明月松间照，清泉石上流。"],
|
||||
"original_paragraphs": ["空山新雨後，天氣晚來秋。", "明月鬆間照，清泉石上流。"],
|
||||
"llm_classification": {
|
||||
"season": ["秋"],
|
||||
"genre": ["山水田园", "隐逸闲适"],
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 多类别组合筛选
|
||||
|
||||
支持同时选择多个分类标签进行组合筛选：
|
||||
- 题材=山水田园 AND 情感=宁静淡泊
|
||||
- 季节=春 AND 地点=江南 AND 情感=喜悦
|
||||
- 使用 SQL 查询优化，支持复杂筛选条件
|
||||
|
||||
### 4. 阅读管理
|
||||
|
||||
- 标记诗词为已读/未读
|
||||
- 阅读进度统计（百分比 + 数量）
|
||||
- 阅读时间记录
|
||||
- 快速切换阅读状态
|
||||
|
||||
### 5. 批量导入
|
||||
|
||||
- 支持 JSON/JSONL 格式
|
||||
- 自动去重（基于内容签名 MD5）
|
||||
- 实时写入数据库
|
||||
- 导入结果反馈
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 1. 安装依赖
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### 2. 使用 LLM 脚本分类诗词
|
||||
|
||||
```bash
|
||||
# 本地模型 (Ollama 等)
|
||||
python classify_pois.py ./poems ./output.jsonl --llm \
|
||||
--base-url http://localhost:11434/v1 \
|
||||
--model qwen:7b
|
||||
|
||||
# 远程模型 (OpenAI 等)
|
||||
python classify_pois.py ./poems ./output.jsonl --llm \
|
||||
--base-url https://api.openai.com/v1 \
|
||||
--model gpt-4 \
|
||||
--api-key sk-xxx
|
||||
|
||||
# 繁体诗词测试
|
||||
python classify_pois.py ./ ./output.jsonl --llm \
|
||||
--base-url http://localhost:11434/v1 \
|
||||
--model qwen:7b
|
||||
```
|
||||
|
||||
### 3. 启动后端服务
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
python main.py
|
||||
```
|
||||
|
||||
服务启动后访问：http://localhost:8000
|
||||
|
||||
### 4. 前端页面
|
||||
|
||||
浏览器打开：http://localhost:8000
|
||||
|
||||
### 5. 上传诗词
|
||||
|
||||
通过前端界面的上传功能，上传分类后的 JSONL 文件到数据库。
|
||||
|
||||
## API 端点
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| GET | `/` | 前端页面 |
|
||||
| GET | `/api/categories` | 获取分类体系 |
|
||||
| GET | `/api/stats` | 获取统计数据 |
|
||||
| POST | `/api/poems/import` | 批量导入诗词 |
|
||||
| GET | `/api/poems` | 获取诗词列表（支持分页、筛选） |
|
||||
| GET | `/api/poems/{id}` | 获取诗词详情 |
|
||||
| PUT | `/api/poems/{id}/read` | 切换阅读状态 |
|
||||
| GET | `/api/poems/random` | 随机一首 |
|
||||
| GET | `/api/tags/cloud` | 标签云数据 |
|
||||
|
||||
### API 使用示例
|
||||
|
||||
```bash
|
||||
# 获取诗词列表（带多类别筛选）
|
||||
GET /api/poems?page=1&page_size=20&categories=genre:山水田园,emotion_tone:宁静淡泊
|
||||
|
||||
# 搜索诗词
|
||||
GET /api/poems?search=李白
|
||||
|
||||
# 获取已读诗词
|
||||
GET /api/poems?is_read=true
|
||||
|
||||
# 获取未读诗词
|
||||
GET /api/poems?is_read=false
|
||||
|
||||
# 标记为已读
|
||||
PUT /api/poems/{id}/read?is_read=true
|
||||
|
||||
# 标记为未读
|
||||
PUT /api/poems/{id}/read?is_read=false
|
||||
```
|
||||
|
||||
## 数据格式
|
||||
|
||||
### 输入格式（JSON/JSONL）
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "poem_001",
|
||||
"title": "山居秋暝",
|
||||
"author": "王维",
|
||||
"paragraphs": [
|
||||
"空山新雨后，天气晚来秋。",
|
||||
"明月松间照，清泉石上流。",
|
||||
"竹喧归浣女，莲动下渔舟。",
|
||||
"随意春芳歇，王孙自可留。"
|
||||
],
|
||||
"llm_classification": {
|
||||
"season": ["秋"],
|
||||
"solar_terms": ["白露"],
|
||||
"time_of_day": "黄昏",
|
||||
"genre": ["山水田园", "隐逸闲适"],
|
||||
"emotion_tone": "宁静淡泊",
|
||||
"emotions": ["静", "喜", "乐"],
|
||||
"nature_scenery": ["山", "水", "月"],
|
||||
"plants": ["松", "竹"],
|
||||
"animals": ["鸟"],
|
||||
"buildings": [],
|
||||
"imagery": ["空山", "新雨", "明月"],
|
||||
"philosophy": ["道家思想", "自然之道"],
|
||||
"life_stage": "中年",
|
||||
"social_role": "隐士",
|
||||
"technique": ["借景抒情", "动静结合"],
|
||||
"rhetoric": ["拟人"],
|
||||
"colors": ["青", "白"],
|
||||
"sounds": [],
|
||||
"location": "终南山",
|
||||
"festival": "无",
|
||||
"analysis": "这首诗描绘了秋日山居的幽静景色..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 输出格式（API 响应）
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "poem_001",
|
||||
"title": "山居秋暝",
|
||||
"author": "王维",
|
||||
"paragraphs": ["空山新雨后，天气晚来秋。", ...],
|
||||
"original_paragraphs": null,
|
||||
"classifications": {
|
||||
"season": ["秋"],
|
||||
"genre": ["山水田园", "隐逸闲适"],
|
||||
...
|
||||
},
|
||||
"is_read": false,
|
||||
"read_at": null,
|
||||
"created_at": "2024-01-01T00:00:00"
|
||||
}
|
||||
```
|
||||
|
||||
## 数据库结构
|
||||
|
||||
### poems 表
|
||||
```sql
|
||||
CREATE TABLE poems (
|
||||
id TEXT PRIMARY KEY,
|
||||
title TEXT NOT NULL,
|
||||
author TEXT NOT NULL,
|
||||
paragraphs TEXT,
|
||||
signature TEXT UNIQUE,
|
||||
created_at TIMESTAMP,
|
||||
updated_at TIMESTAMP
|
||||
);
|
||||
```
|
||||
|
||||
### classifications 表
|
||||
```sql
|
||||
CREATE TABLE classifications (
|
||||
id INTEGER PRIMARY KEY,
|
||||
poem_id TEXT,
|
||||
category TEXT,
|
||||
tags TEXT,
|
||||
FOREIGN KEY (poem_id) REFERENCES poems(id)
|
||||
);
|
||||
```
|
||||
|
||||
### reading_records 表
|
||||
```sql
|
||||
CREATE TABLE reading_records (
|
||||
id INTEGER PRIMARY KEY,
|
||||
poem_id TEXT UNIQUE,
|
||||
is_read BOOLEAN,
|
||||
read_at TIMESTAMP,
|
||||
FOREIGN KEY (poem_id) REFERENCES poems(id)
|
||||
);
|
||||
```
|
||||
|
||||
## 完整分类标签体系
|
||||
|
||||
| 维度 | 键名 | 标签数量 | 标签示例 |
|
||||
|------|------|---------|---------|
|
||||
| 季节 | season | 6 | 春、夏、秋、冬、四季 |
|
||||
| 节气 | solar_terms | 24 | 立春、雨水、清明、谷雨 |
|
||||
| 时辰 | time_of_day | 9 | 清晨、黄昏、夜晚、黎明 |
|
||||
| 题材 | genre | 17 | 山水田园、边塞征战、咏史怀古 |
|
||||
| 情感基调 | emotion_tone | 11 | 宁静淡泊、喜悦欢快、悲伤哀愁 |
|
||||
| 具体情感 | emotions | 20 | 喜、怒、哀、乐、忧、思 |
|
||||
| 自然景物 | nature_scenery | 14 | 山、水、云、雨、日、月 |
|
||||
| 植物 | plants | 15 | 松、竹、梅、兰、菊、荷 |
|
||||
| 动物 | animals | 14 | 鸟、雁、燕、蝉、蛙、鱼 |
|
||||
| 建筑 | buildings | 15 | 楼、阁、亭、台、桥、寺 |
|
||||
| 哲理 | philosophy | 7 | 儒家思想、道家思想、佛家禅理 |
|
||||
| 人生阶段 | life_stage | 5 | 少年、青年、中年、老年 |
|
||||
| 社会身份 | social_role | 10 | 士人、官员、隐士、游子 |
|
||||
| 写作手法 | technique | 9 | 比兴、借景抒情、托物言志 |
|
||||
| 修辞手法 | rhetoric | 9 | 比喻、拟人、夸张、对偶 |
|
||||
| 色彩 | colors | 10 | 青、绿、红、白、黄、紫 |
|
||||
| 声音 | sounds | 9 | 钟声、琴声、鸟鸣、雨声 |
|
||||
| 地理 | location | 9 | 江南、塞北、巴蜀、关中 |
|
||||
| 节日 | festival | 9 | 春节、中秋、重阳、端午 |
|
||||
|
||||
## 技术栈
|
||||
|
||||
- **后端**: FastAPI + SQLite + Uvicorn
|
||||
- **前端**: 原生 JavaScript + CSS (无框架依赖)
|
||||
- **分类**: 基于 LLM API (支持本地/远程模型)
|
||||
- **简繁转换**: LLM 自动识别和转换
|
||||
|
||||
## 扩展开发
|
||||
|
||||
### 添加新的分类维度
|
||||
|
||||
1. 在 `backend/main.py` 的 `CATEGORY_SYSTEM` 中添加新维度
|
||||
2. 在 `classify_pois.py` 的 `CLASSIFICATION_PROMPT` 中添加对应提示
|
||||
3. 在前端 CSS 中添加对应标签样式
|
||||
|
||||
### 部署建议
|
||||
|
||||
```bash
|
||||
# 生产环境使用
|
||||
uvicorn backend.main:app --host 0.0.0.0 --port 8000 --workers 4
|
||||
|
||||
# 或使用 gunicorn
|
||||
gunicorn backend.main:app -w 4 -k uvicorn.workers.UvicornWorker
|
||||
```
|
||||
|
||||
### 简繁切换显示（可选）
|
||||
|
||||
在前端添加简繁切换功能：
|
||||
|
||||
```javascript
|
||||
let showTraditional = false;
|
||||
|
||||
function toggleTraditional() {
|
||||
showTraditional = !showTraditional;
|
||||
const poem = state.currentPoem;
|
||||
const content = showTraditional && poem.original_paragraphs
|
||||
? poem.original_paragraphs
|
||||
: poem.paragraphs;
|
||||
// 重新渲染内容
|
||||
}
|
||||
```
|
||||
|
||||
## 常见问题
|
||||
|
||||
**Q: 导入时提示重复？**
|
||||
A: 系统基于诗词内容签名（MD5）去重，相同内容的诗词只会保留一份。繁体和简体版本会被识别为同一首诗。
|
||||
|
||||
**Q: 如何重置阅读进度？**
|
||||
A: 直接修改数据库中 `reading_records` 表的 `is_read` 字段，或在前端重新标记。
|
||||
|
||||
**Q: 支持哪些 LLM 模型？**
|
||||
A: 任何支持 OpenAI 兼容 API 的模型，包括 Ollama、vLLM、OpenAI GPT、Anthropic Claude 等。
|
||||
|
||||
**Q: 繁体诗词如何处理？**
|
||||
A: 分类脚本会自动识别繁体中文，LLM 会返回简体版本。原始繁体会保存在 `original_paragraphs` 字段中。
|
||||
|
||||
**Q: JSONL 文件和 SQLite 数据库的关系？**
|
||||
A: JSONL 是分类脚本的输出格式（中间产物），SQLite 是网站运行的数据库（最终存储）。通过 API 导入功能将 JSONL 导入数据库。
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
PoemClassify/
|
||||
├── classify_pois.py # LLM 分类脚本
|
||||
├── requirements.txt # Python 依赖
|
||||
├── backend/
|
||||
│ ├── main.py # FastAPI 后端
|
||||
│ └── poems.db # SQLite 数据库（运行时生成）
|
||||
├── frontend/
|
||||
│ ├── index.html # 前端页面
|
||||
│ ├── script.js # 前端逻辑
|
||||
│ └── style.css # 样式文件
|
||||
├── test_traditional.json # 繁体测试文件
|
||||
└── README.md # 本文档
|
||||
```
|
||||
|
||||
## 数据备份
|
||||
|
||||
```bash
|
||||
# 备份 SQLite 数据库
|
||||
cp backend/poems.db backup_$(date +%Y%m%d).db
|
||||
|
||||
# 导出数据库为 JSONL
|
||||
sqlite3 backend/poems.db "SELECT json_object('id',id,'title',title,'author',author,'paragraphs',paragraphs) FROM poems;" > export.jsonl
|
||||
|
||||
# 从 JSONL 恢复
|
||||
curl -X POST http://localhost:8000/api/poems/import -F "file=@export.jsonl"
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
MIT License
|
||||
Reference in New Issue
Block a user