# AuraK 开放 API 使用文档

## 概述

AuraK 提供了一套完整的开放 API，允许外部系统通过 API Key 认证访问知识库功能。

**基础 URL**: `http://localhost:3001`

## 认证方式

支持两种认证方式：

### 方式 1：x-api-key 头（推荐）

```http
x-api-key: kb_your_api_key_here
x-tenant-id: your_tenant_id  # 可选，指定租户
```

### 方式 2：Authorization Bearer 头

```http
Authorization: Bearer kb_your_api_key_here
x-tenant-id: your_tenant_id  # 可选，指定租户
```

### 租户说明

- 一个用户可能属于多个租户
- 如果不指定 `x-tenant-id`，将使用用户的默认租户
- 如果指定 `x-tenant-id`，将验证用户是否属于该租户
- 可以通过 `?tenantId=xxx` 查询参数指定租户

### 获取 API Key

1. 登录 AuraK 系统
2. 进入 **设置** → **API Key** 标签页
3. 复制您的 API Key

---

## API 端点

### 1. 聊天接口

#### 1.1 RAG 聊天（推荐）

与知识库进行对话，支持流式响应。

```http
POST /api/v1/chat
```

**请求头**：
```http
Content-Type: application/json
x-api-key: kb_your_api_key_here
```

**请求体**：
```json
{
  "message": "什么是机器学习？",
  "stream": true,
  "history": [
    {
      "role": "user",
      "content": "你好"
    },
    {
      "role": "assistant",
      "content": "你好！有什么我可以帮助你的吗？"
    }
  ],
  "userLanguage": "zh"
}
```

**参数说明**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `message` | string | ✅ | 用户消息 |
| `stream` | boolean | ❌ | 是否使用流式响应，默认 `true` |
| `history` | array | ❌ | 历史对话记录 |
| `userLanguage` | string | ❌ | 用户语言，支持 `zh`、`en`、`ja` |

**响应（流式）**：

```
data: {"type":"status","data":{"stage":"searching","message":"正在搜索知识库..."}}

data: {"type":"status","data":{"stage":"search_complete","message":"找到 3 条相关信息"}}

data: {"type":"sources","data":[{"fileName":"机器学习入门.pdf","content":"机器学习是人工智能的一个分支...","score":0.95,"chunkIndex":2,"fileId":"xxx"}]}

data: {"type":"content","data":"机器学习是"}

data: {"type":"content","data":"人工智能的一个"}

data: {"type":"content","data":"重要分支..."}

data: [DONE]
```

**响应类型说明**：

| 类型 | 说明 |
|------|------|
| `status` | 状态信息（搜索中、搜索完成、生成中） |
| `sources` | 引用来源 |
| `content` | AI 生成的回答内容 |
| `thinking` | 深度思考过程（仅部分模型支持） |
| `historyId` | 对话历史 ID |

**响应（非流式）**：

```json
{
  "message": "机器学习是人工智能的一个重要分支...",
  "sources": [
    {
      "fileName": "机器学习入门.pdf",
      "content": "机器学习是人工智能的一个分支...",
      "score": 0.95,
      "chunkIndex": 2,
      "fileId": "xxx"
    }
  ],
  "historyId": "hist_xxx"
}
```

---

#### 1.2 简单聊天

不使用知识库的简单聊天。

```http
POST /chat
```

**请求体**：
```json
{
  "message": "你好",
  "stream": true
}
```

---

### 2. 知识库搜索

搜索知识库内容。

```http
POST /api/v1/search
```

**请求体**：
```json
{
  "query": "机器学习",
  "topK": 5,
  "similarityThreshold": 0.7
}
```

**参数说明**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `query` | string | ✅ | 搜索查询 |
| `topK` | number | ❌ | 返回结果数量，默认 5 |
| `similarityThreshold` | number | ❌ | 相似度阈值，默认 0.7 |

**响应**：
```json
{
  "results": [
    {
      "fileName": "机器学习入门.pdf",
      "content": "机器学习是人工智能的一个分支...",
      "score": 0.95,
      "chunkIndex": 2,
      "fileId": "xxx"
    }
  ],
  "total": 1
}
```

---

### 3. 知识库文件管理

#### 3.1 列出文件

获取知识库中的所有文件。

```http
GET /api/v1/knowledge-bases
```

**响应**：
```json
{
  "files": [
    {
      "id": "file_xxx",
      "name": "机器学习入门.pdf",
      "size": 1024000,
      "status": "completed",
      "createdAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "total": 1
}
```

---

#### 3.2 上传文件

上传文件到知识库。

```http
POST /api/v1/knowledge-bases/upload
```

