# 第三方通用知识库接入规范 #### 前言 当您拥有企业内部已有的知识库系统（如内部Wiki、私有文档库），且不希望将数据迁移至AgentArts平台时，可遵循本规范开发适配接口。 #### 典型场景 企业智能体需要检索内部保密文档，通过实现本规范定义的API接口，AgentArts可直接调用您的知识库服务进行问答增强。 #### 工作原理 您需开发并部署两个标准HTTP接口，AgentArts智能体在对话过程中，当需要检索外部知识时，将依次调用您的接口： 1. 调用[获取知识库列表]接口，获取可用的知识库列表。 2. 根据用户问题，调用[检索知识库]接口，获取相关文档切片。 3. 将检索结果注入提示词，增强问答能力。 #### 费用说明 通过AgentArts调用第三方知识库接口，可能会产生公网流量费用，具体取决于您的第三方服务部署环境。该调用过程将消耗智能体的运行时长资源。 #### API接口规范 对于API接口适配，开发者需要新增两个接口，一个是**获取知识库列表** ，一个是**检索知识库** 。开发者按照[接口：获取知识库列表]、[接口：检索知识库]规范提供对外接口，并在接口内实现密钥鉴权、数据查询、知识检索等业务逻辑，最后按照规范返回对应数据。 - [接口：获取知识库列表] - URI ``` GET /knowledge-bases ``` - 查询Query参数 表1查询Query参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | name | 否 | String | **参数解释**： 知识库名称，用于获取知识库列表时筛选知识库名称。 **取值范围：** 长度不超过64个字符。 **默认取值：** 不涉及。 | | offset | 否 | Integer | **参数解释：** 当前请求的分页偏移量，表示从第几条开始获取数据。默认值为0，表示从第0条开始获取数据。 **取值范围：** 0～65535。 **默认取值：** 0。 | | limit | 否 | Integer | **参数解释：** 当前请求返回的分页最大数据条数，表示一次请求返回的数据条数。默认值为10，表示一页最多展示10条数据。 **取值范围：** 1\~100。 **默认取值：** 10。 | - 请求Header参数 表2请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | Authorization | 是 | String | **参数解释**： 认证鉴权使用的api-key密钥，拼接"Bearer "后的字符串。 示例：Bearer d59\*\*\*\*\*\*9C3，用于第三方知识库的鉴权。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | - 响应参数 表3响应参数200 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | total | Integer | **参数解释**： 知识库数据总数。 **取值范围：** 不涉及。 | | knowledge_base_list | Array of [表4] | **参数解释：** 知识库数据信息列表。 注意： 第三方知识库只返回可用的知识库，即在当前时刻可被外部引用并支持检索的知识库数据。 **取值范围：** 不涉及。 | 表4KnowledgeBaseInfo | 参数 | 参数类型 | 描述 | |:---|:---|:---| | knowledge_base_id | String | **参数解释**： 知识库ID。 **取值范围：** 不涉及。 | | name | String | **参数解释：** 知识库名称。 **取值范围：** 不涉及。 | | description | String | **参数解释**： 知识库描述。 **取值范围：** 不涉及。 | 表5响应参数400、500等 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**： 错误码。 **取值范围：** 不涉及。 | | error_msg | String | **参数解释：** 错误描述。 **取值范围：** 不涉及。 | - 请求示例 ``` GET http://10.0.0.0:8090/knowledge-bases?name=123&offset=0&limit=10 ``` - 响应示例 ``` { "total": 1, "knowledge_base_list": [ { "knowledge_base_id": "001", "name": "一个通用第三方知识库的名称 / this is a knowledgeBase name", "description": "一个描述 / a description" } ] } ``` - [接口：检索知识库] - URI ``` POST /knowledge-bases/retrieve ``` - 请求Header参数 表6请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | Authorization | 是 | String | **参数解释**： 认证鉴权使用的api-key密钥，拼接"Bearer "后的字符串。 示例：Bearer d59\*\*\*\*\*\*9C3，用于第三方知识库的鉴权。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | - Body参数 表7Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | knowledge_base_ids | 是 | Array of String | **参数解释**： 知识库ID的列表，用于指定搜索时需要检索的知识库。 **取值范围：** 列表长度大于等于1，即至少指定检索一个知识库。 **默认取值：** 不涉及。 | | query | 是 | String | **参数解释：** 用户的搜索内容，即需要在知识库中检索的问题或关键信息。 **取值范围：** 长度不超过4096个字符。 **默认取值：** 不涉及。 | | method | 是 | String | **参数解释：** 搜索方式。语义检索："doc"。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | offset | 否 | Integer | **参数解释：** 当前请求的分页偏移量，表示从第几条开始获取数据。默认值为0，表示从第0条开始获取数据。 **取值范围：** 0～65535。 **默认取值：** 0。 | | limit | 否 | Integer | **参数解释：** 当前请求返回的分页最大数据数量，表示一次请求返回的数据条数。默认值为10，表示一页最多展示10条数据。 **取值范围：** 1\~100。 **默认取值：** 10。 | | top_k | 否 | Integer | **参数解释：** 检索返回结果的最大召回数量。 **取值范围：** 1-1024。 **默认取值：** 50。 | | search_threshold | 否 | Number | **参数解释：** 检索时的相关度得分阈值，低于该阈值的结果将被过滤。默认值0.0时表示不设置相关度得分阈值。 **取值范围：** 0.0 - 1.0。 **默认取值：** 0.0。 | | extra_params | 否 | Array of [表8] | **参数解释**： 额外的自定义参数，用于传递第三方知识库所需的其他业务参数。 示例： ``` "extra_params": [ { "key": "tenant_id", "value": "enterprise-001" }, { "key": "data_region", "value": "cn-north" } ] ``` **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表8KnowledgeBaseExtraParam | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | key | 是 | String | **参数解释**： 额外参数主键名。 **取值范围：** 不涉及。 | | value | 是 | String | **参数解释：** 额外参数的值。 **取值范围：** 不涉及。 | - 响应参数 表9响应参数200 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | total | Integer | **参数解释**： 检索结果总数。 **取值范围：** 不涉及。 | | search_result_list | Array of [表10] | **参数解释：** 检索结果的信息列表。 **取值范围：** 不涉及。 | 表10SearchChunkInfo | 参数 | 参数类型 | 描述 | |:---|:---|:---| | knowledge_base_id | String | **参数解释**： 该切片所属的知识库ID。 **取值范围：** 不涉及。 | | file_id | String | **参数解释：** 该切片所属的文件ID。 **取值范围：** 不涉及。 | | chunk_id | String | **参数解释**： 切片的唯一标识ID。 **取值范围：** 不涉及。 | | content | String | **参数解释**： 检索返回的文本内容，即实际注入提示词的知识片段。 **取值范围：** 不涉及。 | | score | Number | **参数解释**： 该切片与检索query的相关度得分，将根据此得分决定是否使用该切片。 **取值范围：** 0.0 - 1.0。 | | title | String | **参数解释**： 文本标题，推荐返回文件名称，用于在引用来源时展示给用户。 **取值范围：** 不涉及。 | 表11响应参数400、500等 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**： 错误码。 **取值范围：** 不涉及。 | | error_msg | String | **参数解释：** 错误描述。 **取值范围：** 不涉及。 | - 请求示例 ``` POST http://10.0.0.0:8090/knowledge-bases/retrieve ``` - 响应示例 ``` { "knowledge_base_ids": [ "001" ], "query": "检索", "method": "doc", "offset": 0, "limit": 10, "top_k": 50, "search_threshold": 0.01 } ``` ``` { "total": 1, "search_result_list": [ { "knowledge_base_id": "001", "file_id": "101", "chunk_id": "201", "content": "一个通用第三方知识库的检索切片内容 / this is a retrieve chunk content", "score": 0.8, "title": "检索切片的标题 / retrieve chunk title" } ] } ``` #### API接口实现案例（Java） ``` @Slf4j @RestController public class CommonThirdpartyKnowledgeBaseController { /** * list knowledgeBase function * * @param name * @param offset * @param limit * @param authorization * @return ListKnowledgeBaseResponse */ @GetMapping("/knowledge-bases") public ListKnowledgeBaseResponse listKnowledgeBase( @RequestHeader("Authorization") String authorization, @RequestParam(required = false) String name, @RequestParam(required = false) Integer offset, @RequestParam(required = false) Integer limit) { /** * 对密钥认证鉴权 * Verify and authenticate the key */ if (!authorization.startsWith("Bearer ")) { log.error("invalid authorization"); throw new RuntimeException("invalid authorization"); } String apiKey = authorization.substring("Bearer ".length()); /** * then do something for authorization * */ /** * 根据业务实现代码逻辑，构造返回结果 * Construct and return results based on your business implementation and code logic */ ListKnowledgeBaseResponse response = new ListKnowledgeBaseResponse(); response.total = 1; KnowledgeBaseInfo knowledgeBaseInfo = new KnowledgeBaseInfo(); knowledgeBaseInfo.knowledge_base_id = "001"; knowledgeBaseInfo.name = "一个通用第三方知识库的名称 / this is a knowledgeBase name"; knowledgeBaseInfo.description = "一个描述 / a description"; response.knowledge_base_list = List.of(knowledgeBaseInfo); return response; } /** * @param authorization * @param request * @return RetrieveKnowledgeBaseResponse */ @PostMapping("/knowledge-bases/retrieve") public RetrieveKnowledgeBaseResponse retrieveKnowledgeBase( @RequestHeader("Authorization") String authorization, @RequestBody RetrieveKnowledgeBaseRequest request) { /** * 对密钥认证鉴权 * Verify and authenticate the key */ if (!authorization.startsWith("Bearer ")) { log.error("invalid authorization"); throw new RuntimeException("invalid authorization"); } String apiKey = authorization.substring("Bearer ".length()); /** * then do something for authorization * */ /** * 根据业务实现代码逻辑，构造返回结果 * Construct and return results based on your business implementation and code logic */ RetrieveKnowledgeBaseResponse response = new RetrieveKnowledgeBaseResponse(); response.total = 1; SearchChunkInfo searchChunkInfo = new SearchChunkInfo(); searchChunkInfo.knowledge_base_id = "001"; searchChunkInfo.file_id = "101"; searchChunkInfo.chunk_id = "201"; searchChunkInfo.content = "一个通用第三方知识库的检索切片内容 / this is a retrieve chunk content"; searchChunkInfo.title = "检索切片的标题 / retrieve chunk title"; searchChunkInfo.score = 0.8f; response.search_result_list = List.of(searchChunkInfo); return response; } /* * the response structure of the listKnowledgeBase function */ @Data public class ListKnowledgeBaseResponse { Integer total; List knowledge_base_list; } @Data public class KnowledgeBaseInfo { String knowledge_base_id; String name; String description; } /* * the request structure of the retrieveKnowledgeBase function */ @Data public static class RetrieveKnowledgeBaseRequest { List knowledge_base_ids; String query; String method; Integer offset; Integer limit; Integer top_k; Float search_threshold; List extra_params; } @Data public static class KnowledgeBaseExtraParam { String key; String value; } /* * the response structure of the retrieveKnowledgeBase function */ @Data public class RetrieveKnowledgeBaseResponse { Integer total; List search_result_list; } @Data public class SearchChunkInfo { String knowledge_base_id; String file_id; String chunk_id; String content; Float score; String title; } } ``` #### 常见问题 如果接口调用失败，请检查鉴权头是否正确配置。常见报错排查请参见第三方接入故障排除。