# API Documentation

本文档描述了 RAG 系统的所有 REST API 端点。

## 基础信息

- **Base URL**: `http://localhost:8000`
- **API Version**: `v1`
- **Content Type**: `application/json`
- **Authentication**: 根据配置可能需要 API Key

## 通用响应格式

### 成功响应

```json
{
  "data": { ... },
  "message": "Success"
}
```

### 错误响应

```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Error description",
    "details": { ... }
  }
}
```

## 健康检查端点

### GET /health

检查系统健康状态。

**响应**:
```json
{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00Z",
  "version": "1.0.0"
}
```

### GET /health/ready

检查系统是否准备好接收请求。

**响应**:
```json
{
  "ready": true,
  "checks": {
    "database": "ok",
    "vector_db": "ok"
  }
}
```

### GET /health/live

检查系统是否存活。

**响应**:
```json
{
  "alive": true
}
```

### GET /metrics

获取系统性能指标。

**响应**:
```json
{
  "requests_total": 1000,
  "requests_per_second": 10.5,
  "average_response_time": 0.15,
  "error_rate": 0.01
}
```

## 文档管理端点

### POST /api/v1/documents/

创建新文档。

**请求体**:
```json
{
  "content": "Document content",
  "metadata": {
    "title": "Document Title",
    "author": "Author Name",
    "tags": ["tag1", "tag2"]
  },
  "knowledge_base_id": "kb_123"
}
```

**响应**:
```json
{
  "id": "doc_456",
  "content": "Document content",
  "metadata": { ... },
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}
```

### GET /api/v1/documents/{id}

获取文档详情。

**路径参数**:
- `id` (string): 文档 ID

**响应**:
```json
{
  "id": "doc_456",
  "content": "Document content",
  "metadata": { ... },
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}
```

### PUT /api/v1/documents/{id}

更新文档。

**路径参数**:
- `id` (string): 文档 ID

**请求体**:
```json
{
  "content": "Updated content",
  "metadata": {
    "title": "Updated Title"
  }
}
```

**响应**:
```json
{
  "id": "doc_456",
  "content": "Updated content",
  "metadata": { ... },
  "updated_at": "2024-01-01T00:00:00Z"
}
```

### DELETE /api/v1/documents/{id}

删除文档。

**路径参数**:
- `id` (string): 文档 ID

**响应**:
```json
{
  "message": "Document deleted successfully"
}
```

### POST /api/v1/documents/search

搜索文档。

**请求体**:
```json
{
  "query": "search query",
  "filters": {
    "knowledge_base_id": "kb_123",
    "tags": ["tag1"]
  },
  "limit": 10,
  "offset": 0,
  "search_type": "hybrid"
}
```

**搜索类型**:
- `vector`: 仅向量搜索
- `text`: 仅全文搜索
- `hybrid`: 混合搜索（默认）

**响应**:
```json
{
  "results": [
    {
      "id": "doc_456",
      "content": "Document content",
      "score": 0.95,
      "metadata": { ... }
    }
  ],
  "total": 100,
  "limit": 10,
  "offset": 0
}
```

## 文档解析端点

### POST /api/v1/documents/parse

解析上传的文档（PDF、图片等）。

**请求**:
- Content-Type: `multipart/form-data`
- Form fields:
  - `file`: 文档文件
  - `document_type`: 文档类型（pdf, image）
  - `options`: 解析选项（JSON 字符串）

**解析选项示例**:
```json
{
  "chunking_strategy": "sliding_window",
  "chunk_size": 512,
  "chunk_overlap": 50,
  "extract_images": true
}
```

**响应**:
```json
{
  "document_id": "doc_789",
  "chunks": [
    {
      "id": "chunk_1",
      "content": "Chunk content",
      "metadata": {
        "page": 1,
        "position": 0
      }
    }
  ],
  "metadata": {
    "total_pages": 10,
    "total_chunks": 50,
    "file_size": 1024000
  }
}
```

## 知识库管理端点

### POST /api/v1/knowledge-bases/

创建新知识库。

**请求体**:
```json
{
  "name": "Knowledge Base Name",
  "description": "Description",
  "metadata": {
    "domain": "technical",
    "language": "zh-CN"
  }
}
```

**响应**:
```json
{
  "id": "kb_123",
  "name": "Knowledge Base Name",
  "description": "Description",
  "metadata": { ... },
  "created_at": "2024-01-01T00:00:00Z"
}
```

### GET /api/v1/knowledge-bases/{id}

获取知识库详情。

**路径参数**:
- `id` (string): 知识库 ID

**响应**:
```json
{
  "id": "kb_123",
  "name": "Knowledge Base Name",
  "description": "Description",
  "document_count": 100,
  "metadata": { ... },
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}
```

### PUT /api/v1/knowledge-bases/{id}

