From f415abaec3ade38a7fb5cb29c3dd7e1eb03d6515 Mon Sep 17 00:00:00 2001 From: jinye_huang Date: Tue, 22 Apr 2025 14:21:36 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BF=AE=E6=94=B9=E4=BA=86=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 231 +++++++++++++++++++++++++----------------------------- 1 file changed, 107 insertions(+), 124 deletions(-) diff --git a/README.md b/README.md index 75fd491..a4ef164 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,12 @@ ## 功能特点 -- **自动选题生成**：根据提供的景点信息自动生成吸引人的旅游选题 -- **内容创作**：基于选题自动生成文字内容，包括标题和正文 -- **海报制作**：结合景点图片和生成的文字内容，自动创建精美的宣传海报 -- **批量处理**：支持一次性生成多个选题和多个变体内容 -- **模块化设计**：各功能模块独立，可单独使用或组合使用 +- **自动选题生成**：根据提供的景点信息和配置的提示词模板，自动生成吸引人的旅游选题。 +- **内容创作**：基于选题和配置的提示词模板，自动生成文字内容（标题、正文）。 +- **海报制作**：结合景点图片和生成的文字内容，自动创建精美的宣传海报。 +- **批量处理**：支持一次性生成多个选题和多个变体内容。 +- **模块化设计**：核心功能（配置加载、提示词管理、AI交互、选题、内容生成、海报制作）分离，方便维护和扩展。 +- **配置驱动**：通过 `poster_gen_config.json` 文件集中管理所有运行参数。 ## 安装 @@ -19,6 +20,8 @@ ```bash # 安装依赖库 pip install numpy pandas opencv-python pillow +# 可能还需要安装AI模型的客户端库，例如 requests 或 特定模型的SDK +# pip install requests ``` ### 项目依赖项 @@ -27,175 +30,155 @@ pip install numpy pandas opencv-python pillow - Pandas：数据处理 - PIL (Pillow)：图像处理和绘制 -## 目录结构 +## 核心组件与目录结构 -- `core/`: 核心功能模块 - - `ai_agent.py`: AI代理接口 - - `topic_parser.py`: 选题解析器 - - `contentGen.py`: 内容生成器 - - `posterGen.py`: 海报生成器 - - `simple_collage.py`: 图片拼贴工具 -- `utils/`: 工具函数 - - `resource_loader.py`: 资源加载器 - - `tweet_generator.py`: 推文生成工具 -- `genPrompts/`: 提示词模板 - - `systemPrompt.txt`: 系统提示词 - - `Style/`: 风格提示词 - - `Refer/`: 参考提示词 - - `Demand/`: 需求提示词 -- `SelectPrompt/`: 选题提示词 -- `resource/`: 景点资源信息 -- `examples/`: 使用示例 -- `result/`: 输出结果保存目录 +- `main.py`: 项目入口，负责加载配置、编排主要流程（选题生成 -> 内容与海报生成）。 +- `poster_gen_config.json`: (用户需从 `example_config.json` 创建) 核心配置文件。 +- `core/`: 核心算法与功能模块 + - `ai_agent.py`: **AI代理**: 封装与大语言模型 API 的底层交互逻辑（发送请求、接收响应）。 + - `topic_parser.py`: **选题解析器**: 解析 AI 模型返回的选题文本。 + - `contentGen.py`: **内容处理器**: 对 AI 生成的原始推文内容进行结构化处理，提取适用于海报的元素。 + - `posterGen.py`: **海报生成器**: 负责将图片和文字元素组合生成最终的海报图片，处理字体、布局等。 + - `simple_collage.py`: **图片拼贴工具**: 提供图片预处理和拼贴功能。 +- `utils/`: 工具与辅助模块 + - `resource_loader.py`: **资源加载器**: 负责加载项目所需的各种**原始**资源文件（如文本文件、配置文件中的路径指向的文件）。 + - `prompt_manager.py`: **提示词管理器**: **集中管理**不同阶段（选题、内容生成）的提示词构建逻辑。它调用 `ResourceLoader` 获取基础文件，并根据配置和当前任务（如特定选题）组装最终的 System Prompt 和 User Prompt。 + - `tweet_generator.py`: **流程与数据结构**: 包含选题生成 (`run_topic_generation_pipeline`) 和单篇内容生成 (`generate_single_content`) 的流程函数，以及相关的数据类（如 `tweetTopicRecord`, `tweetContent`）。 +- `genPrompts/`: 内容生成提示词模板目录。 +- `SelectPrompt/`: 选题生成提示词模板目录。 +- `resource/`: 存放基础的景点信息 `.txt` 文件等数据资源。 +- `examples/`: 使用示例和测试脚本。 +- `result/`: 默认输出结果保存目录。 + +## 项目流程与技术细节 + +1. **加载配置**: `main.py` 读取 `poster_gen_config.json` 文件。 +2. **选题生成**: + - 调用 `utils.tweet_generator.run_topic_generation_pipeline`。 + - 内部调用 `utils.prompt_manager.PromptManager.get_topic_prompts()` 来构建选题阶段的系统和用户提示词（结合模板、资源文件、配置参数）。 + - 初始化一个 `core.ai_agent.AI_Agent` 实例。 + - 调用 AI Agent 发送请求生成选题文本。 + - 使用 `core.topic_parser` 解析结果。 + - 保存选题结果 (`tweet_topic.json`) 到输出目录。 + - 关闭此阶段的 AI Agent。 +3. **内容与海报生成**: (在 `main.generate_content_and_posters_step` 中执行) + - 初始化 `utils.prompt_manager.PromptManager` 和 **一个共享的** `core.ai_agent.AI_Agent` 实例供此阶段所有任务使用（**优化点：避免为每个变体重复创建Agent**）。 + - 遍历上一步生成的每个选题 (`topic_item`)： + - 为当前选题调用 `prompt_manager.get_content_prompts(topic_item)` 获取内容生成的特定提示词。 + - 遍历每个变体 (variant)： + - 调用 `utils.tweet_generator.generate_single_content`，传入**共享的 AI Agent** 和**特定于此选题的提示词**，生成推文内容。 + - 调用 `core.contentGen` 处理生成的文本内容，准备海报所需元素。 + - 调用 `core.simple_collage` 处理图片。 + - 调用 `core.posterGen` 结合图片和文本生成最终海报。 + - 所有选题处理完毕后，关闭此阶段共享的 AI Agent。 ## 使用方法 -1. 准备景点资源信息，放入`resource/Object/`目录中 -2. 准备景点图片资源，放入图片目录中 -3. 复制`example_config.json`为`poster_gen_config.json`并进行配置 -4. 运行主程序： - -```bash -python main.py -``` +1. 准备景点资源信息 (`.txt` 文件)，放入 `resource/Object/` 目录（或其他在配置中指定的路径）。 +2. 准备景点图片资源，按照 `README.md` 中"开始使用"部分的说明组织图片目录结构，并确保 `poster_gen_config.json` 中的 `image_base_dir` 指向正确的图片根目录。 +3. 复制 `example_config.json` 为 `poster_gen_config.json`，并根据你的 API Key、模型端点、文件路径、图片根目录等进行修改。 +4. **运行完整流程**: + ```bash + python main.py + ``` +5. **分阶段运行**: (参考 `examples/` 目录下的脚本) + ```bash + # 阶段 1: 仅生成选题 + python examples/run_step1_topics.py + # (记下输出的 Run ID) + + # 阶段 2: 处理已生成的选题 + python examples/run_step2_content_posters.py + ``` ## 配置说明 -必须配置项： +配置文件: `poster_gen_config.json` -- `num`: 生成选题数量 -- `model`: 使用的大语言模型 -- `api_url`: API调用地址 -- `api_key`: API密钥 -- `resource_dir`: 景点资源信息路径 -- `prompts_dir`: 提示词目录 -- `output_dir`: 输出结果保存路径 -- `variants`: 每个选题生成的变体数量 -- `image_base_dir`: 图片资源根目录 -- `topic_system_prompt`: 选题生成系统提示词路径 -- `topic_user_prompt`: 选题生成用户提示词路径 -- `content_system_prompt`: 内容生成系统提示词路径 +**必须配置项**： -可选配置项： +- `api_url`: 大语言模型 API 地址 +- `api_key`: API 密钥 +- `model`: 使用的模型名称 +- `topic_system_prompt`: 选题生成系统提示词文件路径 +- `topic_user_prompt`: 选题生成基础用户提示词文件路径 +- `content_system_prompt`: 内容生成系统提示词文件路径 +- `resource_dir`: 包含景点等资源文件信息的列表 (结构见 `example_config.json`) +- `prompts_dir`: 存放 Demand/Style/Refer 等提示词片段的目录路径 +- `output_dir`: 输出结果保存目录路径 +- `image_base_dir`: **图片资源根目录绝对路径或相对路径** +- `num`: （选题阶段）生成选题数量 +- `variants`: （内容生成阶段）每个选题生成的变体数量 -- `date`: 日期标记（默认为当前日期） -- `topic_temperature`: 选题生成的创意度参数（默认0.2） -- `content_temperature`: 内容生成的创意度参数（默认0.3） -- `camera_image_subdir`: 相机图片子目录名（默认"相机"） -- `modify_image_subdir`: 修改图片子目录名（默认"modify"） -- `poster_target_size`: 海报尺寸 [宽, 高]（默认[900, 1200]） +**可选配置项**： -项目提供了一个示例配置文件 `example_config.json`，可以复制并根据需要修改： +- `date`: 日期标记（用于提示词，默认为当前日期） +- `topic_temperature`, `topic_top_p`, `topic_max_tokens`: 选题生成 API 相关参数 +- `content_temperature`: 内容生成 API 相关参数 +- `camera_image_subdir`: 存放原始照片和描述文件的子目录名（相对于 `image_base_dir`，默认"相机"） +- `modify_image_subdir`: 存放处理后/用于拼贴的图片的子目录名（相对于 `image_base_dir`，默认"modify"） +- `poster_target_size`: 海报目标尺寸 `[宽, 高]`（默认 `[900, 1200]`） + +项目提供了一个示例配置文件 `example_config.json`，请务必复制并修改： ```bash -# 复制示例配置 cp example_config.json poster_gen_config.json - -# 根据自己的需求修改配置 nano poster_gen_config.json ``` -配置文件示例： -```json -{ - "date": "5月15日", - "num": 5, - "model": "qwen", - "api_url": "http://your-api-endpoint/v1/completions", - "api_key": "your-api-key", - "topic_system_prompt": "./SelectPrompt/systemPrompt.txt", - "topic_user_prompt": "./SelectPrompt/userPrompt.txt", - "content_system_prompt": "./genPrompts/systemPrompt.txt", - "resource_dir": [ - { - "type": "Object", - "num": 3, - "file_path": [ - "./resource/Object/景点信息-泰宁古城.txt", - "./resource/Object/景点信息-尚书第.txt", - "./resource/Object/景点信息-明清园.txt" - ] - } - ], - "prompts_dir": "./genPrompts", - "output_dir": "./result", - "image_base_dir": "/path/to/your/image/directory", - "camera_image_subdir": "相机", - "modify_image_subdir": "modify", - "variants": 3, - "topic_temperature": 0.2, - "content_temperature": 0.3, - "poster_target_size": [900, 1200] -} -``` - -## 项目流程 - -整个内容生成流程分为以下几个独立步骤： - -1. **选题生成**：使用AI根据景点信息生成多个选题方向 -2. **内容生成**：根据选题生成具体的旅游推文内容 -3. **海报生成**：使用景点图片和生成的文本内容创建海报 - -每个步骤都有独立的函数处理，也可以作为整体流程一次执行。 - ## 开始使用 ### 1. 准备景点信息文件 -在`resource/Object/`目录中创建景点信息文件，例如`景点信息-泰宁古城.txt`： +在 `resource/Object/` 目录中创建景点信息文件（UTF-8编码），文件名应与配置和选题结果中的 `object` 字段对应，例如 `景点信息-泰宁古城.txt`： ``` 景点名称：泰宁古城 位置：福建省三明市泰宁县 -简介：泰宁古城始建于宋代，是福建省保存较为完好的古代县城之一，具有悠久的历史和丰富的文化遗产。 -特色：古城墙、古街巷、古民居、古牌坊等历史建筑保存完好。 +简介：泰宁古城始建于宋代... +特色：古城墙、古街巷... ``` ### 2. 准备图片资源 -将景点的高质量图片保存在配置的图片目录中，符合以下结构： +将景点的高质量图片保存在配置的 `image_base_dir` 下，并按以下推荐结构组织（子目录名可通过配置修改）： ``` -image_base_dir/ +/ ├── 相机/ (camera_image_subdir) │ ├── 泰宁古城/ │ │ ├── 图片1.jpg │ │ ├── 图片2.jpg -│ │ └── description.txt (可选描述文件) +│ │ └── description.txt (可选的图片描述文件，供内容生成参考) │ └── 其他景点/ +│ └── ... └── modify/ (modify_image_subdir) ├── 泰宁古城/ - │ ├── 图片1.jpg - │ ├── 图片2.jpg - │ └── ... + │ ├── 用于拼贴的图片1.jpg + │ ├── ... └── 其他景点/ + └── ... ``` +**注意**: 海报生成步骤会从 `modify` 子目录中查找用于制作海报的图片。 ### 3. 配置文件 -复制并修改`example_config.json`为`poster_gen_config.json`，确保: -- 设置正确的API信息 -- 配置景点资源文件路径 -- 设置图片资源根目录 +仔细检查并修改 `poster_gen_config.json`，确保所有路径（特别是 `image_base_dir`）和 API 信息正确无误。 ### 4. 运行生成流程 -执行主程序，系统将自动生成选题、内容和海报： +根据需要选择完整流程或分阶段执行（见"使用方法"部分）。 -```bash -python main.py -``` - -生成的结果将保存在配置的`output_dir`目录中。 +生成的结果将保存在配置的`output_dir`目录下的 `run_id` 子目录中。 ## 示例 -查看`examples`目录中的示例代码，了解如何使用本工具的各个组件。 +查看`examples/`目录及其 `README.md` 文件，了解如何运行测试脚本或单独使用项目组件。 ## 注意事项 -- 确保已安装所有依赖库 -- 图片目录结构需要按照配置文件中的规范组织 -- AI生成内容质量取决于提供的景点信息质量和提示词设计 -- 检查您的API密钥和URL配置是否正确 \ No newline at end of file +- 确保已安装所有依赖库。 +- **图片目录结构和命名**需严格符合预期，以便程序能找到对应景点的图片。 +- AI生成内容的质量很大程度上取决于**提示词的设计**和**输入资源信息的质量**。 +- 仔细检查 API Key、URL 和文件路径配置。 +- 如果遇到问题，检查程序输出的日志信息和错误提示。 \ No newline at end of file