# 创建知识库并进行检索
#### 操作场景
本文通过调用一系列知识中心的API，介绍从零开始创建知识库并进行检索的基本流程。API调用方法请参见[如何调用API](https://support.huaweicloud.com/api-appstage/appstage_07_0008.html)。
#### 前提条件
准备一篇名为"问题.txt"的文档，文档内容为：
"什么是量子计算？它是一种利用量子力学原理进行信息处理的计算方式。====
什么是RAG？它是一种通过整合检索系统和生成模型的优势，来提升模型生成文本的质量和上下文相关性。===="
#### 操作流程
[步骤一：创建数据集]。
[步骤二：查询知识数据集创建结果]。
[步骤三：查询数据集版本和索引信息]。
[步骤四：创建知识库]。
[步骤五：查询知识库创建结果]。
[步骤六：启用或停用知识库召回功能]。
[步骤七：检索知识库数据]。
 #### 步骤一：创建数据集
调用[创建知识数据集](https://support.huaweicloud.com/api-appstage/CreateKnowledgeDataSet.html)接口创建数据集，示例如下：
```
{
"name": "测试",
"description": "测试",
"data_type": "TEXT",
"tags": [
"对话问答",
"文案生成"
],
"ingestion_config": {
"data_source": "FILE_UPLOAD",
"file_types": [
"txt"
]
},
"schedule_config": {
"schedule_type": "ONCE"
},
"preprocess_config": {
"cleaning_methods": [
"invisible"
],
"pdf_preprocess_type": "NO_PREPROCESS"
},
"chunk_config": {
"slicing_configs": {
"txt": {
"slicing_method": "sentence",
"sentence_slicing_config": {
"slicing_strategy": "equivalent",
"spec_symbols": [
"===="
],
"contain_separator": false,
"chunk_size": 26,
"chunk_overlap": 0
}
}
}
},
"extraction_config": {
"extraction_example": "今天天气如何？答：还不错哦。",
"extraction_mode": "RULE_EXTRACTION",
"rule_extraction_configs": [
{
"extraction_rule": "SEPARATOR",
"field_name": "question",
"separator_extraction": {
"contain_separator": false,
"extraction_code": 2,
"separator": "？"
}
},
{
"extraction_rule": "TEMPLATE",
"field_name": "answer",
"template_extraction": {
"contain_end": true,
"contain_start": false,
"end_with": "。",
"extraction_code": 1,
"start_with": "它是"
}
}
]
},
"index_config": {
"description": "索引配置",
"long_text_solution": "TRUNCATE_MODE",
"name": "索引配置",
"rag_type": "VECTOR_RAG",
"retrieval_configs": [
{
"category": "FULL_CHUNK",
"name": "chunk",
"retrieval_return": false,
"text_filter": false,
"vector_retrieval": false
},
{
"category": "CHUNK_FRAGMENT",
"name": "question",
"retrieval_return": true,
"text_filter": true,
"vector_retrieval": true
},
{
"category": "CHUNK_FRAGMENT",
"name": "answer",
"retrieval_return": true,
"text_filter": true,
"vector_retrieval": false
}
],
"vector_model_service_key": "GPT-4"
}
}
```
在创建知识数据集中，有几个参数需要注意：
- ingestion_config内的data_source：表明数据来源，FILE_UPLOAD为文件上传，您需上传文件；OBS_INGESTION表示OBS接入，您需添加OBS信息的配置。
- chunk_config：表示如何对文本进行切分。
- extraction_config：表明要对切片做提取操作，切片提取出的字段可以在索引配置中使用。
- index_config：索引配置，其中retrieval_configs配置完整切片内容，以及提取出的字段内容，在知识库检索时如何使用。
记录下接口返回的内容，该内容为知识数据集id。
```
{
"data" : "3f28e62-xxxxxxxx-a15be0d638a2"
}
```
 #### 步骤二：查询知识数据集创建结果
调用[查询知识数据集最新执行记录](https://support.huaweicloud.com/api-appstage/QueryKdsLatestExecutionRecord.html)接口查询创建结果，该接口所需的知识数据集id为[步骤一：创建数据集]返回的内容。
根据返回结果响应：
```
{
"data" : {
"id" : "djh28e62-3a81-4018-a48f-a15be0d63812",
"result" : "SUCCESS",
"progress" : 100.0,
"run_time" : 27684,
"start_time" : "2024-11-22T03:15:49.000+00:00",
"end_time" : "2024-11-22T03:16:17.000+00:00",
"log_detail" : "开始任务......结束任务"
}
}
```
- 如果result字段值为SUCCESS，则表明数据集创建成功。
- 如果result字段值为RUNNING，则表明数据集正在创建，请稍候。
- 如果result字段值为FAILURE，则表明数据集创建失败，请检查文件是否符合要求。
 
 #### 步骤三：查询数据集版本和索引信息
知识数据集创建成功后，调用[查询知识数据集详情](https://support.huaweicloud.com/api-appstage/QueryDataSetDetail.html)接口，查询数据集版本和索引信息，响应示例如下：
```
{
"data" : {
"data_set_versions" : [ {
"id" : "askdjh28e62-xxxxxxxxx-a15be0d63812",
"version" : "v2024-11-21T11:36:55Z",
"created_date" : "2024-11-11 19:36:57",
"last_updated_date" : "2024-11-21 19:36:57"
} ],
"index_configs" : [ {
"id" : "d3f28e62-xxxxxxx-a15be0d638a2",
"name" : "索引配置名称",
"description" : "索引配置",
"data_set_id" : "d3f28e62-3a81-4018-a48f-a15be0d638a2",
"vector_model_service_key" : "service_key",
"index_vector_config" : {
"long_text_solution" : "TRUNCATE_MODE"
}
} ]
}
}
```
保存创建知识库对应的数据集版本id、版本号、索引配置id。数据集版本和索引可能有多个，可以任意组合。
 #### 步骤四：创建知识库
调用[创建知识库](https://support.huaweicloud.com/api-appstage/CreateKnowledgeBase.html)接口创建知识库。根据保存的数据集id，数据集版本号，索引配置id，构建请求体，创建知识库即可。请求体如下：
```
{
"name": "知识库名称",
"description": "知识库描述",
"retrieval_status": "ENABLE",
"rag_type": "VECTOR_RAG",
"retrieval_config": {
"retrieval_modes": [
"SEMANTIC_RETRIEVAL",
"FULL_TEXT_RETRIEVAL"
],
"retrieval_hybrid_mode": "RRF"
},
"knowledge_data_sets": [
{
"data_set_id": "djh28e62-xxxxxxxxx-a15be0d63812",
"data_set_version": "v2024-11-21T11:36:55Z",
"index_config_id": "d3f28e62-xxxxxxx-a15be0d638a2"
}
]
}
```
注意：retrieval_status字段设置知识库是否启用检索，如果启用，则检索前不需要再调用修改知识库召回状态接口启用知识库。
将创建接口响应内容保存起来，该内容为知识库id：
```
{
"data" : "3f28e62-xxxxxxxx-a15be0d638a2"
}
```
 #### 步骤五：查询知识库创建结果
调用[查询知识库最新执行记录](https://support.huaweicloud.com/api-appstage/QueryKbLatestExecutionRecord.html)接口查询创建结果。该接口所需的知识库id为[步骤四：创建知识库]返回的内容。
返回结果响应如下：
```
{
"data" : {
"id" : "djh28e62-3a81-4018-a48f-a15be0d63812",
"result" : "SUCCESS",
"progress" : 100.0,
"run_time" : 27684,
"start_time" : "2024-11-22T03:15:49.000+00:00",
"end_time" : "2024-11-22T03:16:17.000+00:00",
"log_detail" : "开始任务......结束任务"
}
}
```
- 如果result字段值为SUCCESS，则表明知识库创建成功。
- 如果result字段值为RUNNING，则表明知识库正在创建，请稍候。
- 如果result字段值为FAILURE，则表明知识库创建失败，请检查文件是否符合要求。
 
 #### 步骤六：启用或停用知识库召回功能
调用[修改知识库召回状态](https://support.huaweicloud.com/api-appstage/UpdateKnowledgeBaseRetrievalStatus.html)接口启用或停用知识库召回功能。
若创建知识库时已经启用知识库，则不需要执行此步骤。否则需启用知识库，请求体为：
```
ENABLE
```
若响应如下，则启用成功。
```
{
"data" : true
}
```
 #### 步骤七：检索知识库数据
调用[检索知识库数据](https://support.huaweicloud.com/api-appstage/SearchEmbedData.html)接口检索知识库（知识库召回状态需为启用），请求体示例如下：
```
{
"keyword" : "什么是",
"similarity_min" : "0.78",
"limit" : 10,
"filter" : {
"group_type" : "AND",
"expressions" : [ {
"field" : "metadata.answer",
"field_type" : "STRING",
"operator" : "EQUAL",
"values" : [ "一种利用量子力学原理进行信息处理的计算方式。" ]
} ]
},
"order_by" : {
"order_items" : [ {
"field" : "metadata.order",
"field_type" : "INT",
"order_type" : "DESC"
} ]
},
"data_sets" : [ {
"data_set_id" : "a31ed909-xxxx-xxxx-xxxx-10958c90b3f7"
} ]
}
```
根据索引配置，返回结果为：
```
{
"data" : [ {
"id" : "812857ef-xxxx-xxxx-xxxx-24ba9fd5e95c",
"document" : "什么是量子计算？它是一种利用量子力学原理进行信息处理的计算方式。",
"chunk" : "什么是量子计算？它是一种利用量子力学原理进行信息处理的计算方式。",
"chunk_fragments" : {
"question" : "什么是量子计算。",
"answer" : "一种利用量子力学原理进行信息处理的计算方式"
},
"similarity" : 0.87,
"metadata" : {
"order" : 10,
"file_name" : "问题.txt",
"path" : "问题.txt ",
"question" : "什么是量子计算。",
"answer" : "一种利用量子力学原理进行信息处理的计算方式。"
},
"download_addresses" : {
"xxx.png" : "https://xxxx"
},
"download_address" : null,
"data_set_id" : "3967c49d-xxxx-xxxx-xxxx-5eda056a1f1b"
} ]
}
```
响应参数解释：
- document：表示向量化检索内容，索引配置时选择某个字段为向量化字段，检索命中时返回该字段内容，即vector_retrieval为true。
- chunk：表示完整切片，索引配置时配置chunk作为附加字段返回时，该字段有内容，即索引配置中category为FULL_CHUNK，retrieval_return为true。
- chunk_fragments：表示切片提取字段，索引配置时配置所提取的字段作为附加字段返回时，该字段有内容，即索引配置中category为CHUNK_FRAGMENT，retrieval_return为true。
- metadata：默认包含order、file_name、path三个字段，若索引配置时配置所提取的字段作为文本过滤字段时，即索引配置中category为CHUNK_FRAGMENT，text_filter为true时，metadata下会新增该字段及其内容。