Astria AI 训练模型回调问题排查指南

问题背景

在使用 Astria AI 的 headshots-starter 项目时，开发者可能会遇到模型训练回调无法正常工作的问题。具体表现为能够成功发送图片并创建模型，但始终无法接收到来自 Astria 的回调通知。

常见问题分析

1. Vercel 认证设置问题

许多开发者遇到回调失败的首要原因是 Vercel 平台的认证设置。Vercel 默认会为项目启用认证保护，这会阻止外部服务的回调请求。解决方案是：

1. 登录 Vercel 控制台
2. 找到对应项目
3. 在项目设置中关闭认证保护功能
4. 重新部署项目

2. 回调URL格式问题

正确的回调URL应该遵循以下格式：

https://yourdomain.com/astria/train-webhook?user_id=USERID&webhook_secret=SECRET

常见错误包括：

• 使用不完整的域名
• 缺少必要的查询参数
• URL中包含特殊字符或空格

3. 请求体结构问题

训练请求的JSON体必须包含完整的回调配置：

{
  "tune": {
    "title": "模型名称",
    "base_tune_id": 690204,
    "name": "模型类型",
    "branch": "sd15",
    "token": "触发词",
    "image_urls": ["图片URL数组"],
    "callback": "训练回调URL",
    "prompts_attributes": [
      {
        "text": "提示词1",
        "callback": "提示回调URL"
      },
      {
        "text": "提示词2",
        "callback": "提示回调URL"
      }
    ]
  }
}

4. 账户支付设置问题

即使账户有免费额度，某些情况下仍然需要：

1. 添加有效的信用卡信息
2. 确认支付方式已通过验证
3. 检查账户是否有足够的额度

解决方案步骤

1. 检查基础配置

   • 确认Vercel认证已关闭
   • 验证回调URL格式正确
   • 确保请求头包含正确的认证信息

2. 测试环境验证

   • 先在测试分支("fast")进行验证
   • 确认测试回调能正常工作
   • 再切换到生产环境("sd15")

3. 账户设置检查

   • 添加并验证支付方式
   • 确认账户有可用额度
   • 检查API密钥是否正确配置

4. 监控与调试

   • 检查服务器日志
   • 使用网络抓包工具监控请求
   • 验证回调端点是否可达

最佳实践建议

1. 开发阶段使用测试分支("fast")进行快速迭代
2. 实现完善的日志记录机制，记录所有回调请求
3. 为不同的环境(开发/测试/生产)配置独立的回调URL
4. 定期检查账户状态和API限额
5. 考虑实现重试机制处理可能的网络问题

通过以上步骤的系统排查，大多数回调问题都能得到有效解决。如果问题仍然存在，建议联系Astria AI的技术支持团队，提供完整的请求日志和错误信息以便进一步诊断。