Skip to content

errors.md

Latest commit

 

History

History
91 lines (72 loc) · 6.02 KB

errors.md

File metadata and controls

91 lines (72 loc) · 6.02 KB
Raw

pymss Server 错误格式

pymss server 返回 JSON（JavaScript Object Notation，文本对象表示格式）错误对象。客户端可通过 HTTP（HyperText Transfer Protocol，超文本传输协议）状态码判断错误大类，并通过 error.code 执行业务分支处理。

错误对象格式如下：

{
  "error": {
    "message": "Model 'foo' is not loaded by this process.",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

下表说明错误对象字段。error.code 是面向客户端处理逻辑的稳定字段。

字段 说明
error.message 可读错误信息
error.type 错误类别，取值包括 invalid_request_error 和 server_error
error.param 相关参数名；无明确参数时为 null
error.code 稳定错误码

错误码

下表列出 server 代码中显式返回的错误码。type=invalid_request_error 表示请求、状态或资源限制导致的错误；type=server_error 表示下载、模型加载、推理或响应编码过程中的 server 侧失败。

HTTP code type 说明
400 invalid_request invalid_request_error JSON 结构无效、字段类型错误或 Content-Length 非法
400 invalid_query_parameter invalid_request_error 二进制 PCM 请求的 query 参数格式无效
400 invalid_model invalid_request_error model 为空，或模型不支持加载和推理
404 model_not_found invalid_request_error model 未匹配当前已加载模型的 catalog name，或 catalog 中不存在
400 invalid_audio_format invalid_request_error format 必须为 pcm_f32le 或 pcm_s16le
400 invalid_sample_rate invalid_request_error 请求 sample rate 与模型 sample rate 不一致
400 invalid_channel_count invalid_request_error channels 必须为 1 或 2
400 invalid_base64 invalid_request_error JSON input.data 必须是合法 base64
400 empty_audio invalid_request_error decoded PCM bytes 为空
400 invalid_audio_length invalid_request_error PCM bytes 长度无法按 format 和 channels 对齐
400 invalid_audio_data invalid_request_error pcm_f32le 输入包含 NaN（Not a Number，非数字）或 Inf（Infinity，无穷大）
400 missing_audio_metadata invalid_request_error 二进制 PCM 请求缺少 format、sample_rate 或 channels
415 unsupported_content_type invalid_request_error Content-Type 必须为 application/json 或 application/octet-stream
400 invalid_stem invalid_request_error 请求了模型不支持的 stem，或 stems 类型非法
400 invalid_response_format invalid_request_error response_format 必须为 json 或 zip
400 invalid_output_audio_format invalid_request_error output_audio_format 不受支持，或 JSON 响应请求了非 pcm_f32le 输出
413 request_too_large invalid_request_error 请求体或音频时长超过 server 限制
401 invalid_api_key invalid_request_error Bearer token（Bearer 令牌）缺失或不匹配
429 server_overloaded invalid_request_error 推理队列已满
409 model_operation_in_progress invalid_request_error 模型加载、卸载或切换正在进行
409 model_download_in_progress invalid_request_error 模型下载正在进行
503 model_not_loaded invalid_request_error 当前没有已加载模型
400 invalid_inference_parameter invalid_request_error 运行时加载参数未知、格式非法，或当前模型配置不支持
400 invalid_download_source invalid_request_error 下载源或下载 endpoint 非法
504 separation_timeout invalid_request_error 推理超过 --request-timeout-seconds
500 model_unload_failed server_error 卸载当前模型失败
500 model_load_failed server_error 加载请求模型失败
500 model_download_failed server_error 下载模型失败
500 separation_failed server_error 推理或响应编码过程失败
500 webui_assets_missing server_error 启用了 WebUI（Web User Interface，浏览器用户界面），但构建后的 WebUI 静态资源缺失

资源限制相关错误

资源限制由启动参数控制。下表列出限制项和对应错误。

限制项 参数 错误
HTTP body 大小 --max-request-bytes 超过限制时返回 413 request_too_large
decoded PCM 时长 --max-audio-seconds 超过限制时返回 413 request_too_large；参数为 0 时关闭该时长限制
推理队列长度 --max-queue-size 正在处理和等待处理的请求数量达到限制时返回 429 server_overloaded
单请求推理耗时 --request-timeout-seconds 超过限制时返回 504 separation_timeout；参数为 0 时关闭该超时限制

推理执行由单模型锁串行化。--max-queue-size 统计正在处理和等待处理的请求数量，因此一个请求进入推理锁等待区后仍占用队列额度。

模型操作冲突

模型加载或切换期间，server 将公开状态中的已加载模型置空，并将 /health 中的 model_loading 设为 true。该状态下，推理请求返回 409 model_operation_in_progress，/v1/models 返回空列表。

模型下载、模型加载和模型切换互斥。模型下载期间，另一个下载请求返回 409 model_download_in_progress，加载请求返回 409 model_download_in_progress。模型加载或切换期间，下载请求返回 409 model_operation_in_progress。

鉴权错误

API key（Application Programming Interface key，接口访问密钥）只作用于 /v1/* 端点。server 设置 --api-key 后，客户端必须发送 Bearer token（Bearer 令牌）：

Authorization: Bearer <api-key>

令牌缺失或不匹配时，/v1/* 端点返回 401 invalid_api_key。/health 不要求鉴权。