TravelContentCreator/examples/README.md

#!/usr/bin/env python
# -*- coding: utf-8 -*-

# 旅游内容创作工具示例

本目录包含使用旅游内容创作工具各个组件的示例代码。通过这些示例，您可以了解如何调用系统的各个模块，或测试整个工作流程。

## 测试工作流程

`test_workflow.py` 是一个完整的测试脚本，它展示了如何测试整个内容生成流程，包括：

1. 完整流程测试：执行从选题生成到海报制作的全过程
2. 分步骤测试：将流程拆分为独立的步骤，模拟在不同时间或机器上执行的场景

### 使用方法

确保已经正确配置了项目根目录的 `poster_gen_config.json` 文件。

```bash
# 测试完整工作流程（从选题生成到海报制作的全过程）
python examples/test_workflow.py --mode full

# 测试分步骤工作流程（模拟分阶段执行的场景）
python examples/test_workflow.py --mode steps

# 两种测试模式都执行（默认）
python examples/test_workflow.py
```

## 分阶段执行示例

这两个脚本演示了如何将工作流程拆分为两个独立的阶段：

1.  `run_step1_topics.py`: 仅执行选题生成。
2.  `run_step2_content_posters.py`: 加载第一阶段生成的选题结果，然后执行内容和海报生成。

### 使用方法

1.  **执行阶段 1 (生成选题)**:
    ```bash
    python examples/run_step1_topics.py
    ```
    运行结束后，脚本会打印出生成的 `Run ID` 和选题文件路径。请记下这个 `Run ID`。

2.  **执行阶段 2 (生成内容和海报)**:
    将 `<your_run_id>` 替换为你在阶段 1 记下的实际 Run ID。
    ```bash
    python examples/run_step2_content_posters.py <your_run_id>
    ```
    例如:
    ```bash
    python examples/run_step2_content_posters.py 20240515_110000
    ```

## 单组件测试脚本

以下脚本用于独立测试系统的各个组件，有助于开发者了解每个组件的功能和使用方法：

### 1. 图像处理测试 - `test_image_processing.py`

这个脚本专注于测试图像处理功能，**无需连接AI服务**，可独立测试拼贴图和海报生成功能。

```bash
# 基本用法（同时测试拼贴和海报功能）
python examples/test_image_processing.py

# 仅测试拼贴图功能
python examples/test_image_processing.py --collage_only

# 仅测试海报生成功能
python examples/test_image_processing.py --poster_only

# 指定输出目录和配置文件
python examples/test_image_processing.py --output my_test_output --config my_config.json
```

特点：
- 无需连接AI接口，可在离线环境下测试
- 自动创建测试用的彩色图像作为素材
- 测试多种拼贴风格（网格、非对称、胶片条、重叠、马赛克）
- 使用拼贴图作为海报底图，展示完整的图像处理流程
- 详细的日志输出，便于分析问题

### 2. 图片拼贴测试 - `test_simple_collage.py`

这个脚本演示如何使用图片拼贴功能，可以测试不同风格的拼贴效果。

```bash
# 基本用法（自动创建测试图片）
python examples/test_simple_collage.py

# 使用自定义图片目录
python examples/test_simple_collage.py --input_dir /path/to/images

# 指定输出目录和生成数量
python examples/test_simple_collage.py --output_dir my_collages --count 5

# 设置自定义尺寸
python examples/test_simple_collage.py --width 1080 --height 1440
```

特点：
- 支持测试所有拼贴风格（网格、非对称、胶片条、重叠、马赛克）
- 如果未提供输入图片，会自动生成测试用的彩色图片
- 可以指定随机种子，用于获得可重现的结果

### 3. 海报生成测试 - `test_poster_generator.py`

这个脚本演示如何使用海报生成功能，可以测试不同文案、配置的海报效果。

```bash
# 基本用法（使用随机文本和自动创建底图）
python examples/test_poster_generator.py

# 使用自定义底图和输出目录
python examples/test_poster_generator.py --image /path/to/image.jpg --output_dir my_posters

# 使用自定义素材目录和配置文件
python examples/test_poster_generator.py --base_dir /path/to/assets --config poster_config.json
```

特点：
- 支持直接使用现有海报配置文件（由ContentGenerator生成的JSON）
- 自动加载系统配置中的素材路径
- 如果未提供底图，会自动创建渐变测试底图
- 自带多种文案示例，可以测试不同文字效果

### 4. 内容生成测试 - `test_content_generator.py`

这个脚本演示如何使用内容生成功能，生成海报文本配置数据。

