故障排除

# AI Gateway 故障排除 ## 常见错误 | 错误 | 原因 | 修复 | |-------|-------|-----| | 401 | 缺少 `cf-aig-authorization` 请求头 | 添加带有 CF API 令牌的请求头 | | 403 | 无效的提供商密钥 / BYOK 过期 | 在控制面板检查提供商密钥 | | 429 | 超出速率限制 | 增加限制或实现退避策略 | ### 401 修复 typescript const client = new OpenAI({ baseURL: `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/openai`, defaultHeaders: { 'cf-aig-authorization': `Bearer ${CF_API_TOKEN}` } }); ### 429 重试模式 typescript async function requestWithRetry(fn, maxRetries = 3) { for (let i = 0; i < maxRetries; i++) { try { return await fn(); } catch (e) { if (e.status === 429 && i setTimeout(r, Math.pow(2, i) * 1000)); continue; } throw e; } } } ## 注意事项 | 问题 | 现实 | |-------|---------| | 元数据限制 | 最多 5 个条目，仅限扁平结构 (无嵌套) | | 缓存键冲突 | 每个预期响应使用唯一键 | | BYOK + 统一计费 | 互斥 | | 速率限制范围 | 基于网关，而非基于用户 (使用动态路由实现按用户限流) | | 日志延迟 | 30-60 秒为正常 | | 流式传输 + 缓存 | **不兼容** | | 模型名称 (统一 API) | 需要前缀：`openai/gpt-4o`，而非 `gpt-4o` | ## 缓存不工作 **原因：** - 请求参数不同 (temperature 等) - 启用了流式传输 - 设置中禁用了缓存 **检查：** `response.headers.get('cf-aig-cache-status')` → HIT 或 MISS ## 日志未显示 1. 检查是否启用了日志记录：控制面板 → Gateway → Settings 2. 移除 `cf-aig-collect-log: false` 请求头 3. 等待 30-60 秒 4. 检查日志限制 (默认 10M) ## 调试 bash # 测试连接 curl -v https://gateway.ai.cloudflare.com/v1/{account}/{gateway}/openai/models -H "Authorization: Bearer $OPENAI_KEY" -H "cf-aig-authorization: Bearer $CF_TOKEN" typescript // 检查响应头 console.log('Cache:', response.headers.get('cf-aig-cache-status')); console.log('Request ID:', response.headers.get('cf-ray')); ## 分析 控制面板 → AI Gateway → 选择网关 **指标：** 请求数、Token 数、延迟 (p50/p95/p99)、缓存命中率、成本 **日志过滤器：** `status: error`, `provider: openai`, `cost > 0.01`, `duration > 1000` **导出：** Logpush 到 S3/GCS/Datadog/Splunk