From 8326485d8a2a35fd5f2aac100ed9de46fcf033f3 Mon Sep 17 00:00:00 2001 From: jinye_huang Date: Wed, 9 Jul 2025 16:33:38 +0800 Subject: [PATCH] =?UTF-8?q?=E5=A2=9E=E5=8A=A0=E4=BA=86=E6=96=87=E6=A1=A3?= =?UTF-8?q?=EF=BC=8C=E5=AE=8C=E6=88=90=E4=BA=86=E7=94=9F=E6=96=87=E6=A8=A1?= =?UTF-8?q?=E5=9D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 230 ++++++++++++++++++++++ docs/使用指南.md | 309 ++++++++++++++++++++++++++++++ docs/开发指南.md | 486 +++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 1025 insertions(+) create mode 100644 README.md create mode 100644 docs/使用指南.md create mode 100644 docs/开发指南.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..316d545 --- /dev/null +++ b/README.md @@ -0,0 +1,230 @@ +# 旅游内容自动生成系统 + +## 系统概述 + +旅游内容自动生成系统是一个基于AI的内容创作平台，专注于为旅游景点和产品生成营销内容。系统采用三阶段生成流程：选题生成、内容创作和内容审核，每个阶段都由专门的AI模型处理，并通过配置文件进行精细控制。 + +## 系统架构 + +系统由以下主要模块组成： + +### 核心模块 (core) +- **config**: 配置管理，负责加载和管理各种配置 +- **ai**: AI代理，处理与大模型的交互 +- **exception**: 异常处理 + +### 工具模块 (utils) +- **file_io**: 文件输入输出，包括ResourceLoader和OutputManager +- **prompts**: 提示词模板和构建器 +- **pipeline**: 流程管理 +- **tweet**: 内容生成相关模块，包括topic_generator、content_generator、content_judger + +## 功能模块 + +### 1. 选题生成 (TopicGenerator) + +根据指定月份和节日生成旅游营销选题，考虑目标受众、营销风格和产品特性，输出标准化JSON格式的选题信息。 + +**主要功能**: +- 基于时间节点生成选题 +- 考虑产品特性和目标受众 +- 输出结构化选题数据 + +### 2. 内容创作 (ContentGenerator) + +基于选题生成小红书风格的营销文案，包含吸引人的标题、详细正文和SEO优化的标签，遵循特定的文案风格和目标受众需求。 + +**主要功能**: +- 生成符合平台特性的标题 +- 创建详细、有吸引力的正文 +- 生成优化的标签 + +### 3. 内容审核 (ContentJudger) + +审核生成内容是否符合产品资料，检查价格、活动、服务等关键信息的准确性，保留原始内容中的标签和引流语句。 + +**主要功能**: +- 检查内容准确性 +- 修正不符合产品资料的内容 +- 保留原始内容中的关键元素 + +## 配置说明 + +系统通过JSON配置文件管理各组件参数： + +### 系统配置 (system.json) +```json +{ + "debug": false, + "log_level": "INFO", + "parallel_processing": false, + "max_workers": 4 +} +``` + +### AI模型配置 (ai_model.json) +```json +{ + "model": "qwen-plus", + "api_url": "https://dashscope.aliyuncs.com/compatible-mode/v1", + "api_key": "your_api_key", + "temperature": 0.3, + "top_p": 0.4, + "presence_penalty": 1.2, + "timeout": 120, + "max_retries": 3 +} +``` + +### 资源配置 (resource.json) +```json +{ + "resource_dirs": ["."], + "style": { + "paths": ["resource/prompt/Style/攻略风文案提示词.md", "..."] + }, + "demand": { + "paths": ["resource/prompt/Demand/亲子向文旅需求.md", "..."] + }, + "refer": { + "refer_list": [ + { "path": "resource/prompt/Refer/2025各月节日宣传节点时间表.md", "sampling_rate": 1, "step": "topic" }, + { "path": "resource/prompt/Refer/标题参考格式.json", "sampling_rate": 0.25, "step": "content" }, + { "path": "resource/prompt/Refer/正文范文参考.json", "sampling_rate": 0.5, "step": "content" } + ] + }, + "object": { + "paths": ["resource/data/Object/天津冒险湾.txt"] + }, + "product": { + "paths": ["resource/data/Product/天津冒险湾-2大2小套票.txt"] + }, + "output_dir": { + "base_dir": "result" + } +} +``` + +### 选题生成配置 (topic_gen.json) +```json +{ + "topic_system_prompt": "resource/prompt/generateTopics/system.txt", + "topic_user_prompt": "resource/prompt/generateTopics/user.txt", + "model": { + "temperature": 0.2, + "top_p": 0.3, + "presence_penalty": 1.5 + }, + "topic": { + "date": "2024-07-20", + "num": 5, + "variants": 1 + } +} +``` + +### 内容生成配置 (content_gen.json) +```json +{ + "content_system_prompt": "resource/prompt/generateContent/system.txt", + "content_user_prompt": "resource/prompt/generateContent/user.txt", + "judger_system_prompt": "resource/prompt/judgeContent/system.txt", + "judger_user_prompt": "resource/prompt/judgeContent/user.txt", + "enable_content_judge": true, + "model": { + "temperature": 0.3, + "top_p": 0.5, + "presence_penalty": 1.2 + }, + "judger_model": { + "temperature": 0.2, + "top_p": 0.3, + "presence_penalty": 0.8 + } +} +``` + +## 使用指南 + +### 安装依赖 + +```bash +pip install -r requirements.txt +``` + +### 运行系统 + +```bash +python main.py --config_dir config --run_id custom_run_id +``` + +参数说明: +- `--config_dir`: 配置文件目录路径，默认为 "config" +- `--run_id`: 运行ID，用于标识本次运行，默认为时间戳格式 + +### 输出结果 + +系统运行后，会在 `result/{run_id}` 目录下生成以下文件: +- `topics_generated.json`: 生成的选题列表 +- `topics_generated.txt`: 人类可读的选题列表 +- 每个选题的子目录 `topic_{index}`: + - `content_system_prompt.txt`: 内容生成的系统提示 + - `content_user_prompt.txt`: 内容生成的用户提示 + - `content_raw_response.txt`: AI返回的原始响应 + - `article.json`: 生成的文章内容 + - `judger_system_prompt.txt`: 审核的系统提示 + - `judger_user_prompt.txt`: 审核的用户提示 + - `judger_raw_response.txt`: 审核的原始响应 + - `article_judged.json`: 审核后的文章内容 + +## 系统特性 + +1. **资源加载增强**: + - 支持基于文件名(不含后缀)的模糊匹配 + - 对JSON文件内容的直接采样 + +2. **引用内容的阶段控制**: + - 通过step字段控制在不同阶段(topic/content/judge)使用哪些引用资源 + - 通过采样率控制参考内容的使用量 + +3. **模型参数独立配置**: + - 为不同生成阶段配置独立的模型参数 + - 提高各阶段生成内容的质量和多样性 + +4. **内容审核系统**: + - 保留原始内容中的tags标签 + - 对价格、活动等关键信息进行审核 + +5. **文件IO系统**: + - 灵活的资源加载和输出管理 + - 结构化的文件组织方式 + +## 目录结构 + +``` +. +├── main.py # 主程序入口 +├── config/ # 配置文件目录 +│ ├── ai_model.json # AI模型配置 +│ ├── content_gen.json # 内容生成配置 +│ ├── resource.json # 资源配置 +│ ├── system.json # 系统配置 +│ └── topic_gen.json # 选题生成配置 +├── core/ # 核心模块 +│ ├── ai/ # AI代理 +│ ├── config/ # 配置管理 +│ └── exception/ # 异常处理 +├── utils/ # 工具模块 +│ ├── file_io.py # 文件IO +│ ├── pipeline.py # 流程管理 +│ ├── prompts.py # 提示词构建 +│ └── tweet/ # 内容生成相关 +│ ├── content_generator.py # 内容生成器 +│ ├── content_judger.py # 内容审核器 +│ └── topic_generator.py # 选题生成器 +├── resource/ # 资源文件 +│ ├── data/ # 数据文件 +│ └── prompt/ # 提示词模板 +├── result/ # 输出结果 +└── requirements.txt # 依赖包 +``` \ No newline at end of file diff --git a/docs/使用指南.md b/docs/使用指南.md new file mode 100644 index 0000000..8a1e8c2 --- /dev/null +++ b/docs/使用指南.md @@ -0,0 +1,309 @@ +# 旅游内容自动生成系统 - 使用指南 + +## 1. 系统概述 + +旅游内容自动生成系统是一个基于AI的内容创作平台，专注于为旅游景点和产品生成营销内容。系统采用三阶段生成流程：选题生成、内容创作和内容审核，每个阶段都由专门的AI模型处理，并通过配置文件进行精细控制。 + +## 2. 环境准备 + +### 系统要求 +- Python 3.8+ +- 足够的内存（推荐8GB以上） +- 互联网连接（用于API调用） + +### 安装依赖 +```bash +# 克隆仓库 +git clone [仓库地址] +cd [仓库名称] + +# 安装依赖包 +pip install -r requirements.txt +``` + +## 3. 配置系统 + +系统通过JSON配置文件进行控制，所有配置文件位于`config`目录下： + +### 3.1 AI模型配置 (ai_model.json) + +```json +{ + "model": "qwen-plus", // 使用的模型名称 + "api_url": "https://dashscope.aliyuncs.com/compatible-mode/v1", // API地址 + "api_key": "your_api_key", // 替换为您的API密钥 + "temperature": 0.3, // 生成多样性控制 + "top_p": 0.4, // 采样控制 + "presence_penalty": 1.2, // 重复惩罚 + "timeout": 120, // API超时时间（秒） + "max_retries": 3 // 最大重试次数 +} +``` + +> **重要提示**: 请替换`your_api_key`为您的实际API密钥。 + +### 3.2 选题生成配置 (topic_gen.json) + +```json +{ + "topic_system_prompt": "resource/prompt/generateTopics/system.txt", // 系统提示路径 + "topic_user_prompt": "resource/prompt/generateTopics/user.txt", // 用户提示路径 + "model": { + "temperature": 0.2, // 选题生成的温度参数 + "top_p": 0.3, // 选题生成的top_p参数 + "presence_penalty": 1.5 // 选题生成的重复惩罚参数 + }, + "topic": { + "date": "2024-07-20", // 选题目标日期 + "num": 5, // 生成选题数量 + "variants": 1 // 每个选题的变体数量 + } +} +``` + +### 3.3 内容生成配置 (content_gen.json) + +```json +{ + "content_system_prompt": "resource/prompt/generateContent/system.txt", // 内容生成系统提示 + "content_user_prompt": "resource/prompt/generateContent/user.txt", // 内容生成用户提示 + "judger_system_prompt": "resource/prompt/judgeContent/system.txt", // 审核系统提示 + "judger_user_prompt": "resource/prompt/judgeContent/user.txt", // 审核用户提示 + "enable_content_judge": true, // 是否启用内容审核 + "model": { + "temperature": 0.3, // 内容生成温度参数 + "top_p": 0.5, // 内容生成top_p参数 + "presence_penalty": 1.2 // 内容生成重复惩罚参数 + }, + "judger_model": { + "temperature": 0.2, // 内容审核温度参数 + "top_p": 0.3, // 内容审核top_p参数 + "presence_penalty": 0.8 // 内容审核重复惩罚参数 + } +} +``` + +### 3.4 资源配置 (resource.json) + +```json +{ + "resource_dirs": ["."], // 资源基础目录 + "style": { + "paths": [ // 文案风格文件路径 + "resource/prompt/Style/攻略风文案提示词.md", + "resource/prompt/Style/极力推荐风文案提示词.md" + ] + }, + "demand": { + "paths": [ // 用户需求文件路径 + "resource/prompt/Demand/亲子向文旅需求.md", + "resource/prompt/Demand/周边游文旅需求.md" + ] + }, + "refer": { + "refer_list": [ // 参考资料配置 + { + "path": "resource/prompt/Refer/2025各月节日宣传节点时间表.md", + "sampling_rate": 1, // 采样率，1表示100%使用 + "step": "topic" // 使用阶段：topic/content/judge + }, + { + "path": "resource/prompt/Refer/标题参考格式.json", + "sampling_rate": 0.25, + "step": "content" + }, + { + "path": "resource/prompt/Refer/正文范文参考.json", + "sampling_rate": 0.5, + "step": "content" + } + ] + }, + "object": { + "paths": [ // 景点对象文件路径 + "resource/data/Object/天津冒险湾.txt" + ] + }, + "product": { + "paths": [ // 产品信息文件路径 + "resource/data/Product/天津冒险湾-2大2小套票.txt" + ] + }, + "output_dir": { + "base_dir": "result" // 输出目录 + } +} +``` + +### 3.5 系统配置 (system.json) + +```json +{ + "debug": false, // 是否开启调试模式 + "log_level": "INFO", // 日志级别 + "parallel_processing": false, // 是否启用并行处理 + "max_workers": 4 // 最大工作线程数 +} +``` + +## 4. 运行系统 + +### 4.1 基本运行命令 + +```bash +python main.py +``` + +这将使用默认配置运行系统。 + +### 4.2 自定义运行参数 + +```bash +python main.py --config_dir custom_config --run_id my_run_20240601 +``` + +参数说明: +- `--config_dir`: 配置文件目录路径，默认为 "config" +- `--run_id`: 运行ID，用于标识本次运行，默认为时间戳格式 + +## 5. 输出结果 + +系统运行后，会在 `result/{run_id}` 目录下生成以下文件: + +- `topics_generated.json`: 生成的选题列表（JSON格式） +- `topics_generated.txt`: 人类可读的选题列表（文本格式） +- 每个选题的子目录 `topic_{index}`: + - `content_system_prompt.txt`: 内容生成的系统提示 + - `content_user_prompt.txt`: 内容生成的用户提示 + - `content_raw_response.txt`: AI返回的原始响应 + - `article.json`: 生成的文章内容 + - `judger_system_prompt.txt`: 审核的系统提示（如果启用审核） + - `judger_user_prompt.txt`: 审核的用户提示（如果启用审核） + - `judger_raw_response.txt`: 审核的原始响应（如果启用审核） + - `article_judged.json`: 审核后的文章内容（如果启用审核） + +## 6. 资源文件准备 + +### 6.1 提示词模板 + +系统使用以下提示词模板： + +- **选题生成**: + - `resource/prompt/generateTopics/system.txt`: 选题生成系统提示 + - `resource/prompt/generateTopics/user.txt`: 选题生成用户提示 + +- **内容生成**: + - `resource/prompt/generateContent/system.txt`: 内容生成系统提示 + - `resource/prompt/generateContent/user.txt`: 内容生成用户提示 + +- **内容审核**: + - `resource/prompt/judgeContent/system.txt`: 内容审核系统提示 + - `resource/prompt/judgeContent/user.txt`: 内容审核用户提示 + +### 6.2 风格和需求文件 + +- **风格文件** (`resource/prompt/Style/`): + - 每个文件描述一种文案风格 + - 例如：`攻略风文案提示词.md`, `极力推荐风文案提示词.md` + +- **需求文件** (`resource/prompt/Demand/`): + - 每个文件描述一种用户需求 + - 例如：`亲子向文旅需求.md`, `周边游文旅需求.md` + +### 6.3 参考资料文件 + +- **参考资料** (`resource/prompt/Refer/`): + - 节日时间表：`2025各月节日宣传节点时间表.md` + - 标题参考：`标题参考格式.json` + - 正文参考：`正文范文参考.json` + +### 6.4 产品和景点数据 + +- **景点数据** (`resource/data/Object/`): + - 每个文件包含一个景点的详细信息 + - 例如：`天津冒险湾.txt` + +- **产品数据** (`resource/data/Product/`): + - 每个文件包含一个产品的详细信息 + - 例如：`天津冒险湾-2大2小套票.txt` + +## 7. 常见问题解答 + +### 7.1 系统运行失败 + +**问题**: 系统运行时出现错误或无法生成内容。 + +**解决方案**: +1. 检查API密钥是否正确配置 +2. 检查网络连接是否正常 +3. 查看日志输出，定位具体错误 +4. 确保所有资源文件路径正确且文件存在 + +### 7.2 生成内容质量不佳 + +**问题**: 生成的内容质量不符合预期。 + +**解决方案**: +1. 调整模型参数（temperature、top_p、presence_penalty） +2. 改进提示词模板 +3. 提供更高质量的参考资料 +4. 确保产品和景点信息详尽准确 + +### 7.3 审核功能不生效 + +**问题**: 内容审核功能似乎没有生效。 + +**解决方案**: +1. 检查`content_gen.json`中的`enable_content_judge`是否设为`true` +2. 确保审核提示词模板存在且路径正确 +3. 检查日志中是否有审核相关的错误信息 + +### 7.4 如何添加新的景点或产品 + +**步骤**: +1. 在`resource/data/Object/`目录下创建新的景点文件 +2. 在`resource/data/Product/`目录下创建新的产品文件 +3. 更新`resource.json`中的`object.paths`和`product.paths`数组 +4. 重新运行系统 + +### 7.5 如何自定义生成内容的风格 + +**步骤**: +1. 在`resource/prompt/Style/`目录下创建新的风格文件 +2. 更新`resource.json`中的`style.paths`数组 +3. 在选题生成时，系统会自动考虑新添加的风格 + +## 8. 高级使用技巧 + +### 8.1 调整模型参数 + +不同的内容类型可能需要不同的模型参数： +- 高`temperature`（0.7-1.0）：更有创意但可能不够精确 +- 低`temperature`（0.1-0.3）：更精确但可能缺乏创意 +- 高`presence_penalty`：减少重复内容 +- 低`top_p`：更保守的输出 + +### 8.2 参考内容采样率调整 + +通过调整`sampling_rate`参数，可以控制参考内容的使用量： +- `1.0`：全部使用 +- `0.5`：使用约50% +- `0.25`：使用约25% + +### 8.3 自定义提示词模板 + +可以根据需要修改提示词模板，但请确保： +1. 保持JSON输出格式一致 +2. 不要改变关键指令 +3. 测试修改后的效果 + +### 8.4 批量生成内容 + +对于需要批量生成内容的场景，可以： +1. 准备多个景点和产品数据 +2. 编写脚本循环调用主程序 +3. 为每次运行指定不同的`run_id` + +## 9. 联系与支持 + +如有问题或需要支持，请联系系统管理员或开发团队。 \ No newline at end of file diff --git a/docs/开发指南.md b/docs/开发指南.md new file mode 100644 index 0000000..bc7844b --- /dev/null +++ b/docs/开发指南.md @@ -0,0 +1,486 @@ +# 旅游内容自动生成系统 - 开发指南 + +## 1. 系统架构 + +旅游内容自动生成系统采用模块化架构设计，主要分为核心模块(core)和工具模块(utils)两大部分。系统通过Pipeline模式协调各个组件的工作，实现从选题生成到内容审核的完整流程。 + +### 1.1 架构图 + +``` + ┌─────────────┐ + │ 主程序 │ + │ main.py │ + └──────┬──────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ PipelineManager │ +└───────┬───────────────────┬──────────────────┬──────────────┘ + │ │ │ + ▼ ▼ ▼ +┌───────────────┐ ┌───────────────┐ ┌───────────────┐ +│ TopicGenerator │ │ContentGenerator│ │ ContentJudger │ +└───────┬───────┘ └───────┬───────┘ └───────┬───────┘ + │ │ │ + │ │ │ + ▼ ▼ ▼ +┌─────────────────────────────────────────────────────────────┐ +│ AIAgent │ +└─────────────────────────────────────────────────────────────┘ + ▲ ▲ ▲ + │ │ │ + │ │ │ +┌───────┴───────┐ ┌───────┴───────┐ ┌──────┴────────┐ +│PromptBuilders │ │ ResourceLoader│ │ OutputManager │ +└───────────────┘ └───────────────┘ └───────────────┘ +``` + +### 1.2 数据流 + +1. 配置加载: 系统启动时，ConfigManager加载所有配置文件 +2. 选题生成: TopicGenerator调用AIAgent生成选题 +3. 内容生成: ContentGenerator为每个选题调用AIAgent生成内容 +4. 内容审核: ContentJudger审核生成的内容 +5. 结果保存: OutputManager保存所有生成的内容和中间产物 + +## 2. 代码结构 + +### 2.1 目录结构 + +``` +. +├── main.py # 主程序入口 +├── config/ # 配置文件目录 +│ ├── ai_model.json # AI模型配置 +│ ├── content_gen.json # 内容生成配置 +│ ├── resource.json # 资源配置 +│ ├── system.json # 系统配置 +│ └── topic_gen.json # 选题生成配置 +├── core/ # 核心模块 +│ ├── ai/ # AI代理 +│ │ ├── __init__.py +│ │ └── ai_agent.py # AI代理实现 +│ ├── config/ # 配置管理 +│ │ ├── __init__.py +│ │ └── config_manager.py # 配置管理器 +│ └── exception/ # 异常处理 +│ ├── __init__.py +│ └── exceptions.py # 自定义异常类 +├── utils/ # 工具模块 +│ ├── file_io.py # 文件IO +│ ├── pipeline.py # 流程管理 +│ ├── prompts.py # 提示词构建 +│ └── tweet/ # 内容生成相关 +│ ├── __init__.py +│ ├── content_generator.py # 内容生成器 +│ ├── content_judger.py # 内容审核器 +│ ├── topic_generator.py # 选题生成器 +│ └── topic_parser.py # 选题解析器 +├── resource/ # 资源文件 +│ ├── data/ # 数据文件 +│ └── prompt/ # 提示词模板 +├── result/ # 输出结果 +└── requirements.txt # 依赖包 +``` + +### 2.2 主要模块说明 + +#### 2.2.1 核心模块 (core) + +- **ai_agent.py**: 负责与AI模型的交互，封装API调用逻辑 +- **config_manager.py**: 负责加载和管理配置文件 +- **exceptions.py**: 定义系统自定义异常类 + +#### 2.2.2 工具模块 (utils) + +- **file_io.py**: 提供文件读写功能，包括ResourceLoader和OutputManager +- **pipeline.py**: 实现整个生成流程的管理 +- **prompts.py**: 提供提示词模板和构建功能 +- **tweet/**: 内容生成相关的具体实现 + - **topic_generator.py**: 选题生成器 + - **content_generator.py**: 内容生成器 + - **content_judger.py**: 内容审核器 + - **topic_parser.py**: 选题解析器 + +## 3. 核心类说明 + +### 3.1 AIAgent 类 + +`AIAgent` 类是系统与AI模型交互的核心，负责发送请求并处理响应。 + +```python +class AIAgent: + def __init__(self, config: AIModelConfig): + # 初始化AI代理，设置API客户端 + + async def generate_text( + self, system_prompt: str, user_prompt: str, use_stream: bool = False, + temperature: Optional[float] = None, top_p: Optional[float] = None, + presence_penalty: Optional[float] = None, stage: str = "" + ) -> Tuple[str, int, int, float]: + # 生成文本，支持流式和非流式输出 + # 返回: (生成文本, 输入token数, 输出token数, 耗时) +``` + +### 3.2 ConfigManager 类 + +`ConfigManager` 类负责加载和管理配置文件。 + +```python +class ConfigManager: + def __init__(self): + # 初始化配置管理器 + + def load_from_directory(self, config_dir: str): + # 从目录加载所有配置文件 + + def get_config(self, config_name: str, config_class: Type[T]) -> T: + # 获取指定名称的配置对象 +``` + +### 3.3 PipelineManager 类 + +`PipelineManager` 类负责协调整个内容生成流程。 + +```python +class PipelineManager: + def __init__(self, config_dir: str, run_id: Optional[str] = None): + # 初始化管道管理器 + + async def process_content_generation(self, topics: List[Dict[str, Any]]) -> List[Dict[str, Any]]: + # 处理内容生成 + + async def process_content_judging(self, generated_contents: List[Dict[str, Any]]): + # 处理内容审核 + + async def run_pipeline(self): + # 按顺序执行整个流程 +``` + +### 3.4 提示词构建器类 + +系统包含多个提示词构建器，负责构建不同阶段的提示词。 + +```python +class BasePromptBuilder(PromptTemplate): + # 基础提示词构建器，提供通用方法 + +class TopicPromptBuilder(BasePromptBuilder): + # 选题生成提示词构建器 + +class ContentPromptBuilder(BasePromptBuilder): + # 内容生成提示词构建器 + +class JudgerPromptBuilder(BasePromptBuilder): + # 内容审核提示词构建器 +``` + +## 4. 关键流程 + +### 4.1 选题生成流程 + +1. 加载配置和资源 +2. 构建系统提示和用户提示 +3. 调用AI模型生成选题 +4. 解析AI响应，提取选题信息 +5. 保存选题结果 + +```python +# 在TopicGenerator.generate_topics方法中实现 +async def generate_topics(self) -> Optional[List[Dict[str, Any]]]: + # 构建提示 + system_prompt = self.prompt_builder.get_system_prompt() + user_prompt = self.prompt_builder.build_user_prompt(...) + + # 调用AI + raw_result = await self.ai_agent.generate_text(...) + + # 解析结果 + topics = self.parser.parse(raw_result) + + # 保存结果 + self.output_manager.save_json(topics, "topics_generated.json") + + return topics +``` + +### 4.2 内容生成流程 + +1. 为每个选题构建提示 +2. 调用AI模型生成内容 +3. 解析AI响应，提取内容信息 +4. 保存生成的内容 + +```python +# 在ContentGenerator.generate_content_for_topic方法中实现 +async def generate_content_for_topic(self, topic: Dict[str, Any]) -> Dict[str, Any]: + # 构建提示 + system_prompt = self.prompt_builder.get_system_prompt() + user_prompt = self.prompt_builder.build_user_prompt(topic=topic) + + # 调用AI + raw_result = await self.ai_agent.generate_text(...) + + # 解析和保存结果 + content_data = json.loads(raw_result) + self.output_manager.save_json(content_data, "article.json", ...) + + return content_data +``` + +### 4.3 内容审核流程 + +1. 为每个生成的内容构建审核提示 +2. 调用AI模型进行审核 +3. 解析审核结果，提取修改后的内容 +4. 保存审核后的内容 + +```python +# 在ContentJudger.judge_content方法中实现 +async def judge_content(self, generated_content: str, topic: Dict[str, Any]) -> Dict[str, Any]: + # 构建提示 + system_prompt = self.prompt_builder.get_system_prompt() + user_prompt = self.prompt_builder.build_user_prompt(...) + + # 调用AI + raw_result = await self.ai_agent.generate_text(...) + + # 解析结果 + judged_data = json_repair_loads(raw_result) + + # 保存结果 + self.output_manager.save_json(judged_data, "article_judged.json", ...) + + return judged_data +``` + +## 5. 扩展指南 + +### 5.1 添加新的生成阶段 + +要添加新的生成阶段（例如图像生成），需要以下步骤： + +1. 创建新的生成器类，例如 `ImageGenerator` +2. 创建对应的提示词构建器，例如 `ImagePromptBuilder` +3. 在 `PipelineManager` 中添加新的处理方法 +4. 在 `run_pipeline` 方法中调用新的处理方法 + +```python +# 1. 创建新的生成器类 +class ImageGenerator: + def __init__(self, ai_agent, config_manager, output_manager): + # 初始化 + + async def generate_image_for_content(self, content): + # 生成图像的逻辑 + +# 2. 在PipelineManager中添加 +def __init__(self, ...): + # 现有初始化代码 + self.image_generator = ImageGenerator(...) + +async def process_image_generation(self, contents): + # 处理图像生成的逻辑 + +async def run_pipeline(self): + # 现有流程代码 + # 添加新阶段 + if generated_contents: + await self.process_image_generation(generated_contents) +``` + +### 5.2 添加新的AI模型 + +要支持新的AI模型，需要修改 `AIAgent` 类： + +1. 更新 `__init__` 方法，支持新的模型配置 +2. 在 `generate_text` 方法中添加对新模型的支持 +3. 更新配置文件结构 + +```python +class AIAgent: + def __init__(self, config: AIModelConfig): + self.config = config + if config.provider == "openai": + self.client = AsyncOpenAI(...) + elif config.provider == "new_provider": + self.client = NewProviderClient(...) + + async def generate_text(self, ...): + # 根据provider选择不同的API调用方式 + if self.config.provider == "openai": + # 现有OpenAI调用逻辑 + elif self.config.provider == "new_provider": + # 新提供商的API调用逻辑 +``` + +### 5.3 自定义资源加载器 + +要支持新的资源类型或加载方式，可以扩展 `ResourceLoader` 类： + +```python +class ResourceLoader: + # 现有方法 + + @staticmethod + def load_special_format(file_path: str) -> Optional[Dict]: + # 加载特殊格式文件的逻辑 + + @staticmethod + def load_from_database(query: str) -> Optional[str]: + # 从数据库加载资源的逻辑 +``` + +### 5.4 添加新的输出格式 + +要支持新的输出格式，可以扩展 `OutputManager` 类： + +```python +class OutputManager: + # 现有方法 + + def save_html(self, content: str, filename: str, subdir: Optional[str] = None): + # 保存HTML格式的逻辑 + + def export_to_cms(self, content: Dict, api_endpoint: str): + # 导出到CMS系统的逻辑 +``` + +## 6. 最佳实践 + +### 6.1 代码风格 + +- 遵循PEP 8规范 +- 使用类型注解提高代码可读性 +- 为所有公共方法和类提供文档字符串 +- 使用异步编程处理IO密集型操作 + +### 6.2 错误处理 + +- 使用自定义异常类区分不同类型的错误 +- 实现重试机制处理临时性故障 +- 记录详细的错误信息，便于调试 + +```python +try: + result = await self.ai_agent.generate_text(...) +except RetryableError as e: + # 处理可重试错误 + logger.warning(f"遇到可重试错误: {e}") + # 实现重试逻辑 +except NonRetryableError as e: + # 处理不可重试错误 + logger.error(f"遇到不可重试错误: {e}") + # 返回错误信息 +except Exception as e: + # 处理未预期的错误 + logger.critical(f"遇到未知错误: {e}", exc_info=True) + # 返回通用错误信息 +``` + +### 6.3 性能优化 + +- 使用异步IO提高并发性能 +- 实现缓存机制减少重复计算 +- 优化提示词减少token使用量 +- 使用采样率控制参考内容的使用量 + +### 6.4 测试策略 + +- 为核心功能编写单元测试 +- 使用模拟对象测试AI调用 +- 编写集成测试验证完整流程 +- 使用参数化测试覆盖多种场景 + +```python +# 单元测试示例 +async def test_topic_parser(): + parser = TopicParser() + raw_json = '{"topics": [{"index": "1", "date": "2024-07-01", ...}]}' + topics = parser.parse(raw_json) + assert len(topics) == 1 + assert topics[0]["index"] == "1" + assert topics[0]["date"] == "2024-07-01" +``` + +## 7. 常见问题与解决方案 + +### 7.1 AI调用超时 + +**问题**: AI模型调用经常超时。 + +**解决方案**: +1. 增加超时设置 +2. 实现指数退避重试 +3. 减少提示词长度 +4. 考虑使用流式响应 + +```python +# 实现指数退避重试 +backoff_time = 1.0 +for attempt in range(max_retries): + try: + response = await client.chat.completions.create(...) + return response + except APITimeoutError: + logger.warning(f"尝试 {attempt + 1}/{max_retries} 超时") + await asyncio.sleep(backoff_time) + backoff_time *= 2 # 指数增长 +``` + +### 7.2 内存使用过高 + +**问题**: 处理大量内容时内存使用过高。 + +**解决方案**: +1. 使用生成器处理大量数据 +2. 实现批处理机制 +3. 及时释放不再需要的资源 + +```python +# 使用生成器处理大量数据 +async def process_topics_in_batches(self, topics, batch_size=5): + for i in range(0, len(topics), batch_size): + batch = topics[i:i+batch_size] + results = await self.process_batch(batch) + for result in results: + yield result +``` + +### 7.3 JSON解析错误 + +**问题**: AI返回的内容无法解析为JSON。 + +**解决方案**: +1. 使用更健壮的JSON解析库（如json_repair） +2. 在提示词中强调JSON格式要求 +3. 实现后处理逻辑修复常见错误 + +```python +# 使用json_repair修复JSON +try: + data = json.loads(raw_result) +except json.JSONDecodeError: + try: + data = json_repair_loads(raw_result) + logger.warning("使用json_repair修复了JSON格式") + except Exception as e: + logger.error(f"JSON修复失败: {e}") + # 返回错误信息 +``` + +## 8. 未来扩展方向 + +1. **多模态支持**: 添加图像生成和处理能力 +2. **用户反馈系统**: 收集和利用用户对生成内容的反馈 +3. **内容分发集成**: 与社交媒体平台API集成，自动发布内容 +4. **A/B测试框架**: 比较不同提示词和参数的效果 +5. **本地模型支持**: 支持本地部署的开源模型 + +## 9. 贡献指南 + +1. Fork仓库并创建功能分支 +2. 编写代码并添加测试 +3. 确保所有测试通过 +4. 提交Pull Request并描述变更 +5. 等待代码审查和合并 \ No newline at end of file