# 知识库创建 API

## 基础信息

| 项目 | 说明 |
|------|------|
| 基础URL | `http://localhost:8082` |
| 前端页面 | Knowledge Base 创建弹窗 |

## 接口列表

### 1. 创建知识库

**请求**

```
POST /api/knowledge/create
Content-Type: application/json
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | String | 是 | 知识库名称 |
| description | String | 否 | 知识库描述 |
| llm_model_id | String | 是 | LLM 模型 ID（来自 model 表） |
| embedding_model_id | String | 是 | Embedding 模型 ID（来自 model 表） |
| parsing_config | Object | 是 | 解析配置 |
| - engine | String | 是 | 解析引擎：markitdown / docling |
| - docling_url | String | 条件必填 | Docling 服务 URL（engine=docling 时必填） |
| - enable_pdf | Boolean | 否 | 是否启用 PDF 解析（默认 true） |
| - pandoc | Boolean | 否 | 是否启用 Pandoc（默认 true） |
| storage_config | Object | 否 | 存储配置（默认 local） |
| - type | String | 是 | 存储类型：local / minio / s3 |
| - endpoint | String | 否 | MinIO Endpoint（如 minio:9000） |
| - access_key_id | String | 否 | MinIO Access Key ID |
| - secret_access_key | String | 否 | MinIO Secret Access Key |
| - bucket | String | 否 | MinIO Bucket 名称 |

**请求示例**

本地存储：
```json
{
  "name": "产品文档知识库",
  "description": "用于存储产品手册和文档",
  "llm_model_id": "model_001",
  "embedding_model_id": "model_002",
  "parsing_config": {
    "engine": "markitdown",
    "enable_pdf": true,
    "pandoc": true
  },
  "storage_config": {
    "type": "local"
  }
}
```

使用 Docling + MinIO：
```json
{
  "name": "产品文档知识库",
  "description": "用于存储产品手册和文档",
  "llm_model_id": "model_001",
  "embedding_model_id": "model_002",
  "parsing_config": {
    "engine": "docling",
    "docling_url": "http://localhost:8501",
    "enable_pdf": true,
    "pandoc": true
  },
  "storage_config": {
    "type": "minio",
    "endpoint": "localhost:9000",
    "access_key_id": "minioadmin",
    "secret_access_key": "minioadmin",
    "bucket": "x-agents"
  }
}
```

**成功响应**

```json
{
  "success": true,
  "id": "kb_abc123",
  "message": "Knowledge base created successfully"
}
```

**错误响应**

```json
{
  "success": false,
  "message": "LLM model not found"
}
```

---

### 2. 获取知识库列表

**请求**

```
GET /api/knowledge/list
```

**响应**

```json
{
  "success": true,
  "data": [
    {
      "id": "kb_001",
      "name": "产品文档知识库",
      "description": "用于存储产品手册",
      "llm_model_id": "model_001",
      "embedding_model_id": "model_002",
      "status": "active",
      "document_count": 15,
      "chunk_count": 156,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ]
}
```

---

### 3. 获取知识库详情

**请求**

```
GET /api/knowledge/:id
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | String | 是 | 知识库 ID |

**响应**

```json
{
  "success": true,
  "data": {
    "id": "kb_001",
    "name": "产品文档知识库",
    "description": "用于存储产品手册",
    "llm_model_id": "model_001",
    "embedding_model_id": "model_002",
    "parsing_config": {
      "engine": "markitdown",
      "enable_pdf": true,
      "pandoc": true
    },
    "status": "active",
    "document_count": 15,
    "chunk_count": 156,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}
```

---

### 4. 删除知识库

**请求**

```
DELETE /api/knowledge/:id
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | String | 是 | 知识库 ID |

**响应**

```json
{
  "success": true,
  "message": "Knowledge base deleted"
}
```

---

### 5. 获取知识库下的文档列表

**请求**

```
GET /api/knowledge/:id/documents
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | String | 是 | 知识库 ID |

**查询参数**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| status | String | 否 | 过滤状态：all / parsed / parsing / failed |

**响应**

```json
{
  "success": true,
  "data": [
    {
      "id": "doc_001",
      "knowledge_base_id": "kb_001",
      "name": "产品手册_v2.0.pdf",
      "file_key": "abc123.pdf",
      "file_url": "http://localhost:8082/files/abc123.pdf",
      "file_size": 2516582,
      "status": "parsed",
      "chunk_count": 156,
      "uploaded_at": "2024-01-15T10:30:00Z"
    }
  ]
}
```

---

### 6. 上传文档到知识库

**请求**

```
POST /api/knowledge/:id/documents
Content-Type: multipart/form-data
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | String | 是 | 知识库 ID |
| file | File | 是 | 要上传的文件 |

**响应**

```json
{
  "success": true,
  "dataid": "doc_001",
   ": {
    " "name": "产品手册_v2.0.pdf",
    "status": "parsing"
  }
}
```

---

### 7. 删除知识库文档

**请求**

```
DELETE /api/knowledge/:id/documents/:doc_id
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | String | 是 | 知识库 ID |
| doc_id | String | 是 | 文档 ID |

**响应**

```json
{
  "success": true,
  "message": "Document deleted"
}
```

---

### 8. 重新解析文档

**请求**

```
POST /api/knowledge/:id/documents/:doc_id/reparse
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | String | 是 | 知识库 ID |
| doc_id | String | 是 | 文档 ID |

**响应**

```json
{
  "success": true,
  "message": "Document reparse started"
}
```

---

### 9. 获取文档预览内容

**请求**

```
GET /api/knowledge/:id/documents/:doc_id/preview
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | String | 是 | 知识库 ID |
| doc_id | String | 是 | 文档 ID |
| page | Number | 否 | 页码（默认 1） |

**响应**

```json
{
  "success": true,
  "data": {
    "total_pages": 3,
    "current_page": 1,
    "content": "第一章 产品介绍\n\n欢迎使用我们的产品手册..."
  }
}
```

---

## 数据库表设计（参考）

### knowledge_base 表

| 字段 | 类型 | 说明 |
|------|------|------|
| id | String | 主键 |
| name | String | 知识库名称 |
| description | Text | 描述 |
| llm_model_id | String | LLM 模型 ID |
| embedding_model_id | String | Embedding 模型 ID |
| parsing_config | JSON | 解析配置 |
| storage_config | JSON | 存储配置（包含 type, endpoint, access_key_id, secret_access_key, bucket） |
| status | String | 状态：active / inactive |
| document_count | Integer | 文档数量 |
| chunk_count | Integer | 切片数量 |
| created_at | Timestamp | 创建时间 |
| updated_at | Timestamp | 更新时间 |

### knowledge_document 表

| 字段 | 类型 | 说明 |
|------|------|------|
| id | String | 主键 |
| knowledge_base_id | String | 知识库 ID |
| name | String | 文档名称 |
| file_key | String | 文件存储 key |
| file_url | String | 文件访问 URL（本地路径或 MinIO 预签名 URL） |
| file_size | BigInteger | 文件大小 |
| status | String | 状态：parsing / parsed / failed |
| chunk_count | Integer | 切片数量 |
| uploaded_at | Timestamp | 上传时间 |
