Nacos Java SDK 接入 AI 治理中心-微服务引擎(MSE)-阿里云帮助中心

本文介绍如何使用 Nacos Java SDK 访问阿里云 AI 治理中心中的 Skill 和 Prompt 资源。Java SDK 以 ZIP 字节流的形式分发 Skill，以 JSON 字符串的形式分发 Prompt，SDK 支持按名称、按版本、按标签下载，并支持订阅资源变更。

说明

Java SDK 当前仅提供 Skill 和 Prompt 的消费侧能力，Skill 和 Prompt 的上传、评审、发布等生命周期管理操作请使用控制台或 Nacos CLI 接入 AI 治理中心。

前提条件

已开通阿里云 MSE AI 治理中心实例，并创建工作空间。
已准备好阿里云 AccessKey / SecretKey，且 RAM 子账号已授予 Skill 和 Prompt 相关读权限，具体配置方式参考AI 治理中心 RAM 权限配置指南。
已具备 Java 开发环境（JDK 8 及以上）。
已根据应用部署位置完成网络接入配置：本地开发、IDC 或非 VPC 环境请配置公网接入点和 IP 白名单；阿里云 VPC 内应用请配置 VPC 私网访问。

添加 Maven 依赖

在工程中引入 Nacos Java SDK：

<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client</artifactId>
    <version>${nacos.version}</version>
</dependency>

SDK 能力与最低版本要求：

能力	最低 nacos-client 版本
`downloadSkillZip` / `downloadSkillZipByVersion` / `downloadSkillZipByLabel`	3.2.0
`subscribeSkill` / `unsubscribeSkill`	3.2.2
Prompt 相关接口	3.2.3

说明

如同时使用下载与订阅能力，请使用 3.2.2 及以上版本；如需使用 Prompt 能力，请使用 3.2.3 及以上版本。

初始化 SDK

步骤一：选择访问方式

Java SDK 访问 AI 治理中心前，需要先选择网络接入方式：

公网访问：适合本地开发、IDC 或未部署在阿里云 VPC 内的应用。请先参考 AI 治理中心公网访问配置指南添加公网接入点，并将应用所在环境的公网出口 IP 加入白名单。
VPC 私网访问：适合部署在阿里云 VPC 内的应用。请先参考 AI 治理中心 VPC 私网访问配置指南完成 PrivateLink 配置，配置完成后将获得形如 airegistry.{region-id}.mse.aliyuncs.com 的私网域名。

步骤二：初始化 AiService

在运行应用的环境中，通过 Properties 设置 SDK 初始化参数，并调用 AiFactory.createAiService(properties) 创建 AiService 实例。SERVER_ADDR 填写步骤一获取的公网接入点域名或 VPC 私网域名：

Properties properties = new Properties();
// 以下为 VPC 私网地址示例，公网访问请替换为 {实例ID}.airegistry.cn-hangzhou.mse.aliyuncs.com:80
properties.setProperty(PropertyKeyConst.SERVER_ADDR, "airegistry.cn-hangzhou.mse.aliyuncs.com:80");
properties.setProperty(PropertyKeyConst.NAMESPACE, "xxxxxx-xxxx-xxxx-xxxx-xxxxxx");
properties.setProperty(PropertyKeyConst.ACCESS_KEY, "LTAI5tXXXXXXXXXXXXXX");
properties.setProperty(PropertyKeyConst.SECRET_KEY, "XXXXXXXXXXXXXXXXXXXXxx");

AiService aiService = AiFactory.createAiService(properties);

各配置项说明：

配置项	说明	示例
`serverAddr`	AI 治理中心访问地址，格式为 `{host}:{port}`。公网访问填写公网接入点域名和端口；VPC 私网访问填写私网访问域名和端口。	私网：`airegistry.cn-hangzhou.mse.aliyuncs.com:80`；公网：`{实例ID}.airegistry.cn-hangzhou.mse.aliyuncs.com:80`
`namespace`	AI 治理中心的命名空间 ID，可在控制台工作空间页查看	`xxxxxx-xxxx-xxxx-xxxx-xxxxxx`
`accessKey`	阿里云 AccessKey ID	`LTAI5tXXXXXXXXXXXXXX`
`secretKey`	阿里云 AccessKey Secret	`XXXXXXXXXXXXXXXXXXXXxx`

说明

一个 AiService 实例对应一个命名空间。访问多个命名空间时需分别创建实例；应用内尽量复用同一实例，退出时调用 shutdown() 释放资源。

验证配置

SDK 初始化成功后，可通过 aiService.downloadSkillZip(...) 或 Prompt 相关接口获取资源，能正常返回数据即说明配置成功。若提示认证失败，请检查 AccessKey、SecretKey 是否正确以及 RAM 权限是否完备；若网络不通，公网访问请检查公网出口 IP 白名单，VPC 私网访问请检查 ECS 所在 VPC、安全组和私网域名配置。

SDK 能力概览

AiService 提供 Skill 和 Prompt 两类消费侧接口，完整用法参考 Nacos Java SDK Usage。

Skill 能力

SDK 支持按名称、版本、标签下载 Skill ZIP，并可订阅 Skill 变更：

接口	作用
`downloadSkillZip(skillName)`	下载 Skill 的最新版本 ZIP
`downloadSkillZipByVersion(skillName, version)`	下载指定版本的 ZIP
`downloadSkillZipByLabel(skillName, label)`	按标签（如 `latest`）下载对应版本的 ZIP
`subscribeSkill(skillName, version, label, listener)`	订阅 Skill 变更，内容更新时通过监听器回调
`unsubscribeSkill(skillName, version, label, listener)`	取消订阅

返回的 ZIP 字节数组包含 SKILL.md 和全部资源文件，二进制资源自动从 Base64 解码。

Prompt 能力

SDK 支持按名称、版本拉取 Prompt 内容，以及订阅 Prompt 变更：

接口	作用
`getPrompt(promptKey)`	获取 Prompt 的最新版本内容（JSON 字符串）
`getPromptByVersion(promptKey, version)`	获取指定版本的 Prompt 内容
`subscribePrompt(promptKey, version, listener)`	订阅 Prompt 变更，内容更新时通过监听器回调
`unsubscribePrompt(promptKey, version, listener)`	取消订阅

完整的接口签名、参数说明与代码示例参考 Nacos Java SDK Usage。