故障排除指南

本指南帮助您解决使用 Qwen Image Edit 时遇到的常见问题。

常见问题

认证问题

API 密钥无效

问题: 收到 401 未授权错误

解决方案:

# 检查 API 密钥是否正确设置
echo $QWEN_API_KEY

# 验证 API 密钥格式
# 应该是: qwen-xxxxxxxxxxxxxxxxxxxx

速率限制

问题: 收到 429 请求过多错误

解决方案:

实施指数退避策略
在控制台检查您的速率限制
考虑升级您的计划

const retryWithBackoff = async (fn, maxRetries = 3) => {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429 && i < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
        continue;
      }
      throw error;
    }
  }
};

图像处理问题

图像上传失败

问题: 图像上传或处理失败

常见原因:

文件大小过大（最大 10MB）
不支持的格式
图像文件损坏

解决方案:

// 检查文件大小
if (file.size > 10 * 1024 * 1024) {
  throw new Error('文件大小超过 10MB 限制');
}

// 检查文件格式
const supportedFormats = ['image/jpeg', 'image/png', 'image/webp'];
if (!supportedFormats.includes(file.type)) {
  throw new Error('不支持的文件格式');
}

// 如需要可压缩图像
const compressImage = (file, quality = 0.8) => {
  return new Promise((resolve) => {
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d');
    const img = new Image();
    
    img.onload = () => {
      canvas.width = img.width;
      canvas.height = img.height;
      ctx.drawImage(img, 0, 0);
      
      canvas.toBlob(resolve, 'image/jpeg', quality);
    };
    
    img.src = URL.createObjectURL(file);
  });
};

编辑质量差

问题: 编辑效果不自然或不准确

解决方案:

使用更具体的提示词
调整强度参数
尝试不同的编辑模式

// 更好的提示词示例
const goodPrompts = [
  "将红色汽车替换为蓝色跑车",
  "将女士的黑色连衣裙改为优雅的白色",
  "为人物面部添加逼真的太阳镜"
];

// 避免模糊的提示词
const badPrompts = [
  "让它更好",
  "改变颜色",
  "添加一些东西"
];

性能问题

处理时间过长

问题: 图像编辑完成时间过长

解决方案:

在处理前降低图像分辨率
对多个图像使用批量处理
优化您的提示词

// 调整图像大小以加快处理速度
const resizeImage = (file, maxWidth = 1024) => {
  return new Promise((resolve) => {
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d');
    const img = new Image();
    
    img.onload = () => {
      const ratio = Math.min(maxWidth / img.width, maxWidth / img.height);
      canvas.width = img.width * ratio;
      canvas.height = img.height * ratio;
      
      ctx.drawImage(img, 0, 0, canvas.width, canvas.height);
      canvas.toBlob(resolve, 'image/jpeg', 0.9);
    };
    
    img.src = URL.createObjectURL(file);
  });
};

内存问题

问题: 浏览器崩溃或无响应

解决方案:

一次处理一个图像
处理后清理图像数据
对重型操作使用 Web Workers

// 清理图像数据
const processImage = async (imageFile) => {
  try {
    const result = await editImage(imageFile);
    return result;
  } finally {
    // 清理
    if (imageFile instanceof File) {
      URL.revokeObjectURL(imageFile);
    }
  }
};

集成问题

CORS 错误

问题: 跨域请求被阻止

解决方案:

// 对客户端请求使用代理
const proxyUrl = '/api/proxy/qwen';

// 或在服务器上配置 CORS 头
app.use((req, res, next) => {
  res.header('Access-Control-Allow-Origin', '*');
  res.header('Access-Control-Allow-Headers', 'Authorization, Content-Type');
  next();
});

Webhook 失败

问题: 未收到 Webhook

解决方案:

验证 webhook URL 可访问
检查 webhook 签名验证
实施重试逻辑

// Webhook 签名验证
const crypto = require('crypto');

const validateWebhook = (payload, signature, secret) => {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
    
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
};

错误代码参考

代码	描述	解决方案
400	错误请求	检查请求参数
401	未授权	验证 API 密钥
403	禁止访问	检查账户权限
404	未找到	验证端点 URL
413	负载过大	减小图像大小
429	请求过多	实施速率限制
500	内部服务器错误	联系支持
503	服务不可用	稍后重试

调试技巧

启用调试模式

// 启用详细日志记录
const client = new QwenImageEdit({
  apiKey: process.env.QWEN_API_KEY,
  debug: true
});

检查网络请求

// 记录所有请求
const originalFetch = fetch;
window.fetch = async (...args) => {
  console.log('请求:', args);
  const response = await originalFetch(...args);
  console.log('响应:', response);
  return response;
};

监控性能

// 跟踪处理时间
const startTime = performance.now();
const result = await editImage(image, prompt);
const endTime = performance.now();
console.log(`处理耗时 ${endTime - startTime} 毫秒`);

获取帮助

联系支持前

查看此故障排除指南
查阅 API 文档
查看示例中的类似用例
搜索我们的社区论坛

联系支持时

请包含以下信息：

错误消息和代码
请求/响应详情
图像规格（大小、格式）
浏览器/环境详情
重现步骤

支持渠道

避免问题的最佳实践

始终验证输入 在发送请求前
在应用中实施适当的错误处理
为您的用例使用适当的图像大小
监控您的 API 使用情况 以避免速率限制
保护您的 API 密钥安全 并定期轮换
在开发环境中彻底测试 优先
保持更新 最新的 API 变更和最佳实践

最后更新: 2024年1月

故障排除

On this page