SDK 接入配置

本文通过一个完整的非流式文本内容安全检测示例，帮助您在开发项目中完成 SDK 初始化、构造检测请求并解析返回结果。

场景介绍

• 目标：检测一段文本是否合规，并返回判定结果，用于阻断不合规内容。

• 输入：带上下文的文本消息（如用户提示词或模型响应内容），可包含多条历史消息。

• 输出：结构化结果，包含：

  • MsgId：消息标识

  • Decision.Action：决策类型（pass / block / observe / mask / answer）

  • Decision.Score：综合风险分，范围 [0, 1]

  • RiskInfo.Risks：命中的检测分类等详细信息

注意事项

• 接入方式：仅支持通过 SDK 方式接入的配置ID，通过其他方式接入的应用在 SDK 调用中不生效。

• 地域一致性：初始化时传入的 region 参数必须与实例所属地域保持一致。

• 权限要求：子账号至少需具备 AccessKey。其他控制台操作权限说明请参见「开通服务」。

实现流程

1. 安装 SDK

下载并安装 SDK，详情请参见「SDK 安装和初始化」。

2. 初始化客户端

通过环境变量或配置文件提供 Endpoint、AccessKey、SecretKey、AppID 和 Region 等参数。详情请参见「SDK 安装和初始化」。

3. 构造检测请求

设置 Message（单条待检内容），包含以下字段：

4. 发送请求并处理响应

调用 CheckModerateSend 接口获取检测结果，根据 Decision.Action 执行相应处理：

完整示例代码

package main

import (
	"fmt"
	"os"

	kmaf "github.com/kingsoftcloud/sdk-go/v2/ksyun/client/kmaf/v20260130"
	"github.com/kingsoftcloud/sdk-go/v2/ksyun/common"
	"github.com/kingsoftcloud/sdk-go/v2/ksyun/common/profile"
)

func main() {
	// 1. 初始化凭证（建议从环境变量读取）
	ak := os.Getenv("KSYUN_AK")
	sk := os.Getenv("KSYUN_SK")
	if ak == "" || sk == "" {
		ak = "KSYUN_AK_HERE"
		sk = "KSYUN_SK_HERE"
	}
	credential := common.NewCredential(ak, sk)

	// 2. 客户端配置
	cpf := profile.NewClientProfile()
	cpf.HttpProfile.ReqMethod  = "POST"
	cpf.HttpProfile.ReqTimeout = 10
	cpf.HttpProfile.Endpoint   = "kmaf.api.ksyun.com"

	// 3. 创建客户端
	client, err := kmaf.NewClient(credential, "cn-beijing-6", cpf)
	if err != nil {
		fmt.Printf("NewClient error: %s\n", err)
		return
	}

	// 4. 构造检测请求
	req := kmaf.NewCheckModerateRequest()
	req.AppId = common.StringPtr("your-app-id")
	req.MsgId = common.StringPtr("quickstart-msg-001")
	req.UseStream = common.IntPtr(0) // 非流式检测
	req.Message = &kmaf.CheckModerateMessage{
		Role:        common.StringPtr("user"),
		Content:     common.StringPtr("这是一条待检测的文本内容"),
		ContentType: common.IntPtr(1), // 1-文本，2-图片
	}
	// 可选：添加关联上下文
	req.History = []*kmaf.CheckModerateHistory{
		{
			Role:        common.StringPtr("assistant"),
			Content:     common.StringPtr("你好！有什么可以帮你的？"),
			ContentType: common.IntPtr(1), // 1-文本
		},
	}

	// 5. 发送请求并处理响应
	resp, err := client.CheckModerateSend(req)
	if err != nil {
		fmt.Printf("CheckModerate error: %s\n", err)
		return
	}

	// 6. 解析结果
	action := ""
	if resp.Data.Decision.Action != nil {
		action = *resp.Data.Decision.Action
	}
	fmt.Printf("检测完成，MsgId: %s, 决策: %s\n", *resp.Data.MsgId, action)

	switch action {
	case "pass":
		fmt.Println("✅ 内容安全，直接放行")
	case "block":
		fmt.Println("❌ 内容违规，已被拦截")
		// 打印风险详情
		for _, risk := range resp.Data.RiskInfo.Risks {
			if risk.Category != nil {
				fmt.Printf("  - 风险分类: %s\n", *risk.Category)
			}
		}
	case "observe":
		fmt.Println("⚠  命中策略，仅记录不拦截")
	case "mask":
		fmt.Println("? 返回脱敏后内容")
		if resp.Data.Decision.Masked != nil {
			fmt.Printf("脱敏内容: %+v\n", resp.Data.Decision.Masked)
		}
	case "answer":
		fmt.Println("? 需调用安全代答接口")
		// 调用 QueryAnswer 获取安全代答
		queryReq := kmaf.NewQueryAnswerRequest()
		queryReq.AppId = req.AppId
		queryReq.MsgId = req.MsgId
		queryReq.UseStream = common.IntPtr(0)
		queryResp, _ := client.QueryAnswerSend(queryReq)
		if queryResp != nil && queryResp.Data.Message.Content != nil {
			fmt.Printf("安全代答: %s\n", *queryResp.Data.Message.Content)
		}
	default:
		fmt.Printf("未知决策类型: %s\n", action)
	}
}

运行结果示例

检测完成，MsgId: quickstart-msg-001, 决策: pass
内容安全，直接放行