# KnSearch 接口测试用例

用于人工在 Postman 等工具中验证 `POST /api/agent-retrieval/in/v1/kn/kn_search` 接口。

**说明**：将下方 `base_url` 替换为实际环境地址，例如 `http://agent-retrieval:30779` 或 `http://localhost:30779`。

**完整 URL**：`POST {{base_url}}/api/agent-retrieval/in/v1/kn/kn_search`

---

## 1. 最小必填参数

**目的**：仅传必填字段，验证默认行为（概念召回 + 语义实例召回）。

**Method**：`POST`

**URL**：`{{base_url}}/api/agent-retrieval/in/v1/kn/kn_search`

**Headers**：
- `Content-Type`: `application/json`

**Body (raw JSON)**：
```json
{
  "query": "化工企业",
  "kn_id": "129"
}
```

**预期**：HTTP 200；响应包含 `object_types`、`relation_types`、`action_types`；若知识网络有实例且未设 only_schema，可能包含 `nodes`。

---

## 2. 仅概念召回（only_schema）

**目的**：只召回概念，不召回语义实例。

**Method**：`POST`

**URL**：`{{base_url}}/api/agent-retrieval/in/v1/kn/kn_search`

**Headers**：
- `Content-Type`: `application/json`

**Body (raw JSON)**：
```json
{
  "query": "化工企业",
  "kn_id": "129",
  "only_schema": true
}
```

**预期**：HTTP 200；响应包含 `object_types`、`relation_types`、`action_types`；`nodes` 为空或不出现。

---

## 3. 仅概念召回 + 少量概念配置

**目的**：仅概念召回，并限制 top_k、拉取样例数据。

**Method**：`POST`

**URL**：`{{base_url}}/api/agent-retrieval/in/v1/kn/kn_search`

**Headers**：
- `Content-Type`: `application/json`

**Body (raw JSON)**：
```json
{
  "query": "化工企业",
  "kn_id": "129",
  "only_schema": true,
  "retrieval_config": {
    "concept_retrieval": {
      "top_k": 5,
      "include_sample_data": true
    }
  }
}
```

**预期**：HTTP 200；概念数量受 top_k 限制；object_types 中可能包含 `sample_data`。

---

## 4. 完整概念 + 实例（默认）

**目的**：概念召回 + 语义实例召回，使用默认配置。

**Method**：`POST`

**URL**：`{{base_url}}/api/agent-retrieval/in/v1/kn/kn_search`

**Headers**：
- `Content-Type`: `application/json`

**Body (raw JSON)**：
```json
{
  "query": "催化剂信息",
  "kn_id": "129"
}
```

**预期**：HTTP 200；响应包含 `object_types`、`relation_types`、`action_types`；若有可检索实例则包含 `nodes`，否则可能有 `message` 说明。

---

## 5. 自定义召回配置

**目的**：覆盖概念、语义实例、属性过滤等配置。

**Method**：`POST`

**URL**：`{{base_url}}/api/agent-retrieval/in/v1/kn/kn_search`

**Headers**：
- `Content-Type`: `application/json`

**Body (raw JSON)**：
```json
{
  "query": "催化剂信息",
  "kn_id": "129",
  "retrieval_config": {
    "concept_retrieval": {
      "top_k": 10,
      "schema_brief": true
    },
    "semantic_instance_retrieval": {
      "per_type_instance_limit": 10,
      "initial_candidate_count": 100
    },
    "property_filter": {
      "max_properties_per_instance": 30
    }
  }
}
```

**预期**：HTTP 200；概念与实例数量、实例属性数量受上述参数影响。

---

## 6. 带账户 Header

**目的**：验证 Header 透传（x-account-id、x-account-type）。

**Method**：`POST`

**URL**：`{{base_url}}/api/agent-retrieval/in/v1/kn/kn_search`

**Headers**：
- `Content-Type`: `application/json`
- `x-account-id`: `user123`
- `x-account-type`: `user`

**Body (raw JSON)**：
```json
{
  "query": "化工企业",
  "kn_id": "129"
}
```

**预期**：HTTP 200；行为与用例 1 一致，Header 被服务接收（若下游需要会透传）。

---

## 7. 关闭重排序（enable_rerank）

**目的**：不调用 Rerank，关系类型按简单匹配排序。

**Method**：`POST`

**URL**：`{{base_url}}/api/agent-retrieval/in/v1/kn/kn_search`

**Headers**：
- `Content-Type`: `application/json`

**Body (raw JSON)**：
```json
{
  "query": "化工企业",
  "kn_id": "129",
  "enable_rerank": false
}
```

**预期**：HTTP 200；概念召回不依赖 Rerank 服务，结果仍包含 object_types、relation_types、action_types。

---

## 8. 错误场景：缺少 kn_id

**目的**：校验必填参数。

**Method**：`POST`

**URL**：`{{base_url}}/api/agent-retrieval/in/v1/kn/kn_search`

**Headers**：
- `Content-Type`: `application/json`

**Body (raw JSON)**：
```json
{
  "query": "化工企业"
}
```

**预期**：HTTP 400；响应体为错误信息（如 error/message）。

---

## 9. 错误场景：缺少 query

**目的**：校验必填参数。

**Method**：`POST`

**URL**：`{{base_url}}/api/agent-retrieval/in/v1/kn/kn_search`

**Headers**：
- `Content-Type`: `application/json`

**Body (raw JSON)**：
```json
{
  "kn_id": "129"
}
```

**预期**：HTTP 400；响应体为错误信息。

---

## Postman 使用说明

1. 新建 Environment，添加变量 `base_url`（如 `http://agent-retrieval:30779`）。
2. 新建 Request，Method 选 POST，URL 填：`{{base_url}}/api/agent-retrieval/in/v1/kn/kn_search`。
3. Headers 中增加 `Content-Type: application/json`。
4. Body 选择 raw、JSON，将上述各用例的 Body 复制粘贴后发送。
5. 根据「预期」检查状态码与响应字段。
