135 lines
14 KiB
Markdown
135 lines
14 KiB
Markdown
|
## ClassDef KBSummaryService
|
|||
|
|
**KBSummaryService**: KBSummaryService类的功能是管理和操作知识库摘要的生成、添加和删除。
|
|||
|
|
|
|||
|
|
**属性**:
|
|||
|
|
- `kb_name`: 知识库的名称。
|
|||
|
|
- `embed_model`: 嵌入模型的名称。
|
|||
|
|
- `vs_path`: 向量存储的路径。
|
|||
|
|
- `kb_path`: 知识库的路径。
|
|||
|
|
|
|||
|
|
**代码描述**:
|
|||
|
|
KBSummaryService类是一个抽象基类（ABC），用于定义操作知识库摘要的基本方法和属性。它主要负责知识库摘要的创建、添加和删除。类的初始化方法接受知识库名称和嵌入模型名称作为参数，并根据这些参数设置知识库路径和向量存储路径。如果向量存储路径不存在，则会创建该路径。
|
|||
|
|
|
|||
|
|
- `get_vs_path`方法返回向量存储的完整路径。
|
|||
|
|
- `get_kb_path`方法返回知识库的完整路径。
|
|||
|
|
- `load_vector_store`方法负责加载或创建向量存储。
|
|||
|
|
- `add_kb_summary`方法用于将文档摘要添加到向量存储和数据库中。
|
|||
|
|
- `create_kb_summary`方法用于创建知识库摘要的存储空间，如果存储空间不存在则创建。
|
|||
|
|
- `drop_kb_summary`方法用于删除知识库摘要的向量存储和数据库记录。
|
|||
|
|
|
|||
|
|
在项目中，`KBSummaryService`类被用于处理知识库摘要的生成和管理。例如，在`recreate_summary_vector_store`和`summary_file_to_vector_store`的场景中，通过`KBSummaryService`类的实例来重新创建或更新知识库的摘要信息。这涉及到从知识库中读取文档，生成摘要，然后将这些摘要添加到向量存储和数据库中。
|
|||
|
|
|
|||
|
|
**注意**:
|
|||
|
|
- 在使用`KBSummaryService`类之前，确保已经正确设置了知识库的路径和嵌入模型。
|
|||
|
|
- 在调用`add_kb_summary`方法之前，应确保摘要信息已经准备好，并且向量存储已经创建。
|
|||
|
|
|
|||
|
|
**输出示例**:
|
|||
|
|
由于`KBSummaryService`类的方法主要进行数据处理和存储操作，它们的输出通常不直接返回给用户，而是通过日志记录或数据库状态反映操作结果。例如，当成功添加知识库摘要时，可能会在日志中记录相应的信息，如“知识库'example_kb'的摘要添加成功”。
|
|||
|
|
### FunctionDef __init__(self, knowledge_base_name, embed_model)
|
|||
|
|
**__init__**: 此函数的功能是初始化KBSummaryService类的实例。
|
|||
|
|
|
|||
|
|
**参数**:
|
|||
|
|
- knowledge_base_name: 知识库的名称，类型为字符串。
|
|||
|
|
- embed_model: 嵌入模型的名称，默认值为EMBEDDING_MODEL，类型为字符串。
|
|||
|
|
|
|||
|
|
**代码描述**: `__init__` 方法是 `KBSummaryService` 类的构造函数，用于初始化类的实例。在这个方法中，首先将传入的 `knowledge_base_name` 和 `embed_model` 参数分别赋值给实例变量 `self.kb_name` 和 `self.embed_model`。这两个实例变量分别存储了知识库的名称和使用的嵌入模型名称。
|
|||
|
|
|
|||
|
|
接下来，方法调用 `self.get_kb_path()` 和 `self.get_vs_path()` 分别获取知识库的完整路径和向量存储的完整路径，并将这些路径分别赋值给实例变量 `self.kb_path` 和 `self.vs_path`。`get_kb_path` 方法返回知识库文件的完整路径，而 `get_vs_path` 方法则基于 `get_kb_path` 方法返回的路径，进一步构造出向量存储的完整路径。
|
|||
|
|
|
|||
|
|
最后，通过检查 `self.vs_path` 指定的路径是否存在，如果不存在，则使用 `os.makedirs` 方法创建该路径。这一步骤确保了向量存储的目录在使用前已经被正确创建。
|
|||
|
|
|
|||
|
|
**注意**: 在使用 `__init__` 方法初始化 `KBSummaryService` 类的实例时，需要确保传入的 `knowledge_base_name` 是有效的，且对应的知识库在文件系统中存在。此外，考虑到不同操作系统的路径表示可能有所不同，`get_kb_path` 和 `get_vs_path` 方法内部使用了 `os.path.join` 来构造路径，以确保路径的正确性和兼容性。
|
|||
|
|
***
|
|||
|
|
### FunctionDef get_vs_path(self)
|
|||
|
|
**get_vs_path**: 此函数的功能是获取向量存储的完整路径。
|
|||
|
|
|
|||
|
|
**参数**: 此函数没有参数。
|
|||
|
|
|
|||
|
|
**代码描述**: `get_vs_path` 函数是 `KBSummaryService` 类的一个方法，用于构造并返回知识库摘要向量存储的完整路径。它首先调用 `get_kb_path` 方法获取知识库的完整路径，然后使用 `os.path.join` 方法将此路径与字符串 "summary_vector_store" 拼接起来，从而生成向量存储的完整路径。这个方法在 `KBSummaryService` 类的初始化方法 `__init__` 中被调用，并将生成的路径赋值给实例变量 `self.vs_path`。如果检测到该路径不存在，则会创建对应的目录。
|
|||
|
|
|
|||
|
|
**注意**: 使用此函数时，需要确保 `get_kb_path` 方法能够正确返回知识库的路径，且该路径已经存在于文件系统中。此外，考虑到不同操作系统之间的路径表示差异，使用 `os.path.join` 方法可以确保路径的正确性和兼容性。
|
|||
|
|
|
|||
|
|
**输出示例**: 假设 `get_kb_path` 方法返回的路径为 "/data/knowledge_bases/tech_docs"，那么此函数的返回值将会是 "/data/knowledge_bases/tech_docs/summary_vector_store"。这意味着向量存储将位于知识库 "tech_docs" 下的 "summary_vector_store" 目录中。
|
|||
|
|
***
|
|||
|
|
### FunctionDef get_kb_path(self)
|
|||
|
|
**get_kb_path**: 此函数的功能是获取知识库的完整路径。
|
|||
|
|
|
|||
|
|
**参数**: 此函数没有参数。
|
|||
|
|
|
|||
|
|
**代码描述**: `get_kb_path` 函数是 `KBSummaryService` 类的一个方法，用于返回知识库文件的完整路径。它通过将 `KB_ROOT_PATH`（一个预定义的知识库根路径常量）与 `self.kb_name`（知识库的名称，是在类的初始化时通过参数传入的）使用 `os.path.join` 方法拼接起来，从而构造出知识库的完整路径。这个方法在 `KBSummaryService` 类的初始化方法 `__init__` 中被调用，用于设置实例变量 `self.kb_path`，即知识库路径。此外，它还被 `get_vs_path` 方法调用，作为构造向量存储路径的一部分。
|
|||
|
|
|
|||
|
|
在项目中，`get_kb_path` 方法的调用确保了知识库路径的一致性和正确性，无论是直接获取知识库路径还是作为其他路径（如向量存储路径）构建的基础，都能确保路径的准确性。
|
|||
|
|
|
|||
|
|
**注意**: 使用此函数时，需要确保 `KB_ROOT_PATH` 和 `self.kb_name` 已经正确设置，且 `KB_ROOT_PATH` 指向的目录存在于文件系统中。此外，考虑到操作系统的差异，`os.path.join` 方法能够确保路径的正确性，无论是在 Windows 还是在类 Unix 系统上。
|
|||
|
|
|
|||
|
|
**输出示例**: 假设 `KB_ROOT_PATH` 为 "/data/knowledge_bases"，且 `self.kb_name` 为 "tech_docs"，那么此函数的返回值将会是 "/data/knowledge_bases/tech_docs"。
|
|||
|
|
***
|
|||
|
|
### FunctionDef load_vector_store(self)
|
|||
|
|
**load_vector_store**: 此函数的功能是加载一个线程安全的FAISS向量库实例。
|
|||
|
|
|
|||
|
|
**参数**: 此函数没有显式参数，但它依赖于`KBSummaryService`类的实例属性。
|
|||
|
|
|
|||
|
|
**代码描述**: `load_vector_store`函数通过调用`kb_faiss_pool.load_vector_store`方法来加载一个FAISS向量库。这个方法接受几个关键参数：`kb_name`（知识库的名称），`vector_name`（向量库的名称，这里固定为"summary_vector_store"），`embed_model`（嵌入模型），以及`create`（一个布尔值，指示如果向量库不存在时是否创建）。这些参数的值来源于`KBSummaryService`类的实例属性。函数返回一个`ThreadSafeFaiss`实例，这是一个线程安全的封装，用于操作和管理FAISS向量库。
|
|||
|
|
|
|||
|
|
**注意**: 使用`load_vector_store`函数时，需要确保`KBSummaryService`类的实例属性已正确设置，因为这些属性将直接影响向量库的加载过程。此外，返回的`ThreadSafeFaiss`实例支持线程安全的操作，适用于多线程环境。
|
|||
|
|
|
|||
|
|
**输出示例**: 假设`KBSummaryService`的实例属性已正确设置，调用`load_vector_store`可能会返回如下的`ThreadSafeFaiss`实例表示：
|
|||
|
|
`<ThreadSafeFaiss: key: summary_vector_store, obj: <FAISS向量库对象的表示>, docs_count: 100>`
|
|||
|
|
|
|||
|
|
此函数在项目中的调用情况包括在`add_kb_summary`方法中，用于获取向量库实例以添加文档并将其保存到本地路径。这表明`load_vector_store`函数是知识库摘要服务中管理和操作FAISS向量库的关键组成部分，支持知识库摘要的添加和存储过程。
|
|||
|
|
***
|
|||
|
|
### FunctionDef add_kb_summary(self, summary_combine_docs)
|
|||
|
|
**add_kb_summary**: 此函数的功能是将文档摘要添加到向量存储并更新数据库。
|
|||
|
|
|
|||
|
|
**参数**:
|
|||
|
|
- `summary_combine_docs`: `List[Document]`类型，包含需要添加到向量存储和数据库中的文档摘要信息。
|
|||
|
|
|
|||
|
|
**代码描述**:
|
|||
|
|
`add_kb_summary`函数首先通过调用`load_vector_store`方法加载一个线程安全的FAISS向量库实例。接着，使用`acquire`方法安全地获取向量库实例，并向其中添加文档摘要信息，这些信息来自于`summary_combine_docs`参数。添加完成后，向量库的状态会被保存到本地路径。
|
|||
|
|
|
|||
|
|
随后，函数构造一个包含摘要信息的列表`summary_infos`，每个摘要信息包括摘要内容、摘要ID、文档ID列表和元数据。这些信息是基于`summary_combine_docs`中每个文档的`page_content`、生成的ID、`metadata`中的`doc_ids`和`metadata`本身。
|
|||
|
|
|
|||
|
|
最后，`add_kb_summary`函数调用`add_summary_to_db`函数，将摘要信息添加到数据库中。此操作依赖于当前知识库服务实例的`kb_name`属性和构造的`summary_infos`列表。函数执行成功后，返回`add_summary_to_db`的执行结果，通常是一个表示操作成功的布尔值。
|
|||
|
|
|
|||
|
|
**注意**:
|
|||
|
|
- 确保`summary_combine_docs`参数中的每个文档都包含必要的摘要信息和元数据。
|
|||
|
|
- 在多线程环境下操作向量库和数据库时，函数内部已采取必要的线程安全措施，请避免在外部重复加锁。
|
|||
|
|
- 函数执行成功并不直接返回摘要信息，而是通过数据库操作的结果来反映操作是否成功。
|
|||
|
|
|
|||
|
|
**输出示例**:
|
|||
|
|
调用`add_kb_summary`函数通常不会直接返回具体的摘要信息，而是返回一个布尔值，例如`True`，表示所有摘要信息已成功添加到向量存储并更新到数据库中。
|
|||
|
|
|
|||
|
|
在项目中，`add_kb_summary`函数被用于处理知识库文档的摘要信息，支持知识库摘要的创建和更新流程。例如，在知识库摘要API中，通过处理文档文件生成摘要并调用此函数，将摘要信息添加到向量存储和数据库，从而实现知识库的动态更新和管理。
|
|||
|
|
***
|
|||
|
|
### FunctionDef create_kb_summary(self)
|
|||
|
|
**create_kb_summary**: 此函数的功能是创建知识库摘要的存储路径。
|
|||
|
|
|
|||
|
|
**参数**: 此函数没有参数。
|
|||
|
|
|
|||
|
|
**代码描述**: `create_kb_summary` 函数是 `KBSummaryService` 类的一个方法，用于在指定的存储路径不存在时创建该路径。这个方法首先检查 `self.vs_path`（一个类属性，代表知识库摘要的存储路径）是否存在。如果该路径不存在，函数则会使用 `os.makedirs` 方法创建这个路径。这个功能在知识库摘要的生成和存储过程中非常关键，确保了存储知识库摘要的目录是存在的，从而可以顺利地保存摘要数据。
|
|||
|
|
|
|||
|
|
在项目中，`create_kb_summary` 函数被 `recreate_summary_vector_store` 和 `summary_file_to_vector_store` 两个方法调用。这两个方法分别位于 `kb_summary_api.py` 文件中，它们的共同点是都会在处理知识库摘要之前调用 `create_kb_summary` 函数来确保摘要数据的存储路径是存在的。无论是重新创建知识库摘要还是将单个文件的摘要信息保存到向量存储中，`create_kb_summary` 都是一个必要的步骤，以保证后续操作的顺利进行。
|
|||
|
|
|
|||
|
|
**注意**: 在使用 `create_kb_summary` 函数时，需要确保 `self.vs_path` 已经正确设置为期望的存储路径。此外，考虑到文件系统权限的问题，调用此函数的环境需要有相应的权限来创建目录。
|
|||
|
|
|
|||
|
|
**输出示例**: 由于 `create_kb_summary` 函数的主要作用是创建目录，它本身不返回任何值。但是，如果目录创建成功，指定的路径将会存在于文件系统中，这可以通过文件系统的检查工具（如在终端使用 `ls` 命令）来验证。如果之前路径不存在，调用此函数后，你将能够看到新创建的目录。
|
|||
|
|
***
|
|||
|
|
### FunctionDef drop_kb_summary(self)
|
|||
|
|
**drop_kb_summary**: 该函数的功能是删除指定知识库的chunk summary。
|
|||
|
|
|
|||
|
|
**参数**: 此函数不接受任何外部参数。
|
|||
|
|
|
|||
|
|
**代码描述**: `drop_kb_summary` 函数是 `KBSummaryService` 类的一个方法，用于删除特定知识库的摘要信息。该方法首先通过 `kb_faiss_pool.atomic` 确保操作的原子性，接着使用 `kb_faiss_pool.pop(self.kb_name)` 从缓存池中移除指定知识库的摘要信息。紧接着，`shutil.rmtree(self.vs_path)` 调用用于删除与知识库相关的向量存储目录。最后，调用 `delete_summary_from_db(kb_name=self.kb_name)` 方法从数据库中删除该知识库的chunk summary信息。
|
|||
|
|
|
|||
|
|
在删除过程中，首先确保通过缓存池的原子操作来维护数据一致性，然后从缓存中移除知识库摘要信息，接着删除文件系统中的相关数据，最后从数据库中彻底清除该知识库的摘要信息。这一系列操作确保了知识库摘要的完全删除，避免了数据残留问题。
|
|||
|
|
|
|||
|
|
**注意**:
|
|||
|
|
- 在执行此函数之前，确保 `self.kb_name` 和 `self.vs_path` 已正确设置，分别代表了知识库的名称和向量存储的路径。
|
|||
|
|
- 由于该操作会从缓存、文件系统和数据库中删除数据，因此操作不可逆，请在调用前确保确实需要删除对应的知识库摘要信息。
|
|||
|
|
- 该函数不返回任何值，但会影响系统中的缓存、文件系统和数据库状态。
|
|||
|
|
|
|||
|
|
**输出示例**: 该函数不提供输出示例，因为它不返回任何数据，而是直接对系统状态产生影响。
|
|||
|
|
|
|||
|
|
通过对 `drop_kb_summary` 函数的分析，开发者应能理解其在知识库管理中的重要作用，特别是在需要清理或重置知识库摘要信息时。务必谨慎使用此函数，以避免不必要的数据丢失。
|
|||
|
|
***
|