docs/streaming-modes.md

# 流式处理模式详解

本文档详细介绍 AI Studio Proxy API 的三层流式响应获取机制，包括各种模式的工作原理、配置方法和适用场景。

## 🔄 三层响应获取机制概览

项目实现了三层响应获取机制，确保高可用性和最佳性能：

```
请求 → 第一层: 集成流式代理 → 第二层: 外部Helper服务 → 第三层: Playwright页面交互
```

### 工作原理

1. **优先级处理**: 按层级顺序尝试获取响应
2. **自动降级**: 上层失败时自动降级到下层
3. **性能优化**: 优先使用高性能方案
4. **完整后备**: 确保在任何情况下都能获取响应

## 🚀 第一层: 集成流式代理 (Stream Proxy)

### 概述
集成流式代理是默认启用的高性能响应获取方案，提供最佳的性能和稳定性。

### 技术特点
- **独立进程**: 运行在独立的进程中，不影响主服务
- **直接转发**: 直接转发请求到 AI Studio，减少中间环节
- **流式处理**: 原生支持流式响应，实时传输数据
- **高性能**: 最小化延迟，最大化吞吐量

### 配置方式

#### .env 文件配置 (推荐)
```env
# 启用集成流式代理
STREAM_PORT=3120

# 禁用集成流式代理
STREAM_PORT=0
```

#### 命令行配置
```bash
# 启用 (默认端口 3120)
python launch_camoufox.py --headless --stream-port 3120

# 自定义端口
python launch_camoufox.py --headless --stream-port 3125

# 禁用
python launch_camoufox.py --headless --stream-port 0
```

### 工作流程
1. 主服务接收 API 请求
2. 将请求转发到集成流式代理 (端口 3120)
3. 流式代理直接与 AI Studio 通信
4. 实时流式返回响应数据
5. 主服务转发响应给客户端

### 适用场景
- **日常使用**: 提供最佳性能体验
- **生产环境**: 稳定可靠的生产部署
- **高并发**: 支持多用户同时使用
- **流式应用**: 需要实时响应的应用

## 🔧 第二层: 外部 Helper 服务

### 概述
外部 Helper 服务是可选的备用方案，当集成流式代理不可用时启用。

### 技术特点
- **外部服务**: 独立部署的外部服务
- **认证依赖**: 需要有效的认证文件
- **灵活配置**: 支持自定义端点
- **备用方案**: 作为流式代理的备用

### 配置方式

#### .env 文件配置
```env
# 配置 Helper 服务端点
GUI_DEFAULT_HELPER_ENDPOINT=http://your-helper-service:port

# 或留空禁用
GUI_DEFAULT_HELPER_ENDPOINT=
```

#### 命令行配置
```bash
# 启用 Helper 服务
python launch_camoufox.py --headless --helper 'http://your-helper-service:port'

# 禁用 Helper 服务
python launch_camoufox.py --headless --helper ''
```

### 认证要求
- **认证文件**: 需要 `auth_profiles/active/*.json` 文件
- **SAPISID Cookie**: 从认证文件中提取必要的认证信息
- **有效性检查**: 自动验证认证文件的有效性

### 工作流程
1. 检查集成流式代理是否可用
2. 如果不可用，检查 Helper 服务配置
3. 验证认证文件的有效性
4. 将请求转发到外部 Helper 服务
5. Helper 服务处理请求并返回响应

### 适用场景
- **特殊环境**: 需要特定网络环境的部署
- **自定义服务**: 使用自己开发的 Helper 服务
- **备用方案**: 当集成代理不可用时的备选
- **分布式部署**: Helper 服务独立部署的场景

## 🎭 第三层: Playwright 页面交互

### 概述
Playwright 页面交互是最终的后备方案，通过浏览器自动化获取响应。

