使用Java SDK创建自定义视觉图像分类项目失败如何解决

问题描述 #

• 参照Azure自定义视觉服务Java SDK官方快速入门开展开发时，无法通过SDK创建自定义视觉图像分类项目
• 报错触发点：CustomVisionQuickstart.java 文件main方法中执行如下代码时运行失败：

  Project project = createProject(trainClient);
  

• 参考资料为官方英文版本的自定义视觉图像分类Java快速入门指南。

根因及修复方案 #

1. 方法签名/入参不匹配（最高发） #

官方快速入门中的createProject并非SDK内置的单参数方法，是示例中自定义封装的工具方法，直接复制调用代码但没补全对应方法实现、没传必填参数时会直接报错。

• 修正调用逻辑，补全必填参数：

  // 传入训练客户端、项目名称、分类类型、域ID参数
  Project project = createProject(
          trainClient,
          "自定义分类项目名",
          ClassifierType.MULTICLASS, // 单图单标签选MULTICLASS，单图多标签选MULTILABEL
          "通用图像分类"
  );
  

• 对应补全createProject方法的实现，和你引入的SDK版本对齐，稳定版SDK的方法实现参考：

  private static Project createProject(
          CustomVisionTrainingClient trainClient,
          String projectName,
          ClassifierType classificationType,
          String description
  ) {
      ProjectCreateParameters createOptions = new ProjectCreateParameters()
              .withName(projectName)
              .withClassificationType(classificationType)
              .withDescription(description)
              // 通用图像分类域ID为固定值，不需要额外查询
              .withDomainId(UUID.fromString("ee85a74c-405e-4adc-bb47-ffa8ca0c9f31"));
      return trainClient.createProject(createOptions);
  }
  

2. 训练客户端初始化配置错误 #

trainClient实例配置错误时，哪怕方法写对也会调用失败：

• 不要混用预测资源和训练资源的密钥、端点：创建项目属于训练侧操作，必须使用自定义视觉训练资源的密钥和端点，预测资源的密钥仅能调用预测接口，传入会返回401权限错误
• 端点不要拼接多余路径：正确端点格式为https://<你的自定义资源名>.cognitiveservices.azure.com/，不要手动拼接/customvision/v3.3/training这类后缀，SDK会自动补全请求路径
• SDK依赖版本保持统一：不要同时引入不同大版本的训练、预测SDK包，Maven配置统一使用同一release版本的依赖，避免类冲突。

3. 资源配额/网络限制拦截 #

• 免费层（F0）自定义视觉训练资源最多支持创建2个项目，超出配额后调用创建接口会返回403错误，删除无用项目或者升级到标准层即可恢复
• 如果资源开启了虚拟网络访问限制，需要将代码运行环境的出口IP加入资源允许列表，否则请求会被网络策略拦截

排查时可以在createProject调用外层加try-catch块打印完整异常栈，根据HTTP错误码快速定位：401优先查密钥端点配置，403优先查配额和权限，400优先查参数格式，连接超时优先查网络连通性。

内容的提问来源于stack exchange，提问作者Nishant Gupta