# 如何定义知识Knowledge组件
根据agentUniverse领域组件的设计特性，同其他组件一样，创建一个知识knowledge定义由2部分组成:
* knowledge_xx.yaml
* knowledge_xx.py

其中`knowledge_xx.yaml`包含了Knowledge组件的名称、描述、加载方式、存储方式等重要信息；`knowledge_xx.py`包含了的知识具体定义。理解这一原理后，让我们具体看看该如何创建这两部分内容。

## 创建Knowledge配置 - knowledge_xx.yaml

### 一个Knowledge定义配置的实际样例
```yaml
name: "sample_knowledge"
description: "a knowledge sample"
stores:
    - "a_store"
    - "another_store"
query_paraphrasers:
    - "a_query_paraphraser"
insert_processors:
    - "a_doc_processor"
rag_router: "a_rag_router"
post_processors:
    - "another_doc_processor"
readers:
    pdf: "default_pdf_reader"

metadata:
  type: 'KNOWLEDGE'
  module: 'sample_standard_app.intelligence.agentic.knowledge.sample_knowledge'
  class: 'SampleKnowledge'
```
- stores: 所有关联的Store。一个string的list，每个string表示一个Store组件的名称。
- query_paraphrasers: 查询改写器，用于将输入的查询转换为更加适合检索的形式。一个string的list，每个string表示一个QueryParaphraser组件的名称。
- insert_processors: 插入处理器，用于在将文本插入知识库时对其进行处理，例如递归字符切分，一个string的list，每个string表示一个DocProcessor组件的名称。
- rag_router: 检索增强生成（RAG）路由器，控制查询在知识库中的路由方式。
- post_processors: 后处理器，用于对检索结果进行优化和排序，提升返回结果的相关性。一个string的list，每个string表示一个DocProcessor组件的名称。
- readers: Dict形式，其中key表示文件类型，value表示对应的Reader组件名称。

## 创建Knowledge领域行为定义 - knowledge_xx.py
agentUniverse提供了一个标准的Knowledge类，您可以直接在yaml定义文件中使用该类或是继承它并改写其中的部分方法。  

### [Knowledge类的定义:](../../../../../../agentuniverse/agent/action/knowledge/knowledge.py)

- _load_data(self, *args: Any, **kwargs: Any) -> List[Document]
: 加载数据源，根据数据源的类型（文件或URL）选择合适的`Reader`，并加载文档数据。

- _insert_process(self, origin_docs: List[Document]) -> List[Document]
: 处理插入的原始文档，依次应用配置的`DocProcessor`进行文档的预处理。 

- _rag_post_process(self, origin_docs: List[Document], query: Query)
: 对检索到的原始文档进行后处理，根据查询条件应用配置的后处理器`DocProcessor`对文档进行进一步处理。

- _paraphrase_query(self, origin_query: Query) -> Query
: 对原始查询进行改写，应用配置的`QueryParaphraser`对查询进行改写处理。

- insert_knowledge(self, **kwargs) -> None
: 插入知识数据。该方法调用`_load_data`加载文档数据，经过`_insert_process`预处理后，将文档并行插入到存储中。

- _route_rag(self, query: Query)
: 通过指定的`RagRouter`，根据查询条件选择合适的存储来进行查询操作。

- query_knowledge(self, **kwargs) -> List[Document]
: 查询知识数据。该方法首先调用`_paraphrase_query`对查询进行改写，然后通过`_route_rag`选择存储，并行执行查询操作，最后调用`_rag_post_process`对查询结果进行后处理。

- to_llm(self, retrieved_docs: List[Document]) -> Any
: 将检索到的文档转换为LLM输入格式，拼接所有文档文本以供后续处理。


## 关注您定义的Knowledge所在的包路径
通过上面的Knowledge配置与定义，您已经掌握了知识创建的所有步骤；接下去我们将使用这些Knowledge，在使用前请关注创建的Knowledge是否在正确的包扫描路径内。

在agentUniverse项目的config.toml中需要配置Knowledge配置对应的package, 请再次确认您创建的文件所在的包路径是否在`CORE_PACKAGE`中`knowledge`路径或其子路径下。

以示例工程中的配置为例，如下：
```yaml
[CORE_PACKAGE]
# Scan and register knowledge components for all paths under this list, with priority over the default.
knowledge = ['sample_standard_app.intelligence.agentic.knowledge']
```

# 如何使用知识Knowledge组件
## 在Agent中配置使用
您可以根据[智能体创建与使用](../智能体/智能体创建与使用.md)中的内容在agent的action下的knowledge中设置您创建的任意知识。

## 使用Knowledge管理器
通过Knowledge管理器中的`.get_instance_obj(xx_knowledge_name)` 方法可以获取对应名称的Knowledge实例, 使用`query_knowledge`方法进行调用。

```python
from agentuniverse.agent.action.knowledge.knowledge_manager import KnowledgeManager

knowledge = KnowledgeManager().get_instance_obj("knowledge_name")
knowledge.insert_knowledge(source_path="source_file")
knowledge.query_knowledge()
```

## 了解更多已有知识Knowledge
[Knowledge法律咨询案例](../../../实践应用/法律咨询案例.md)
