jinye_huang/TravelContentCreator

Template

Fork 0

jinye_huang 6d100714db 清理了部分无效的模块

2025-12-10 10:07:40 +08:00

15 KiB

Raw Blame History

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 结构

# 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

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	自动指向最新版本

版本选择逻辑：

如果指定版本存在，使用指定版本
如果指定 latest，使用版本号最大的
如果版本不存在，抛出异常

3. AIGC 引擎系统

3.1 引擎架构

BaseAIGCEngine (基类)
├── TopicGenerateEngineV2    # 选题生成
├── ContentGenerateEngineV2  # 内容生成
└── PosterGenerateEngineV2   # 海报生成

3.2 引擎接口

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 设计，合并景区和产品信息：

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 (参考内容)

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 调用:

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 (热点信息)

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 执行引擎

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)

styles:
  - id: gonglue
    name: 攻略风
    description: 实用信息为主，提供详细的游玩攻略
  - id: tuijian
    name: 极力推荐风
    description: 强烈推荐语气，突出产品优势

6.2 人群配置 (config/audiences.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. 运行服务

cd /root/TravelContentCreator
PYTHONPATH=. python3 -m uvicorn api.main:app --host 0.0.0.0 --port 8001

健康检查：

curl http://localhost:8001/health

测试选题生成：

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": "亲子向"}
    }
  }'

15 KiB Raw Blame History Unescape Escape