# 概述本文档介绍联网问答智能体API知识库接入时的接入流程、并提供的查询知识库接口应当遵守的规范。当智能体需要查询知识库时，需要按本文描述实现相应的接口方能正常查询。 # 接入流程接入联网问答智能体知识库功能时，客户侧需要按照如下步骤完成： 1. 依据知识库接口说明，实现知识库接口 2. 在【联网问答Agent控制台】的【知识库配置】页面完成配置，包括【路径导入】【检索配置】

3. 在上述页面中【请求路径调试】点击“测试”以发送测试数据，测试接口连通性，确认接口可用后完成保存

4. 保存后再次点击【知识库配置】可获取鉴权密钥，支持请求校验（非必要） 5. 完成知识库配置后，在【联网问答Agent控制台】的【联网问答Agent】中，进入智能体配置页进行知识库绑定，完成后开始使用

# 知识库接口说明 ## 请求方式 HTTPS * Method：POST * Content\-Type：application/json ## 签名校验客户侧通过检验 signature 对请求进行校验（下面有校验方式），以确认请求来自内容定制系统。 ### 签名参数 |参数 |描述 | |---|---| |timestamp |unix时间戳，单位：秒。为保证安全，与当前时间戳绝对值不要超过3600s。|\ | |从请求头中获取，键为：X\-Content\-Timestamp | |nonce |请求随机串。随机串长度为6\-32位数字和字母的组合，大小写敏感。|\ | |从请求头中获取，键为：X\-Content\-Nonce | |signature |签名字符串。|\ | |从请求头中获取，键为：X\-Content\-Signature | |payload |业务数据。请求体body字节流。 | |secret_key |鉴权密钥。在【联网问答Agent控制台】的【智能体配置】页面中点击【知识库配置】查看。 | ### 签名算法 Hmac_SHA256算法 ### 签名步骤 1. 将 timestamp、nonce 和 payload 依次进行拼接； 2. 使用 secret_key 对上述拼接的字符串进行 hmac sha256 加密，然后转成十六进制字符串； 3. 得到加密后的字符串可与 signature 对比，标识该请求来源于内容定制的内容事件推送。 ### 签名示例检验signature的Java示例代码： ```Java public static String genSignature(String timestamp, String nonce, String body, String secretKey) throws NoSuchAlgorithmException, InvalidKeyException { // 按照 timestamp,nonce,body 顺序拼接签名字符串 String signatureStr = timestamp + nonce + body; // 进行 hmac sha256 加密 Mac hmacSha256 = hmacSha256 = Mac.getInstance("HmacSHA256"); SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256"); hmacSha256.init(secretKeySpec); byte[] signatureBytes = hmacSha256.doFinal(signatureStr.getBytes(StandardCharsets.UTF_8)); // 将 sha256 字节数组转成16进制字符串 StringBuilder signatureBuilder = new StringBuilder(); for (byte signatureByte : signatureBytes) { String hex = Integer.toHexString(signatureByte & 0xFF); if (hex.length() == 1) { signatureBuilder.append('0'); } signatureBuilder.append(hex); } return signatureBuilder.toString(); } ``` 检验signature的Go示例代码： ```Go func GenSignature(timestamp, nonce, body, secretKey string) string { // 按照 timestamp,nonce,body 顺序拼接签名字符串 signatureStr := timestamp + nonce + body // 进行 hmac sha256 加密 hmacSha256 := hmac.New(sha256.New, []byte(secretKey)) hmacSha256.Write([]byte(signatureStr)) // 将 sha256 字节数组转成16进制字符串 signature := fmt.Sprintf("%x", hmacSha256.Sum(nil)) return signature } ``` ## 请求参数 > 请求方指“火山引擎\-联网智能体”。 ### Header |**KEY** |**VALUE/说明** | |---|---| |method |POST | |Content\-Type |application/json | |X\-Content\-Timestamp |unix时间戳（单位：秒） | |X\-Content\-Nonce |随机串（6\-32位数字、字母组成） | |X\-Content\-Signature |回调签名（生成逻辑见上文） | ### Body |字段名 |字段类型 |说明 | |---|---|---| |FirstLevelId |string |知识库一级路径，与客户配置一致 | |SecondLevelId |string |知识库二级路径，与客户配置一致 | |Query |string |查询内容 | |Limit |number |查询条数 | ## 响应参数 > 响应方指“客户侧”。 |字段名 |字段类型 |说明 | |---|---|---| |Ret |number |响应状态码。0\-成功；非0\-失败，并在msg中补充说明。 | |Msg |string |响应信息。例如：成功时提供"success"；失败时提供失败相关信息。 | |Result |Array |查询结果数组 | ### Result |字段名 |字段类型 |说明 | |---|---|---| |Id |string |内容id，不可重复，重复会导致内容丢失 | |Title |string |内容标题 | |Summary |string |内容摘要，用于大模型总结，建议提供 | |PublishTime |number |发布时间，秒级时间戳 | |Url |string |跳转链接 | |CoverImage |CoverImage |封面图 | |KnowledgeContent |string |内容信息，透传字段 | ### CoverImage |字段名 |字段类型 |说明 | |---|---|---| |Height |number |图片高度 | |Width |number |图片宽度 | |Url |string |图片链接 | ## 请求示例 ```HTTP POST / HTTP/1.1 Host: xxx.xxx.xxx Content-Type: application/json X-Content-Timestamp: 1690366367 X-Content-Nonce: kfcv50 X-Content-Signature: 2d3891cee3dcc777ba27a29f70758c581e93f21f3dad1deeaadf11aa440fe4b2 Body: { "FirstLevelId": "tech", "SecondLevelId": "software", "Query": "寻找相关软件信息", "Limit": 5 } ``` 注意：这里的Body应该作为一个字符串接收。不要利用引入的SDK或者框架的能力作为一个JSONObject接收，再转为字符串，这样可能导致Body的字符串内容不一致，从而导致签名计算出来的最终结果不一致。 ## 响应示例客户侧服务端返回给火山引擎侧的响应数据 ```JSON { "Ret": 0, "Msg": "success", "Result": [ { "Id": "1001", "Title": "示例知识内容标题", "Summary": "这是一段用于大模型总结的内容摘要", "PublishTime": 1690000000, "Url": "https://example.com/knowledge/1", "CoverImage": { "Height": 300, "Width": 300, "Url": "https://example.com/cover_1001.jpg" }, "KnowledgeContent": "详细的知识内容信息，可根据实际需求填充" } ] } ```