华为云用户手册

使用证书 证书用于终端设备与MQTT broker通信时鉴权。 下面是Go语言代码样例和Java语言代码样例，演示了如何使用证书做鉴权。 客户端不需要校验服务端证书，单向认证即可。 内置MQTT broker默认开启8883端口。 样例中的Go语言MQTT Client引用了github.com/eclipse/paho.mqtt.golang开源库。 客户端需要处理断连事件，实现掉线重连机制，提高连接可靠性。

Go语言代码样例 package main import ( "crypto/tls" "crypto/x509" "fmt" "math/rand" "sync" "time" MQTT "github.com/eclipse/paho.mqtt.golang" ) func main() { subClient := InitMqttClient(onSubConnectionLost) pubClient := InitMqttClient(onPubConnectionLost) wait := sync.WaitGroup{} wait.Add(1) go func() { for { time.Sleep(1*time.Second) pubClient.Publish("topic", 0, false, "hello world") } }() subClient.Subscribe("topic", 0, onReceived) wait.Wait() } func InitMqttClient(onConnectionLost MQTT.ConnectionLostHandler) MQTT.Client { pool := x509.NewCertPool() cert, err := tls.LoadX509KeyPair("/tmp/example_cert.crt", "/tmp/example_cert.key") if err != nil { panic(err) } tlsConfig := &tls.Config{ RootCAs: pool, Certificates: []tls.Certificate{cert}, // 单向认证，client不校验服务端证书 InsecureSkipVerify: true, } // 使用tls或者ssl协议，连接8883端口 opts := MQTT.NewClientOptions().AddBroker("tls://127.0.0.1:8883").SetClientID(fmt.Sprintf("%f",rand.Float64())) opts.SetTLSConfig(tlsConfig) opts.OnConnect = onConnect opts.AutoReconnect = false // 回调函数，客户端与服务端断连后立刻被触发 opts.OnConnectionLost = onConnectionLost client := MQTT.NewClient(opts) loopConnect(client) return client } func onReceived(client MQTT.Client, message MQTT.Message) { fmt.Printf("Receive topic: %s, payload: %s \n", message.Topic(), string(message.Payload())) } // sub客户端与服务端断连后，触发重连机制 func onSubConnectionLost(client MQTT.Client, err error) { fmt.Println("on sub connect lost, try to reconnect") loopConnect(client) client.Subscribe("topic", 0, onReceived) } // pub客户端与服务端断连后，触发重连机制 func onPubConnectionLost(client MQTT.Client, err error) { fmt.Println("on pub connect lost, try to reconnect") loopConnect(client) } func onConnect(client MQTT.Client) { fmt.Println("on connect") } func loopConnect(client MQTT.Client) { for { token := client.Connect() if rs, err := CheckClientToken(token); !rs { fmt.Printf("connect error: %s\n", err.Error()) } else { break } time.Sleep(1 * time.Second) } } func CheckClientToken(token MQTT.Token) (bool, error) { if token.Wait() && token.Error() != nil { return false, token.Error() } return true, nil }

约束与限制 证书与边缘节点绑定，在一个边缘节点下申请的证书只能用来访问该边缘节点的MQTT broker，如果访问其他边缘节点的MQTT broker，会导致认证失败。 一个边缘节点最多只能申请10份证书。 证书的有效期为5年。 MQTT使用限制 表1 MQTT使用限制 描述 限制 支持的MQTT协议版本 3.1.1 与标准MQTT协议的区别 支持QoS 0 支持Topic自定义 不支持QoS 1和QoS 2 不支持will、retain msg MQ TTS 支持的安全等级 采用TCP通道基础 + TLS协议（TLSV1.2 版本）

设备孪生（DeviceTwin） 终端设备通常包含两类数据： 一是不会改变的元数据，包括序列号、资产标识符、Mac地址等描述设备信息的数据。这种数据也可以称为终端设备的静态属性或设备属性。 另一类是终端设备的动态数据，包括特定背景下的终端设备专有实时数据，例如灯的开、关状态。这种数据也可以称为终端设备的孪生属性。 设备孪生具有与物理设备相同的特性，便于终端设备与应用之间进行更好地通信。应用发送的命令首先到达设备孪生，设备孪生根据应用设置的Expected State（期望的状态）进行状态更新，此外终端设备实时反馈自身的Actual State（真实的状态），设备孪生同时记录终端设备的Actual State和Expected State 。这种方式也使终端设备在离线状况下再次上线时，终端设备的状态也能得到同步。 图2 DeviceTwin 在IEF中可以创建终端设备，并能将终端设备与边缘节点关联，关联后会在边缘节点上保存被关联设备的属性和孪生信息。边缘节点上的应用程序可在边缘节点获取终端设备属性、设备孪生信息、以及修改终端设备孪生期望值和真实值。同时IEF负责同步云、边的孪生信息，当有冲突时，将以边缘侧的修改为主。 详细的终端设备状态边云协同机制请参见设备孪生工作原理。

设备孪生（DeviceTwin） 终端设备通常包含两类数据： 一是不会改变的元数据，包括序列号、资产标识符、Mac地址等描述设备信息的数据。这种数据也可以称为终端设备的静态属性或设备属性。 另一类是终端设备的动态数据，包括特定背景下的终端设备专有实时数据，例如灯的开、关状态。这种数据也可以称为终端设备的孪生属性。 设备孪生具有与物理设备相同的特性，便于终端设备与应用之间进行更好地通信。应用发送的命令首先到达设备孪生，设备孪生根据应用设置的Expected State（期望的状态）进行状态更新，此外终端设备实时反馈自身的Actual State（真实的状态），设备孪生同时记录终端设备的Actual State和Expected State 。这种方式也使终端设备在离线状况下再次上线时，终端设备的状态也能得到同步。 图2 DeviceTwin 在IEF中可以创建终端设备，并能将终端设备与边缘节点关联，关联后会在边缘节点上保存被关联设备的属性和孪生信息。边缘节点上的应用程序可在边缘节点获取终端设备属性、设备孪生信息、以及修改终端设备孪生期望值和真实值。同时IEF负责同步云、边的孪生信息，当有冲突时，将以边缘侧的修改为主。 详细的终端设备状态边云协同机制请参见设备孪生工作原理。

操作步骤 安装GPU驱动。 下载GPU驱动，推荐驱动链接： https://www.nvidia.com/content/DriverDownload-March2009/confirmation.php?url=/tesla/440.33.01/NVIDIA-Linux-x86_64-440.33.01.run&lang=us&type=Tesla 执行如下安装驱动命令。 bash NVIDIA-Linux-x86_64-440.33.01.run 执行如下命令检查GPU驱动安装状态。 nvidia-smi 以root用户登录边缘节点。 执行如下命令。 nvidia-modprobe -c0 -u 创建文件夹。 mkdir -p /var/IEF/nvidia/drivers /var/IEF/nvidia/bin /var/IEF/nvidia/lib64 拷贝驱动文件。 对于CentOS，依次执行如下命令拷贝驱动文件： cp /lib/modules/{当前环境内核版本号}/kernel/drivers/video/nvi* /var/IEF/nvidia/drivers/ cp /usr/bin/nvidia-* /var/IEF/nvidia/bin/ cp -rd /usr/lib64/libcuda* /var/IEF/nvidia/lib64/ cp -rd /usr/lib64/libEG* /var/IEF/nvidia/lib64/ cp -rd /usr/lib64/libGL* /var/IEF/nvidia/lib64/ cp -rd /usr/lib64/libnv* /var/IEF/nvidia/lib64/ cp -rd /usr/lib64/libOpen* /var/IEF/nvidia/lib64/ cp -rd /usr/lib64/libvdpau_nvidia* /var/IEF/nvidia/lib64/ cp -rd /usr/lib64/vdpau /var/IEF/nvidia/lib64/ 对于Ubuntu，依次执行如下命令拷贝驱动文件： cp /lib/modules/{当前环境内核版本号}/kernel/drivers/video/nvi* /var/IEF/nvidia/drivers/ cp /usr/bin/nvidia-* /var/IEF/nvidia/bin/ cp -rd /usr/lib/x86_64-linux-gnu/libcuda* /var/IEF/nvidia/lib64/ cp -rd /usr/lib/x86_64-linux-gnu/libEG* /var/IEF/nvidia/lib64/ cp -rd /usr/lib/x86_64-linux-gnu/libGL* /var/IEF/nvidia/lib64/ cp -rd /usr/lib/x86_64-linux-gnu/libnv* /var/IEF/nvidia/lib64/ cp -rd /usr/lib/x86_64-linux-gnu/libOpen* /var/IEF/nvidia/lib64/ cp -rd /usr/lib/x86_64-linux-gnu/libvdpau_nvidia* /var/IEF/nvidia/lib64/ cp -rd /usr/lib/x86_64-linux-gnu/vdpau /var/IEF/nvidia/lib64/ 其中，当前环境内核版本号可以使用uname -r命令查看获取，如下所示，请替换为实际取值。 # uname -r 3.10.0-514.e17.x86_64 执行以下命令修改目录权限。 chmod -R 755 /var/IEF

操作步骤 安装GPU驱动。 下载GPU驱动，推荐驱动链接： https://www.nvidia.com/content/DriverDownload-March2009/confirmation.php?url=/tesla/440.33.01/NVIDIA-Linux-x86_64-440.33.01.run&lang=us&type=Tesla 执行如下安装驱动命令。 bash NVIDIA-Linux-x86_64-440.33.01.run 执行如下命令检查GPU驱动安装状态。 nvidia-smi 以root用户登录边缘节点。 执行如下命令。 nvidia-modprobe -c0 -u 创建文件夹。 mkdir -p /var/IEF/nvidia/drivers /var/IEF/nvidia/bin /var/IEF/nvidia/lib64 拷贝驱动文件。 对于CentOS，依次执行如下命令拷贝驱动文件： cp /lib/modules/{当前环境内核版本号}/kernel/drivers/video/nvi* /var/IEF/nvidia/drivers/ cp /usr/bin/nvidia-* /var/IEF/nvidia/bin/ cp -rd /usr/lib64/libcuda* /var/IEF/nvidia/lib64/ cp -rd /usr/lib64/libEG* /var/IEF/nvidia/lib64/ cp -rd /usr/lib64/libGL* /var/IEF/nvidia/lib64/ cp -rd /usr/lib64/libnv* /var/IEF/nvidia/lib64/ cp -rd /usr/lib64/libOpen* /var/IEF/nvidia/lib64/ cp -rd /usr/lib64/libvdpau_nvidia* /var/IEF/nvidia/lib64/ cp -rd /usr/lib64/vdpau /var/IEF/nvidia/lib64/ 对于Ubuntu，依次执行如下命令拷贝驱动文件： cp /lib/modules/{当前环境内核版本号}/kernel/drivers/video/nvi* /var/IEF/nvidia/drivers/ cp /usr/bin/nvidia-* /var/IEF/nvidia/bin/ cp -rd /usr/lib/x86_64-linux-gnu/libcuda* /var/IEF/nvidia/lib64/ cp -rd /usr/lib/x86_64-linux-gnu/libEG* /var/IEF/nvidia/lib64/ cp -rd /usr/lib/x86_64-linux-gnu/libGL* /var/IEF/nvidia/lib64/ cp -rd /usr/lib/x86_64-linux-gnu/libnv* /var/IEF/nvidia/lib64/ cp -rd /usr/lib/x86_64-linux-gnu/libOpen* /var/IEF/nvidia/lib64/ cp -rd /usr/lib/x86_64-linux-gnu/libvdpau_nvidia* /var/IEF/nvidia/lib64/ cp -rd /usr/lib/x86_64-linux-gnu/vdpau /var/IEF/nvidia/lib64/ 其中，当前环境内核版本号可以使用uname -r命令查看获取，如下所示，请替换为实际取值。 # uname -r 3.10.0-514.e17.x86_64 执行以下命令修改目录权限。 chmod -R 755 /var/IEF

密钥的使用 您可以在创建容器应用高级配置中选择数据存储时使用Secret。 图2 使用密钥 Secret挂载到容器后，会根据Secret的内容在挂载目录下创建文件，每条密钥数据（属性名-属性值）为一个文件，其中属性名即文件的名称，属性值为文件的内容。例如Secret的属性名为“key”，属性值为“ZXhhbXBsZSB2YWx1ZQ==”，这条Secret挂载到/tmp0目录下，那么挂载成功后，在/tmp0录下就存在一个名为“key”的文件，其内容为“example value”。

密钥的使用 您可以在创建容器应用高级配置中选择数据存储时使用Secret。 图2 使用密钥 Secret挂载到容器后，会根据Secret的内容在挂载目录下创建文件，每条密钥数据（属性名-属性值）为一个文件，其中属性名即文件的名称，属性值为文件的内容。例如Secret的属性名为“key”，属性值为“ZXhhbXBsZSB2YWx1ZQ==”，这条Secret挂载到/tmp0目录下，那么挂载成功后，在/tmp0录下就存在一个名为“key”的文件，其内容为“example value”。

注意事项 为了让您的边缘节点应用更稳定可靠的运行，IEF不会主动升级您的边缘节点上的EdgeCore，需要由您在业务影响最小的时间窗内进行节点升级，以减轻对您业务的影响。 处于维护周期中的版本升级，边缘节点上的应用业务不会中断，如果您有使用消息路由功能，可能会有短暂影响。 处于维护周期外的版本升级，可能会因为容器重启引起业务的短暂中断。 请勿在节点升级过程中变更节点配置，比如重启Docker、安装卸载GPU/NPU驱动、OS内核升级、变更网络配置等，这些操作会增大节点升级失败风险。

注意事项 为了让您的边缘节点应用更稳定可靠的运行，IEF不会主动升级您的边缘节点上的EdgeCore，需要由您在业务影响最小的时间窗内进行节点升级，以减轻对您业务的影响。 处于维护周期中的版本升级，边缘节点上的应用业务不会中断，如果您有使用消息路由功能，可能会有短暂影响。 处于维护周期外的版本升级，可能会因为容器重启引起业务的短暂中断。 请勿在节点升级过程中变更节点配置，比如重启Docker、安装卸载GPU/NPU驱动、OS内核升级、变更网络配置等，这些操作会增大节点升级失败风险。

消息端点 IEF提供如下默认消息端点： SystemEventBus：边缘节点上的MQTT，代表节点通信，可以作为源端点向云上发数据，也可以作为目的端点，接收云上消息。端点资源为边缘节点MQTT Topic。 SystemREST：云端的REST网关接口，可以作为源端点，向边缘侧发送REST请求。端点资源为REST请求的路径。 您还可以创建如下消息端点： Service Bus：边缘节点上的事务请求处理端点，可以作为目的端点，处理文件上传请求。端点资源为REST请求的路径。 DIS： 数据接入服务 ，可以作为目的端点，接收由IEF转发的数据。端点资源为在DIS服务中创建的DIS通道。 APIG：API网关服务，可以作为目的端点，接收由IEF转发的数据。端点资源为在API网关服务中创建的API地址。

消息路由 目前支持如下几种消息转发路径： SystemREST到Service Bus：通过调用云端的REST Gateway接口，获取边缘节点上的文件服务。需配合边缘市场中的边缘文件服务应用一起使用。 SystemREST到SystemEventBus：通过调用云端的REST Gateway接口，向边缘节点中的SystemEventBus（MQTT broker）发送消息。 SystemEventBus到DIS/APIG服务：您可以将终端设备数据发送到边缘节点SystemEventBus（MQTT broker）的自定义Topic中，IEF会将这些数据转发到DIS通道或APIG后端地址。数据转发到DIS通道或者APIG后端地址后，您可以提取这些数据，并对数据进行处理分析。这条路径需要在创建消息路由时自定义MQTT Topic，自定义Topic的详细说明请参见自定义Topic。

消息路由 目前支持如下几种消息转发路径： SystemREST到Service Bus：通过调用云端的REST Gateway接口，获取边缘节点上的文件服务。需配合边缘市场中的边缘文件服务应用一起使用。 SystemREST到SystemEventBus：通过调用云端的REST Gateway接口，向边缘节点中的SystemEventBus（MQTT broker）发送消息。 SystemEventBus到DIS/APIG服务：您可以将终端设备数据发送到边缘节点SystemEventBus（MQTT broker）的自定义Topic中，IEF会将这些数据转发到DIS通道或APIG后端地址。数据转发到DIS通道或者APIG后端地址后，您可以提取这些数据，并对数据进行处理分析。这条路径需要在创建消息路由时自定义MQTT Topic，自定义Topic的详细说明请参见自定义Topic。

消息端点 IEF提供如下默认消息端点： SystemEventBus：边缘节点上的MQTT，代表节点通信，可以作为源端点向云上发数据，也可以作为目的端点，接收云上消息。端点资源为边缘节点MQTT Topic。 SystemREST：云端的REST网关接口，可以作为源端点，向边缘侧发送REST请求。端点资源为REST请求的路径。 您还可以创建如下消息端点： Service Bus：边缘节点上的事务请求处理端点，可以作为目的端点，处理文件上传请求。端点资源为REST请求的路径。 DIS：数据接入服务，可以作为目的端点，接收由IEF转发的数据。端点资源为在DIS服务中创建的DIS通道。 APIG：API网关服务，可以作为目的端点，接收由IEF转发的数据。端点资源为在API网关服务中创建的API地址。

约束与限制 边缘节点磁盘占用超过70%时，会启动镜像回收机制回收容器镜像占用的磁盘空间，此时部署容器应用会导致容器启动变慢，请在部署容器应用前规划好边缘节点磁盘空间。 创建容器应用时，边缘节点会从 容器镜像服务 拉取镜像，如果镜像超大且边缘节点下载带宽较小，容器镜像没有拉取完成，从而导致控制台上容器应用显示创建失败。虽然应用创建失败，但容器镜像拉取不会中断，等容器镜像拉取成功后，容器应用的状态会刷新为创建成功。此情况下也可以先将容器镜像拉取到边缘节点，然后再创建容器应用。 容器镜像的架构必须与节点架构一致，比如节点为x86，那容器镜像的架构也必须是x86。

配置项的使用 您可以在创建容器应用高级配置中选择数据存储时使用ConfigMap。 图2 使用ConfigMap ConfigMap挂载到容器后，会根据ConfigMap的内容在挂载目录下创建文件，每条配置数据（属性名-属性值）为一个文件，其中属性名即文件的名称，属性值为文件的内容。例如ConfigMap的属性名为“key”，属性值为“value”，这条ConfigMap挂载到/tmp0目录下，那么挂载成功后，在/tmp0目录下就存在一个名为“key”的文件，其内容为“value”。

配置项的使用 您可以在创建容器应用高级配置中选择数据存储时使用ConfigMap。 图2 使用ConfigMap ConfigMap挂载到容器后，会根据ConfigMap的内容在挂载目录下创建文件，每条配置数据（属性名-属性值）为一个文件，其中属性名即文件的名称，属性值为文件的内容。例如ConfigMap的属性名为“key”，属性值为“value”，这条ConfigMap挂载到/tmp0目录下，那么挂载成功后，在/tmp0目录下就存在一个名为“key”的文件，其内容为“value”。

边缘节点概述 边缘节点是您自己的边缘计算机器，用于运行边缘应用，处理您的数据，并安全、便捷地和云端应用进行协同。您可以通过智能边缘平台部署系统应用来延伸云服务能力到边缘节点，或者通过部署您自己的应用来构建您自己的边缘计算能力。 为了使智能边缘平台能够管理您的边缘节点，您需要做如下步骤： 准备边缘节点，边缘节点需要满足一定的规格要求，具体请参见配置边缘节点环境。 在IEF中创建边缘节点，获取边缘节点的安装工具和配置文件，具体请参见注册自建边缘节点。 使用上一步获取的安装工具和配置文件纳管边缘节点，具体请参见纳管边缘节点。 图1 使用流程 父主题： 节点管理

边缘节点概述 边缘节点是您自己的边缘计算机器，用于运行边缘应用，处理您的数据，并安全、便捷地和云端应用进行协同。您可以通过智能边缘平台部署系统应用来延伸云服务能力到边缘节点，或者通过部署您自己的应用来构建您自己的边缘计算能力。 为了使智能边缘平台能够管理您的边缘节点，您需要做如下步骤： 准备边缘节点，边缘节点需要满足一定的规格要求，具体请参见配置边缘节点环境。 在IEF中创建边缘节点，获取边缘节点的安装工具和配置文件，具体请参见注册边缘节点。 使用上一步获取的安装工具和配置文件纳管边缘节点，具体请参见纳管边缘节点。 图1 使用流程 父主题： 节点管理

使用IEF构建边缘计算 使用IEF构建边缘计算的步骤如图1所示。 纳管边缘节点，绑定终端设备。 使用IEF构建边缘计算首先需要将边缘节点纳入IEF的管理（通过在边缘节点安装边缘节点软件），并将终端设备绑定到边缘节点，做完这些后您就可以通过IEF往边缘节点部署应用。 纳管边缘节点、绑定终端设备的详细内容将在节点管理和终端设备管理中介绍。 开发应用并制作镜像，上传到容器 镜像服务 （SWR）。 这个步骤是针对实际业务场景开发应用，开发完成后制作成容器镜像，并上传到SWR上，这样后面IEF下发应用后，边缘节点就可以从SWR中拉取应用镜像。 虽然这里将开发应用放在了步骤 1之后，但这两个步骤之间并没有明确的先后顺序，您也可以先开发应用，然后再纳管边缘节点、绑定终端设备。 部署应用。 边缘节点纳管、应用开发完后，就可以通过IEF将应用部署到边缘节点，运行您的实际业务。 应用运行后，就能通过 AOM 对应用进行监控和告警，提供运维便利性。 部署应用的详细内容将在容器应用管理中详细介绍。 （可选）回传数据到云上做进一步处理，根据处理结果更新应用。 这个步骤与IEF的使用本身没有强相关，但是这是一个常见的根据数据改进应用的方法，您可以根据自身需求选择是否操作。 图1 构建边缘计算

安全可靠 IAM 认证 通过创建IAM角色，允许从边缘节点访问AOM、SWR、DIS等资源。 边缘节点安全 Edge Agent创建专属服务用户，能够访问的目录和拥有的权限都受限，向云端上传日志、监控信息由用户自行选择。 云边协同通讯安全 Edge Agent与IEF建立双向加密通道，Edge Agent自下向上发起，双向消息收发通过证书认证、加密。 云安全 前置DDoS网络安全防护，防恶意攻击。 为每个边缘节点颁布唯一接入证书，双向通讯通过证书认证、加密。 设备安全 终端设备使用证书进行身份认证。 图4 IEF安全性方案

IEF权限 默认情况下，管理员创建的IAM用户没有任何权限，需要将其加入用户组，并给用户组授予策略或角色，才能使得用户组中的用户获得对应的权限，这一过程称为授权。授权后，用户就可以基于被授予的权限对云服务进行操作。 IEF部署时通过物理区域划分，为项目级服务。授权时，“作用范围”需要选择“区域级项目”，然后在指定区域（如华北-北京四）对应的项目（cn-north-4）中设置相关权限，并且该权限仅对此项目生效；如果在“所有项目”中设置权限，则该权限在所有区域项目中都生效。访问IEF时，需要先切换至授权区域。 权限根据授权精细程度分为角色和策略。 角色：IAM最初提供的一种根据用户的工作职能定义权限的粗粒度授权机制。具有Tenant Administrator系统角色的用户可以操作IEF所有资源。 策略：IAM最新提供的一种细粒度授权的能力，可以精确到具体服务的操作、资源以及请求条件等。基于策略的授权是一种更加灵活的授权方式，能够满足企业对权限最小化的安全管控要求。多数细粒度策略以API接口为粒度进行权限拆分。 如表1所示，包括了IEF的所有系统权限。 表1 IEF系统权限 系统角色/策略名称 描述 类别 依赖关系 IEF FullAccess IEF管理员权限，拥有该权限的用户可以操作并使用IEF的基本资源。注意：如需操作IEF所有资源，请配置Tenant Administrator系统角色。 系统策略 无 IEF ReadOnlyAccess IEF只读权限，拥有该权限的用户仅能查看IEF资源。 系统策略 无 表2列出了IEF常用操作与系统权限的授权关系，您可以参照该表选择合适的系统权限。 表2 常用操作与系统权限的关系 操作 IEF FullAccess IEF ReadOnlyAccess Tenant Administrator 创建/删除/修改服务实例 √ x √ 查看服务实例 √ √ √ 切换实例 √ √ √ 创建/删除/修改边缘节点 √ x √ 查看边缘节点 √ √ √ 创建/删除/修改边缘节点组 √ x √ 查看边缘节点组 √ √ √ 创建/删除/修改边缘容器应用 √ x √ 查看边缘容器应用 √ √ √ 创建/删除/修改设备 √ x √ 查看设备 √ √ √ 创建/删除/修改应用部署 √ x √ 查看应用部署 √ √ √ 创建/删除/修改应用模板 √ x √ 查看应用模板 √ √ √ 创建/删除/修改节点注册作业 √ x √ 查看节点注册作业 √ √ √ 创建/删除/修改消息端点 √ x √ 查看消息端点 √ √ √ 创建/删除/修改消息路由 √ x √ 查看消息路由 √ √ √ 创建/删除/修改批量作业 √ x √ 查看批量作业 √ √ √ 创建/删除/修改配置项 √ x √ 查看配置项 √ √ √ 创建/删除/修改密钥 √ x √ 查看密钥 √ √ √ 创建/删除/修改加密数据 √ x √ 查看加密数据 √ √ √ 创建/删除/修改系统订阅 √ x √ 查看系统订阅 √ √ √ 创建/删除/修改插件 √ x √ 查看插件 √ √ √

修订记录 发布日期 修订记录 2024-08-23 新增事件记录 2024-07-11 新增Windows服务器WinRM服务配置与故障排查 2024-03-21 新增Edge安装端口被占用，导致无法安装，如何处理？ 新增AK/SK验证失败，如何处理？ 2024-01-15 更新添加资源凭证 2023-12-20 新增工具采集 新增采集失败，提示：The collector is not installed如何处理？ 新增采集器参数配置说明 新增如何卸载Edge？ 2023-11-30 第一次发布

修订记录 发布日期 修订记录 2024-08-20 新增配置 主机迁移 方案 2024-07-23 更新导入RVTools资源 2024-07-10 新增手动添加数据库。 2024-07-09 新增资源类型和安全组配置说明。 2024-07-03 新增迁移风险评估。 2024-06-18 新增IAM用户权限。 2024-06-07 主机迁移迁移工作流中新增使用须知。 2024-06-03 支持导入的阿里云资源类型新增：对象存储OSS桶、云数据库 RDS MySQ L实例 和云数据库 Redis实例。 2024-05-08 在公网发现与采集中，新增数据库深度采集（袁林昌）。 新增工作流配额限制说明 2024-4-17 新增迁移方案配置 新增创建对象存储批量迁移工作流 2024-03-21 新增委托权限说明。 新增导入阿里云资源清单。 2024-03-11 公网采集源端新增Azure。 2024-02-20 新增迁移集群。 2024-01-31 新增采集主机性能。 规格评估新增基于性能推荐主机规格。 2023-12-30 新增购买资源。 2023-10-30 第一次发布。

体验问答 在“体验平台”页面右上角单击“问答”，切换至问答体验页面。 在输入框中输入问题，单击，查看返回的答案。 图1 体验问答 表2 图标说明 图标 说明 认同内容，在对话框中输入正面反馈意见，单击“提交”。 不认同内容，在对话框中输入负面反馈意见，单击“提交”。 复制内容。 刷新内容。 查看答案参考源。在参考列表中，单击“阅读全文”，可查看文档原文。 说明： 当前针对上传的多栏排版docx文档，查看文档原文时存在内容显示错位及显示不全的问题。

新建知识库 在 KooSearch 控制台，左侧导航栏选择“知识库管理”。 进入知识库管理页面。 在知识库管理页面，单击右上角“新建知识库”。 在“新建知识库”页面设置知识库信息。 在创建知识库页签填写“知识库名称”、选择“知识库语言”，填写知识库“描述”，单击“下一步”。 图1 创建知识库 在“解析拆分设置”页签配置解析设置和拆分设置，然后单击“下一步”。 解析设置：勾选需要解析的能力。 表1 解析设置 参数 说明 OCR增强 勾选后，即可调用OCR服务进行智能文档识别，如表格解析或扫描文件等。 解析图片 未勾选，在文档中遇到图片默认跳过，不处理图片。 勾选后，有两种解析方式可供选择： 提取图片文本：识别图片内文字。 仅保留原图：将图片提取后上传OBS桶，便于问答图文展示。 解析页眉页脚 未勾选，解析结果中不包含页眉页脚。 勾选后，解析结果中包含页眉页脚。 解析目录页 未勾选，解析结果中不包含目录页。 勾选后，解析结果中包含目录页。 拆分设置：即分段设置，选择分段方式。 表2 拆分设置 参数 说明 自动分段 系统根据文档特点自动选择合适的分段方式。 长度分段 默认按照段落进行拆分合并，如果段落过长则通过标识符进行分段。 分段标识符：分段方式为遇到所选符号即截断，符号之间没有优先级，最终分割后合并到预计最大长度。自定义分段中如果未命中分段标识符，分段将会失败。 分段预计长度：分段的最大长度，文档的正文如果超过设定的[最大长度]，则截取[最大长度]的片段为新文档，随后回溯[分段重叠]字符，继续向后检查，直到文档结束。 层级分段 先按照文章的标题层级分段，再按照段落进行拆分合并，如果段落过长则通过标识符进行分段。 层级解析模式：可选择自动解析和规则解析。选择规则解析需要自定义层级规。 层级分段详情如表3所示。 表3 层级分段 参数 说明 层级解析模式 自动解析：按照系统规则自动解析。 规则解析： 由于不同文档的层次结构多样且不一致，针对不同的文档可自定义其文档层次解析规则，更好地解析切分文档从而提升基于文档知识问答的准确率。 自定义默认规则 将最常见的规则，作为默认规则可选，详情请参见提供的默认规则示例。 自定义解析规则 当前解析规则采用正则语言编写，可参见如表5示例。 标题层级深度 选择文章的标题层级深度。 标题保存方式 可选择“保存多标题组合”和“保存最后一级标题”。 分段标识符 分段方式为遇到所选符号即截断，符号之间没有优先级，最终分割后合并到预计最大长度。自定义分段中如果未命中分段标识符，分段将会失败。 分段预计长度 分段的最大长度，文档的正文如果超过设定的[最大长度]，则截取[最大长度]的片段为新文档，随后回溯[分段重叠]字符，继续向后检查，直到文档结束。 跨标题合并 打开“跨标题合并”开关：不同标题段落文字较少时，会自动合并到指定的分段长度，有助于生成更全面的结果。关闭“跨标题合并”开关：不会自动合并不同标题。 说明： “层级分段”页签中有此按钮，可以自己设置开关。“自动分段”和“长度分段”页签中没有此按钮，跨标题合并使用的是系统默认参数，等于true。 表4 规则解析默认规则示例 类别 规则 描述 第一章 第一节 第一条 ^第([零〇一二三四五六七八九十百千万1-9]{1,7})章 ^第([零〇一二三四五六七八九十百千万1-9]{1,7})节 ^第([零〇一二三四五六七八九十百千万1-9]{1,7})条 以章的规则为例： 中括号内大写的阿拉伯可以匹配，例如：第一章。 支持1-9的阿拉伯数字匹配，例如： 第1章。 最大支持中间位数出现的位数有7位。例如：第一千一百三十七章。 节和条的规则类似。 表5 自定义规则解析示例 类别 规则 描述 第一章 第一节 第一条 ^第([零〇一二三四五六七八九十百千万1-9]{1,7})章 ^第([零〇一二三四五六七八九十百千万1-9]{1,7})节 ^第([零〇一二三四五六七八九十百千万1-9]{1,7})条 / 1 1.1 1.1.1 ^(\d+\.)(?=\s) ^(\d+)(\.\d+)(?!\.)(?=\s) ^(\d+)(\.\d+)(\.\d+)(?!\.)(?=\s) 可以匹配数字开头的段落。 备注： [\u4e00-\u9fa5]+ 限制中文） 例如： 1. 简介 1.1 说明 1.1.1 详细说明 一、 （一） 1、 1） ^([零〇一二三四五六七八九十百千万]+)[、] ^（([零〇一二三四五六七八九十百千万]+)） ^[\d+]、 ^[\d+]） / 图2 自定义规则解析示例 在“模型设置”页签配置好模型后，单击“下一步”。 搜索模型设置 选择Embedding模型服务、精排模型服务、搜索规划模型服务。 Embedding模型服务：基于盘古大模型技术的文本表示模型，将文本转化为用数值表示的向量形式，用于文本检索、聚类、推荐等场景。 精排模型服务：基于盘古大模型技术的文本表示模型，将文本转化为用数值表示的向量形式，用于文本检索、聚类、推荐等场景，语义搜索场景下，加入了精排模型，提升搜索的效果。 搜索规划模型服务：搜索规划模型服务提供了意图分类、多轮查询改写、复杂查询分解、时间抽取等功能，在搜索增强生成任务中，通过意图分类的结果将路由到后续不同的流程；通过改写查询词及查询分解以提高搜索的准确率。 NLP模型设置 选择NLP模型服务。基于盘古大模型的人工智能语言模型，可进行对话互动、回答问题、协助创作。 扩展长上下文： 如果打开了此参数，模型在解析过程中会扩展长上下文以生成更全面结果。 有效输入长度(K)：如果打开“扩展长上下文”按钮，则需要设置有效输入长度，输入令牌的有效长度以保证最佳输出。 进入高级设置页面，设置好后，单击“确定”。 引用定位：针对回答结果定位到原文位置。 图文结合：展示原文引用关联图片。 知识库缓存：如果打开知识库缓存按钮，您的搜索效率会相对高效。使用知识库缓存需要选择以下几个参数。 缓存生成模型服务：选择一个模型服务。 缓存阈值：达到缓存阈值，就会使用缓存输入值必须在0.1到1之间。 缓存策略：达到缓存阈值，如果有多个答案，可以设置最高分或者随机。 过期策略配置：缓存过期的方式，有3中选择。 Least Recently Used：根据当前时间与最后一次访问时间的差值超过存活时间时删除。 First In First Out：根据当前时间与创建时间的差值超过存活时间时删除。 Least Frequency Used：小于缓存命中阈值且当前时间与创建时间大于存活时间时清除，大于阈值时保留 存活时间（秒）：可以自己设置缓存的存活时间，或者直接设置成永久。 知识库创建好后，可以在知识库管理页面查看到新创建的知识库基本信息，包括知识库ID、知识库名称、知识库状态等信息。

版本管理 您创建成功知识库的时候，系统会自动创建一个知识库初始版本，对版本的一些管理操作如下所示： 进入KooSearch控制台。 左侧导航栏选择“知识库管理”，进入“知识库管理”页面。 单击“版本管理”页签。 您创建好知识库后，系统会默认创建一个初始版本，如下图所示。 如果您需要再创建一个版本，单击操作列的“重建”按钮，依次选好参数，即可创建成功。 图3 重建版本 版本名称：版本的名称。 重建来源：选择“索引”或者“文档”。 索引：按照索引重建版本，会直接复用已经完成的向量数据库索引。 文档：按照文档重建版本。选择文档的话，要设置好解析规则是继承原有的规则还是使用最新的规则。 是否立即激活：选择是否立即激活。 描述：对于重建版本的描述。 重建好版本后，可以对版本进行以下操作。 图4 版本操作 状态为“使用中”的版本可进行如下操作： “重建”：按照步骤4重新建一个版本。 “更新”：可以单击此按钮更新版本描述。 状态为“可用”的版本除了“重建”、“更新”还可以进行如下操作： “关闭”：当版本不用时，可以关闭版本释放索引资源。 “删除”：当不再需要此版本时，可以删除版本。 “激活”：可用状态的版本可以激活，激活后此版本的状态变为“使用中”，之前“使用中”的版本状态变为“可用”。 被关闭的版本可进行如下操作： “启用”：被关闭版本如果想再次使用，可以单击此按钮启用，启用后版本状态会变成“可用”。 “删除”：当不再需要此版本时，可以删除版本。 “更新”：可以单击此按钮更新版本描述。

调用已发布的KooSearch API 在业务环境中调用已发布的KooSearch API。 构造API请求，KooSearch API的请求说明请参见《API参考》。 为API请求添加认证信息。 表2 认证方式 认证方式 API请求参数配置 APP认证 表示由API网关服务负责接口请求的安全认证。推荐使用APP认证方式。关于使用APP认证的方法，具体请参考《开发指南》。 当选择“APP认证”时，需要配置“APP凭据”。 “APP凭据”：使用APP认证的API，需要在API网关中创建一个凭据，以生成凭据ID和密钥对（Key、Secret）。将创建的凭据绑定API后，才可以使用APP认证调用API。客户端（API调用者）在调用API过程中，把密钥对替换SDK中的密钥对，API网关服务根据密钥对进行身份核对，完成鉴权。具体创建凭据的步骤，请参考创建凭据 。 华为IAM认证 表示借助IAM服务进行安全认证。 说明： 选择“华为IAM认证”时，任何API网关租户均可以访问此API，可能存在恶意刷流量，导致过量计费的风险。

场景描述 KooSearch服务开通成功后，会自动创建KooSearch API。在KooSearch服务详情页的API管理页签，可以看到 知识管理 和文档解析两类API。 知识管理：该类API主要用于知识库管理，例如上传文档、刷新文档等。 文档解析：该类API主要用于对文档数据进行处理，例如切分文档内容。 将KooSearch API发布到不同环境后，支持在环境中调用API使用KooSearch服务。操作流程如下： 在APIG服务配置API网关：配置API网关。 在 CSS 服务发布KooSearch API：发布KooSearch API。 在业务环境中调用已发布的KooSearch API：调用已发布的KooSearch API。 当已发布的KooSearch API需要修改安全认证方式时，可以编辑API。 当已发布的KooSearch API不希望被调用时，可以下线API。