TravelContentCreator/docs/streaming.md

# 流式输出处理功能

TravelContentCreator 现在支持三种不同的流式输出处理方法，让您能够更灵活地处理 AI 模型生成的文本内容。这些方法都在 `AI_Agent` 类中实现，可以根据不同的使用场景进行选择。

## 为什么需要流式处理？

流式处理（Streaming）相比于传统的一次性返回完整响应的方式有以下优势：

1. **实时性**：内容生成的同时即可开始处理，无需等待完整响应
2. **用户体验更好**：可以实现"打字机效果"，让用户看到文本逐步生成的过程
3. **更早检测错误**：可以在响应生成过程中及早发现问题
4. **长文本处理更高效**：特别适合生成较长的内容，避免长时间等待

## 流式处理方法

`AI_Agent` 类提供了三种不同模式的流式处理方法：

### 1. 同步流式响应 (generate_text_stream)

这种方法虽然使用了流式 API 连接，但会将所有的输出整合后一次性返回，适合简单的 API 调用。

```python
def generate_text_stream(self, system_prompt, user_prompt, temperature, top_p, presence_penalty):
    """
    生成文本内容（使用流式API但返回完整响应）
    
    Args:
        system_prompt: 系统提示词
        user_prompt: 用户提示词
        temperature: 温度参数
        top_p: 核采样参数
        presence_penalty: 存在惩罚参数
        
    Returns:
        str: 完整的生成文本
    """
```

使用示例：

```python
agent = AI_Agent(base_url, model_name, api_key, timeout=30, stream_chunk_timeout=10)
result = agent.generate_text_stream(system_prompt, user_prompt, 0.7, 0.9, 0.0)
print(result)  # 输出完整的生成结果
```

### 2. 回调式流式响应 (generate_text_stream_with_callback)

这种方法使用回调函数来处理流中的每个文本块，非常适合实时显示、分析或保存过程数据，更加灵活。

```python
def generate_text_stream_with_callback(self, system_prompt, user_prompt, 
                                     callback_fn, temperature=0.7, top_p=0.9, 
                                     presence_penalty=0.0):
    """
    生成文本流并通过回调函数处理每个块
    
    Args:
        system_prompt: 系统提示词
        user_prompt: 用户提示词
        callback_fn: 处理每个文本块的回调函数，接收(content, is_last, is_timeout, is_error, error)参数
        temperature: 温度参数
        top_p: 核采样参数
        presence_penalty: 存在惩罚参数
        
    Returns:
        str: 完整的响应文本
    """
```

回调函数应符合以下格式：

```python
def my_callback(content, is_last=False, is_timeout=False, is_error=False, error=None):
    """
    处理流式响应的回调函数
    
    Args:
        content: 文本块内容
        is_last: 是否为最后一个块
        is_timeout: 是否发生超时
        is_error: 是否发生错误
        error: 错误信息
    """
    if content:
        print(content, end="", flush=True)  # 实时打印
        
    # 处理特殊情况
    if is_last:
        print("\n完成生成")
        if is_timeout:
            print("警告: 响应流超时")
        if is_error:
            print(f"错误: {error}")
```

使用示例：

```python
agent = AI_Agent(base_url, model_name, api_key, timeout=30, stream_chunk_timeout=10)
result = agent.generate_text_stream_with_callback(
    system_prompt, 
    user_prompt, 
    my_callback,  # 传入回调函数
    temperature=0.7, 
    top_p=0.9, 
    presence_penalty=0.0
)
```

### 3. 异步流式响应 (async_generate_text_stream)

这种方法基于 `asyncio`，返回一个异步生成器，非常适合与其他异步操作集成，例如在异步网络应用中使用。

```python
async def async_generate_text_stream(self, system_prompt, user_prompt, temperature=0.7, top_p=0.9, presence_penalty=0.0):
    """
    异步生成文本流
    
    Args:
        system_prompt: 系统提示词
        user_prompt: 用户提示词
        temperature: 温度参数
        top_p: 核采样参数
        presence_penalty: 存在惩罚参数
        
    Yields:
        str: 生成的文本块
        
    Raises:
        Exception: 如果API调用在所有重试后失败
    """
```

使用示例：

```python
async def demo_async_stream():
    agent = AI_Agent(base_url, model_name, api_key, timeout=30, stream_chunk_timeout=10)
    
    full_response = ""
    try:
        # 使用异步生成器
        async for chunk in agent.async_generate_text_stream(
            system_prompt, 
            user_prompt, 
            temperature=0.7,
            top_p=0.9,
            presence_penalty=0.0
        ):
            print(chunk, end="", flush=True)  # 实时显示
            full_response += chunk
            
            # 这里可以同时执行其他异步操作
            # await some_other_async_operation()
            
    except Exception as e:
        print(f"错误: {e}")
    finally:
        agent.close()

# 在异步环境中运行
asyncio.run(demo_async_stream())
```

## 超时处理

所有流式处理方法都支持两种超时设置：

1. **全局请求超时**：控制整个API请求的最大持续时间
2. **流块超时**：控制接收连续两个数据块之间的最大等待时间

在创建 `AI_Agent` 实例时设置：

```python
agent = AI_Agent(
    base_url="your_api_base_url",
    model_name="your_model_name",
    api="your_api_key",
    timeout=60,            # 整体请求超时(秒)
    max_retries=3,         # 最大重试次数
    stream_chunk_timeout=10 # 流块超时(秒)
)
```

## 完整示例

我们提供了一个完整的示例脚本，演示所有三种流式处理方法的使用：

```
examples/test_stream.py
```

运行方式：

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

这将依次演示三种流式处理方法，并展示它们的输出和性能差异。

## 在WebUI中的应用

TravelContentCreator的WebUI已经集成了基于回调的流式处理，实现了生成内容的实时显示，大大提升了用户体验，特别是在生成长篇内容时。

## 在自定义项目中使用

如果您想在自己的项目中使用这些流式处理功能，只需导入 `AI_Agent` 类并按照上述示例使用相应的方法即可。所有流式处理方法都内置了完善的错误处理和重试机制，提高了生产环境中的稳定性。