本文面向需要在深度伪造场景中定位风险具体位置并解释检测原因的开发人员与安全运营人员。大模型应用防火墙 SDK 在返回检测结果的同时，可通过 Position 标记疑似伪造区域，并通过 SourceInfos.SourceDetail.interpretation 提供检测原因，帮助审核人员快速定位可疑内容并完成人工核查。本文以图片检测为主，说明 SDK 接入、调用、结果解析与日志核对方法。 # 适用范围本教程重点说明深度伪造检测结果的定位和原因解释能力。SDK 返回风险分类与处置决策时，还可以返回疑似风险区域的位置坐标和自然语言检测依据，供审核工作台标记可疑画面并展示复核线索。该信息用于辅助人工判断，不应单独作为素材真实性的最终结论。 |适合 |典型用途 | |---|---| |人工核查辅助 |在审核界面标记疑似伪造区域，并展示检测原因 | |风险前置拦截 |在理赔、风控、内容治理等环节识别高风险素材 | |复核系统集成 |把标签、概率、解释和位置回传给审核工作台 | # 接入前准备 ## 账号、实例与 SDK * 已购买大模型应用防火墙实例，并开通伪造内容检测能力。 * 已按官方[SDK 安装和初始化](https://www.volcengine.com/docs/84990/1827488?lang=zh)完成对应语言的依赖安装。 * 已准备火山引擎账号的 Access Key ID（AK）和 Secret Access Key（SK）。不要把真实密钥提交到代码仓库或输出到日志。 * 已确认实例地域。`myUrl`、`region` 与资产所属地域必须一致。 * 应用运行环境能够访问实例对应的 SDK 服务地址。 > **说明** > 示例中的 AK、SK、AppID 和本地文件路径均为占位值。生产环境应从密钥管理系统或受控环境变量读取凭据，并限制最小可用权限。 ## 支持的检测素材调用 SDK 前，请先确认图片素材格式和大小满足要求。 * **格式**：支持 `jpg`、`jpeg`、`png`、`webp`。 * **大小**：单张不超过 10 MB。 * **Base64 前缀**：图片通常可直接传 Base64 字符串，无需额外添加 MIME 前缀；如果您的业务侧统一使用 Data URI，也可分别使用以下前缀： * `jpg`、`jpeg`：`data:image/jpeg;base64,` * `png`：`data:image/png;base64,` * `webp`：`data:image/webp;base64,` > **说明** > 优先使用原始素材。多次压缩、截图转存或二次编辑可能损失检测所需的细节。 # 步骤一创建检测资产 1. 登录[大模型应用防火墙控制台](https://console.volcengine.com/omni-shield/llm-shield)。 2. 在左侧导航栏，选择**资产管理**，然后单击**添加资产**。 3. 配置以下参数并单击**提交**。 * **接入方式**：SDK 接入。 * **应用名称**：以 deepfake_demo 为例。 * **防护场景**：伪造内容检测。 > **说明** > 若页面中没有“伪造内容检测”选项，先确认实例是否已购买或开通对应能力。SDK 调用只应使用通过 SDK 方式接入的资产 AppID；其他接入方式的资产可能不生效。 ![图片](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/d3fde7473b364d92bd81ef9af597c0c4~tplv-goo7wpa0wc-topic.webp) 4. 返回控制台，获取资产 `AppID`，作为 `scene` 参数值。 ![图片](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/8fd0a3c7013846efbb6e071dbd4dcf21~tplv-goo7wpa0wc-topic.webp) # 步骤二准备配置参数 |参数 |示例 |说明 | |---|---|---| |`myUrl` |`https://cn-beijing.sdk.access.llm-shield.omini-shield.com` |大模型应用防火墙对外提供的服务地址，形如`https://{region}.sdk.access.llm-shield.omini-shield.com`，其中 region 为您购买的实例所属地域。

* 华北2（北京）：cn\-beijing

