# 创建知识库 #### 功能介绍 创建知识库。 #### URI POST /v1/koosearch/repos #### 请求参数 表1请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | X-Auth-Token | 是 | String | **参数解释：** 接口鉴权使用的Token，Token获取方式参考：3.2节 认证鉴权。 **约束限制：** 不涉及。 | 表2请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | name | 是 | String | **参数解释：** 知识库名称。 **约束限制：** 只能由中文字符、英文字母、数字及"_"、"-"组成，且长度为\[1-64\]个字符。 **默认取值：** 不涉及。 | | detail | 是 | String | **参数解释：** 知识库的描述信息。 **约束限制：** 长度为\[1-100\]个字符。 **默认取值：** 不涉及。 | | embedding_model | 是 | String | **参数解释：** 当前知识库使用的embedding模型名称。 embedding模型：用于将文本内容向量化，进行向量检索的模型。 **约束限制：** - 只能由中文字符、英文字母、数字及"_"、"-"组成，且长度为\[1-32\]个字符。 - 必须是平台上配置的embedding模型。平台上配置的模型可以通过ListModels接口查看。 **默认取值：** 不涉及。 | | rerank_model | 是 | String | **参数解释：** 当前知识库使用的rerank模型名称。 rerank模型：对embedding模型通过向量检索返回的top_k个结果，进行重排序，目的是将与query匹配度最高的结果通过rerank模型排上来。 **约束限制：** - 只能由中文字符、英文字母、数字及"_"、"-"组成，且长度为\[1-32\]个字符。 - 必须是平台上配置的rerank模型。平台上配置的模型可以通过ListModels接口查看。 **默认取值：** 不涉及。 | | pangu_nlp_model | 是 | String | **参数解释：** 当前知识库使用的NLP大模型名称。 NLP大模型：chat接口使用的生成模型，可以基于输入的文本，生成答案。 **约束限制：** - 只能由中文字符、英文字母、数字及"_"、"-"组成，且长度为\[1-32\]个字符。 - 必须是平台上配置的nlp模型。平台上配置的模型可以通过ListModels接口查看。 **默认取值：** 不涉及。 | | file_extract | 是 | [FileExtractConf] object | 文档解析整体配置。 | | search_plan_category_ids | 否 | Array of strings | **参数解释：** 搜索规划category类型配置。 当未命中配置的类型时，先使用知识库检索再进行大模型总结。 当命中配置的类型时，直接使用大模型回答。 **取值范围：** \["人设类", "天气类", "行业知识类", "行业知识类-制造", "行业知识类-医疗", "行业知识类-政务", "行业知识类-金融", "语言任务类", "通用知识类", "闲聊类"\] **约束限制：** 不涉及。 | | language_id | 否 | String | **参数解释：** 当前知识库的语言ID。 **取值范围：** zh==CHINESE en==ENGLISH th==THAI ar==ARABIC **约束条件：** 不涉及。 | | cache_enabled | 否 | Boolean | **参数解释：** 当前知识库是否打开缓存。 false: 不缓存结果。 true：缓存query/reference/answer结果，并在下次检索时，遇到相似query时，直接返回缓存结果，提升时延。 **约束限制：** 不涉及。 **默认取值：** false | | answer_reference_enabled | 否 | Boolean | **参数解释：** 当前知识库是否开启引用溯源：定位答案的参考来源位置。 **约束限制：** 不涉及。 **默认取值：** false | | answer_image_reference_enabled | 否 | Boolean | **参数解释：** 是否开启图文并茂。 true: 当文档中有与问题相关的图片时，返回问题的文字答案的同时，返回图片。 false：不召回图片。 **约束限制：** 需要同时打开"引用定位"(answer_reference_enabled)。 **默认取值：** false | | session_config | 否 | [SessionConfig] object | 缓存策略。 | | extend_config | 否 | [KnowledgeRepoExtendConfig] object | 知识库扩展配置。 | | tags | 否 | Array of [TagInfo] objects | 标签列表。 | | refs | 否 | String | **参数解释：** 引用知识库标识列表，以逗号分隔，用于支持多个知识库联合检索问答的场景。 **约束限制：** 不同知识库ID之间以逗号分隔。 | | search_plan_model | 否 | String | **参数解释：** search_plan模型名称。 search_plan模型：搜索规划模型，将用户输入的query重新规划为更适合检索的query，包含query改写、query补全等。 **约束限制：** - 只能由中文字符、英文字母、数字及"_"、"-"组成，且长度为\[1-32\]个字符。 - 必须是平台上配置的search_plan模型。平台上配置的模型可以通过ListModels接口查看。 | | prompt_info | 否 | [KnowledgeRepoPromptInfo] object | 提示词信息。 | 表3FileExtractConf | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | parse_conf | 否 | [ParseConf] object | **参数解释：** 文档解析配置，包含是否使用OCR增强、是否解析图片、解析图片是否需要提取文字、是否解析页眉页脚、是否解析目录页。 **约束限制：** 不涉及。 | | split_conf | 否 | [SplitConf] object | **参数限制：** 拆分配置，包括分段方式设置、层级解析模式设置、标题层级深度设置、标题保存方式设置、分段长度配置、标题匹配pattern配置等。 **约束限制：** 不涉及。 | | id | 否 | String | **参数解释：** 文档解析ID。 **约束限制：** 不涉及。 | 表4ParseConf | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | ocr_enabled | 否 | Boolean | **参数解释：** 当前知识库是否使用OCR增强。 - 纯word文档无需使用OCR解析。 - pdf/pptx等需要使用OCR服务进行智能文档识别，如表格解析、文字提取等。 **约束限制：** 不涉及。 **默认取值：** false | | image_enabled | 否 | Boolean | **参数解释：** 当前知识库是否需要解析图片。 true：解析图片。具体解析方式在image_conf中配置。 false：在文档中遇到图片默认跳过，不处理图片。 **约束限制：** 不涉及。 **默认取值：** false | | header_footer_enabled | 否 | Boolean | **参数解释：** 当前知识库中的文件，是否需要解析页眉页脚。 true: 解析结果中包含页眉页脚。 false: 解析结果中不包含页眉页脚。（当页眉页脚中没有关键文本信息时，建议为false，避免干扰。） **约束限制：** 不涉及 **默认取值：** false | | catalog_enabled | 否 | Boolean | **参数解释：** 当前知识库中的文件，是否需要解析目录页。 false：解析结果中不包含目录页。（当目录页中没有特别需要保留的信息时，建议默认为false。通常目录页中含有大量关键词，会干扰检索结果。） true：解析结果中包含目录页。 **约束限制：** 不涉及。 **默认取值：** false | | image_conf | 否 | String | **参数解释：** 图片解析开启（image_enable为True）时，使用的图片解析方式。 - TEXT ：将图片中的文本提取出来，图片本身不保留。 - IMAGE： 保留图片的原图。 **约束限制：** 当需要使用图文并茂返回答案时，必须使用IMAGE模式，保留原图。 **默认取值：** TEXT | 表5SplitConf | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | split_mode | 否 | String | **参数解释：** 文档切分的模式选择。 **取值范围：** 有四种模式可选： - AUTO- 自动拆分，自动识别文档格式匹配适合的拆分解析方式。 - LENGTH-按长度拆分，例如每500字分一段。 - CATALOG-层级分段下-自动解析。自动识别文章的层级结构，按照文章的层级结构分片。例如1.1.2章节为一个分片，1.1.3章节为一个分片。 - RULE- 层级分段下-规则解析。自定义层级标题的匹配规则，并依据自定义的规则进行章节匹配、切分。 **约束限制：** 不涉及 **默认取值：** AUTO | | separator_ids | 否 | Array of strings | **参数解释：** 自动分段和长度分段模式下的，分段标识符ID列表。 分段标识符：用于决定分片切片时的结束符。 **取值范围：** 具体取值映射： "period_zh"：中文句号。 "period_en"：英文句号. "exclamation_mark_zh"：中文叹号！ "exclamation_mark_en"：英文叹号! "question_mark_zh"：中文问号？ "question_mark_en"：英文问号? "comma_zh"：中文逗号， "comma_en"：英文逗号, "space_en"：空格 **约束限制：** 不涉及。 **默认取值：** \["period_zh", "period_en", "exclamation_mark_zh", "exclamation_mark_en", "question_mark_zh", "question_mark_en"\] | | rule_regex_id | 否 | String | **参数解释：** 选择的用户自定义解析规则ID。 **约束限制：** 不涉及。 | | chunk_size | 否 | Integer | **参数解释：** 文档分段切片的最大长度。文档切片时根据该最大长度进行切片。 **约束限制：** 不涉及。 **默认取值：** 500 | | title_level | 否 | Integer | **参数解释：** 分片保留的标题层级深度。例如： 深度为3时：当前段落为1.1.3，父标题1.1 和 父标题1 均会保留。 深度为2时：当前段落为1.1.3，父标题1.1 保留，父标题1 舍弃。 **约束限制：** 不涉及。 **默认取值：** 3 | | combine_title | 否 | Boolean | **参数解释：** 是否保留层级标题组合。 **取值说明：** false：仅保留最后一级标题。 true：保存多层标题组合，从第一级到最后一级。例如：1 说明 1.1 使用说明 1.1.1 如何打开冰箱 **约束限制：** 不涉及。 **默认取值：** false | | merge_titles | 否 | Boolean | **参数解释：** 是否跨标题合并。 **取值说明：** true：不同标题的段落，单个段落文字较少时，自动合并到指定的分段长度，有助于生成更全面的结果。例如：相邻的两个子段落都不足200字，预期分段长度为500，此时会将两段内容合并为一段内容。 false：不同标题的段落，不做合并。 **约束限制：** 不涉及。 **默认取值：** true | 表6SessionConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | similarity_threshold | 是 | Float | **参数解释：** 命中缓存问题的query2query相似度阈值。 **取值范围：** 0.1 \~ 1.0，阈值设置的越高，query和缓存问题的相似程度要求就越高。 **约束限制：** 不涉及。 | | answer_select_policy | 是 | String | **参数解释：** 缓存命中选择策略。 **取值范围：** FIRST：在匹配到的结果中选择分数最高的作为答案。 RANDOM：在匹配到的结果中随机选择一个作为答案。 **约束限制：** 不涉及。 | | eviction | 是 | [Eviction] object | 缓存过期策略。 | | model_name | 是 | String | **参数解释：** 缓存命中时，使用的query2query模型名称，用于计算新query和缓存query的相似度。 **约束限制：** 不涉及。 | 表7Eviction | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | policy | 是 | String | **参数解释：** 声明缓存使用哪种过期策略。 **取值范围：** LRU:（Least Recently Used） now - accessTime \> ttl，清除。 FIFO:（First In First Out） now - createTime \> ttl，清除。 LFU:（Least Frequency Used）hit_count \< 阈值，清除。 **约束限制：** 不涉及。 | | ttl | 否 | Long | **参数解释：** 缓存过期时间，当缓存超过设定时间时清理缓存。单位： 毫秒。 **约束限制：** 不涉及。 | | hit_count_threshold | 否 | Long | **参数解释：** 缓存命中次数阈值，当命中次数达到阈值时，不使用缓存结果。 **约束限制：** 不涉及。 | 表8KnowledgeRepoExtendConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | extend_context | 否 | Boolean | **参数解释：** 是否对参考分片进行长上下文扩展。提供更广泛的上下文，以提供给模型生成完整回答。 **约束限制：** 不涉及。 | | effective_input_length | 否 | Integer | **参数解释：** 扩展上下文打开时，控制选取的上下文的长度。 与模型相关，确保输入令牌的有效长度以保证最佳输出。 **约束限制：** 考虑到多轮对话，建议控制在模型上下文长度的60%（向上取整）。 **取值范围：** 2 \~ 128，单位：k。 | | top_p | 否 | Float | **参数解释：** 一种替代温度采样的方法，称为nucleus sampling，通过限制词汇的选择范围来控制生成文本的多样性。top_p值越高，候选单词越多，文本多样性越高。 **约束限制：** 通常建议更改top_p或temperature来调整生成文本的倾向性，但不要同时更改这两个参数。 **取值范围：** 0.1 \~ 1 **默认取值：** 0.1 | | max_tokens | 否 | Integer | **参数解释：** 模型生成最大新词数。 **约束限制：** 和模型最长支持的上下文长度有关，max_tokens小于\<模型支持的最大上下文长度 - 输入给模型的token长度\>。 **取值范围：** 1 \~ 131072 **默认取值：** 131072 | | chat_temperature | 否 | Float | **参数解释：** 非搜索增强场景下，用于控制模型生成文本的多样性和创造力。 取值接近0表示最低的随机性，1表示最高的随机性。一般来说，temperature越低，适合完成确定性的任务。temperature越高，例如0.9，适合完成创造性的任务。 **约束限制：** 不涉及。 **取值范围：** 0 \~ 1。 | | search_temperature | 否 | Float | **参数解释：** 搜索增强场景下，控制模型生成文本的多样性和创造力。 取值接近0表示最低的随机性，1表示最高的随机性。一般来说，temperature越低，适合完成确定性的任务。temperature越高，例如0.9，适合完成创造性的任务。 **约束限制：** 不涉及。 **取值范围：** 0 \~ 1，盘古NLP模型一般设置为0.2/0.3。 **默认取值：** 0.3 | | presence_penalty | 否 | Float | **参数解释：** 控制生成的文本中重复内容的程度。presence_penalty的目的是减少模型在生成文本时重复使用相同或类似的内容，以提高生成文本的多样性。即如果一个Token已经在之前的文本中出现过，那么模型在生成这个Token时会受到一定的惩罚。 presence_penalty越小，模型考虑之前生成的Token越少，可能导致文本中出现重复内容。 presence_penalty越大，模型会更倾向于生成新的、未出现过的Token，生成的文本会更加多样化。 **取值范围：** -2 \~ 2，具体的取值需要权衡，盘古NLP模型一般情况下可以取1.1。 **默认取值：** 0 | | use_system_prompt | 否 | Boolean | **参数解释：** 是否使用系统prompt，与盘古NLP模型的RAG场景中prompt标准拼接方案保持一致。 **约束限制：** 当NLP模型选用盘古NLP模型时，通用场景中，可以考虑使用系统prompt。 **默认取值：** false | | system_prompt | 否 | String | **参数解释：** 系统prompt。 **约束限制：** 1.当 use_system_prompt为true时必填。 2.不需要拼接query。 | | embedding_search_enable | 否 | Boolean | **参数解释：** 在检索相关文档时，是否打开向量检索。 **约束限制：** 不涉及。 **默认取值：** true | | keyword_search_enable | 否 | Boolean | **参数解释：** 在检索相关文档时，是否打开关键词检索。 **约束限制：** 不涉及。 **默认取值：** false | | keyword_top_k | 否 | Integer | **参数解释：** 使用关键词检索时返回的top多少的结果。 **约束限制：** 不涉及。 **取值范围：** 0 \~ 100 **默认取值：** 10 | | refuse_enable | 否 | Boolean | **参数解释：** 如果未找到相关参考文档内容，是否选择不触发模型调用，直接让平台拒绝回答。 **约束限制：** 不涉及。 **默认取值：** false | | refuse_answer | 否 | String | **参数解释：** 当refuse_enabled为true时，如果未找到相关参考文档内容，平台拒答使用的话术配置。 **约束限制：** 不涉及。 | | image_match_type | 否 | String | **参数解释：** 图文召回的场景下，两种图片召回的模式选择。 **取值范围：** 当前仅支持context_match和reference_match。 context_match：仅召回语义相关图片：引用文段中图片的上下文与生成文段语义相似即召回，否则不召回。 reference_match：引用文段中图片全部召回。 **约束限制：** 不涉及。 **默认取值：** context_match | | custom_types | 否 | Map\ | **参数解释：** 自定义字段的mapping类型字典，适用于结构化数据场景，指定可查询字段。 例如：{"companyName": "keyword"} 解释：需要检索的字段名：companyName， 检索方式：关键词匹配。 **约束限制：** mapping字典中的value值需要符合ES查询支持的类型，例如keyword/integer/text等。 | 表9TagInfo | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | tag_key | 是 | String | **参数解释：** 集群标签的key值。 **取值范围：** 可输入的字符串长度为1\~36个字符。只能包含数字、字母、中划线"-"和下划线"_"。 **约束限制：** 不涉及。 | | tag_value | 是 | String | **参数解释：** 集群标签的value值。 **取值范围：** 可输入的字符串长度为0\~43个字符。只能包含数字、字母、中划线"-"和下划线"_"。 **约束限制：** 不涉及。 | 表10KnowledgeRepoPromptInfo | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | prompt_id | 否 | String | **参数解释：** 当前知识库使用的NLP模型提示词ID。 **约束限制：** prompt_id必须是prompt管理中存在的prompt_id。 | | qa_question_prompt_id | 否 | String | **参数解释：** 当前知识库使用的QA问题生成提示词ID，该提示词用于使用文档自动生成QA对的场景。 **约束限制：** prompt_id必须是prompt管理中存在的prompt_id。 | | qa_answer_prompt_id | 否 | String | **参数解释：** 当前知识库使用的QA答案生成提示词ID。该提示词用于使用文档自动生成QA对的场景。 **约束限制：** prompt_id必须是prompt管理中存在的prompt_id。 | #### 响应参数 **状态码：200** 表11响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | repo_id | String | **参数解释：** 当前知识库ID。 **约束限制：** 不涉及。 | **状态码：400** 表12响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | [错误码](https://support.huaweicloud.com/api-koosearch/ErrorCode.html) | | error_msg | String | 错误描述 | **状态码：500** 表13响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | [错误码](https://support.huaweicloud.com/api-koosearch/ErrorCode.html) | | error_msg | String | 错误描述 | #### 请求示例 ``` POST https://{endpoint}/v1/koosearch/repos { "name" : "知识库A", "language_id" : "zh", "detail" : "", "tags" : [ ], "file_extract" : { "parse_conf" : { "ocr_enabled" : true, "image_enabled" : true, "header_footer_enabled" : false, "catalog_enabled" : false, "image_conf" : "IMAGE" }, "split_conf" : { "split_mode" : "AUTO" } }, "extend_config" : { "extend_context" : false, "effective_input_length" : 20, "custom_types" : { }, "image_match_type" : "context_match" }, "embedding_model" : "pangu_embedding", "rerank_model" : "pangu_rerank", "search_plan_model" : "search-plan", "pangu_nlp_model" : "KooSearch-N1", "cache_enabled" : false, "answer_reference_enabled" : false, "answer_image_reference_enabled" : false } ``` #### 响应示例 **状态码：200** 知识库ID。 ``` { "repo_id" : "acd90739-2e22-4870-b2db-35018699b623" } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | 知识库ID。 | | 400 | 请求体参数错误 | | 500 | 内部异常 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-koosearch/ErrorCode.html)。