【免费下载链接】splashA local inference engine for Apple silicon, built around the model.项目地址https://gitcode.com/gh_mirrors/splash20/splash点击查看免费下载Splash 是一个为 Apple silicon 打造的本地推理引擎a local inference engine for Apple silicon提供 OpenAI 兼容的 HTTP API可像调用云端大模型一样调用自己 Mac 上的模型。本文带你快速看懂 Splash 返回的400、413、503等常见 HTTP 状态码到底意味着什么以及引擎崩溃时如何用crash trace一键回放定位问题——一张速查表 三步排障法新手也能照着解决。 一张表速查Splash 常见错误码状态码常见code一句话解释400invalid_request_error请求体或字段格式不对400context_length_exceededprompt 超出上下文窗口400capacity_exhausted显存/内存不够请求装不下401authentication_errorAPI key 缺失或错误404not_found路径或资源不存在413request_too_large请求体超过--max-request-size上限415—Content-Type 不是application/json422unprocessable_entity仅/v1/systemoneFastAPI 风格字段校验失败429rate_limit_error触发限流500engine_failed引擎进程内部错误503frontend_overloaded队列满了稍后重试503runtime_unavailable引擎意外退出正在重启503server_shutdown服务正在关闭504request_timeout请求超时529—/v1/systemone路径上 503 的等价返回 所有503/529都是可重试状态响应会带Retry-After头客户端按其建议延时重试即可逻辑见 server/errors.py。不同 API 路径的错误方言略有差异OpenAI 兼容路径返回{error: {...}}Anthropic 兼容路径返回{type: error, error: {...}}/v1/systemone则模仿 FastAPI 服务422 逐字段detail。映射规则都在 server/errors.py 中定义。 400 Bad Request请求本身有问题400 意味着服务器根本没打算处理这个请求重试原样请求没有用必须改请求或改服务配置。三种最常见场景1. prompt 超出上下文窗口context_length_exceeded报错信息固定为prompt exceeds the context windowserver/errors.py。Anthropic 兼容路径会额外给出 token 明细例如prompt is too long: 40961 tokens 32768 maximum input tokens。✅怎么办缩短 prompt删掉超长系统提示、压缩对话历史、裁剪粘贴的大段代码若带图片图片 token 会单独计数报错会注明(image tokens alone; text not yet counted)可先用更小/更少的图片需要长文本时用更大的--max-context启动 Splash前提是内存足够。2. 内存装不下capacity_exhausted报错信息会直接告诉你解法server/backend.pythe request does not fit in the memory this server may use, even after every cached prefix was evicted; restart the server with a larger--max-memoryor a smaller--max-context✅怎么办重启服务时调大--max-memory或调小--max-context二选一通常先调小上下文更快见效。3. JSON 或字段不合法invalid_request_error典型原因请求体不是合法 JSON信息为invalid JSON request body空 body、缺Content-Length、Transfer-Encoding编码这些都会直接 400见 server/server.py采样参数、max_tokens等字段取值非法。✅怎么办先在本地用jq或编辑器校验 JSON再用最小 payload 逐字段二分定位问题字段。 413 Request Too Large请求体超限错误信息形如request body is 134217728 bytes; limit is 128000000 bytes (--max-request-size)对应的判断逻辑在 server/server.py。关键参数是启动时的--max-request-size默认 128MDEFAULT_MAX_REQUEST_BYTESserver/serve_options.py所有并发请求共享一份输入预算max(512M, 2 × 单请求上限)所以单请求调得太大也会挤压并发常见触发场景一次请求里塞了多张未压缩的高清图base64 后体积会膨胀约 1.33 倍。✅最快配置方法先用curl -I或打印Content-Length确认请求体实际大小临时调大启动参数例如--max-request-size 256M长期方案客户端压缩/降采样图片或分批发送。⏳ 503 Service Unavailable服务暂时不行503 是唯一值得原样重试的状态码。Splash 中有四类 503见 server/backend.pycode含义处理建议frontend_overloaded同时在跑 排队的请求数超过--queue-size按Retry-After退避重试或调大队列runtime_busy引擎正忙如约束 mask 计算竞争短暂等待后重试runtime_unavailable引擎意外停止、正在自动重启等几秒重试反复出现 → 查 crash traceserver_shutdown你触发了服务关闭等待关闭完成即可注意/v1/systemone路径上同样的过载会返回529而不是 503SystemOneErrors的特例server/errors.py排障时两者等价看待。✅调优入口--queue-size同时放行的请求数默认值内超出的请求直接吃 503、--max-memory、--request-timeout参数说明见 server/serve_options.py。先确认引擎是否真的活着GET /ready会直接返回 200ready或 503unavailableGET /status和GET /metrics还能看到引擎状态与 Prometheus 指标是排障的第一站。 引擎崩溃了怎么办crash trace 完整用法Splash 的 HTTP 服务层和原生推理引擎是两个进程引擎崩溃时服务会自动重启引擎而崩溃前最后一批客户端→引擎的协议帧会被环形缓冲区自动记录下来落成一份crash trace文件——这是定位为什么崩的关键证据。1. 文件在哪里~/Library/Logs/Splash/crash/ └── splash-crash-g{generation}-{时间戳}.json由 server/runtime.py 在引擎进程异常结束时自动 dump无需手动开启目录只保留最近 4 个文件、合计 64MB更早的会被自动清理server/crash_trace.py内存中的环形缓冲区上限是 512 帧 / 16MB超出的最旧帧会被丢弃——所以尽早回放。2. 怎么读这份 JSON{ schema_version: 1, created_at: 2026-10-12T08:00:00.00000000:00, generation: 3, pid: 4242, process_returncode: 134, error: { type: EngineUnhealthy, message: engine exited unexpectedly }, last_status_json: {...崩溃前最后一次状态快照...}, frames: [ { offset_micros: 0, direction: client_to_engine, frame_base64: ... } ], omitted_frames: 0 }排障四步看process_returncode负数通常是信号如-11 SIGSEGVerror.type/messagePython 侧观察到的失败类型last_status_json崩溃前引擎的自我状态模型、请求、内存水位frames崩溃前实际发往引擎的每一个帧——回放就是靠它。3. 本地回放replaySplash 内置了确定性回放器把录制帧按原始时间偏移喂给一个新引擎进程请求超时时间戳会自动重打server/crash_trace.pypython -m server.crash_trace ~/Library/Logs/Splash/crash/splash-crash-g3-xxxx.json若引擎复现崩溃返回码与现场一致问题可稳定复现若回放顺利跑完说明可能是资源/并发相关的偶发问题可结合last_status_json里的内存水位分析若 trace 中omitted_frames 0且省略的恰是发给引擎的帧回放会直接报cannot be replayed——说明关键输入过大16MB未录下此时只能依赖error与last_status_json。回放器的行为边界超时、EOF、SIGTERM 兜底都有完整测试覆盖可参考 dev/tests/server/test_crash_trace.py。 日常巡检5 分钟健康检查清单curl http://127.0.0.1:port/health→ 进程活着curl http://127.0.0.1:port/ready→ 引擎就绪503 未就绪curl http://127.0.0.1:port/status→ 模型、队列、内存概览翻一下~/Library/Logs/Splash/crash/有没有新 trace有异常再python -m server.crash_trace trace回放。❓ 高频疑问 FAQQ1503 和 500 有什么区别要不要都重试503frontend_overloaded/runtime_unavailable等是可重试的临时状态带Retry-After500engine_failed、runtime_error通常指向引擎内部错误原样重试大概率无效优先看 crash trace 和服务日志。Q2我把--max-request-size调大后还是 413确认启动命令真的生效了旧进程没重启并且检查是不是被共享输入预算卡住——它等于max(512M, 2×单请求上限)单请求上限与并发会互相制约。Q3trace 里frames很多但direction都是client_to_engine正常吗正常。回放只重放客户端发给引擎的帧引擎的响应帧不参与回放见 server/crash_trace.py。Q4Anthropic 路径报错格式和 OpenAI 路径不一样是的Splash 按各家的方言作答OpenAI 风格{error: {...}}、Anthropic 风格{type:error, ...}、/v1/systemone为 FastAPI 风格 422。同一状态码在三个路径上的type命名也不同对照 server/errors.py 即可。 小结与延伸阅读场景记忆点400改请求上下文超限就缩短内存不够就调--max-memory/--max-context413调--max-request-size先压缩图片503 / 529可重试看Retry-After反复出现查--queue-size与 crash trace崩溃~/Library/Logs/Splash/crash/→ 读 JSON →python -m server.crash_trace回放错误分类与状态映射server/errors.py503/400/504 的错误码翻译层server/backend.py请求体大小与 413 判断server/server.pycrash trace 环形缓冲与回放实现server/crash_trace.py启动参数全集server/serve_options.py引擎侧崩溃处理与 dump 时机server/runtime.py性能基线判断是否异常退化的参照docs/performance.md项目总览README.md赞分享【免费下载链接】splashA local inference engine for Apple silicon, built around the model.项目地址https://gitcode.com/gh_mirrors/splash20/splash点击查看免费下载相关推荐OpenLLMetry故障排查指南常见错误与解决方案速查手册OpenLLMetry故障排查指南常见错误与解决方案速查手册 还在为LLM应用的可观测性监控问题头疼吗OpenLLMetry作为基于OpenTelemetrLLMOps可观测性PathOfBuilding终极故障排查指南快速解决常见错误PathOfBuilding终极故障排查指南快速解决常见错误 PathOfBuildingPoB是流放之路Path of Exile玩家最常用的BD桌面应用快速备份QQ空间历史说说GetQzonehistory 新手完整指南快速备份QQ空间历史说说GetQzonehistory 新手完整指南 GetQzonehistory 是一个把你自己QQ空间里的历史说说抓取下来并导出为Ex网页爬虫数据分析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考