docs/streaming-modes.md

流式处理模式详解

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

🔄 三层响应获取机制概览

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

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

工作原理

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

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

概述

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

技术特点

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

配置方式

.env 文件配置 (推荐)

# 启用集成流式代理
STREAM_PORT=3120

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

命令行配置

# 启用 (默认端口 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 文件配置

# 配置 Helper 服务端点
GUI_DEFAULT_HELPER_ENDPOINT=http://your-helper-service:port

# 或留空禁用
GUI_DEFAULT_HELPER_ENDPOINT=

命令行配置

# 启用 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 文件配置

# 禁用前两层，强制使用 Playwright
STREAM_PORT=0
GUI_DEFAULT_HELPER_ENDPOINT=

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

命令行配置

# 纯 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. 解析并返回响应数据

适用场景

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

⚙️ 模式选择和配置

推荐配置

生产环境

# 优先使用集成流式代理
STREAM_PORT=3120
GUI_DEFAULT_HELPER_ENDPOINT=
LAUNCH_MODE=headless

开发环境

# 启用调试日志
DEBUG_LOGS_ENABLED=true
STREAM_PORT=3120
LAUNCH_MODE=normal

调试模式

# 强制使用 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 问题

• 检查浏览器连接状态
• 验证页面加载状态
• 查看浏览器控制台错误

🔍 监控和调试

日志配置

# 启用详细日志
DEBUG_LOGS_ENABLED=true
TRACE_LOGS_ENABLED=true
SERVER_LOG_LEVEL=DEBUG

健康检查

访问 /health 端点查看各层状态：

{
  "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)

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