FlashCoding.AI 文档

外观

故障排查 ​

排障的核心是先把问题缩小：同一个 Key、同一个模型，用最小 HTTP 请求能否成功？如果可以，问题多半在客户端配置或附加参数；如果不可以，再检查网络、鉴权和账户状态。

五分钟排查流程 ​

  1. 查看 FlashCoding.AI 控制台的站内公告，确认是否有已知维护或异常。
  2. 从控制台重新复制模型 ID，不手动猜写。
  3. 用下面的最小请求绕过第三方客户端进行测试。
  4. 根据状态码检查鉴权、路径或限流。
  5. 最小请求成功后，再回到 SDK 或客户端逐项比对。
bash
curl -i https://flashcoding.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-id",
    "messages": [
      {"role": "user", "content": "请只回复：连接成功"}
    ]
  }'

Windows PowerShell 中建议明确运行 curl.exe，避免旧环境里的 curl 别名改变参数含义。

脱敏后再分享

终端历史、curl -v 输出和截图都可能包含完整 Key。发给他人之前，替换为 sk-***，同时移除 Cookie、支付信息和用户数据。

1. 网络与 TLS ​

如果没有收到任何 HTTP 状态码，先检查网络层。

Windows ​

powershell
Resolve-DnsName flashcoding.ai
Test-NetConnection flashcoding.ai -Port 443
curl.exe -I https://flashcoding.ai/

macOS / Linux ​

bash
curl -I https://flashcoding.ai/

常见原因：

  • 公司代理或防火墙拦截目标域名或 443 端口。
  • HTTP_PROXY、HTTPS_PROXY 或客户端代理配置不一致。
  • 系统时间错误导致 TLS 证书校验失败。
  • 容器、云函数或服务器的出口网络与本机不同。
  • DNS 缓存或本地 hosts 记录指向错误地址。

不要通过关闭 TLS 校验来“解决”证书错误。应修正系统时间、代理证书或网络策略。

2. 鉴权 ​

不同协议使用不同请求头：

协议鉴权方式
OpenAI 兼容Authorization: Bearer sk-your-key
Anthropic Messagesx-api-key: sk-your-key
Gemini 原生以控制台说明为准；上游格式通常使用 x-goog-api-key

检查 Key 前后是否有空格、引号或换行。若 Key 曾公开，应立即在控制台撤销并替换，不要继续用它做排障。

3. Base URL 与路径 ​

SDK 配置项通常需要 Base URL，而手写 HTTP 请求需要完整端点：

场景地址示例
OpenAI SDK Base URLhttps://flashcoding.ai/v1
Chat Completions 完整路径https://flashcoding.ai/v1/chat/completions
Responses 完整路径https://flashcoding.ai/v1/responses
Anthropic Messages 完整路径https://flashcoding.ai/v1/messages

如果 SDK 自动追加 /v1，而配置值也包含重复路径，最终会请求 .../v1/v1/... 并得到 404。开启 SDK HTTP 日志，确认它最终访问的 URL。

4. 模型与账户 ​

出现“model not found”、404 或权限错误时：

  1. 从控制台复制完整模型 ID。
  2. 确认当前 Key 属于正确账户和分组。
  3. 确认该模型支持正在使用的协议。
  4. 检查余额、套餐或账户状态是否满足当前调用条件。
  5. 换用控制台确认可用的另一个模型做对照测试。

品牌名不是模型 ID；不同版本、日期后缀和大小写也不一定能互换。

5. 请求体 ​

先把请求缩减到最少字段：

  • OpenAI Chat：只保留 model 和一条 messages。
  • OpenAI Responses：只保留 model 和 input。
  • Anthropic：保留 model、max_tokens 和一条 messages。
  • Gemini：只保留一个 contents / parts 文本块。

最小请求成功后，逐个恢复温度、工具、图片、结构化输出等参数。一次恢复多个字段会让问题难以定位。

还要确保 JSON 本身合法：JSON 不允许注释、尾随逗号、单引号字段名或未转义的控制字符。

6. 第三方客户端 ​

当 curl 成功但客户端失败时，重点检查：

  • 客户端选择的供应商协议是否正确。
  • Base URL 字段需要域名、/v1，还是完整端点。
  • 客户端是否暗中覆盖模型名或附加不兼容参数。
  • 环境变量是否被旧配置覆盖。
  • 客户端版本是否支持自定义 Base URL。
  • 客户端内置代理与系统代理是否冲突。

可临时开启客户端调试日志查看最终 URL、状态码和错误正文，但分享日志前必须脱敏。

7. 流式输出异常 ​

表现为长时间无内容、输出半途停止或 JSON 解析错误时：

  • 用非流式请求验证模型和请求体是否正常。
  • curl 使用 -N，避免客户端缓冲事件流。
  • 确认反向代理没有缓冲或过早关闭长连接。
  • 按 SSE 事件解析，不要把每个网络分片当成完整 JSON。
  • 为首字节等待和整个流分别设置合理超时。

流式连接中断时，已生成内容可能不完整。业务需要避免重复时，应保存已接收内容和业务请求 ID。

8. 超时与慢请求 ​

不要只设置一个很短的统一超时。连接建立、等待首字节、持续读取和整个任务适合分别限制。图片或复杂生成通常比短文本请求更慢，但具体时间不能作为固定承诺。

发生超时时先判断服务端是否可能已经处理请求，再决定是否重试。无限重试既会放大故障，也可能产生重复用量。

9. 仍然无法解决 ​

联系支持前准备：发生时间和时区、协议、请求路径、模型 ID、状态码、脱敏后的错误正文、SDK 与版本、最小复现请求，以及响应头中的请求标识（若存在）。

通过联系支持页面找到当前官方渠道。不要提交完整 Key 或未经脱敏的业务数据。