# Context Loader (Feature 806350) 需求设计文档

> **最后更新**: 2025-02-01

## 1. 功能概述

**Context Loader** 是 Agent Retrieval 服务的核心模块，为智能体（Agent）提供基于知识网络（Knowledge Network）的上下文加载能力。该功能解决了 Agent 在面对海量知识数据时"找不到"和"找不准"的核心问题。

本功能包含两个独立的核心子模块：

| 模块名称 | 功能定位 | 核心能力 |
|---------|---------|---------|
| **KnSearch** | 知识网络搜索 | 提供从 Schema 到 Instance 的全链路检索（本地实现） |
| **KnowledgeRerank** | 知识重排序 | 提供基于 LLM/Vector 的精细化排序过滤（内部模块） |

### 1.1 应用场景

- **Agent 意图理解**: Agent 接收用户指令后，需确定知识网络中哪些 ObjectType 和 RelationType 与指令相关
- **RAG 检索增强生成**: 在生成回答前，检索具体的实体数据（Nodes）作为背景知识
- **ActionType 召回**: 返回与召回 ObjectType 关联的操作类型

### 1.2 模块调用关系图

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              外部 API 入口                                   │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   ┌──────────────────────────┐              ┌──────────────────────────┐   │
│   │  POST /kn/kn_search      │              │  POST /kn/semantic-search │   │
│   │     (知识网络搜索)        │              │     (语义检索)            │   │
│   └────────────┬─────────────┘              └────────────┬─────────────┘   │
│                │                                         │                  │
│                ▼                                         ▼                  │
│   ┌──────────────────────────┐              ┌──────────────────────────┐   │
│   │       KnSearch 模块       │              │     KnRetrieval 模块     │   │
│   │     (本地实现)            │              │                          │   │
│   │  调用方:                  │              │  调用方:                  │   │
│   │  - Agent App (智能体应用) │              │  - Agent App (智能体应用) │   │
│   │  - MCP Proxy (MCP代理)    │              │  - 外部系统语义检索       │   │
│   │  - KnLogicPropertyResolver│              │                          │   │
│   └────────────┬─────────────┘              └────────────┬─────────────┘   │
│                │                                         │                  │
└────────────────┼─────────────────────────────────────────┼──────────────────┘
                 │                                         │
                 │                                         │      ┌──────────────────────────┐
                 │                                         │      │   KnowledgeRerank 模块    │
                 │                                         └─────►│  (内部模块，不对外暴露API) │
                 │                                                │                          │
                 │                                                │  被调用方: 仅 KnRetrieval  │
                 │                                                └──────────────────────────┘
                 │
                 ▼                                         ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              外部依赖服务                                    │
