KnowledgeBase/docs/API_USAGE.md

AuraK 开放 API 使用文档

概述

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

基础 URL: http://localhost:3001

认证方式

支持两种认证方式：

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

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

方式 2：Authorization Bearer 头

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 聊天（推荐）

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

POST /api/v1/chat

请求头：

Content-Type: application/json
x-api-key: kb_your_api_key_here

请求体：

{
  "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

响应（非流式）：

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

---

1.2 简单聊天

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

POST /chat

请求体：

{
  "message": "你好",
  "stream": true
}

---

2. 知识库搜索

搜索知识库内容。

POST /api/v1/search

请求体：

{
  "query": "机器学习",
  "topK": 5,
  "similarityThreshold": 0.7
}

参数说明：

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

响应：

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

---

3. 知识库文件管理

3.1 列出文件

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

GET /api/v1/knowledge-bases

响应：

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

---

3.2 上传文件

上传文件到知识库。

POST /api/v1/knowledge-bases/upload

请求头：

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

响应：

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

---

3.3 获取文件详情

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

响应：

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

---

3.4 删除文件

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

响应：

{
  "message": "文件删除成功"
}

---

错误处理

错误响应格式

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

常见错误码

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

---

使用示例

JavaScript/TypeScript

// 流式聊天
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

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

# 流式聊天
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 认证