209 lines
6.3 KiB
Markdown
209 lines
6.3 KiB
Markdown
# 流式输出处理功能
|
||
|
||
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` 类并按照上述示例使用相应的方法即可。所有流式处理方法都内置了完善的错误处理和重试机制，提高了生产环境中的稳定性。 |