team-api/scripts/relay_stress_test.md

Relay 层压力测试说明

对 /v1/chat/completions（OpenAI 兼容代理端点）进行压力测试，验证 relaykit 转换层在高并发下的稳定性与性能，并与旧 relay 代码路径对照。

适用阶段 6.4。本测试需要可访问的运行中服务 + 可用的上游渠道/Key，在本地开发环境无法真正执行；以下为执行手册。

前置

• 服务已启动（gf run 或部署实例），监听如 http://localhost:8080
• 一个有效的租户 API Key（RELAY_API_KEY）
• 目标模型对应的上游渠道已配置且健康
• 已安装 wrk

基础压测

# 压 OpenAI 兼容模型（OpenAI 透传路径，无转换）
RELAY_API_KEY=sk-xxx RELAY_MODEL=gpt-4 \
  wrk -t4 -c100 -d30s --latency -s scripts/wrk_relay.lua http://localhost:8080

# 压 Claude（OpenAI↔Claude 转换路径）
RELAY_API_KEY=sk-xxx RELAY_MODEL=claude-3-5-sonnet \
  wrk -t4 -c100 -d30s --latency -s scripts/wrk_relay.lua http://localhost:8080

# 压流式
RELAY_API_KEY=sk-xxx RELAY_MODEL=gemini-2.0-flash RELAY_STREAM=1 \
  wrk -t4 -c100 -d30s --latency -s scripts/wrk_relay.lua http://localhost:8080

参数：-t4 4 线程，-c100 100 并发连接，-d30s 持续 30 秒，--latency 输出延迟分布。

新旧路径对照（核心目的）

relaykit 默认关闭（relaykit.enabled: false），所有请求走旧 relay 代码。对照步骤：

1. 旧路径基线：保持 relaykit.enabled: false，重启服务，压测并记录指标。
2. relaykit 路径：在 manifest/config/config.yaml 设置 relaykit.enabled: true 并把目标供应商加入 providers（如 ["claude"]），重启服务，相同参数再压一次。
3. 对比：两次的 QPS、P95/P99 延迟、错误率、错误日志。

验收指标（阶段 6.4）

指标	目标
QPS	不低于旧路径的 95%
P95 延迟增加	< 10ms（转换开销）
P99 延迟增加	< 20ms
错误率	< 0.1%
转换成功率（relaykit 路径）	≥ 99.5%（见 GetRelaykitConverterMetrics）

转换层本身开销见 Benchmark（relaykit/relayconvert/internal/*/benchmark_test.go）：单次请求转换 < 1µs 级、< 1KB 分配，远低于上游模型推理耗时，因此对端到端 QPS/延迟的影响应可忽略。

观测

• monitor.GetRelaykitConverterMetrics()：转换器累计成功/失败/平均耗时/错误率（relaykit.enabled=true 时才有数据）
• 服务日志 [relaykit] 前缀：转换失败回退旧路径的告警
• 错误率 / 延迟超阈值 → 参见 docs/relaykit-gray-release-runbook.md 回滚。