### 技术特点
- **浏览器自动化**: 使用 Camoufox 浏览器模拟用户操作
- **完整参数支持**: 支持所有 AI Studio 参数
- **反指纹检测**: 使用 Camoufox 降低检测风险
- **最终后备**: 确保在任何情况下都能工作

### 配置方式

#### .env 文件配置
```env
# 禁用前两层，强制使用 Playwright
STREAM_PORT=0
GUI_DEFAULT_HELPER_ENDPOINT=

# 浏览器配置
LAUNCH_MODE=headless
DEFAULT_CAMOUFOX_PORT=9222
```

#### 命令行配置
```bash
# 纯 Playwright 模式
python launch_camoufox.py --headless --stream-port 0 --helper ''

# 调试模式 (有头浏览器)
python launch_camoufox.py --debug
```

### 参数支持
Playwright 模式支持完整的 AI Studio 参数控制：

- **基础参数**: `temperature`, `max_output_tokens`, `top_p`
- **停止序列**: `stop` 参数
- **思考预算**: `reasoning_effort` 参数
- **工具调用**: `tools` 参数 (Google Search 等)
- **URL上下文**: `ENABLE_URL_CONTEXT` 配置

### 工作流程
1. 检查前两层是否可用
2. 如果都不可用，启用 Playwright 模式
3. 在 AI Studio 页面设置参数
4. 发送消息到聊天界面
5. 通过编辑/复制按钮获取响应
6. 解析并返回响应数据

### 适用场景
- **调试模式**: 开发和调试时使用
- **参数精确控制**: 需要精确控制所有参数
- **首次认证**: 获取认证文件时使用
- **故障排除**: 当其他方式都失败时的最终方案

## ⚙️ 模式选择和配置

### 推荐配置

#### 生产环境
```env
# 优先使用集成流式代理
STREAM_PORT=3120
GUI_DEFAULT_HELPER_ENDPOINT=
LAUNCH_MODE=headless
```

#### 开发环境
```env
# 启用调试日志
DEBUG_LOGS_ENABLED=true
STREAM_PORT=3120
LAUNCH_MODE=normal
```

#### 调试模式
```env
# 强制使用 Playwright，启用详细日志
STREAM_PORT=0
GUI_DEFAULT_HELPER_ENDPOINT=
DEBUG_LOGS_ENABLED=true
TRACE_LOGS_ENABLED=true
LAUNCH_MODE=normal
```

### 性能对比

| 模式 | 延迟 | 吞吐量 | 参数支持 | 稳定性 | 适用场景 |
|------|------|--------|----------|--------|----------|
| 集成流式代理 | 最低 | 最高 | 基础 | 最高 | 生产环境 |
| Helper 服务 | 中等 | 中等 | 取决于实现 | 中等 | 特殊环境 |
| Playwright | 最高 | 最低 | 完整 | 中等 | 调试开发 |

### 故障排除

#### 集成流式代理问题
- 检查端口是否被占用
- 验证代理配置
- 查看流式代理日志

#### Helper 服务问题
- 验证认证文件有效性
- 检查 Helper 服务可达性
- 确认 SAPISID Cookie

#### Playwright 问题
- 检查浏览器连接状态
- 验证页面加载状态
- 查看浏览器控制台错误

## 🔍 监控和调试

### 日志配置
```env
# 启用详细日志
DEBUG_LOGS_ENABLED=true
TRACE_LOGS_ENABLED=true
SERVER_LOG_LEVEL=DEBUG
```

### 健康检查
访问 `/health` 端点查看各层状态：
```json
{
  "status": "healthy",
  "playwright_ready": true,
  "browser_connected": true,
  "page_ready": true,
  "worker_running": true,
  "queue_length": 0,
  "stream_proxy_status": "running"
}
```

### 实时监控
- Web UI 的"服务器信息"标签页
- WebSocket 日志流 (`/ws/logs`)
- 队列状态端点 (`/v1/queue`)

这种三层机制确保了系统的高可用性和最佳性能，为不同的使用场景提供了灵活的配置选项。