```bash
# 基本用法（交互式输入）
python examples/test_content_generator.py

# 按提示进行操作，可以指定描述文件和生成数量
```

特点：
- 使用交互式命令行提示用户输入参数
- 自动尝试从系统配置中查找描述文件
- 如果未找到描述文件，会创建临时测试文件
- 生成完成后会将配置保存为JSON文件

### 5. 流式输出测试 - `test_stream.py`

这个脚本演示如何使用AI_Agent的流式输出功能，逐块接收生成内容。

```bash
# 运行流式输出测试
python examples/test_stream.py
```

特点：
- 展示如何配置和使用AI_Agent的流式输出接口
- 演示实时输出文本块的处理方式
- 说明如何收集完整响应和估计token数

## 流式处理演示 (test_stream.py)

`test_stream.py` 是一个演示脚本，展示了AI_Agent类中新增的三种不同流式输出处理方法：

1. **同步流式响应** (generate_text_stream) - 使用流式API但返回完整响应
2. **回调式流式响应** (generate_text_stream_with_callback) - 通过回调函数处理每个文本块
3. **异步流式响应** (async_generate_text_stream) - 使用异步生成器返回文本流

### 运行演示

```bash
cd TravelContentCreator
python examples/test_stream.py
```

演示脚本会依次执行这三种方法，并展示它们的输出和性能差异。

### 更多信息

关于流式处理功能的详细文档，请参阅：

```
docs/streaming.md
```

## 其他示例

`generate_poster.py` 是一个简化的海报生成示例，主要用于快速测试特定图片的海报效果。

```bash
# 使用默认参数生成海报
python examples/generate_poster.py

# 指定输入图片和输出路径
python examples/generate_poster.py --input_image /path/to/image.jpg --output_path /path/to/output.jpg
```

## 注意事项

- 这些示例依赖于主项目中的配置和资源，确保已正确设置 `poster_gen_config.json`
- 测试脚本会自动调节某些参数（如生成数量）以加快测试速度
- 实际使用时，您可能需要调整参数以获得更好的效果
- 部分测试脚本需要连接AI模型API，确保您的API配置正确

### 完整工作流测试脚本
`test_workflow.py`文件展示了一个完整的内容生成过程，从主题生成到海报创作。

#### 运行完整工作流测试:
```bash
python examples/test_workflow.py
```

该脚本将执行以下步骤:
1. 生成旅游目的地主题
2. 根据主题生成内容
3. 生成配图海报
4. 保存结果

#### 分步测试:
如果您想分阶段测试系统，可以分别执行以下脚本:

##### 第一阶段: 主题生成
```bash
python examples/run_step1_topics.py
```
此命令将生成旅游目的地主题并保存在`outputs/topics`目录中。

##### 第二阶段: 内容和海报生成
```bash
python examples/run_step2_content_posters.py
```
此命令将读取`outputs/topics`目录中的主题，生成内容并创建海报，结果保存在`outputs/content`和`outputs/posters`目录中。

### 仅生成海报示例
如果只想测试海报生成功能，可以使用以下示例:

```bash
python examples/generate_poster.py
```

该脚本默认将使用示例内容生成海报并保存在`outputs/posters`目录。

您也可以指定输入内容和输出路径:
```bash
python examples/generate_poster.py --input "您的旅游内容" --output "您的输出路径.jpg"
```

### 流式处理示例

#### 基本流式输出测试
```bash
python examples/test_stream.py
```
该脚本展示了如何使用三种不同的流式处理方法:
1. 同步流式输出 (`generate_text_stream`)
2. 基于回调的流式输出 (`generate_text_stream_with_callback`)
3. 异步流式输出 (`async_generate_text_stream`)

#### 超时处理测试
```bash
python examples/test_stream_with_timeout_handling.py
```
该脚本演示了如何处理流式生成中的超时情况，包括全局请求超时和流块超时的配置。

#### 并发流式处理
```bash
python examples/concurrent_stream_processing.py
```
该脚本展示了如何使用异步流式处理同时处理多个不同的AI生成任务，包括:
1. 并发处理多个不同提示的任务
2. 顺序与并发处理的性能对比
3. 任务状态监控和异常处理

该示例特别适用于需要同时生成多个旅游内容片段的场景，如同时生成多个目的地的介绍、美食推荐和旅行建议。

### 未来示例
我们将继续添加更多示例，展示如何独立使用系统的各个组件。

### 重要说明
- 这些示例依赖于项目主配置和资源，请确保已正确配置
- 您可能需要调整参数以获得最佳结果
- 如有任何问题，请参阅主文档或提交issue