第三方通用知识库接入规范

前言

当您拥有企业内部已有的知识库系统（如内部Wiki、私有文档库），且不希望将数据迁移至AgentArts平台时，可遵循本规范开发适配接口。

典型场景

企业智能体需要检索内部保密文档，通过实现本规范定义的API接口，AgentArts可直接调用您的知识库服务进行问答增强。

工作原理

您需开发并部署两个标准HTTP接口，AgentArts智能体在对话过程中，当需要检索外部知识时，将依次调用您的接口：

1. 调用获取知识库列表接口，获取可用的知识库列表。
2. 根据用户问题，调用检索知识库接口，获取相关文档切片。
3. 将检索结果注入提示词，增强问答能力。

费用说明

通过AgentArts调用第三方知识库接口，可能会产生公网流量费用，具体取决于您的第三方服务部署环境。该调用过程将消耗智能体的运行时长资源。

API接口规范

对于API接口适配，开发者需要新增两个接口，一个是获取知识库列表，一个是检索知识库。开发者按照接口：获取知识库列表、接口：检索知识库规范提供对外接口，并在接口内实现密钥鉴权、数据查询、知识检索等业务逻辑，最后按照规范返回对应数据。

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<KnowledgeBaseInfo> 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<String> knowledge_base_ids;
        String query;
        String method;
        Integer offset;
        Integer limit;
        Integer top_k;
        Float search_threshold;
        List<KnowledgeBaseExtraParam> 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<SearchChunkInfo> search_result_list;
    }

    @Data
    public class SearchChunkInfo {
        String knowledge_base_id;
        String file_id;
        String chunk_id;
        String content;
        Float score;
        String title;
    }
}

常见问题

如果接口调用失败，请检查鉴权头是否正确配置。常见报错排查请参见第三方接入故障排除。