mcpField
M
model-debugging

model-debugging

github.com/pollinations云与 DevOps5.3k69 次安装今天更新
代码仓库

关于 model-debugging

用于诊断 Pollinations 服务中模型线上故障的仓库技能，指导工程师追踪请求、检查可观测性数据并汇报证据，同时注意敏感数据保护。

主要功能

  1. 01追踪请求经过 Workers 和提供方的路径
  2. 02检查健康与错误观测数据
  3. 03执行有界的生产 SQL 查询
  4. 04按用户和请求格式对比故障
  5. 05使用针对性错误报告脚本

适用场景

  1. 01调查模型错误或服务中断
  2. 02检查回退机制是否掩盖主路径故障
  3. 03分析超时和流式响应问题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/pollinations/pollinations --skill model-debugging

安装后在 Claude Code 中输入/model-debugging确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

scripts/
check-user-errors.sh
find-402-users.sh
find-403-users.sh
find-500-errors.sh
tinybird-query.sh

详细介绍

模型调试

诊断线上问题前，先阅读仓库中的 AGENTS.md 并检查当前路由。将报告中的原因视为假设。首先确认受影响的模型、请求形态、环境、时间范围和用户可见的症状。

追踪故障

  1. 检查 Model Monitor 以及 enter.pollinations.ai/observability/endpoints/model_health.pipe 和 recent_server_errors.pipe 的当前定义。监控面板显示汇总健康状况；错误管道包含近期可采取行动的服务端故障。
  2. 通过 enter 和 gen Workers 追踪请求 ID，然后追踪到提供商。使用相关 Worker 的日志或 wrangler tail 查看实时事件。查询前先确认目标环境。
  3. 对于生产 SQL，请使用 enter.pollinations.ai/observability/scripts/tb-prod.sh。该脚本会加载现有读取令牌，但不会打印令牌。使用 --check 验证访问权限和近期事件。查询必须限制时间范围和行数。
  4. 将受影响用户的请求与使用相同模型和路由的其他用户进行比较。按状态、上游状态、提供商、请求形态和时间分组。必要时使用现有的授权测试凭据重现精确请求；使用唯一提示词，避免将缓存响应误判为上游正常。
  5. 报告证据、影响、仍存在的不确定性以及最小修复方案。如果请求修复代码，请遵循相关仓库技能和测试说明。

解读数据

  • generation_event_v2 包含经过身份验证且未命中缓存的请求。编写 SQL 前，请检查其当前数据源定义。每个请求可能对应多条上游尝试记录；is_final 标识用户可见的结果。如果只统计最终响应，成功的回退可能会掩盖主上游故障。
  • 在 model_health 中，total_requests 和状态计数使用最终结果；own_calls、primary_5xx、primary_retried_503s 和 fallback_rescues 描述上游健康状况和恢复情况。两种视图都要检查。
  • 401、402、403、400 或 429 可能源自不同层。检查 generation_event_v2 中的 error_source 和 error_response_code；在将其视为调用方噪声或模型故障前，通过 recent_server_errors.pipe（保留 24 小时）检查 error_event 中的 upstream_status、upstream_body 和 upstream_host。
  • 即使服务端返回 200，响应也可能在客户端超时后才到达。应按用户和请求形态检查延迟尾部，而不只是查看状态比率或 p95。
  • 对于流式故障或用量缺失，在归咎于提供商前，应检查最终的 SSE 数据块，以及提供商、适配器和校验器之间的原始传输错误。
  • 提供商返回 500 可能是由无效的调用方输入导致，例如 seed 超出有符号 INT32 范围。宣布上游故障前，先按请求形态比较失败情况。
  • 如果 Azure Content Safety 缺少配置或请求失败，它会返回安全结果。如果图片审核似乎未运行，请检查当前配置和 gen 日志；图片响应成功并不能证明安全检查已执行。
  • 立即出现的队列已满或速率限制错误，可能是由限流器状态造成，也可能是多个客户端共用一个代理 IP，而后端处于空闲状态。重启 Worker 前，先比较限流器和后端计数器。
  • 如果怀疑超时由部署或代理导致，请比较变更前后的症状，并检查最外层跳点。从相关区域依次执行直连和代理探测；并行突发请求可能造成误导性的客户端故障。

定向辅助脚本

scripts/ 中的脚本通过仓库的只读辅助程序查询生产环境中的 Tinybird。它们接受范围受限的数字窗口，应从仓库根目录运行：

.claude/skills/model-debugging/scripts/find-402-users.sh 24 10
.claude/skills/model-debugging/scripts/find-403-users.sh 24 10
.claude/skills/model-debugging/scripts/find-500-errors.sh 24
.claude/skills/model-debugging/scripts/check-user-errors.sh USER_ID 24

这些报告包含用户标识符和错误详情。只检查完成任务所需的行，并避免在共享输出中泄露敏感值。

机密变更和生产部署必须遵守 AGENTS.md 中的审批与 CI 规则；事故诊断并不授权执行这两项操作。

评论

支持 Markdown