**请求头**：
```http
Content-Type: multipart/form-data
x-api-key: kb_your_api_key_here
```

**请求体**：
```
file: [文件]
mode: fast
chunkSize: 1000
chunkOverlap: 200
```

**参数说明**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file` | File | ✅ | 要上传的文件 |
| `mode` | string | ❌ | 处理模式：`fast`（快速）或 `precise`（精确） |
| `chunkSize` | number | ❌ | 分块大小，默认 1000 |
| `chunkOverlap` | number | ❌ | 分块重叠，默认 200 |

**响应**：
```json
{
  "id": "file_xxx",
  "name": "机器学习入门.pdf",
  "size": 1024000,
  "status": "indexing",
  "message": "文件上传成功，正在处理中"
}
```

---

#### 3.3 获取文件详情

```http
GET /api/v1/knowledge-bases/:id
```

**响应**：
```json
{
  "id": "file_xxx",
  "name": "机器学习入门.pdf",
  "size": 1024000,
  "status": "completed",
  "chunkCount": 50,
  "createdAt": "2024-01-01T00:00:00.000Z"
}
```

---

#### 3.4 删除文件

```http
DELETE /api/v1/knowledge-bases/:id
```

**响应**：
```json
{
  "message": "文件删除成功"
}
```

---

## 错误处理

### 错误响应格式

```json
{
  "statusCode": 400,
  "message": "错误描述",
  "error": "Bad Request"
}
```

### 常见错误码

| 状态码 | 说明 |
|--------|------|
| 400 | 请求参数错误 |
| 401 | 认证失败（API Key 无效或缺失） |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

---

## 使用示例

### JavaScript/TypeScript

```javascript
// 流式聊天
const response = await fetch('http://localhost:3001/api/v1/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'kb_your_api_key_here'
  },
  body: JSON.stringify({
    message: '什么是机器学习？',
    stream: true
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  const chunk = decoder.decode(value);
  const lines = chunk.split('\n');
  
  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = line.slice(6);
      if (data === '[DONE]') break;
      
      const parsed = JSON.parse(data);
      console.log(parsed);
    }
  }
}
```

### Python

```python
import requests

# 非流式聊天
response = requests.post(
    'http://localhost:3001/api/v1/chat',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'kb_your_api_key_here'
    },
    json={
        'message': '什么是机器学习？',
        'stream': False
    }
)

data = response.json()
print(data['message'])
```

### cURL

```bash
# 流式聊天
curl -X POST http://localhost:3001/api/v1/chat \
  -H "Content-Type: application/json" \
  -H "x-api-key: kb_your_api_key_here" \
  -d '{"message": "什么是机器学习？", "stream": true}'

# 上传文件
curl -X POST http://localhost:3001/api/v1/knowledge-bases/upload \
  -H "x-api-key: kb_your_api_key_here" \
  -F "file=@/path/to/file.pdf" \
  -F "mode=fast"

# 搜索知识库
curl -X POST http://localhost:3001/api/v1/search \
  -H "Content-Type: application/json" \
  -H "x-api-key: kb_your_api_key_here" \
  -d '{"query": "机器学习", "topK": 5}'
```

---

## 支持的文件格式

上传文件时支持以下格式：

- **文档**：PDF、DOCX、DOC、TXT、MD
- **表格**：XLSX、XLS、CSV
- **演示**：PPTX、PPT
- **代码**：JS、TS、PY、JAVA、CPP、C、H、HPP
- **其他**：JSON、XML、HTML、YAML

---

## 速率限制

目前暂无速率限制，但建议：
- 聊天请求：每分钟不超过 30 次
- 文件上传：每小时不超过 100 个文件
- 搜索请求：每分钟不超过 60 次

---

## 常见问题

### Q: API Key 在哪里获取？

A: 登录系统后，进入 **设置** → **API Key** 标签页即可查看和复制。

### Q: 如何重新生成 API Key？

A: 在 API Key 管理页面点击"重新生成 API Key"按钮。注意：旧 Key 将立即失效。

### Q: 支持哪些语言？

A: 支持中文（zh）、英文（en）、日文（ja），通过 `userLanguage` 参数指定。

### Q: 文件上传后多久可以搜索？

A: 取决于文件大小和处理模式：
- 快速模式：通常 1-5 分钟
- 精确模式：可能需要 5-30 分钟

### Q: 如何查看文件处理状态？

A: 使用 `GET /api/v1/knowledge-bases/:id` 接口查看文件状态。

---

## 更新日志

### v1.0.0 (2024-01-01)

- 初始版本发布
- 支持 RAG 聊天（流式/非流式）
- 支持知识库搜索
- 支持文件上传/删除/查询
- 支持 API Key 认证