Home Explore Help
Sign In
anhuiqiang
/
KnowledgeBase
1
0
Fork 0
Files Issues 0 Pull Requests 0 Wiki
Tree: 53bf8c47cf
Branches Tags
KnowledgeBase
/
docs
/
API.md

API.md 11 KB
History Raw

API 参考文档

基本信息

  • 基础 URL: http://localhost:3000
  • 认证方式: JWT Bearer 令牌
  • Content-Type: application/json

认证 API

用户注册

POST /auth/register
Content-Type: application/json

{
  "username": "string",
  "password": "string"
}

响应:

{
  "message": "用户创建成功",
  "user": {
    "id": "string",
    "username": "string",
    "isAdmin": false
  }
}

用户登录

POST /auth/login
Content-Type: application/json

{
  "username": "string", 
  "password": "string"
}

响应:

{
  "access_token": "jwt_token_string",
  "user": {
    "id": "string",
    "username": "string",
    "isAdmin": false
  }
}

密码修改

POST /auth/change-password
Authorization: Bearer <token>
Content-Type: application/json

{
  "currentPassword": "string",
  "newPassword": "string"
}

模型配置 API

获取模型列表

GET /model-configs
Authorization: Bearer <token>

响应:

[
  {
    "id": "string",
    "name": "string",
    "provider": "openai|gemini",
    "modelId": "string",
    "baseUrl": "string",
    "type": "llm|embedding|rerank",
    "supportsVision": boolean
  }
]

创建模型配置

POST /model-configs
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "string",
  "provider": "openai|gemini", 
  "modelId": "string",
  "baseUrl": "string",
  "apiKey": "string",
  "type": "llm|embedding|rerank",
  "supportsVision": boolean
}

更新模型配置

PUT /model-configs/:id
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "string",
  "apiKey": "string",
  // ... 其他字段
}

删除模型配置

DELETE /model-configs/:id
Authorization: Bearer <token>

知识库 API

文件上传

POST /upload
Authorization: Bearer <token>
Content-Type: multipart/form-data

{
  "file": File,
  "chunkSize": number,
  "chunkOverlap": number,
  "embeddingModelId": "string",
  "mode": "fast|precise"  // 处理模式
}

响应:

{
  "id": "string",
  "name": "string",
  "originalName": "string",
  "size": number,
  "mimetype": "string",
  "status": "pending|indexing|completed|failed"
}

获取文件列表

GET /knowledge-bases
Authorization: Bearer <token>

响应:

[
  {
    "id": "string",
    "name": "string", 
    "originalName": "string",
    "size": number,
    "mimetype": "string",
    "status": "pending|indexing|completed|failed",
    "createdAt": "datetime"
  }
]

删除文件

DELETE /knowledge-bases/:id
Authorization: Bearer <token>

清空知识库

DELETE /knowledge-bases/clear
Authorization: Bearer <token>

聊天 API

流式聊天

POST /chat/stream
Authorization: Bearer <token>
Content-Type: application/json

{
  "message": "string",
  "history": [
    {
      "role": "user|assistant",
      "content": "string"
    }
  ],
  "userLanguage": "zh|en|ja"
}

响应: Server-Sent Events (SSE)

data: {"type": "content", "data": "正在搜索知识库..."}

data: {"type": "content", "data": "找到相关信息..."}

data: {"type": "content", "data": "回答内容片段"}

data: {"type": "sources", "data": [
  {
    "fileName": "string",
    "content": "string", 
    "score": number,
    "chunkIndex": number
  }
]}

data: [DONE]

用户设置 API

获取用户设置

GET /user-settings
Authorization: Bearer <token>

响应:

{
  "selectedLLMId": "string",
  "selectedEmbeddingId": "string", 
  "selectedRerankId": "string",
  "temperature": number,
  "maxTokens": number,
  "topK": number,
  "enableRerank": boolean,
  "similarityThreshold": number,
  "enableFullTextSearch": boolean,
  "language": "zh|en|ja"
}

更新用户设置

PUT /user-settings
Authorization: Bearer <token>
Content-Type: application/json

{
  "selectedLLMId": "string",
  "temperature": number,
  "maxTokens": number,
  // ... 其他设置字段
}

视觉管道 API

获取推荐模式

GET /api/vision/recommend-mode?file=xxx&size=xxx
Authorization: Bearer <token>

响应:

{
  "recommendedMode": "precise",
  "reason": "由于文件较大，推荐使用高精度模式",
  "estimatedCost": 0.5,
  "estimatedTime": 60,
  "warnings": ["处理时间可能会较长", "会产生API使用费用"]
}

LibreOffice 转换服务

POST /libreoffice/convert
Content-Type: multipart/form-data

{
  "file": File
}

响应:

{
  "pdf_path": "/uploads/document.pdf",
  "converted": true,
  "original": "document.docx",
  "file_size": 102400
}

健康检查

GET /libreoffice/health

响应:

{
  "status": "healthy",
  "service": "libreoffice-converter",
  "version": "1.0.0",
  "uptime": 3600.5
}

用户管理 API（管理员专用）

获取用户列表

GET /users
Authorization: Bearer <admin_token>

创建用户

POST /users
Authorization: Bearer <admin_token>
Content-Type: application/json

{
  "username": "string",
  "password": "string",
  "isAdmin": boolean
}

删除用户

DELETE /users/:id
Authorization: Bearer <admin_token>

错误响应格式

