# SDK接入与卸载 AI安全护栏SDK是一个用于集成AI安全检测功能的开发工具包。它的主要目的是帮助开发者在应用程序中实现文本和图片内容安全检测，确保应用内容的合规性和安全性。 当下生成式AI业务普遍面临输入输出内容不合规风险，开发者需要快速集成内容安全检测能力，但缺少标准化SDK集成指引，AI安全护栏SDK可帮助业务快速实现文本、图片内容安全检测，本文档提供Python、Java SDK完整接入与卸载操作。 #### 接入方案 AI安全护栏支持**Python** 、**Java**两种编程语言的接入方式。 - [Python SDK] **环境要求** | 项目 | 要求 | |:---|:---| | Python | Python JDK 3.9或更高版本。 | | 核心依赖 | httpx\>=0.24.0（自动安装）。 | | 网络 | 可访问护栏服务端地址。 | | SSL | 默认不验证服务端证书（verify_ssl=False），后续版本支持证书验证。 | | SDK安装包 | 联系客户经理获取。 | **安装部署** ``` # 从 whl 文件安装（推荐） pip install aiguard--py3-none-any.whl # 验证安装 python -c "import aiguard; print(aiguard.__version__)" # 输出: +，例如 0.1.0+20260610092627 ``` **接入示例代码** AI安全护栏提供最小接入配置、标准接入配置。用户可根据实际业务，选择适合的方式完成接入。关于示例代码中ClientConfig参数说明，请参见[表1]。 - **未使用代理** **场景** - 最小接入配置 ``` from aiguard import AiGuardClient, ClientConfig # 1. 创建客户端 config = ClientConfig( base_url="YOUR_BASE_URL", # 必填：护栏服务端地址，如 https://aiguard.huaweicloudwaf.cn project_id="YOUR_PROJECT_ID", # 必填：项目ID app_id="YOUR_APP_ID", # 必填：AI应用ID verify_ssl=False, # 当前版本默认不验证服务端证书 ) with AiGuardClient( ak="YOUR_AK", # 必填：Access Key sk="YOUR_SK", # 必填：Secret Key config=config, ) as client: # 2. 文本检测 result = client.text_detect("今天天气怎么样？") print(f"结果: {result.suggestion}") # pass 或 block # 3. 图像检测（支持 raw base64 或 data:image/xxx;base64,... 格式） import base64 with open("image.png", "rb") as f: image_data = base64.b64encode(f.read()).decode() img_result = client.image_detect(image_data) print(f"结果: {img_result.suggestion}") ``` - 标准接入配置 ``` #!/usr/bin/env python import base64 from aiguard import AiGuardClient, ClientConfig, TextDetectOptions, Message config = ClientConfig( base_url="https://aiguard.huaweicloudwaf.cn", # 必填：护栏服务端地址 project_id="YOUR_PROJECT_ID", # 必填：项目ID app_id="YOUR_APP_ID", # 必填：AI应用ID verify_ssl=False, # 当前版本默认不验证服务端证书 connect_timeout=10, # 连接超时（秒），默认5 read_timeout=30, # 读取超时（秒），默认5 max_retries=5, # 最大重试次数，默认3 initial_delay=2, # 重试初始延迟（秒），默认1 max_delay=60, # 重试最大延迟（秒），默认60 log_level="DEBUG", # 日志级别，可选 DEBUG/INFO/ERROR，默认 INFO # proxy="http://127.0.0.1:8888", # 可选：HTTP代理地址（详见1.10节） ) with AiGuardClient( ak="YOUR_AK", # 必填：Access Key sk="YOUR_SK", # 必填：Secret Key config=config, ) as client: # 1. 带对话历史的文本检测 history = [ Message(role="user", content="你好"), Message(role="assistant", content="你好，有什么可以帮助你的？"), ] options = TextDetectOptions( role="user", history=history, end_user="tenant_123", source_region="cn-north-4", app_id="YOUR_APP_ID", # 可选：单次请求覆盖 app_id ) result = client.text_detect("谢谢", options=options) print(f"文本结果(带历史): {result.suggestion}") # 2. 图像检测 image_path = "/path/to/image.bmp" with open(image_path, "rb") as f: image_data = base64.b64encode(f.read()).decode() img_result = client.image_detect(image_data) print(f"图像结果: {img_result.suggestion}") # 3. 单次请求覆盖 project_id/app_id options_override = TextDetectOptions(project_id="YOUR_PROJECT_ID") result2 = client.text_detect("测试覆盖", options=options_override) print(f"文本结果(覆盖project_id): {result2.suggestion}") ``` 表1ClientConfig参数说明 | 参数 | 是否必选 | 参数类型 | 默认值 | 描述 | |:---|:---|:---|:---|:---| | base_url | 是 | str | -- | 服务端地址。 | | project_id | 是 | str | -- | 项目ID。 | | app_id | 是 | str | -- | AI应用ID。 | | verify_ssl | 否 | bool/str | False | 当前版本默认不验证服务端证书，后续版本支持证书验证。 | | connect_timeout | 否 | int | 5 | 连接超时（秒）。 | | read_timeout | 否 | int | 5 | 读取超时（秒）。 | | max_retries | 否 | int | 3 | 最大重试次数。 | | initial_delay | 否 | int | 1 | 重试初始延迟（秒）。 | | max_delay | 否 | int | 60 | 重试最大延迟（秒）。 | | log_level | 否 | str | INFO | 日志级别： - DEBUG：输出请求/响应详情、重试过程等，用于问题排查。 - INFO：输出常规操作日志（默认）。 - ERROR：仅输出错误日志。 | | proxy | 否 | str | None | HTTP代理地址，例如http://127.0.0.1:8888 | - **使用代理场景** 如下业务场景时，可在ClientConfig中配置proxy参数，通过HTTP代理访问护栏服务。 - 企业网络要求所有外网请求通过代理 - 需要通过抓包工具（Fiddler/Charles/Nginx）调试请求 - 服务端在内网，需通过代理网关转发 接入示例如下所示： ``` import base64 from aiguard import AiGuardClient, ClientConfig config = ClientConfig( base_url="https://aiguard.huaweicloudwaf.cn", project_id="YOUR_PROJECT_ID", app_id="YOUR_APP_ID", verify_ssl=False, # 当前版本默认不验证服务端证书 proxy="http://127.0.0.1:8888", # HTTP 代理地址 log_level="ERROR", ) with AiGuardClient(ak="YOUR_AK", sk="YOUR_SK", config=config) as client: # 文本检测（经代理） result = client.text_detect("你好，今天天气怎么样？") print(f"结果: {result.suggestion}") # 图像检测（经代理） with open("image.png", "rb") as f: image_data = base64.b64encode(f.read()).decode() img_result = client.image_detect(image_data) print(f"结果: {img_result.suggestion}") ``` ![](https://support.huaweicloud.com/usermanual-waf/public_sys-resources/note_3.0-zh-cn.png) - proxy仅支持HTTP/HTTPS协议代理，格式为http://host:port或https://host:port。 - 使用代理时，SDK默认不验证服务端证书（verifySsl(false)），后续版本将支持证书验证。 - 配置proxy后，SDK的所有请求（包括文本检测和图像检测）都会经过代理。 **日志配置** SDK使用Python 标准logging模块，logger名称为aiguard。默认输出到控制台，级别为INFO。 - **日志级别设置** ： 通过ClientConfig.logLevel参数控制SDK日志级别： | 级别 | 参数值 | 说明 | |:---|:---|:---| | DEBUG | .logLevel("DEBUG") | 输出请求/响应详情、重试过程等，用于问题排查。 | | INFO | .logLevel("INFO") | 输出常规操作日志（默认）。 | | ERROR | .logLevel("ERROR") | 仅输出错误日志。 | - **日志输出到文件** ： SDK默认输出日志到控制台。如需写入文件，业务方可通过Python标准logging模块自行添加FileHandler。 ![](https://support.huaweicloud.com/usermanual-waf/public_sys-resources/note_3.0-zh-cn.png) - SDK只负责日志输出，不管理日志写入位置。业务方通过Python标准logging模块灵活配置日志输出方式（例如控制台、文件、轮转等），与业务自身的日志体系无缝集成。 - SDK已内置AK/SK脱敏，日志中密钥字段统一显示为 \*\*\*。但业务方自身的日志代码需注意不要打印实际密钥值。 ``` # 方式1：仅输出到控制台（默认行为，无需额外配置） config = ClientConfig( base_url="YOUR_BASE_URL", project_id="YOUR_PROJECT_ID", app_id="YOUR_APP_ID", log_level="DEBUG", ) # 方式2：输出到文件（业务方自行配置 Python logging） import logging sdk_logger = logging.getLogger("aiguard") # 使用 FileHandler 写入文件 file_handler = logging.FileHandler("/path/to/sdk.log", encoding="utf-8") file_handler.setFormatter(logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")) sdk_logger.addHandler(file_handler) # 方式3：高级场景 — 使用 RotatingFileHandler 实现日志轮转 from logging.handlers import RotatingFileHandler rotating_handler = RotatingFileHandler("/path/to/sdk.log", maxBytes=10*1024*1024, backupCount=5, encoding="utf-8") rotating_handler.setFormatter(logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")) sdk_logger.addHandler(rotating_handler) ``` - **日志输出示例** ： ``` 2026-06-17 10:30:00,123 - aiguard.http - INFO - AiGuardClient initialized - project_id=c12d..., app_id=a5ca... 2026-06-17 10:30:00,456 - aiguard.http - DEBUG - POST https://aiguard.huaweicloudwaf.cn/v1/.../text-detect - Body: {'app_id': 'a5ca...', 'message': {'role': 'user', 'content': '你好'}} 2026-06-17 10:30:01,789 - aiguard.http - DEBUG - Response status: 200 2026-06-17 10:30:01,789 - aiguard.http - DEBUG - Request successful - request_id: 20260617... 2026-06-17 10:30:02,000 - aiguard.http - INFO - AiGuardClient closed ``` **SSL配置** 当前版本SDK默认不验证服务端证书（verify_ssl=False），证书验证功能将在后续版本支持。 ``` # 当前版本：不验证服务端证书（默认） config = ClientConfig( base_url="https://aiguard.huaweicloudwaf.cn", project_id="YOUR_PROJECT_ID", app_id="YOUR_APP_ID", # verify_ssl=False 为默认值，无需显式配置 ) ``` ![](https://support.huaweicloud.com/usermanual-waf/public_sys-resources/note_3.0-zh-cn.png) 不验证服务端证书意味着SDK不会校验服务端身份，存在中间人攻击风险。该配置仅适用于当前版本，后续版本将默认开启证书验证。 **接入异常处理** ``` from aiguard import AiGuardClient, ClientConfig from aiguard.exceptions import ( AiGuardValidationException, AiGuardAuthenticationException, AiGuardRateLimitException, AiGuardServerException, AiGuardTimeoutException, AiGuardNetworkException, AiGuardException, ) config = ClientConfig(project_id="p1", app_id="a1") with AiGuardClient(ak="ak", sk="sk", config=config) as client: try: result = client.text_detect("内容") except AiGuardValidationException: # 参数错误（空内容、非法role等），不重试 # 子类包括： # AiGuardAppDisabledException — 应用已禁用（MAF.1007） # AiGuardUnsupportedUrlException — 不支持的 URL（MAF.1001） # AiGuardMediaTypeException — 不支持的媒体类型（MAF.1002） # AiGuardImageFormatException — 图像格式错误（MAF.1300/1304） # AiGuardImageParseException — 图像解析失败（MAF.1301/1303） # AiGuardImageDownloadException — 图像下载失败（MAF.1302） # AiGuardImageSizeException — 图像大小超限（MAF.1305） pass except AiGuardAuthenticationException: # AK/SK 认证失败（MAF.1004），不重试 pass except AiGuardRateLimitException: # 限流（MAF.3000/3001 或 HTTP 429），SDK 自动重试后仍失败 pass except AiGuardServerException as e: # 服务端异常，可重试但重试耗尽 # e.error_code / e.error_msg 可获取详情 pass except AiGuardTimeoutException: # 请求超时，可重试但重试耗尽 pass except AiGuardNetworkException: # 网络异常（DNS失败、连接拒绝），可重试但重试耗尽 pass except AiGuardException: # 其他 SDK 异常兜底 pass ``` **接入验证清单** | 序号 | 验证项 | 方法 | 预期结果 | |:---|:---|:---|:---| | 1 | SDK包安装成功 | python -c "import aiguard" | 无报错 | | 2 | 版本正确 | python -c "import aiguard; print(aiguard.version)" | 输出对应版本号 | | 3 | 客户端初始化成功 | 构造 AiGuardClient(ak, sk, config) | 无报错 | | 4 | 缺少ak抛异常 | AiGuardClient(ak="", sk="x", config=config) | 抛AiGuardMissingParamException | | 5 | 缺少project_id抛异常 | config=ClientConfig() | 抛 AiGuardMissingParamException | | 6 | 文本检测正常 | client.text_detect("你好") | 返回 DetectResult | | 7 | 空内容抛异常 | client.text_detect("") | 抛 AiGuardValidationException | | 8 | 图像检测正常 | client.image_detect("data:image/png;base64,...") | 返回 DetectResult | | 9 | 资源释放 | client.close() 或 with 退出 | 无报错，日志输出 closed | | 10 | 日志无AK/SK泄漏 | 设置 log_level="DEBUG" 后检测 | 日志中不含AK/SK明文 | **查看版本号** 版本号嵌入在包元数据中，可通过以下方式查看： ``` # 方式一：pip show pip show aiguard # 方式二：代码中读取 python -c "import aiguard; print(aiguard.__version__)" ``` - [Java SDK] **环境要求** | 项目 | 要求 | |:---|:---| | JDK | JDK 17或更高版本 | | 构建工具 | Maven | | 依赖 | OkHttp 4.12.0、Jackson 2.15.3（自动传递） | | 日志 | SLF4J 2.0.9。需业务方提供实现，例如logback | | SSL | 默认不验证服务端证书（verifySsl(false)），后续版本支持证书验证 | | SDK安装包 | 联系客户经理获取。 | **安装部署示例** ``` com.huawei aiguard-sdk ${aiguard-sdk.version} ch.qos.logback logback-classic 1.4.11 ``` **接入示例** AI安全护栏提供最小接入配置、标准接入配置。用户可根据实际业务，选择适合的方式完成接入。ClientConfig参数说明请参见[表2]。 - **未使用代理** **场景** - 最小接入配置 ``` import com.huawei.aiguard.client.AiGuardClient; import com.huawei.aiguard.config.ClientConfig; import com.huawei.aiguard.model.DetectResult; // 1. 创建客户端（try-with-resources 自动释放） ClientConfig config = ClientConfig.builder() .baseUrl("YOUR_BASE_URL") // 必填：护栏服务端地址，如 https://aiguard.huaweicloudwaf.cn .projectId("YOUR_PROJECT_ID") .appId("YOUR_APP_ID") .verifySsl(false) // 当前版本默认不验证服务端证书 .build(); try (AiGuardClient client = new AiGuardClient("YOUR_AK", "YOUR_SK", config)) { // 2. 文本检测 DetectResult result = client.textDetect("今天天气怎么样？", null); System.out.println("结果: " + result.getSuggestion()); // pass 或 block // 3. 图像检测 String imageData = "data:image/png;base64,iVBORw0KGgo..."; DetectResult imgResult = client.imageDetect(imageData, null); System.out.println("结果: " + imgResult.getSuggestion()); } // 4. try-with-resources 自动调用 close() ``` - 标准接入配置 ``` import com.huawei.aiguard.client.AiGuardClient; import com.huawei.aiguard.config.ClientConfig; import com.huawei.aiguard.model.DetectResult; import com.huawei.aiguard.model.Message; import com.huawei.aiguard.model.TextDetectOptions; ClientConfig config = ClientConfig.builder() .baseUrl("https://aiguard.huaweicloudwaf.cn") // 必填：护栏服务端地址 .projectId("YOUR_PROJECT_ID") .appId("YOUR_APP_ID") .verifySsl(false) // 当前版本默认不验证服务端证书 // .sslCertPath("/path/to/ca.pem") // 后续版本支持 .connectTimeout(10) .readTimeout(30) .maxRetries(5) .initialDelay(2) .maxDelay(60) .logLevel("DEBUG") // 日志级别，可选 DEBUG/INFO/ERROR，默认 INFO // .proxy("http://127.0.0.1:8888") // 可选：HTTP代理地址（详见2.10节） .build(); try (AiGuardClient client = new AiGuardClient("ak", "sk", config)) { // 带对话历史的文本检测 Message history1 = new Message("user", "你好"); Message history2 = new Message("assistant", "你好，有什么可以帮助你的？"); TextDetectOptions options = TextDetectOptions.builder() .role("user") .history(Arrays.asList(history1, history2)) .endUser("tenant_project_id") .sourceRegion("cn-north-4") .appId("YOUR_APP_ID") // 可选：单次请求覆盖 appId .build(); DetectResult result = client.textDetect("谢谢", options); } ``` 表2ClientConfig参数说明 | 参数 | 是否必选 | 参数类型 | 默认值 | 描述 | |:---|:---|:---|:---|:---| | baseUrl | 是 | String | 必填 | 服务端地址。 | | projectId | 是 | String | 必填 | 项目ID。 | | appId | 是 | String | 必填 | AI应用ID。 | | verifySsl | 否 | boolean | false | 当前版本默认不验证服务端证书。 | | sslCertPath | 否 | String | null | 后续版本支持。 | | connectTimeout | 否 | int | 5 | 连接超时（秒）。 | | readTimeout | 否 | int | 5 | 读取超时（秒）。 | | maxRetries | 否 | int | 3 | 最大重试次数。 | | initialDelay | 否 | int | 1 | 重试初始延迟（秒）。 | | maxDelay | 否 | int | 60 | 重试最大延迟（秒）。 | | logLevel | 否 | String | INFO | 日志级别： - DEBUG：输出请求/响应详情、重试过程等，用于问题排查。 - INFO：输出常规操作日志（默认）。 - ERROR：仅输出错误日志。 | | proxy | 否 | String | null | HTTP代理地址，例如http://127.0.0.1:8888。 | - **使用代理场景** 如下业务场景时，可在ClientConfig中配置proxy参数，通过HTTP代理访问护栏服务。 - 企业网络要求所有外网请求通过代理 - 需要通过抓包工具（Fiddler/Charles/Nginx）调试请求 - 服务端在内网，需通过代理网关转发 接入示例如下所示： ``` import com.huawei.aiguard.client.AiGuardClient; import com.huawei.aiguard.config.ClientConfig; import com.huawei.aiguard.model.DetectResult; import java.nio.file.Files; import java.nio.file.Paths; import java.util.Base64; ClientConfig config = ClientConfig.builder() .baseUrl("https://aiguard.huaweicloudwaf.cn") .projectId("YOUR_PROJECT_ID") .appId("YOUR_APP_ID") .verifySsl(false) // 当前版本默认不验证服务端证书 .proxy("http://127.0.0.1:8888") // HTTP 代理地址 .logLevel("ERROR") .build(); try (AiGuardClient client = new AiGuardClient("YOUR_AK", "YOUR_SK", config)) { // 文本检测（经代理） DetectResult result = client.textDetect("你好，今天天气怎么样？", null); System.out.println("结果: " + result.getSuggestion()); // 图像检测（经代理） byte[] imageBytes = Files.readAllBytes(Paths.get("/path/to/image.png")); String imageData = Base64.getEncoder().encodeToString(imageBytes); DetectResult imgResult = client.imageDetect(imageData, null); System.out.println("结果: " + imgResult.getSuggestion()); } ``` ![](https://support.huaweicloud.com/usermanual-waf/public_sys-resources/note_3.0-zh-cn.png) - proxy仅支持HTTP/HTTPS协议代理，格式为http://host:port 或 https://host:port。 - 使用代理时，SDK 默认不验证服务端证书（verifySsl(false)），后续版本将支持证书验证。 - 配置 proxy 后，SDK的所有请求（包括文本检测和图像检测）都会经过代理。 **日志配置** 如果SDK要使用SLF4J 2.x作为日志门面，业务方必须提供SLF4J实现，否则日志不会输出（SLF4J会打印警告并回退到NOP）。 - **日志级别设置** ： 通过ClientConfig.logLevel参数控制SDK日志级别： | 级别 | 参数值 | 说明 | |:---|:---|:---| | DEBUG | .logLevel("DEBUG") | 输出请求/响应详情、重试过程等，用于问题排查。 | | INFO | .logLevel("INFO") | 输出常规操作日志（默认）。 | | ERROR | .logLevel("ERROR") | 仅输出错误日志。 | - **日志输出到文件** ： SDK不管理日志写入位置，由业务方通过SLF4J实现自行配置。默认输出到控制台。 ![](https://support.huaweicloud.com/usermanual-waf/public_sys-resources/note_3.0-zh-cn.png) SDK只负责日志输出，不管理日志写入位置。日志路径和格式由业务方选择的SLF4J实现决定。例如logback通过logback.xml配置，slf4j-simple通过JVM参数配置。 ``` // 仅输出到控制台（默认行为，无需额外配置） ClientConfig config = ClientConfig.builder() .baseUrl("YOUR_BASE_URL") .projectId("YOUR_PROJECT_ID") .appId("YOUR_APP_ID") .logLevel("DEBUG") .build(); ``` - **方式1：使用 logback（推荐，生产环境）** 在pom.xml中添加依赖： ``` ch.qos.logback logback-classic 1.4.11 ``` 在src/main/resources/logback.xml中配置日志格式和输出： ``` %d{yyyy-MM-dd HH:mm:ss.SSS} - %logger{36} - %level - %msg%n /path/to/sdk.log %d{yyyy-MM-dd HH:mm:ss.SSS} - %logger{36} - %level - %msg%n ``` - **方式2：使用 slf4j-simple（快速测试）** 在pom.xml中添加依赖： ``` org.slf4j slf4j-simple 2.0.13 test ``` 通过命令行JVM参数配置日志级别和输出位置： ``` # 日志输出到控制台（DEBUG级别） java "-Dorg.slf4j.simpleLogger.defaultLogLevel=DEBUG" \ -cp "your-app.jar:aiguard-sdk-0.1.0-with-dependencies.jar:slf4j-simple-2.0.13.jar" \ com.example.YourMain # 日志输出到文件 java "-Dorg.slf4j.simpleLogger.defaultLogLevel=DEBUG" \ "-Dorg.slf4j.simpleLogger.logFile=/path/to/sdk.log" \ -cp "your-app.jar:aiguard-sdk-0.1.0-with-dependencies.jar:slf4j-simple-2.0.13.jar" \ com.example.YourMain ``` ![](https://support.huaweicloud.com/usermanual-waf/public_sys-resources/caution_3.0-zh-cn.png) - slf4j-simple版本必须与SDK中的slf4j-api版本匹配（2.x）。使用1.7.x版本会导致 "No SLF4J providers were found" 错误，因为SLF4J 2.x会忽略1.7.x的绑定。 - SDK已内置AK/SK脱敏，日志中密钥字段统一显示为 \*\*\*。但业务方自身的日志代码需注意不要打印实际密钥值。 - **日志输出示例** ： ``` 2026-06-17 10:30:00.123 - com.huawei.aiguard.http.HttpClient - INFO - AiGuardClient initialized - projectId=c12d..., appId=a5ca... 2026-06-17 10:30:00.456 - com.huawei.aiguard.http.HttpClient - DEBUG - POST https://aiguard.huaweicloudwaf.cn/v1/.../text-detect 2026-06-17 10:30:01.789 - com.huawei.aiguard.http.HttpClient - DEBUG - Response status: 200 2026-06-17 10:30:01.789 - com.huawei.aiguard.http.HttpClient - DEBUG - Request successful - requestId=20260617... 2026-06-17 10:30:02.000 - com.huawei.aiguard.http.HttpClient - INFO - AiGuardClient closed ``` **SSL配置** 当前版本SDK默认不验证服务端证书（verifySsl(false)），证书验证功能将在后续版本支持。 ``` // 当前版本：不验证服务端证书（默认） ClientConfig config = ClientConfig.builder() .baseUrl("https://aiguard.huaweicloudwaf.cn") .projectId("YOUR_PROJECT_ID") .appId("YOUR_APP_ID") // verifySsl(false) 为默认值，无需显式配置 .build(); ``` ![](https://support.huaweicloud.com/usermanual-waf/public_sys-resources/note_3.0-zh-cn.png) 不验证服务端证书意味着SDK不会校验服务端身份，存在中间人攻击风险。该配置仅适用于当前版本，后续版本将默认开启证书验证。 **接入异常处理** ``` import com.huawei.aiguard.exception.*; try { DetectResult result = client.textDetect("内容", null); } catch (AiGuardValidationException e) { // 参数错误，不重试 // 子类包括： // AiGuardAppDisabledException — 应用已禁用（MAF.1007） // AiGuardUnsupportedUrlException — 不支持的 URL（MAF.1001） // AiGuardMediaTypeException — 不支持的媒体类型（MAF.1002） // AiGuardImageFormatException — 图像格式错误（MAF.1300/1304） // AiGuardImageParseException — 图像解析失败（MAF.1301/1303） // AiGuardImageDownloadException — 图像下载失败（MAF.1302） // AiGuardImageSizeException — 图像大小超限（MAF.1305） } catch (AiGuardAuthenticationException e) { // AK/SK 认证失败（MAF.1004），不重试 } catch (AiGuardRateLimitException e) { // 限流，SDK 自动重试后仍失败 } catch (AiGuardServerException e) { // 服务端异常，e.getErrorCode() / e.getErrorMsg() } catch (AiGuardTimeoutException e) { // 请求超时 } catch (AiGuardNetworkException e) { // 网络异常 } catch (AiGuardException e) { // 其他 SDK 异常兜底 } ``` **接入验证清单** | 序号 | 验证项 | 方法 | 预期结果 | |:---|:---|:---|:---| | 1 | 依赖解析成功 | mvn dependency:resolve | 无报错 | | 2 | 客户端初始化成功 | new AiGuardClient(ak, sk, config) | 无报错 | | 3 | 缺少ak抛异常 | new AiGuardClient("", sk, config) | 抛AiGuardMissingParamException | | 4 | 文本检测正常 | client.textDetect("你好", null) | 返回DetectResult | | 5 | 空内容抛异常 | client.textDetect("", null) | 抛AiGuardValidationException | | 6 | 图像检测正常 | client.imageDetect(imageData, null) | 返回DetectResult | | 7 | try-with-resources释放 | 退出try块 | 日志输出closed | | 8 | 日志无 AK/SK 泄漏 | DEBUG级别检查日志 | 日志中不含AK/SK明文 | **查看版本号** 版本号嵌入在包元数据中，可通过以下方式查看： ``` # 方式一：jar 内 pom.properties unzip -p aiguard_java_sdk.jar META-INF/maven/com.huawei/aiguard-sdk/pom.properties | grep version # 方式二：jar 内 MANIFEST.MF unzip -p aiguard_java_sdk.jar META-INF/MANIFEST.MF | grep Implementation-Version ``` #### 卸载方案 SDK的安全设计原则决定了AK/SK仅通过构造函数显式传入，SDK自身**不会存储、缓存或持久化**任何凭证信息。因此卸载时无需从SDK内部清理凭证，但需要检查业务代码中是否残留了AK/SK。 #### 卸载流程 SDK卸载流程分为4个步骤，按序执行即可。其中步骤一、步骤二为必选操作，步骤三为安全检查，步骤为回归验证。 ![](https://support.huaweicloud.com/usermanual-waf/public_sys-resources/note_3.0-zh-cn.png) 关于凭证安全，需要特别强调：**AI安全护栏SDK在设计上不存储、不缓存、不持久化AK/SK** 。AK/SK仅通过AiGuardClient(ak, sk, config) 构造函数显式传入，保存在Client实例的私有字段中，Client关闭后随对象一起被 GC回收。SDK不会将AK/SK写入文件、不会读取环境变量、不会在日志中输出实际密钥值（日志中统一脱敏为\*\*\*）。因此卸载时**不需要从SDK内部"清理凭证"** ，但需要检查**业务方自己的代码、配置文件、环境变量和日志**中是否残留了AK/SK。如果发现AK/SK曾泄露到代码仓库或日志中，应前往云管理控制台轮换凭证（禁用旧的、生成新的）。 图1卸载流程 ![](https://support.huaweicloud.com/usermanual-waf/zh-cn_image_0000002660079693.png "点击放大") #### 卸载方案 SDK的安全设计原则决定了AK/SK仅通过构造函数显式传入，SDK自身**不会存储、缓存或持久化**任何凭证信息。因此卸载时无需从SDK内部清理凭证，但需要检查业务代码中是否残留了AK/SK。 - [卸载Python SDK] 1. 停止使用SDK，移除代码引用。 在卸载依赖之前，必须先移除所有对SDK的代码调用，否则卸载后项目会报ModuleNotFoundError。 ``` # 第一步：搜索项目中所有 SDK 引用，确认影响范围 grep -rn "from aiguard" --include="*.py" . grep -rn "import aiguard" --include="*.py" . # 输出示例： # src/main.py:3:from aiguard import AiGuardClient, ClientConfig # src/main.py:20:from aiguard.exceptions import AiGuardException # src/utils/check.py:5:from aiguard import TextDetectOptions ``` 逐个打开搜索到的文件，删除以下内容： - from aiguard import ... 或 import aiguard 语句 - AiGuardClient(...) 实例化代码 - client.text_detect(...) / client.image_detect(...) 调用代码 - client.close() 或 with AiGuardClient(...) as client: 相关代码 - 所有 AiGuardXxxException 的 try/except 块（或改为业务自身异常处理） 2. 卸载SDK包。 ``` # 卸载 aiguard 包 pip uninstall aiguard -y # 输出示例： # Found existing installation: aiguard- # Uninstalling aiguard-: # Successfully uninstalled aiguard- ``` 如果项目中没有其他地方使用如下库，清理随aiguard自动安装的依赖： ``` # 先检查 httpx 是否被其他包依赖 pip show httpx # 输出中的 "Required-by:" 字段会显示谁依赖了它 # 如果 "Required-by:" 为空或只有 aiguard，说明可以安全卸载 pip uninstall httpx -y # httpx 的子依赖也可以一并清理（按需） pip uninstall httpcore sniffio anyio h11 -y ``` ![](https://support.huaweicloud.com/usermanual-waf/public_sys-resources/note_3.0-zh-cn.png) 如果项目中有其他库也依赖httpx（如respx、httpx-socks等），则不要卸载httpx，只卸载aiguard即可。 3. 检查凭证残留。 SDK不会存储AK/SK，但业务方可能在以下位置写入了凭证，需逐一检查： | 检查位置 | 说明 | 检查方法 | |:---|:---|:---| | 业务代码 | AK/SK 是否硬编码在Python源码中 | grep -rn "AK\\\|SK\\\|access_key\\\|secret_key" --include="\*.py" . | | 环境变量 | 是否通过 os.environ\["AIGUARD_AK"\] 等方式注入 | 检查 .env 文件、Docker compose、K8s ConfigMap、CI/CD 变量 | | 配置文件 | 是否在yaml/json/ini中配置了AK/SK | grep -rn "aiguard\\\|ak:\\\|sk:" --include=".yaml" --include=".yml" --include="\*.json" . | | 日志文件 | SDK 已内置脱敏，但业务方自身日志是否打印了AK/SK | 检查应用日志输出，搜索是否有类似 AKX\*\*\* 之外的实际密钥值 | | Git 历史 | AK/SK是否曾被提交到代码仓库 | git log -p --all -S "YOUR_AK_VALUE" -- "\*.py" 替换为实际值搜索 | ![](https://support.huaweicloud.com/usermanual-waf/public_sys-resources/note_3.0-zh-cn.png) 如果发现AK/SK曾泄露到Git历史，不能仅删除代码，还需使用git filter-branch或bfg-repo-cleaner从历史中彻底清除，然后在云控制台轮换凭证。 4. 验证是否已完成卸载。 ``` # 验证1：确认包已卸载 python -c "import aiguard" # 预期输出: ModuleNotFoundError: No module named 'aiguard' # 验证2：确认包列表中无 aiguard pip list | grep aiguard # 预期输出: （无结果） # 验证3：项目可以正常运行 python -m pytest tests/ -v # 或 python your_main_script.py ``` - [卸载Java SDK] 1. 停止使用SDK，移除代码引用。 ``` # 搜索项目中所有 SDK 引用 grep -rn "com.huawei.aiguard" --include="*.java" . grep -rn "AiGuardClient" --include="*.java" . # 输出示例： # src/main/java/com/example/Service.java:5:import com.huawei.aiguard.client.AiGuardClient; # src/main/java/com/example/Service.java:20: private AiGuardClient client; ``` 逐个删除： - import com.huawei.aiguard.\*语句 - AiGuardClient声明和实例化 - client.textDetect(...) / client.imageDetect(...) 调用 - client.close() 或 try-with-resources 中的 AiGuardClient 引用 - AiGuardXxxException 的catch块 2. 打开项目根目录的pom.xml，找到并删除aiguard-sdk依赖： ``` com.huawei aiguard-sdk ${aiguard-sdk.version} ``` 删除后，Maven不会再拉取aiguard-sdk及其传递依赖。执行以下命令让变更生效： ``` # 刷新依赖，移除 aiguard-sdk 及其独占的传递依赖 mvn dependency:resolve # 如果使用 IDE（IntelliJ IDEA），刷新 Maven 项目： # 右键 pom.xml -> Maven -> Reload Project # 或点击 IDE 右侧 Maven 面板的刷新按钮 ``` 关于传递依赖的处理：aiguard-sdk声明了OkHttp、Jackson、SLF4J作为传递依赖。移除aiguard-sdk后： | 传递依赖 | 是否自动移除 | 说明 | |:---|:---|:---| | OkHttp 4.12.0 | 自动移除（如无其他组件依赖） | Maven依赖传递机制会自动清理 | | Jackson 2.15.3 | 自动移除（如无其他组件依赖） | Maven依赖传递机制会自动清理 | | SLF4J API 2.0.9 | 不会移除 | SLF4J 是日志门面，通常被其他库也依赖 | 确认传递依赖状态： ``` # 查看当前依赖树，确认 aiguard-sdk 已移除 mvn dependency:tree | grep -i aiguard # 预期输出: （无结果，说明已完全移除） # 检查 OkHttp/Jackson 是否还在（可能被其他组件依赖） mvn dependency:tree | grep -E "okhttp|jackson" # 如有输出，说明项目中其他组件也在使用，无需额外处理 ``` 3. 检查凭证残留。 SDK不会存储AK/SK，但业务方可能在以下位置写入了凭证，需逐一检查： | 检查位置 | 说明 | 检查方法 | |:---|:---|:---| | Java源码 | AK/SK是否硬编码在Java代码中 | grep -rn "ak\\\|sk\\\|accessKey\\\|secretKey" --include="\*.java" . | | 配置文件 | 是否在application.yml/properties中配置 | grep -rn "aiguard\\\|ak:\\\|sk:" --include=".yml" --include=".properties" . | | 环境变量 | 是否通过System.getenv("AIGUARD_AK") 等方式注入 | 检查Docker/K8s/CI配置 | | 日志配置 | logback/log4j2中是否配置了aiguard 包的logger | 检查 logback.xml、log4j2.xml | | 日志文件 | SDK 已内置脱敏，但业务方日志是否打印了实际密钥值 | 检查应用日志输出 | | Git历史 | AK/SK是否曾被提交 | git log -p --all -S "YOUR_AK_VALUE" -- "*.java" "*.xml" "\*.properties" | 4. 验证是否已完成卸载。 ``` # 验证1：Maven 编译通过（确认代码中无 SDK 引用残留） mvn clean compile # 预期: BUILD SUCCESS # 验证2：依赖树中无 aiguard mvn dependency:tree | grep aiguard # 预期输出: （无结果） # 验证3：测试通过 mvn test # 预期: BUILD SUCCESS ``` #### 卸载后检查清单 | 序号 | 检查项 | Python 验证方式 | Java 验证方式 | 通过标准 | |:---|:---|:---|:---|:---| | 1 | 代码中无SDK引用 | grep -rn "from aiguard" --include="\*.py" . 无结果 | grep -rn "com.huawei.aiguard" --include="\*.java" . 无结果 | 无输出 | | 2 | 依赖已移除 | pip list \\\| grep aiguard 无结果 | mvn dependency:tree \\\| grep aiguard 无结果 | 无输出 | | 3 | 项目可正常编译、运行 | python your_main.py 无报错 | mvn clean compile BUILD SUCCESS | 无报错 | | 4 | 测试通过 | pytest tests/ -v 全部通过 | mvn test BUILD SUCCESS | 全部通过 | | 5 | 业务代码无AK/SK硬编码 | grep 搜索源码无实际密钥值 | grep 搜索源码无实际密钥值 | 无泄露 | | 6 | 配置文件中无SDK配置 | 检查 .env/yaml/json | 检查 application.yml/properties | 无残留 | | 7 | 日志文件中无敏感信息 | 检查应用日志输出 | 检查应用日志输出 | 无泄露 | | 8 | 已泄露的AK/SK已轮换 | 在云管理控制台操作 | 在云管理控制台操作 | 旧凭证已禁用 |