更新知识库。

**路径参数**:
- `id` (string): 知识库 ID

**请求体**:
```json
{
  "name": "Updated Name",
  "description": "Updated Description"
}
```

**响应**:
```json
{
  "id": "kb_123",
  "name": "Updated Name",
  "description": "Updated Description",
  "updated_at": "2024-01-01T00:00:00Z"
}
```

### DELETE /api/v1/knowledge-bases/{id}

删除知识库。

**路径参数**:
- `id` (string): 知识库 ID

**查询参数**:
- `delete_documents` (boolean): 是否同时删除关联的文档（默认 false）

**响应**:
```json
{
  "message": "Knowledge base deleted successfully"
}
```

### POST /api/v1/knowledge-bases/{id}/documents

向知识库添加文档。

**路径参数**:
- `id` (string): 知识库 ID

**请求体**:
```json
{
  "document_ids": ["doc_456", "doc_789"]
}
```

**响应**:
```json
{
  "added": 2,
  "failed": 0,
  "knowledge_base_id": "kb_123"
}
```

### DELETE /api/v1/knowledge-bases/{id}/documents/{document_id}

从知识库移除文档。

**路径参数**:
- `id` (string): 知识库 ID
- `document_id` (string): 文档 ID

**响应**:
```json
{
  "message": "Document removed from knowledge base"
}
```

### GET /api/v1/knowledge-bases/{id}/documents

获取知识库中的文档列表。

**路径参数**:
- `id` (string): 知识库 ID

**查询参数**:
- `limit` (integer): 每页数量（默认 20）
- `offset` (integer): 偏移量（默认 0）

**响应**:
```json
{
  "documents": [
    {
      "id": "doc_456",
      "content": "Document content",
      "metadata": { ... }
    }
  ],
  "total": 100,
  "limit": 20,
  "offset": 0
}
```

## 错误代码

| 错误代码 | HTTP 状态码 | 描述 |
|---------|-----------|------|
| `VALIDATION_ERROR` | 400 | 请求参数验证失败 |
| `RESOURCE_NOT_FOUND` | 404 | 资源不存在 |
| `DUPLICATE_RESOURCE` | 409 | 资源已存在 |
| `INTERNAL_ERROR` | 500 | 内部服务器错误 |
| `DATABASE_ERROR` | 500 | 数据库错误 |
| `VECTOR_DB_ERROR` | 500 | 向量数据库错误 |
| `PARSING_ERROR` | 422 | 文档解析失败 |
| `INVALID_FILE_TYPE` | 422 | 不支持的文件类型 |

## 速率限制

- 默认速率限制：100 请求/分钟
- 搜索端点：20 请求/分钟
- 文档解析端点：10 请求/分钟

超过速率限制将返回 429 状态码。

## 分页

所有列表端点支持分页：

**查询参数**:
- `limit`: 每页数量（默认 20，最大 100）
- `offset`: 偏移量（默认 0）

**响应包含**:
- `total`: 总数量
- `limit`: 当前每页数量
- `offset`: 当前偏移量

## 自动生成的 API 文档

FastAPI 自动生成交互式 API 文档：

- **Swagger UI**: `http://localhost:8000/docs`
- **ReDoc**: `http://localhost:8000/redoc`
- **OpenAPI Schema**: `http://localhost:8000/openapi.json`

## 示例代码

### Python 客户端示例

```python
import requests

# 创建文档
response = requests.post(
    "http://localhost:8000/api/v1/documents/",
    json={
        "content": "Document content",
        "metadata": {"title": "Test Document"}
    }
)
document = response.json()

# 搜索文档
response = requests.post(
    "http://localhost:8000/api/v1/documents/search",
    json={
        "query": "search query",
        "limit": 10
    }
)
results = response.json()
```

### cURL 示例

```bash
# 创建文档
curl -X POST http://localhost:8000/api/v1/documents/ \
  -H "Content-Type: application/json" \
  -d '{"content": "Document content", "metadata": {"title": "Test"}}'

# 搜索文档
curl -X POST http://localhost:8000/api/v1/documents/search \
  -H "Content-Type: application/json" \
  -d '{"query": "search query", "limit": 10}'

# 上传并解析文档
curl -X POST http://localhost:8000/api/v1/documents/parse \
  -F "file=@document.pdf" \
  -F "document_type=pdf"
```

## 版本控制

API 使用 URL 路径进行版本控制：`/api/v1/...`

当前版本：**v1**

## 向后兼容性

系统保持向后兼容性，旧的 API 端点仍然可用但会记录废弃警告。建议迁移到新的 API 端点。

## 支持

如有问题，请参考：
- [架构文档](architecture.md)
- [配置指南](configuration.md)
- [GitHub Issues](https://github.com/YOUR_USERNAME/YOUR_REPO/issues)