├─────────────────────────────────────────────────────────────────────────────┤
│   ┌────────────────┐   ┌────────────────┐   ┌────────────────┐              │
│   │ OntologyManager│   │ OntologyQuery  │   │ MF Model API   │              │
│   │  (Schema管理)  │   │  (实例查询)    │   │ (Rerank)       │              │
│   └────────────────┘   └────────────────┘   └────────────────┘              │
└─────────────────────────────────────────────────────────────────────────────┘
```

### 1.3 KnowledgeRerank 调用场景

KnowledgeRerank 是一个**内部复用模块**，不对外提供独立 API。

| 调用方 | 调用场景 | 对应 API |
|--------|----------|----------|
| **KnRetrieval** | 概念重排序 | `POST /kn/semantic-search` |

**说明**：KnSearch **不调用** KnowledgeRerank。KnSearch 的关系类型排序直接使用 MF Model API Rerank。

---

## 2. KnSearch 模块

KnSearch（知识网络搜索）提供从 Schema 到 Instance 的全链路检索，采用**本地实现**，接口为 `POST /kn/kn_search`。

### 2.1 核心能力

1. **概念召回**：获取知识网络详情 → 可选粗召回 → MF Rerank 对关系类型排序 → 对象类型选择 → 响应结构转换
2. **语义实例召回**：按对象类型 KNN/Match 检索 → 打分 → 全局分数过滤 → 属性过滤
3. **ActionType 召回**：根据召回的 ObjectType 返回关联操作类型

### 2.2 详细文档

- 逻辑设计：[KnSearch模块逻辑设计.md](./KnSearch模块逻辑设计.md)
- 实现设计：[KnSearch模块实现设计.md](./KnSearch模块实现设计.md)

---

## 3. KnowledgeRerank 模块

KnowledgeRerank（知识重排序）提供 LLM/Vector 两种模式的概念排序能力，**仅被 KnRetrieval 调用**，无独立 API。

### 3.1 详细文档

- 逻辑设计：[KnowledgeRerank模块逻辑设计.md](./KnowledgeRerank模块逻辑设计.md)
- 实现设计：[KnowledgeRerank模块实现设计.md](./KnowledgeRerank模块实现设计.md)

---

## 4. 关键配置项

### 4.1 KnSearch 配置

#### 4.1.1 根级请求参数

| 配置项 | 说明 | 默认值 |
|-------|------|-------|
| `query` | 用户查询问题或关键词 | 必填 |
| `kn_id` | 知识网络ID | 必填 |
| `session_id` | 会话ID，用于多轮对话缓存 | 可选 |
| `additional_context` | 额外上下文，拼接到查询 | 可选 |
| `only_schema` | 是否只返回Schema | false |
| `enable_rerank` | 是否启用重排序 | true |

#### 4.1.2 concept_retrieval 配置

| 配置项 | 说明 | 默认值 |
|-------|------|-------|
| `top_k` | Schema 召回的最大关系类型数量 | 10 |
| `skip_llm` | 跳过LLM直接返回TopK（高召回/低成本模式） | false |
| `return_union` | 多轮对话是否返回节点并集 | false |
| `include_sample_data` | 是否获取对象类型样例数据 | false |
| `schema_brief` | 是否返回精简Schema | true |
| `enable_coarse_recall` | 是否启用粗召回（大规模KN优化） | true |
| `coarse_object_limit` | 对象类型粗召回限制 | 2000 |
| `coarse_relation_limit` | 关系类型粗召回限制 | 300 |
| `coarse_min_relation_count` | 触发粗召回的最小关系数量 | 5000 |
| `enable_property_brief` | 是否启用属性相关性裁剪 | true |
| `per_object_property_top_k` | 每个对象类型保留的属性数量 | 8 |
| `global_property_top_k` | 全局保留的属性总数量 | 30 |

#### 4.1.3 semantic_instance_retrieval 配置

| 配置项 | 说明 | 默认值 |
|-------|------|-------|
| `initial_candidate_count` | 初始召回候选数量 | 50 |
| `per_type_instance_limit` | 每个ObjectType检索的实例上限 | 5 |
| `max_semantic_sub_conditions` | 查询条件最大数量 | 10 |
| `semantic_field_keep_ratio` | 语义字段保留比例 | 0.2 |
| `semantic_field_keep_min` | 语义字段最少保留数 | 5 |
| `semantic_field_keep_max` | 语义字段最多保留数 | 15 |
| `semantic_field_rerank_batch_size` | 字段重排批次大小 | 128 |
| `min_direct_relevance` | 最小直接相关性阈值 | 0.3 |
| `enable_global_final_score_ratio_filter` | 是否启用全局分数过滤 | true |
| `global_final_score_ratio` | 全局分数过滤阈值 | 0.25 |
| `exact_name_match_score` | 名称完全匹配保底分 | 0.85 |

#### 4.1.4 property_filter 配置

| 配置项 | 说明 | 默认值 |
|-------|------|-------|
| `max_properties_per_instance` | 每个实例最大属性数 | 20 |
| `max_property_value_length` | 属性值最大长度 | 500 |
| `enable_property_filter` | 是否启用属性过滤 | true |

### 4.2 KnowledgeRerank 配置

| 配置项 | 说明 | 默认值 |
|-------|------|-------|
| `batchSize` | LLM 模式的批次大小 | 128 |
| `model` | 使用的 LLM 模型 | 配置文件指定 |
| `temperature` | LLM 采样温度 | 0.0 |
| `maxTokens` | LLM 最大输出 Token | 配置文件指定 |
