第三方通用知识库接入规范-j9九游会登录

前言

当您拥有企业内部已有的知识库系统（如内部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 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;
    }
}

常见问题

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