故障排除 (简体中文)

本文档提供了 QwenImageEdit SDK 常见问题和错误解决方案。如果您在使用 SDK 过程中遇到问题，请参考以下指南。

1. 认证错误

1.1. 无效的 API 密钥

问题： 收到 AuthenticationError: Invalid API Key 或 Unauthorized 错误。

原因： 提供的 API 密钥不正确、已过期或未激活。

解决方案：

检查 API 密钥： 确保您在初始化 QwenImageEdit 客户端时使用了正确的 API 密钥。
重新生成密钥： 登录 QwenImageEdit 控制台，检查您的 API 密钥状态。如果需要，生成一个新的 API 密钥。
环境变量： 如果您使用环境变量存储密钥，请确保变量名正确且值已正确加载。

// 确保您的 API 密钥是正确的
const qwenImageEdit = new QwenImageEdit({
  apiKey: 'YOUR_CORRECT_API_KEY',
});

1.2. 速率限制

问题： 收到 RateLimitExceededError: Too Many Requests 错误。

原因： 您在短时间内发送了过多的请求，超出了您的 API 密钥的速率限制。

解决方案：

检查速率限制： 查阅 QwenImageEdit API 文档，了解您的账户的速率限制。
实现指数退避： 在重试失败的请求时，使用指数退避策略。SDK 默认支持重试，但您可以自定义。
优化请求： 考虑批量处理图像或优化您的工作流以减少 API 调用次数。

const qwenImageEdit = new QwenImageEdit({
  apiKey: 'YOUR_API_KEY',
  retries: 5,     // 增加重试次数
  timeout: 60000, // 增加超时时间
});

// 手动实现指数退避示例
async function callApiWithRetry(apiCallFunction, maxRetries = 5) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await apiCallFunction();
    } catch (error) {
      if (error.name === 'RateLimitExceededError' && i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000 + Math.random() * 1000; // 1s, 2s, 4s...
        console.warn(`速率限制，正在重试... (${i + 1}/${maxRetries}) 延迟 ${delay / 1000} 秒`);
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
}

// 示例用法
// callApiWithRetry(() => qwenImageEdit.image.removeBackground({ imageUrl: '...' }));

2. 网络和超时问题

2.1. 连接超时

问题： 收到 TimeoutError: Request timed out 或类似的网络错误。

原因： 网络连接不稳定，或 API 响应时间过长。

解决方案：

增加超时设置： 在 SDK 初始化时增加 timeout 参数的值。
检查网络连接： 确保您的应用程序可以稳定访问互联网和 QwenImageEdit API 端点。
选择合适的区域： 尝试连接到地理位置上更近的区域，以减少网络延迟。

const qwenImageEdit = new QwenImageEdit({
  apiKey: 'YOUR_API_KEY',
  timeout: 60000, // 将超时时间设置为 60 秒
});

2.2. 代理配置问题

问题： 如果您使用代理，请求可能无法通过代理服务器。

原因： 代理地址或配置不正确。

解决方案：

验证代理设置： 确保 proxy 参数配置正确，包括协议、主机和端口。
检查代理服务器状态： 确保您的代理服务器正在运行且可访问。

const qwenImageEdit = new QwenImageEdit({
  apiKey: 'YOUR_API_KEY',
  proxy: 'http://your.proxy.com:8080', // 验证代理地址和端口
});

3. 图像处理失败

3.1. 图像不可访问或格式不支持

问题： 收到 ImageProcessingError: Image not found or unsupported format 错误。

原因： 提供的图像 URL 无效、图像文件不存在、服务器无法访问图像，或图像格式不受支持。

解决方案：

验证图像 URL： 确保 imageUrl 参数指向一个公开可访问且有效的图像文件。
检查图像格式： 确保图像格式（例如 JPEG, PNG, WebP）受 QwenImageEdit 支持。
CORS/防火墙： 确保图像源服务器没有 CORS 限制或防火墙阻止 QwenImageEdit 访问。

async function processImage(imageUrl) {
  try {
    // 确保 imageUrl 是有效的且可公开访问的
    const result = await qwenImageEdit.image.removeBackground({ imageUrl: imageUrl });
    console.log('处理成功:', result.outputUrl);
  } catch (error) {
    if (error.name === 'ImageProcessingError') {
      console.error('图像处理失败，请检查 URL 和格式:', error.message);
    } else {
      throw error;
    }
  }
}

// 示例用法
// processImage('https://valid-image-url.com/image.jpg');

3.2. 意外结果或低质量输出

问题： 处理后的图像质量不佳，或结果不符合预期。

原因： 输入图像质量低，或操作参数不当。

解决方案：

提高输入图像质量： 使用高分辨率和清晰的原始图像。
调整操作参数： 仔细检查您使用的操作参数（例如，调整大小的 fit 模式，滤镜类型，文本位置等）。
尝试不同的模型： 如果适用，尝试使用不同的模型或模型版本。

4. 缓存问题

4.1. 缓存未按预期工作

问题： 即使启用了缓存，请求仍然很慢或重复调用 API。

原因： 缓存配置不正确，或缓存策略不适合您的用例。

解决方案：

检查缓存配置： 确保 caching.enabled 设置为 true，并且 strategy 和 ttl 参数配置正确。
验证缓存存储： 如果使用 Redis 或文件系统缓存，请检查存储是否可访问且正常工作。
清除缓存： 尝试手动清除缓存以确保没有脏数据。

const qwenImageEdit = new QwenImageEdit({
  apiKey: 'YOUR_API_KEY',
  caching: {
    enabled: true,
    strategy: 'memory', // 或 'redis', 'filesystem'
    ttl: 3600,           // 确保 TTL 足够长
  },
});

// 如果使用自定义缓存，确保其 get/set/delete 方法正确实现

5. 日志记录问题

5.1. 没有日志输出或日志信息不足

问题： 无法看到 SDK 的日志输出，或日志级别太低无法提供足够的信息。

原因： logLevel 设置不正确，或自定义日志器未正确配置。

解决方案：

调整日志级别： 将 logLevel 设置为 debug 以获取最详细的输出。
检查自定义日志器： 如果您提供了自定义日志器，请确保其方法（debug, info, warn, error）正确地将消息输出到您的日志系统。

const qwenImageEdit = new QwenImageEdit({
  apiKey: 'YOUR_API_KEY',
  logLevel: 'debug', // 设置为 debug 以获取所有日志
});

// 如果使用自定义日志器
const customLogger = {
  debug: (message, ...args) => console.log('[DEBUG]', message, ...args),
  info: (message, ...args) => console.log('[INFO]', message, ...args),
  warn: (message, ...args) => console.warn('[WARN]', message, ...args),
  error: (message, ...args) => console.error('[ERROR]', message, ...args),
};

const qwenImageEditWithCustomLogger = new QwenImageEdit({
  apiKey: 'YOUR_API_KEY',
  logger: customLogger,
});

提示： 如果以上解决方案未能解决您的问题，请提供详细的错误信息、代码片段和操作步骤，联系 QwenImageEdit 支持团队以获得进一步帮助。

故障排除

On this page