554 lines
15 KiB
Markdown
554 lines
15 KiB
Markdown
# TravelContentCreator 项目状态文档
|
||
|
||
> 更新日期: 2024-12-10
|
||
> 版本: 2.3.0
|
||
|
||
---
|
||
|
||
## 1. 项目概述
|
||
|
||
TravelContentCreator 是一个旅游内容自动生成系统的 Python 后端服务，提供：
|
||
- 选题生成 (Topic Generate)
|
||
- 内容生成 (Content Generate)
|
||
- 海报生成 (Poster Generate)
|
||
|
||
### 1.1 技术栈
|
||
|
||
| 组件 | 技术 |
|
||
|-----|------|
|
||
| Web 框架 | FastAPI |
|
||
| AI 模型 | OpenAI API (GPT-4) |
|
||
| 模板引擎 | Jinja2 |
|
||
| 配置格式 | YAML |
|
||
| 运行端口 | 8001 |
|
||
|
||
### 1.2 目录结构
|
||
|
||
```
|
||
TravelContentCreator/
|
||
├── api/ # FastAPI 应用
|
||
│ ├── main.py # 应用入口
|
||
│ └── routers/ # 路由定义
|
||
│ ├── v2_aigc.py # V2 统一 AIGC API
|
||
│ └── prompt.py # Prompt 管理 API
|
||
├── domain/ # 领域逻辑
|
||
│ ├── aigc/ # AIGC 引擎
|
||
│ │ ├── engines/ # 引擎实现
|
||
│ │ │ ├── base.py
|
||
│ │ │ ├── topic_generate_v2.py
|
||
│ │ │ ├── content_generate_v2.py
|
||
│ │ │ └── poster_generate_v2.py
|
||
│ │ └── shared/ # 共享组件
|
||
│ │ └── llm_client.py
|
||
│ └── prompt/ # Prompt 管理
|
||
│ ├── __init__.py
|
||
│ └── registry.py # PromptRegistry
|
||
├── prompts/ # Prompt 模板 (YAML)
|
||
│ ├── topic_generate/
|
||
│ │ ├── v1.0.0.yaml
|
||
│ │ └── v2.0.0.yaml
|
||
│ ├── content_generate/
|
||
│ │ ├── v1.0.0.yaml
|
||
│ │ └── v2.0.0.yaml
|
||
│ └── content_judge/
|
||
│ └── v1.0.0.yaml
|
||
├── config/ # 配置文件
|
||
│ ├── styles.yaml # 风格配置
|
||
│ └── audiences.yaml # 人群配置
|
||
├── docs/ # 文档
|
||
│ ├── PROJECT_STATUS.md # 本文档
|
||
│ ├── FIELD_REFACTOR_DESIGN.md
|
||
│ ├── FIELD_MAPPING.md
|
||
│ └── JAVA_MIGRATION_GUIDE.md
|
||
└── tests/ # 测试
|
||
└── test_full_flow.py
|
||
```
|
||
|
||
---
|
||
|
||
## 2. Prompt 管理系统
|
||
|
||
### 2.1 PromptRegistry 核心功能
|
||
|
||
`PromptRegistry` 是 Prompt 管理的核心组件，位于 `domain/prompt/registry.py`。
|
||
|
||
**主要功能**：
|
||
- YAML 格式 Prompt 加载和解析
|
||
- 版本管理 (v1.0.0, v2.0.0, latest)
|
||
- Jinja2 模板渲染
|
||
- 变量验证
|
||
- 模型参数绑定
|
||
|
||
### 2.2 Prompt YAML 结构
|
||
|
||
```yaml
|
||
# prompts/{engine_name}/{version}.yaml
|
||
|
||
meta:
|
||
name: topic_generate # 引擎名称
|
||
version: "2.0.0" # 版本号
|
||
description: "小红书选题生成" # 描述
|
||
author: "team"
|
||
created_at: "2024-12-09"
|
||
changelog: "新增热点信息支持" # 变更说明
|
||
|
||
model: # 模型参数
|
||
temperature: 0.2
|
||
top_p: 0.3
|
||
presence_penalty: 1.5
|
||
|
||
variables: # 变量定义
|
||
num_topics:
|
||
type: integer
|
||
required: true
|
||
description: "选题数量"
|
||
month:
|
||
type: string
|
||
required: true
|
||
description: "选题日期/月份"
|
||
subject:
|
||
type: object
|
||
required: false
|
||
description: "主体信息对象"
|
||
hot_topics:
|
||
type: object
|
||
required: false
|
||
description: "热点信息对象"
|
||
|
||
system: | # System Prompt (Jinja2 模板)
|
||
你是景区小红书的每月选题策划投流师...
|
||
|
||
## 选题规则
|
||
1. 根据当前年历...
|
||
|
||
user: | # User Prompt (Jinja2 模板)
|
||
请为以下景区/产品生成 {{ num_topics }} 个选题。
|
||
|
||
{% if subject %}
|
||
## 主体信息
|
||
- 名称：{{ subject.name }}
|
||
{% endif %}
|
||
```
|
||
|
||
### 2.3 PromptRegistry API
|
||
|
||
```python
|
||
from domain.prompt import PromptRegistry
|
||
|
||
# 初始化
|
||
registry = PromptRegistry('prompts')
|
||
|
||
# 获取 Prompt 配置
|
||
config = registry.get('topic_generate', 'v2.0.0')
|
||
config = registry.get('topic_generate', 'latest') # 获取最新版本
|
||
|
||
# 渲染 Prompt
|
||
system_prompt, user_prompt = registry.render(
|
||
'topic_generate',
|
||
context={
|
||
'num_topics': 5,
|
||
'month': '2025-02',
|
||
'subject': {...},
|
||
'hot_topics': {...}
|
||
},
|
||
version='v2.0.0'
|
||
)
|
||
|
||
# 获取模型参数
|
||
model_params = config.get_model_params()
|
||
# {'temperature': 0.2, 'top_p': 0.3, 'presence_penalty': 1.5}
|
||
|
||
# 列出所有版本
|
||
versions = registry.list_versions('topic_generate')
|
||
# ['v1.0.0', 'v2.0.0']
|
||
|
||
# 获取元信息
|
||
meta = config.get_meta()
|
||
# {'name': 'topic_generate', 'version': '2.0.0', ...}
|
||
```
|
||
|
||
### 2.4 版本管理策略
|
||
|
||
| 版本 | 说明 |
|
||
|-----|------|
|
||
| v1.0.0 | 初始版本，基础功能 |
|
||
| v2.0.0 | 新增热点信息、参考内容支持 |
|
||
| latest | 自动指向最新版本 |
|
||
|
||
**版本选择逻辑**：
|
||
1. 如果指定版本存在，使用指定版本
|
||
2. 如果指定 `latest`，使用版本号最大的
|
||
3. 如果版本不存在，抛出异常
|
||
|
||
---
|
||
|
||
## 3. AIGC 引擎系统
|
||
|
||
### 3.1 引擎架构
|
||
|
||
```
|
||
BaseAIGCEngine (基类)
|
||
├── TopicGenerateEngineV2 # 选题生成
|
||
├── ContentGenerateEngineV2 # 内容生成
|
||
└── PosterGenerateEngineV2 # 海报生成
|
||
```
|
||
|
||
### 3.2 引擎接口
|
||
|
||
```python
|
||
class BaseAIGCEngine:
|
||
engine_id: str # 引擎 ID
|
||
engine_name: str # 引擎名称
|
||
version: str # 版本
|
||
description: str # 描述
|
||
|
||
def get_param_schema(self) -> Dict[str, Any]:
|
||
"""定义参数结构"""
|
||
pass
|
||
|
||
def estimate_duration(self, params: Dict) -> int:
|
||
"""预估执行时间(秒)"""
|
||
pass
|
||
|
||
async def execute(self, params: Dict, task_id: str = None) -> EngineResult:
|
||
"""执行引擎"""
|
||
pass
|
||
```
|
||
|
||
### 3.3 当前引擎状态
|
||
|
||
| 引擎 | 状态 | Prompt 版本 |
|
||
|-----|------|------------|
|
||
| topic_generate | ✅ 可用 | v1.0.0, v2.0.0 |
|
||
| content_generate | ✅ 可用 | v1.0.0, v2.0.0 |
|
||
| poster_generate | ⚠️ 待修复 | v1.0.0 |
|
||
|
||
---
|
||
|
||
## 4. 字段设计
|
||
|
||
### 4.1 Subject (主体信息)
|
||
|
||
参考 Java 端 `ProductPackage` 设计，合并景区和产品信息：
|
||
|
||
```python
|
||
subject = {
|
||
"id": 1, # 主体 ID
|
||
"name": "北京环球影城", # 名称 (packageName)
|
||
"type": "scenic_spot", # 类型
|
||
"description": "亚洲最大的环球影城", # 描述
|
||
"location": "北京市通州区", # 地址 (address)
|
||
"highlights": ["哈利波特", "变形金刚"], # 亮点
|
||
"traffic_info": "地铁1号线...", # 交通指南
|
||
"products": [ # 产品列表
|
||
{
|
||
"id": 10,
|
||
"name": "单日票",
|
||
"price": 638,
|
||
"original_price": 738,
|
||
"description": "含一次入园",
|
||
"sales_period": "2025-01-01 至 2025-03-31",
|
||
"usage_rules": "...",
|
||
"package_info": "..."
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**与 Java ProductPackage 完整对应关系**：
|
||
|
||
| Python subject | Java ProductPackage | 说明 |
|
||
|---------------|---------------------|------|
|
||
| id | id | 主键 ID |
|
||
| name | packageName / scenicName | 套餐/景区名称 |
|
||
| type | dataType | 数据类型 (1景区/2产品/3套餐) |
|
||
| description | description | 详细描述 |
|
||
| location | address | 地址 |
|
||
| traffic_info | trafficInfo | 交通指南 |
|
||
| highlights | highlights | 亮点 |
|
||
| advantages | advantages | 优势/特色 |
|
||
| products[].id | productId | 产品 ID |
|
||
| products[].name | - | 产品名称 |
|
||
| products[].price | realPrice | 实际价格 |
|
||
| products[].original_price | originPrice | 原价 |
|
||
| products[].sales_period | salesPeriod | 售卖期 |
|
||
| products[].usage_rules | usageRules | 使用规则 |
|
||
| products[].package_info | packageInfo | 套票详情 |
|
||
| products[].surcharge | surcharge | 加价说明 |
|
||
| products[].reservation | reservation | 预约规则 |
|
||
| products[].refund | refund | 退改政策 |
|
||
| products[].discounts | discounts | 优惠内容 |
|
||
|
||
### 4.2 Reference (参考内容)
|
||
|
||
```python
|
||
reference = {
|
||
"mode": "reference", # none / reference / rewrite
|
||
"title": "参考标题",
|
||
"content": "参考正文..."
|
||
}
|
||
```
|
||
|
||
### 4.3 内置参考文献库
|
||
|
||
当用户没有指定 `reference` 时，系统会自动加载内置参考文献库：
|
||
|
||
| 文件 | 内容 | 数量 |
|
||
|-----|------|------|
|
||
| `prompts/reference/标题参考格式.json` | 爆款标题模板 | 100+ |
|
||
| `prompts/reference/正文范文参考.json` | 完整正文范例 | 10+ |
|
||
|
||
**使用逻辑**：
|
||
- 无 reference 或 `mode: none` → 随机抽取 20 个标题 + 3 篇范文
|
||
- 有 reference (`mode: reference/rewrite`) → 使用用户指定的参考内容
|
||
|
||
**Prompt 版本**：
|
||
- v2.0.0: 支持用户指定参考内容
|
||
- v2.1.0: 新增内置参考文献库自动加载
|
||
|
||
### 4.2.1 海报生成 (poster_generate)
|
||
|
||
**状态**: ✅ 可用 (方案 B 完成)
|
||
|
||
**架构**:
|
||
```
|
||
poster_generate_v2.py (v2.1.0)
|
||
└── domain/poster/poster_service.py (轻量服务，无数据库依赖)
|
||
└── poster/templates/*.py (模板渲染)
|
||
```
|
||
|
||
**API 调用**:
|
||
```bash
|
||
POST /api/v2/aigc/execute
|
||
{
|
||
"engine": "poster_generate",
|
||
"params": {
|
||
"template_id": "vibrant", # vibrant/business/collage
|
||
"content": {"title": "...", "content": "...", "tag": "..."},
|
||
"image_urls": ["https://..."], # 可选
|
||
"generate_fabric_json": false # 可选
|
||
}
|
||
}
|
||
```
|
||
|
||
**后续计划**: 方案 C 完整重构 (见 `docs/POSTER_REFACTOR_PLAN.md`)
|
||
|
||
### 4.2.2 热点数据模块
|
||
|
||
**状态**: ✅ 可用
|
||
|
||
**支持平台**:
|
||
- 百度热搜 ✅ (含旅游榜)
|
||
- 节日日历 ✅
|
||
- 小红书 ✅ (MediaCrawler 集成，需扫码登录)
|
||
- Bing 搜索 ✅
|
||
- 微博热搜 ⚠️ (需要优化)
|
||
|
||
**API 路由** (`/api/v2/hotspot/`):
|
||
- `GET /all` - 获取所有来源
|
||
- `GET /baidu` - 百度热搜 (实时 + 旅游榜)
|
||
- `GET /xiaohongshu` - 小红书热门 (需登录)
|
||
- `GET /bing` - Bing 搜索建议
|
||
- `GET /calendar` - 节日日历
|
||
- `GET /travel` - 旅游相关热点聚合
|
||
- `GET /trending` - 热门话题合并
|
||
- `POST /custom` - 添加自定义热点
|
||
|
||
**MediaCrawler 集成**:
|
||
- 位置: `libs/MediaCrawler/`
|
||
- 来源: https://github.com/NanmiCoder/MediaCrawler
|
||
- 支持: 小红书、抖音、微博、B站、快手、知乎、贴吧
|
||
|
||
**详细文档**: `docs/HOTSPOT_MODULE.md`
|
||
|
||
**参考文献管理 API** (`/api/v2/reference/`):
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|-----|------|------|
|
||
| GET | `/reference/list` | 获取统计信息 |
|
||
| GET | `/reference/titles` | 获取标题列表 (支持 count/random 参数) |
|
||
| GET | `/reference/titles/{index}` | 获取指定标题 |
|
||
| POST | `/reference/titles` | 添加新标题 |
|
||
| PUT | `/reference/titles/{index}` | 更新标题 |
|
||
| DELETE | `/reference/titles/{index}` | 删除标题 |
|
||
| GET | `/reference/contents` | 获取正文范文列表 |
|
||
| GET | `/reference/contents/{index}` | 获取指定范文 |
|
||
| POST | `/reference/contents` | 添加新范文 |
|
||
| PUT | `/reference/contents/{index}` | 更新范文 |
|
||
| DELETE | `/reference/contents/{index}` | 删除范文 |
|
||
| POST | `/reference/batch/add` | 批量添加 |
|
||
| POST | `/reference/reload` | 刷新缓存 |
|
||
|
||
**模式说明**：
|
||
|
||
| 模式 | 说明 | 适用场景 |
|
||
|-----|------|---------|
|
||
| none | 不使用参考 | 完全原创 |
|
||
| reference | 参考风格，原创内容 | 学习爆款风格 |
|
||
| rewrite | 保留框架，换主体 | 快速复制成功内容 |
|
||
|
||
### 4.3 Hot Topics (热点信息)
|
||
|
||
```python
|
||
hot_topics = {
|
||
"events": [ # 热点事件
|
||
{
|
||
"title": "春节档电影热映",
|
||
"source": "微博热搜",
|
||
"heat_score": 98,
|
||
"related_keywords": ["春节", "亲子"],
|
||
"expire_date": "2025-02-28"
|
||
}
|
||
],
|
||
"festivals": [ # 节日节气
|
||
{
|
||
"name": "春节",
|
||
"date": "2025-01-29",
|
||
"marketing_angle": "团圆、年味"
|
||
}
|
||
],
|
||
"trending": [ # 趋势话题
|
||
{
|
||
"topic": "#春节去哪玩",
|
||
"platform": "小红书",
|
||
"trend_direction": "rising"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. API 接口
|
||
|
||
### 5.1 V2 统一 API
|
||
|
||
**基础路径**: `/api/v2/aigc`
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|-----|------|------|
|
||
| GET | /engines | 获取引擎列表 |
|
||
| POST | /execute | 执行引擎 |
|
||
| GET | /config/styles | 获取风格列表 |
|
||
| GET | /config/audiences | 获取人群列表 |
|
||
| GET | /config/all | 获取所有配置 |
|
||
|
||
### 5.2 执行引擎
|
||
|
||
```bash
|
||
POST /api/v2/aigc/execute
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"engine": "topic_generate",
|
||
"params": {
|
||
"month": "2025-02",
|
||
"num_topics": 5,
|
||
"subject": {...},
|
||
"style": {"id": "gonglue", "name": "攻略风"},
|
||
"audience": {"id": "qinzi", "name": "亲子向"},
|
||
"hot_topics": {...}
|
||
},
|
||
"prompt_version": "v2.0.0" // 可选
|
||
}
|
||
```
|
||
|
||
### 5.3 Prompt 管理 API
|
||
|
||
**基础路径**: `/api/prompt`
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|-----|------|------|
|
||
| GET | /list | 列出所有 Prompt |
|
||
| GET | /{name}/versions | 获取版本列表 |
|
||
| GET | /{name}/{version} | 获取 Prompt 详情 |
|
||
| POST | /{name}/{version}/render | 渲染 Prompt |
|
||
|
||
---
|
||
|
||
## 6. 配置文件
|
||
|
||
### 6.1 风格配置 (config/styles.yaml)
|
||
|
||
```yaml
|
||
styles:
|
||
- id: gonglue
|
||
name: 攻略风
|
||
description: 实用信息为主，提供详细的游玩攻略
|
||
- id: tuijian
|
||
name: 极力推荐风
|
||
description: 强烈推荐语气，突出产品优势
|
||
```
|
||
|
||
### 6.2 人群配置 (config/audiences.yaml)
|
||
|
||
```yaml
|
||
audiences:
|
||
- id: qinzi
|
||
name: 亲子向
|
||
description: 家庭出游，关注儿童友好设施
|
||
- id: zhoubianyou
|
||
name: 周边游
|
||
description: 短途出行，追求性价比
|
||
- id: gaoshe
|
||
name: 高奢酒店
|
||
description: 高端消费，追求品质体验
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 待办事项
|
||
|
||
### 7.1 Python 端
|
||
|
||
- [ ] 修复海报生成引擎依赖
|
||
- [ ] 添加节日日历数据
|
||
- [ ] 完善错误处理和日志
|
||
|
||
### 7.2 Java 端
|
||
|
||
- [ ] 新增 AIGCConfigService
|
||
- [ ] 改造 TopicGenerateServiceImpl
|
||
- [ ] 改造 ContentGenerateServiceImpl
|
||
- [ ] 更新 API 调用为 V2 接口
|
||
|
||
### 7.3 热点数据源 (规划中)
|
||
|
||
- [ ] 节日日历 (静态数据)
|
||
- [ ] 运营热点 (手动维护)
|
||
- [ ] 微博热搜 API (可选)
|
||
|
||
---
|
||
|
||
## 8. 运行服务
|
||
|
||
```bash
|
||
cd /root/TravelContentCreator
|
||
PYTHONPATH=. python3 -m uvicorn api.main:app --host 0.0.0.0 --port 8001
|
||
```
|
||
|
||
**健康检查**：
|
||
```bash
|
||
curl http://localhost:8001/health
|
||
```
|
||
|
||
**测试选题生成**：
|
||
```bash
|
||
curl -X POST http://localhost:8001/api/v2/aigc/execute \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"engine": "topic_generate",
|
||
"params": {
|
||
"month": "2025-02",
|
||
"num_topics": 2,
|
||
"subject": {
|
||
"id": 1,
|
||
"name": "北京环球影城",
|
||
"products": [{"id": 10, "name": "单日票", "price": 638}]
|
||
},
|
||
"style": {"id": "gonglue", "name": "攻略风"},
|
||
"audience": {"id": "qinzi", "name": "亲子向"}
|
||
}
|
||
}'
|
||
```
|