Nacos Java SDK 接入 AI 治理中心 - Microservices Engine

本文介紹如何使用 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。

Microservices Engine：Nacos Java SDK 接入 AI 治理中心