{
  "statusCode": number,
  "message": "string",
  "error": "string"
}

状态码说明

  • 200 - 成功
  • 201 - 创建成功
  • 400 - 请求参数无效
  • 401 - 认证错误 / 令牌无效
  • 403 - 权限不足
  • 404 - 资源未找到
  • 409 - 资源冲突
  • 500 - 服务器内部错误

实现示例

JavaScript/TypeScript

// 登录
const loginResponse = await fetch('/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    username: 'user',
    password: 'password'
  })
});

const { access_token } = await loginResponse.json();

// 获取文件列表
const filesResponse = await fetch('/knowledge-bases', {
  headers: {
    'Authorization': `Bearer ${access_token}`
  }
});

const files = await filesResponse.json();

// 流式聊天
const chatResponse = await fetch('/chat/stream', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${access_token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: '你好',
    history: [],
    userLanguage: 'ja'
  })
});

const reader = chatResponse.body.getReader();
// SSE 流的处理...

开放API功能实现总结

概述

本项目已实现完整的开放API功能，支持外部系统通过API Key进行认证和访问。

后端实现

API控制器

基础API控制器 (ApiController)

端点 方法 描述 认证方式
/health GET 健康检查 无
/chat POST 简单聊天接口 JWT

V1版本开放API控制器 (ApiV1Controller)

端点 方法 描述 认证方式
/api/v1/chat POST RAG聊天（支持流式SSE和JSON响应） API Key
/api/v1/search POST 知识库混合搜索 API Key
/api/v1/knowledge-bases GET 列出知识库文件 API Key
/api/v1/knowledge-bases/upload POST 上传文件到知识库 API Key
/api/v1/knowledge-bases/:id DELETE 删除知识库文件 API Key
/api/v1/knowledge-bases/:id GET 获取单个文件详情 API Key

API Key认证机制

文件位置: server/src/auth/api-key.guard.ts

支持两种方式传递API Key：

  • Authorization: Bearer kb_xxx 头
  • x-api-key 头

API Key格式: kb_ + 64位十六进制字符串

API Key数据模型

文件位置: server/src/auth/entities/api-key.entity.ts

@Entity('api_keys')
export class ApiKey {
    id: string;           // UUID主键
    userId: string;       // 关联用户ID
    key: string;          // API Key值（唯一）
    createdAt: Date;      // 创建时间
}

API Key管理服务

文件位置: server/src/user/user.service.ts

方法 描述
findByApiKey(apiKey) 通过API Key查找用户
getOrCreateApiKey(userId) 获取或创建用户的API Key
regenerateApiKey(userId) 重新生成API Key

前端实现

登录支持

文件位置: web/src/pages/auth/Login.tsx

支持两种登录方式：

  • 用户名/密码登录
  • API Key直接登录

API客户端

文件位置: web/services/apiClient.ts

  • 自动在请求头中添加 x-api-key
  • 支持多租户切换（x-tenant-id）

认证上下文

文件位置: web/src/contexts/AuthContext.tsx

  • 管理API Key状态
  • 持久化存储到 localStorage

功能特点

特性 状态 说明
API Key认证 ✅ 已实现 支持Bearer Token和x-api-key两种方式
多租户隔离 ✅ 已实现 每个API Key关联到特定用户和租户
RAG聊天（流式） ✅ 已实现 支持SSE流式响应
知识库搜索 ✅ 已实现 支持向量搜索和全文搜索的混合搜索
文件上传/管理 ✅ 已实现 支持文件上传、列表查询和删除
前端API Key登录 ✅ 已实现 支持直接使用API Key登录

使用示例

使用API Key进行认证

// 使用x-api-key头
const response = await fetch('/api/v1/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'kb_your_api_key_here'
  },
  body: JSON.stringify({
    message: '你好',
    stream: false
  })
});

// 或使用Authorization头
const response = await fetch('/api/v1/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer kb_your_api_key_here'
  },
  body: JSON.stringify({
    message: '你好',
    stream: true
  })
});

上传文件到知识库

const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('mode', 'fast');
formData.append('chunkSize', '1000');
formData.append('chunkOverlap', '200');

const response = await fetch('/api/v1/knowledge-bases/upload', {
  method: 'POST',
  headers: {
    'x-api-key': 'kb_your_api_key_here'
  },
  body: formData
});

待完善功能

功能 状态 说明
API Key管理界面 ❌ 未实现 需要在设置页面提供API Key的查看/复制/重新生成功能
API文档页面 ❌ 未实现 需要独立的API文档页面
细粒度权限控制 ❌ 未实现 目前所有API Key权限相同
API使用统计 ❌ 未实现 需要记录和展示API调用次数和频率
API速率限制 ❌ 未实现 需要防止API滥用

相关文件清单

后端文件

  • server/src/api/api.controller.ts - 基础API控制器
  • server/src/api/api-v1.controller.ts - V1版本开放API控制器
  • server/src/api/api.service.ts - API服务
  • server/src/api/api.module.ts - API模块
  • server/src/auth/api-key.guard.ts - API Key认证守卫
  • server/src/auth/entities/api-key.entity.ts - API Key实体
  • server/src/user/user.service.ts - 用户服务（包含API Key管理）

前端文件

  • web/src/pages/auth/Login.tsx - 登录页面（支持API Key登录）
  • web/src/contexts/AuthContext.tsx - 认证上下文
  • web/services/apiClient.ts - API客户端