* 华东2（上海）：cn\-shanghai | |`ak` / `sk` |`AK********` / `SK********` |火山引擎账号的 **Access Key ID** 和 **Secret Access Key**。获取说明请参见 [Access Key（密钥）管理](https://www.volcengine.com/docs/6291/65568)。 | |`appid` |`app-********` |资产的唯一标识，完成控制台接入配置后，系统将自动生成 AppID。对应[检测输入或输出内容是否合规](https://docs.volcengine.com/docs/84990/1827500)中的`scene`。可前往[大模型应用防火墙控制台](https://console.volcengine.com/omni-shield/llm-shield/)资产管理模块，查看已通过 SDK 方式接入的资产 AppID。 | |`region` |`cn-beijing` |**资产**所属地域，与 myUrl 中的 region 保持一致。

* 华北2（北京）：cn\-beijing

* 华东2（上海）：cn\-shanghai | |`image_file` |`/Users/DeepFakeTest/image_001.png` |待检测对象的本地路径。 | |`message.role` |`user` |内容来源。可选值包括 `user`、`assistant`。对于用户上传的图片或视频，建议传入 `user`。 | |`message.contenttype` |`IMAGE` |内容类型。在 SDK 中通常对应枚举值 `ContentTypeV2.IMAGE` 和 `ContentTypeV2.VIDEO`。 | # 步骤三调用 SDK **Python** ```Python #!/usr/bin/env python3 # -*- coding: utf-8 -*- import sys import base64 import mimetypes from pathlib import Path # 将本地 SDK 路径加入 sys.path 以便导入 SDK_ROOT = "/Users/xxxx/volcengine-python-sdk" if SDK_ROOT not in sys.path: sys.path.insert(0, SDK_ROOT) from volcenginesdkllmshield import * def main(): myUrl = "https://cn-beijing.sdk.access.llm-shield.omini-shield.com" ak = "AK**********" sk = "SK***********==" appid = "app-d*******" region = "cn-beijing" TIMEOUT = 50 # 超时时间（秒） # 发送请求并获取响应 client = ClientV2(myUrl, ak, sk, region, TIMEOUT) client.SetConnMax(100) imageFile = "/Users/xxxxx/multidata/df-2.png" deepImage = MultiPart(content = load_image_content("image", imageFile), content_type = ContentTypeV2.IMAGE) # 构建请求（使用 pydantic 模型） request = ModerateV2Request( scene=appid, # 资产的 AppId message=MessageV2( role="user", # 检测的内容来源，user-用户提示词；assistant-模型响应内容 multi_part = [deepImage], ), ) try: response = client.Moderate(request) # 使用 pydantic 的内置序列化方法 print("审核结果（JSON格式）:") print(response.model_dump_json(by_alias=True, indent=2)) # pydantic 模型直接转 JSON except Exception as e: print(f"请求失败: {e}") def load_image_content(ftype, image_file): """将文件内容编码为 data URI，支持图片、音频、视频及常见文档类型。参数: - ftype: 文件类型标识。可传扩展名（如 'jpg'、'mp4'、'pdf'），或 MIME（如 'image/jpeg'），或传入 'auto' 自动识别。 - image_file: 文件路径。返回: - 形如 "data:;base64," 的字符串。 """ # 读取字节 with open(image_file, 'rb') as f: file_bytes = f.read() # 常见扩展名到 MIME 的映射（覆盖更常用类型） EXT_TO_MIME = { # 图片 'jpg': 'image/jpeg', 'jpeg': 'image/jpeg', 'png': 'image/png', 'gif': 'image/gif', 'bmp': 'image/bmp', 'webp': 'image/webp' } # 规范化 ftype normalized_ftype = (ftype or '').strip().lower() # 优先使用显式 MIME if '/' in normalized_ftype: mime = normalized_ftype else: # 如果传入扩展名，先用映射表 if normalized_ftype in EXT_TO_MIME: mime = EXT_TO_MIME[normalized_ftype] else: # 自动或未知类型时，基于文件名猜测 suffix = Path(image_file).suffix.lower().lstrip('.') mime = EXT_TO_MIME.get(suffix) if not mime: guessed, _ = mimetypes.guess_type(image_file) mime = guessed or 'application/octet-stream' base64_str = base64.b64encode(file_bytes).decode('utf-8') data_uri = f"data:{mime};base64,{base64_str}" return data_uri if __name__ == "__main__": main() ``` **Java** ```Java package org.example; import java.io.IOException; import java.nio.file.Files; import java.nio.file.Path; import java.nio.file.Paths; import java.util.Base64; import java.util.HashMap; import java.util.Map; import com.volcengine.llmshield.*; public class Main { private static final Map EXT_TO_MIME = new HashMap<>(); static { EXT_TO_MIME.put("jpg", "image/jpeg"); EXT_TO_MIME.put("jpeg", "image/jpeg"); EXT_TO_MIME.put("png", "image/png"); EXT_TO_MIME.put("gif", "image/gif"); EXT_TO_MIME.put("bmp", "image/bmp"); EXT_TO_MIME.put("webp", "image/webp"); EXT_TO_MIME.put("tiff", "image/tiff"); } public static String buildDataBase64(String filePath) throws IOException { Path path = Paths.get(filePath); byte[] fileBytes = Files.readAllBytes(path); String base64Str = Base64.getEncoder().encodeToString(fileBytes); return "data:" + resolveMimeType(path) + ";base64," + base64Str; } public static ContentTypeV2 resolveContentType(String filePath) throws IOException { String mime = resolveMimeType(Paths.get(filePath)); if (mime.startsWith("image/")) { return ContentTypeV2.IMAGE; } if (mime.startsWith("video/")) { return ContentTypeV2.VIDEO; } return ContentTypeV2.FILE; } private static String resolveMimeType(Path path) throws IOException { String mime = Files.probeContentType(path); if (mime != null && !mime.isBlank()) { return mime; } String fileName = path.getFileName().toString(); int dotIndex = fileName.lastIndexOf('.'); if (dotIndex >= 0 && dotIndex < fileName.length() - 1) { String extension = fileName.substring(dotIndex + 1).toLowerCase(); String mappedMime = EXT_TO_MIME.get(extension); if (mappedMime != null) { return mappedMime; } } return "application/octet-stream"; } public static void main(String[] args) throws IOException { String myUrl = "https://cn-beijing.sdk.access.llm-shield.omini-shield.com"; String ak = "AK**********"; String sk = "SK*******=="; String myAppID = "app-**********"; String region = "cn-beijing"; String image_file = "/Users/xxxxxx/df-2.png"; long timeout = 50000; // 超时时间，单位毫秒 ApiClient client = ApiClient.New(myUrl, ak, sk, region, timeout, "", 100); ModerateV2Request request = new ModerateV2Request(); request.setScene(myAppID); // 设置检测内容 MessageV2 message = new MessageV2(); message.setRole("user"); // 检测的内容来源，user-用户提示词；assistant-模型响应内容 String fileContent = buildDataBase64(image_file); MultiPart contPartTxt = new MultiPart(); contPartTxt.setContent(fileContent); contPartTxt.setContentType(resolveContentType(image_file)); message.appendMultiPart(contPartTxt); request.setMessage(message); try { // 调用 Moderate 接口进行检查 ModerateV2Response response = client.Moderate(request ); if (response != null) { System.out.println("response: " + response); } } catch (Exception e) { e.printStackTrace(); } } } ``` **Go** ```Go func main() { var ( err error response *llmshield.ModerateV2Response ) request := llmshield.ModerateV2Request{ Message: nil, Scene: appid, } //创建客户端实例 client := llmshield.NewAdvanced(myUrl, ak, sk, region, TimeOut, proxy, connMax) if client == nil { fmt.Printf("Failed to create client instance\n") return } request.Message = filledMsgContent(role) start := time.Now() response, err = client.Moderate(&request) if err != nil { fmt.Printf("Error occurred while checking LLM response stream: %v\n", err) } if response == nil { fmt.Println("Received empty result") } fmt.Printf("Received result: %s\n", response.String()) fmt.Printf("UsedTime: %vms\n", time.Since(start).Milliseconds()) } func filledMsgContent(role string) *llmshield.MessageV2 { var ( err error content string ) msg_multi := &llmshield.MessageV2{ Role: role, } for dataInfo, cGroup := range dataMap { switch cGroup.Dtype { case llmshield.ContentTypeV2_TEXT: content = dataInfo case llmshield.ContentTypeV2_IMAGE, llmshield.ContentTypeV2_FILE: content, err = encodeFileToBase64(cGroup.ftype, dataInfo) if err != nil { fmt.Printf("Failed to encode file content:%v,err:%v\n", content, err) } } multPart := &llmshield.MultiPart{ Content: content, ContentType: cGroup.Dtype, } msg_multi.MultiPart = append(msg_multi.MultiPart, multPart) } return msg_multi } func encodeFileToBase64(ftype string, filePath string) (string, error) { data, err := os.ReadFile(filePath) if err != nil { return "", fmt.Errorf("读取文件失败: %v", err) } base64Str := base64.StdEncoding.EncodeToString(data) switch ftype { case "doc": base64Str = "data:application/msword;base64," + base64Str case "docx": base64Str = "data:application/vnd.openxmlformats-officedocument.wordprocessingml.document;base64," + base64Str case "txt": base64Str = "data:text/plain;base64," + base64Str case "xls": base64Str = "data:application/vnd.ms-excel;base64," + base64Str case "xlsx": base64Str = "data:application/vnd.openxmlformats-officedocument.spreadsheetml.sheet;base64," + base64Str case "pdf": base64Str = "data:application/pdf;base64," + base64Str } if len(base64Str) > 50 { fmt.Printf("Headfile: %v\n", strings.Split(base64Str[:50], "base64,")[0]) } return base64Str, nil } ``` # 步骤四分析响应结果 ## 原始响应 ```JavaScript 审核结果（JSON格式）: { "ResponseMetadata": { "Error": { "Code": "", "CodeN": "", "Message": "" }, "RequestId": "02178763817827300000000000000000000ffff0a0800432e41cf", "Service": "llmshield_dev", "Action": "Moderate", "Version": "2025-08-31", "Region": "cn-beijing" }, "Result": { "MsgID": "b181a7654fe8488b9d2a1decf01f2ccf", "RiskInfo": { "Risks": [ { "Category": "109", "Label": "10903000", "Prob": 0.5761031141647925, "Matches": [ { "Word": "", "Action": null, "Source": 0, "RuleID": null, "Position": { "ImagePosition": { "xStart": "127", "yStart": "406", "xEnd": "367", "yEnd": "626" } } } ], "SourceInfos": [ { "Source": "module_aigc_ps", "SourceDetail": { "interpretation": "结论：这张图像是AIGC生成的伪造图像。 \n1. 电脑机箱的玻璃侧板存在明显的不自然裂纹，裂纹从中心向外呈放射状扩展，但裂纹的走向和密度在不板和线缆在玻璃面板的反射中呈现异常的、不连续的光晕和高亮，且反射的细节与周围环境的光照不匹配，出现局部的“漂白”和“过曝”伪影，这在真实拍摄中难以出现。" } } ] }, { "Category": "109", "Label": "10902000", "Prob": 0.9876612820094679, "Matches": [ { "Word": "", "Action": null, "Source": 0, "RuleID": null, "Position": { "ImagePosition": { "xStart": "127", "yStart": "406", "xEnd": "367", "yEnd": "626" } } } ], "SourceInfos": [ { "Source": "module_aigc_ps", "SourceDetail": { "interpretation": "结论：这张图像是AIGC生成的伪造图像。 \n1. 电脑机箱的玻璃侧板存在明显的不自然裂纹，裂纹从中心向外呈放射状扩展，但裂纹的走向和密度在不板和线缆在玻璃面板的反射中呈现异常的、不连续的光晕和高亮，且反射的细节与周围环境的光照不匹配，出现局部的“漂白”和“过曝”伪影，这在真实拍摄中难以出现。" } } ] } ] }, "Decision": { "DecisionType": 2, "DecisionDetail": { "BlockDetail": {}, "ReplaceDetail": { "Replacement": null } }, "DecisionStrategyID": null, "HitStrategyIDs": [ "rule-da65mfjmu2pc73dsd1cg", "rule-da65mfjmu2pc73dsd1cg" ] }, "PermitInfo": { "Permits": [] }, "ContentInfo": "png", "Degraded": false, "DegradeReason": "" } } ``` ## 关键字段说明 |参数 |示例值 |说明 | |---|---|---| |RiskInfo.Risks.Category |109 |风险一级分类，109 表示命中了深度伪造风险。 | |RiskInfo.Risks.Label |10900000 |命中的二级检测分类标签信息：

* 10900000：默认伪造

* 10901000：PS 伪造

* 10902000：伪造实体

* 10903000：伪造文本

* 10904000：伪造人脸 | |RiskInfo.Risks.Prob |1.0 |风险概率，表示检测内容属于该风险的可能性，取值范围为 0 到 1 之间。 | |RiskInfo.Risks.SourceInfos.Source |module_aigc_ps |返回检测来源标识。该值由实际参与检测或元数据解析的模块决定，不应在业务代码中假定为固定值。 | |RiskInfo.Risks.SourceInfos.Source.SourceDetail.interpretation |结论：这张图像是AIGC生成的伪造图像。 \n1. 电脑机箱的玻璃侧板存在明显的不自然裂纹，裂纹从中心向外呈放射状扩展，但裂纹的走向和密度在不板和线缆在玻璃面板的反射中呈现异常的、不连续的光晕和高亮，且反射的细节与周围环境的光照不匹配，出现局部的“漂白”和“过曝”伪影，这在真实拍摄中难以出现。 |自然语言解释，提供判断结论和详细的风险命中原因和说明。 | |RiskInfo.Risks.Matches.Position.ImagePosition |"xStart" : "127",

"yStart" : "406",

"xEnd" : "367",

"yEnd" : "626" |返回图片中命中风险的四个像素点位置：

* xStart：水平起点

* yStart：垂直起点

* xEnd：水平终点

* yEnd：垂直终点 | |Decision.DecisionType |2 |命中的策略动作，表示对该命中内容的处理动作：

* 1：通过，表示检测内容未命中深度伪造检测策略，直接放行

* 2：拦截，表示检测内容命中了深度伪造检测策略且被拦截 | |Decision.HitStrategyIDs |rule\-d87gnhdtmscn1mp2\*\*\*\* |命中策略 ID 列表，表示内容命中的所有策略。深度伪造检测场景内置检测策略（为固定 ID），其他自定义策略不会生效。 | |ContentInfo |png |风险内容的格式。

* 图片：支持 `jpg`、`jpeg`、`png`、`webp` | `SourceDetail` 还可能承载素材中解析出的来源或内容凭证元数据。该对象中的键由素材和生成工具决定，接入方应按 JSON 对象兼容读取未知字段，不要依赖固定键集合。内容凭证用于辅助判断素材来源：无凭证不等同于伪造，存在来源声明也不表示素材内容必然真实。 # 步骤五查看日志检测完成后，您还可以在控制台查看对应的深度伪造日志，便于后续审计和排查。 1. 登录[大模型应用防火墙控制台](https://console.volcengine.com/omni-shield/llm-shield)。 2. 在左侧菜单栏选择**攻击日志**。 3. 在**深度伪造日志**页签下，查看判别结果为**伪造**的日志。 ![图片](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/77d94d01873946cdaec4d4e879f4a205~tplv-goo7wpa0wc-topic.webp) # 常见问题 ## 鉴权失败或请求无法到达服务 * 确认 AK/SK 已正确注入，且没有多余空格、换行或过期值。 * 确认 `myUrl` 中的地域、`region` 和资产所属地域一致。 * 确认网络出口、代理和 DNS 可以访问对应服务地址。 ## 返回通过，但预期应命中风险 * 确认 `scene` 是“SDK 接入”且防护场景为“伪造内容检测”的资产 AppID。 * 确认素材格式受支持，传入的 `ContentType` 与实际内容一致。 * 优先用原始素材复测，避免压缩或转码导致细节丢失。 ## 日志中找不到调用记录确认调用使用了正确的 AppID，并检查“攻击日志”中的“深度伪造日志”页签。该页签用于查看判别结果为“伪造”的记录；若响应为通过，应结合调用侧日志核对。需要进一步定位时，可使用脱敏后的 RequestId、MsgID、资产 ID 和命中策略 ID 关联排查。