故障排查

401 Invalid token

确认 Key 是 HKGAI NewAPI 网关的 Key，并与以下地址配套：

https://test-new-api.hkchat.app/v1

moautoai/server/.env 中的旧 HKGAI_KEY 配套 openspeech.hkgai.net，不能直接用于 Qwen 网关。

404 /v1/models

当前网关实测 GET /v1/models 成功，POST /v1/models 可能返回 404。项目会自动尝试另一种方法，并在结果中显示 methodUsed。

Qwen 没有可见正文

设置：

"chat_template_kwargs": {"enable_thinking": false}

并为短回复保留足够的 max_tokens，例如 128～256。

TTS 音色错误

tts-v1 当前使用 male 或 female，不要传 alloy 或讯飞音色资源 ID。

粤语转写错字

这是当前 speech-recognize 的已知限制。保留音频和原始结果，人工修订后再进入翻译或字幕流程。

视频模型测试超时

t2_minimax-h3_bf16_7k2p 属于视频 LLM，不应使用 /v1/chat/completions 测试。视频任务是异步的，创建请求返回 200 只代表已排队，生成耗时可能明显高于 Chat。请在模型详情中点击“视频异步测试”，等待状态变为 completed；任务完成后再下载内容。若任务长时间停留在 queued / processing，先刷新状态并查看详情中的任务编号、HTTP 状态和响应摘要，不要连续重复创建任务。

健康检查

curl -sS http://127.0.0.1:9001/api/health

如果模型目录可用但单个端点失败，应按模型的 supported_endpoint_types 和实际错误继续判断。

模型探测结果

页面的“测试当前 / 测试筛选 / 测试全部”按钮调用 POST /api/models/probe；视频模型的详情页另调用 /api/models/video-task 轮询状态：

可用：对应 Chat、TTS、ASR 请求实际返回成功，或视频任务已成功创建。
不可用：端点返回明确的业务或服务错误。
鉴权失败：401/403，先检查 Key 权限；批量任务会自动停止。
限流：429，等待网关窗口恢复后再手动重试。
超时：网络或队列暂时未完成，不应直接删除模型。
暂无探针：无法从动态元数据判断能力，可在模型详情中手动指定探测端点。视频模型不走批量探针，需使用详情页的异步测试。

Chat 的 token/s 依赖上游返回 usage.completion_tokens。若显示 --，表示网关没有提供 usage 或输出过短；这不是模型不可用。TTS、ASR 只看端点耗时，不使用 token/s。

测试时间与共享结果

探测结果由服务器保存，不依赖浏览器缓存。页面启动时会调用：

GET /api/models/probe-results

如果刷新页面后仍显示“未测试”，先检查服务器上的 data/model-probes.sqlite 是否存在、PM2 进程是否有目录写权限，以及 /api/models/probe-results 是否返回 200。表格中的“测试时间”是上游调用完成时间，不是页面打开时间。

脱敏调试信息

模型详情的“查看脱敏调试信息”只展示允许的请求头和响应头，例如 Content-Type、Accept、上游 Request ID 和限流头。Authorization 只显示“已配置（已隐藏）”；如果需要排查 401/403，结合 HTTP 状态、Key 权限和 PM2 日志判断，不要在日志或截图中粘贴真实请求头。