1. 目录 #

1. 2. 概述
2. 3. 认证相关 API
3. 4. 知识库管理 API
4. 5. 文档管理 API
5. 6. 聊天相关 API
6. 7. 系统设置 API
7. 8. 错误码说明
8. 9. 附录

2. 概述 #

2.1 基础信息 #

• Base URL: http://localhost:5000
• API 版本: v1
• 数据格式: JSON
• 字符编码: UTF-8

2.2 统一响应格式 #

所有 API 响应遵循统一的 JSON 格式：

2.2.1 成功响应 #

{
  "code": 200,
  "message": "success",
  "data": {
    // 响应数据
  }
}

2.2.2 错误响应 #

{
  "code": 400,
  "message": "错误信息",
  "data": null
}

2.3 认证方式 #

API 使用基于 Session 的认证方式。需要登录后才能访问的 API，需要在请求中携带有效的 Session Cookie。

2.4 请求头 #

对于需要认证的 API，请求头应包含：

Cookie: session=<session_id>

3. 认证相关 API #

3.1 用户注册 #

注册新用户账户。

端点: POST /register

请求方式: POST (表单提交)

请求参数 (表单数据):

参数名	类型	必填	说明
username	string	是	用户名
password	string	是	密码
password_confirm	string	是	确认密码
email	string	否	邮箱地址

响应: 重定向到首页

示例:

curl -X POST http://localhost:5000/register \
  -d "username=testuser&password=123456&password_confirm=123456&email=test@example.com"

---

3.2 用户登录 #

用户登录，创建会话。

端点: POST /login

请求方式: POST (表单提交)

请求参数 (表单数据):

参数名	类型	必填	说明
username	string	是	用户名
password	string	是	密码
next	string	否	登录成功后重定向的 URL

响应: 重定向到指定页面或首页

示例:

curl -X POST http://localhost:5000/login \
  -d "username=testuser&password=123456" \
  -c cookies.txt

---

3.3 用户登出 #

登出当前用户，清除会话。

端点: GET /logout

请求方式: GET

响应: 重定向到首页

示例:

curl -X GET http://localhost:5000/logout \
  -b cookies.txt

4. 知识库管理 API #

4.1 创建知识库 #

创建新的知识库。

端点: POST /api/v1/kb

认证: 需要登录

请求方式: POST

Content-Type: multipart/form-data 或 application/json

请求参数:

4.1.1 multipart/form-data 格式: #

参数名	类型	必填	说明
name	string	是	知识库名称
description	string	否	知识库描述
chunk_size	integer	否	文档分块大小，默认 512
chunk_overlap	integer	否	分块重叠大小，默认 50
cover_image	file	否	封面图片文件

4.1.2 application/json 格式: #

{
  "name": "我的知识库",
  "description": "知识库描述",
  "chunk_size": 512,
  "chunk_overlap": 50
}

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "abc123def456",
    "user_id": "user123",
    "name": "我的知识库",
    "description": "知识库描述",
    "cover_image": "covers/xxx.png",
    "chunk_size": 512,
    "chunk_overlap": 50,
    "created_at": "2024-01-01T00:00:00",
    "updated_at": "2024-01-01T00:00:00"
  }
}

示例:

# multipart/form-data 方式
curl -X POST http://localhost:5000/api/v1/kb \
  -H "Cookie: session=xxx" \
  -F "name=我的知识库" \
  -F "description=知识库描述" \
  -F "chunk_size=512" \
  -F "chunk_overlap=50" \
  -F "cover_image=@/path/to/image.png"

# JSON 方式
curl -X POST http://localhost:5000/api/v1/kb \
  -H "Cookie: session=xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "我的知识库",
    "description": "知识库描述",
    "chunk_size": 512,
    "chunk_overlap": 50
  }'

---

4.2 更新知识库 #

更新知识库信息。

端点: PUT /api/v1/kb/<kb_id>

认证: 需要登录，且必须是知识库所有者

请求方式: PUT

路径参数:

参数名	类型	必填	说明
kb_id	string	是	知识库 ID

Content-Type: multipart/form-data 或 application/json

请求参数:

4.2.1 multipart/form-data 格式: #

参数名	类型	必填	说明
name	string	否	知识库名称
description	string	否	知识库描述
chunk_size	integer	否	文档分块大小
chunk_overlap	integer	否	分块重叠大小
cover_image	file	否	封面图片文件
delete_cover	string	否	是否删除封面，值为 "true" 时删除

4.2.2 application/json 格式: #

{
  "name": "更新后的名称",
  "description": "更新后的描述",
  "chunk_size": 1024,
  "chunk_overlap": 100,
  "delete_cover": false
}

响应示例:

{
  "code": 200,
  "message": "知识库更新成功",
  "data": {
    "id": "abc123def456",
    "user_id": "user123",
    "name": "更新后的名称",
    "description": "更新后的描述",
    "cover_image": "covers/xxx.png",
    "chunk_size": 1024,
    "chunk_overlap": 100,
    "created_at": "2024-01-01T00:00:00",
    "updated_at": "2024-01-01T01:00:00"
  }
}

示例:

curl -X PUT http://localhost:5000/api/v1/kb/abc123def456 \
  -H "Cookie: session=xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "更新后的名称",
    "description": "更新后的描述"
  }'

---

4.3 删除知识库 #

删除指定的知识库。

端点: DELETE /api/v1/kb/<kb_id>

认证: 需要登录，且必须是知识库所有者

请求方式: DELETE

路径参数:

参数名	类型	必填	说明
kb_id	string	是	知识库 ID

响应示例:

{
  "code": 200,
  "message": "知识库删除成功",
  "data": null
}

示例:

curl -X DELETE http://localhost:5000/api/v1/kb/abc123def456 \
  -H "Cookie: session=xxx"

---

4.4 获取知识库封面图片 #

获取知识库的封面图片。

端点: GET /kb/<kb_id>/cover

认证: 需要登录，且必须是知识库所有者

请求方式: GET

路径参数:

参数名	类型	必填	说明
kb_id	string	是	知识库 ID

响应: 图片文件（二进制流）

Content-Type: image/jpeg, image/png, image/gif, image/webp 等

示例:

curl -X GET http://localhost:5000/kb/abc123def456/cover \
  -H "Cookie: session=xxx" \
  --output cover.png

5. 文档管理 API #

5.1 上传文档 #

上传文档到指定知识库。

端点: POST /api/v1/knowledgebases/<kb_id>/documents

认证: 需要登录

请求方式: POST

Content-Type: multipart/form-data

路径参数:

参数名	类型	必填	说明
kb_id	string	是	知识库 ID

请求参数 (表单数据):

参数名	类型	必填	说明
file	file	是	文档文件（支持 PDF、DOCX、TXT、MD）
name	string	否	自定义文档名称（可选，不提供则使用原文件名）

文件限制:

• 支持格式: pdf, docx, txt, md
• 最大文件大小: 100MB (可在配置中修改)

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "doc123abc456",
    "kb_id": "abc123def456",
    "name": "文档名称.pdf",
    "file_path": "documents/kb_id/doc_id/文档名称.pdf",
    "file_type": "pdf",
    "file_size": 1024000,
    "status": "pending",
    "chunk_count": 0,
    "error_message": null,
    "created_at": "2024-01-01T00:00:00",
    "updated_at": "2024-01-01T00:00:00"
  }
}

示例:

curl -X POST http://localhost:5000/api/v1/knowledgebases/abc123def456/documents \
  -H "Cookie: session=xxx" \
  -F "file=@/path/to/document.pdf" \
  -F "name=我的文档"

---

5.2 处理文档 #

触发文档处理任务（解析、分块、向量化）。

端点: POST /api/v1/documents/<doc_id>/process

认证: 需要登录

请求方式: POST

路径参数:

参数名	类型	必填	说明
doc_id	string	是	文档 ID

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "message": "文档处理任务已提交"
  }
}

示例:

curl -X POST http://localhost:5000/api/v1/documents/doc123abc456/process \
  -H "Cookie: session=xxx"

说明: 文档上传后会自动触发处理，此接口用于重新处理已上传的文档。

6. 聊天相关 API #

6.1 普通聊天（流式） #

进行普通聊天对话（不基于知识库），支持流式输出。

端点: POST /api/v1/knowledgebases/chat

认证: 需要登录

请求方式: POST

Content-Type: application/json

请求参数:

{
  "question": "你好",
  "session_id": "session123",
  "max_tokens": 1000,
  "stream": true
}

参数名	类型	必填	说明
question	string	是	用户问题
session_id	string	否	会话 ID，不提供则创建新会话
max_tokens	integer	否	最大 token 数，默认 1000，范围 1-10000
stream	boolean	否	是否流式输出，默认 true

响应: Server-Sent Events (SSE) 流

响应格式:

data: {"type": "start", "content": ""}

data: {"type": "content", "content": "你好"}

data: {"type": "content", "content": "！"}

data: [DONE]

事件类型:

• start: 开始响应
• content: 内容块
• error: 错误信息
• [DONE]: 响应完成

示例:

curl -X POST http://localhost:5000/api/v1/knowledgebases/chat \
  -H "Cookie: session=xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "你好",
    "stream": true
  }'

JavaScript 示例:

const eventSource = new EventSource('/api/v1/knowledgebases/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    question: '你好',
    stream: true
  })
});

eventSource.onmessage = (event) => {
  if (event.data === '[DONE]') {
    eventSource.close();
    return;
  }

  const data = JSON.parse(event.data);
  if (data.type === 'content') {
    console.log(data.content);
  }
};

---

6.2 知识库问答（流式） #

基于知识库进行问答，支持流式输出。

端点: POST /api/v1/knowledgebases/<kb_id>/chat

认证: 需要登录，且必须是知识库所有者

请求方式: POST

Content-Type: application/json

路径参数:

参数名	类型	必填	说明
kb_id	string	是	知识库 ID

请求参数:

{
  "question": "文档中提到了什么？",
  "session_id": "session123",
  "max_tokens": 1000
}

参数名	类型	必填	说明
question	string	是	用户问题
session_id	string	否	会话 ID，不提供则创建新会话
max_tokens	integer	否	最大 token 数，默认 1000，范围 1-10000

响应: Server-Sent Events (SSE) 流

响应格式:

data: {"type": "start", "content": ""}

data: {"type": "content", "content": "根据文档内容"}

data: {"type": "content", "content": "..."}

data: {"type": "done", "sources": [...]}

data: [DONE]

事件类型:

• start: 开始响应
• content: 内容块
• done: 完成，包含引用来源
• error: 错误信息
• [DONE]: 响应完成

引用来源格式:

{
  "type": "done",
  "sources": [
    {
      "doc_name": "文档名称.pdf",
      "chunk_index": 0,
      "content": "文档片段内容",
      "score": 0.85
    }
  ]
}

示例:

curl -X POST http://localhost:5000/api/v1/knowledgebases/abc123def456/chat \
  -H "Cookie: session=xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "文档中提到了什么？"
  }'

---

6.3 获取会话列表 #

获取当前用户的所有聊天会话列表。

端点: GET /api/v1/knowledgebases/sessions

认证: 需要登录

请求方式: GET

查询参数:

参数名	类型	必填	说明
page	integer	否	页码，默认 1
page_size	integer	否	每页数量，默认 10，最大 1000

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "items": [
      {
        "id": "session123",
        "user_id": "user123",
        "kb_id": "abc123def456",
        "title": "会话标题",
        "created_at": "2024-01-01T00:00:00",
        "updated_at": "2024-01-01T00:00:00"
      }
    ],
    "total": 10,
    "page": 1,
    "page_size": 10,
    "total_pages": 1
  }
}

示例:

curl -X GET "http://localhost:5000/api/v1/knowledgebases/sessions?page=1&page_size=10" \
  -H "Cookie: session=xxx"

---

6.4 创建会话 #

创建新的聊天会话。

端点: POST /api/v1/knowledgebases/sessions

认证: 需要登录

请求方式: POST

Content-Type: application/json

请求参数:

{
  "title": "新会话"
}

参数名	类型	必填	说明
title	string	否	会话标题

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "session123",
    "user_id": "user123",
    "kb_id": null,
    "title": "新会话",
    "created_at": "2024-01-01T00:00:00",
    "updated_at": "2024-01-01T00:00:00"
  }
}

示例:

curl -X POST http://localhost:5000/api/v1/knowledgebases/sessions \
  -H "Cookie: session=xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "新会话"
  }'

---

6.5 获取会话详情 #

获取指定会话的详情和消息列表。

端点: GET /api/v1/knowledgebases/sessions/<session_id>

认证: 需要登录，且必须是会话所有者

请求方式: GET

路径参数:

参数名	类型	必填	说明
session_id	string	是	会话 ID

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "session": {
      "id": "session123",
      "user_id": "user123",
      "kb_id": "abc123def456",
      "title": "会话标题",
      "created_at": "2024-01-01T00:00:00",
      "updated_at": "2024-01-01T00:00:00"
    },
    "messages": [
      {
        "id": "msg123",
        "session_id": "session123",
        "role": "user",
        "content": "你好",
        "sources": null,
        "created_at": "2024-01-01T00:00:00"
      },
      {
        "id": "msg456",
        "session_id": "session123",
        "role": "assistant",
        "content": "你好！有什么可以帮助你的吗？",
        "sources": [
          {
            "doc_name": "文档名称.pdf",
            "chunk_index": 0,
            "content": "文档片段",
            "score": 0.85
          }
        ],
        "created_at": "2024-01-01T00:01:00"
      }
    ]
  }
}

示例:

curl -X GET http://localhost:5000/api/v1/knowledgebases/sessions/session123 \
  -H "Cookie: session=xxx"

---

6.6 删除会话 #

删除指定的聊天会话。

端点: DELETE /api/v1/knowledgebases/sessions/<session_id>

认证: 需要登录，且必须是会话所有者

请求方式: DELETE

路径参数:

参数名	类型	必填	说明
session_id	string	是	会话 ID

响应示例:

{
  "code": 200,
  "message": "Session deleted",
  "data": null
}

示例:

curl -X DELETE http://localhost:5000/api/v1/knowledgebases/sessions/session123 \
  -H "Cookie: session=xxx"

---

6.7 清空所有会话 #

删除当前用户的所有聊天会话。

端点: DELETE /api/v1/knowledgebases/sessions

认证: 需要登录

请求方式: DELETE

响应示例:

{
  "code": 200,
  "message": "Deleted 5 sessions",
  "data": {
    "deleted_count": 5
  }
}

示例:

curl -X DELETE http://localhost:5000/api/v1/knowledgebases/sessions \
  -H "Cookie: session=xxx"

7. 系统设置 API #

7.1 获取系统设置 #

获取当前系统设置。

端点: GET /api/v1/settings

认证: 不需要登录

请求方式: GET

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "global",
    "embedding_provider": "huggingface",
    "embedding_model_name": "sentence-transformers/all-MiniLM-L6-v2",
    "embedding_api_key": null,
    "embedding_base_url": null,
    "llm_provider": "deepseek",
    "llm_model_name": "deepseek-chat",
    "llm_api_key": "your-api-key",
    "llm_base_url": "https://api.deepseek.com",
    "llm_temperature": "0.7",
    "chat_system_prompt": "你是一个友好的AI助手。",
    "rag_system_prompt": "你是一个专业的AI助手。请基于文档内容回答问题。",
    "rag_query_prompt": "文档内容：\n{context}\n\n问题：{question}\n\n请基于文档内容回答问题。",
    "retrieval_mode": "vector",
    "vector_threshold": "0.2",
    "keyword_threshold": "0.5",
    "vector_weight": "0.7",
    "top_n": "5",
    "created_at": "2024-01-01T00:00:00",
    "updated_at": "2024-01-01T00:00:00"
  }
}

示例:

curl -X GET http://localhost:5000/api/v1/settings

---

7.2 更新系统设置 #

更新系统设置。

端点: PUT /api/v1/settings

认证: 不需要登录

请求方式: PUT

Content-Type: application/json

请求参数:

{
  "llm_provider": "openai",
  "llm_model_name": "gpt-3.5-turbo",
  "llm_api_key": "your-api-key",
  "llm_temperature": "0.7",
  "embedding_provider": "openai",
  "embedding_model_name": "text-embedding-ada-002",
  "embedding_api_key": "your-api-key",
  "retrieval_mode": "hybrid",
  "vector_threshold": "0.2",
  "keyword_threshold": "0.5",
  "vector_weight": "0.7",
  "top_n": "5",
  "rag_system_prompt": "自定义系统提示词",
  "rag_query_prompt": "文档内容：\n{context}\n\n问题：{question}\n\n请回答。"
}

可配置字段:

字段名	类型	说明
embedding_provider	string	Embedding 提供商: huggingface, openai, ollama
embedding_model_name	string	Embedding 模型名称
embedding_api_key	string	Embedding API Key
embedding_base_url	string	Embedding Base URL (Ollama 需要)
llm_provider	string	LLM 提供商: deepseek, openai, ollama
llm_model_name	string	LLM 模型名称
llm_api_key	string	LLM API Key
llm_base_url	string	LLM Base URL
llm_temperature	string	LLM 温度参数 (0-1)
chat_system_prompt	string	普通聊天系统提示词
rag_system_prompt	string	知识库聊天系统提示词
rag_query_prompt	string	知识库聊天查询提示词 (可包含 {context} 和 {question})
retrieval_mode	string	检索模式: vector, keyword, hybrid
vector_threshold	string	向量检索阈值
keyword_threshold	string	关键词检索阈值
vector_weight	string	向量检索权重 (混合检索时使用)
top_n	string	TopN 结果数量

响应示例:

{
  "code": 200,
  "message": "Settings updated successfully",
  "data": {
    "id": "global",
    "llm_provider": "openai",
    "llm_model_name": "gpt-3.5-turbo",
    // ... 其他字段
  }
}

示例:

curl -X PUT http://localhost:5000/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{
    "llm_provider": "openai",
    "llm_model_name": "gpt-3.5-turbo",
    "llm_api_key": "your-api-key"
  }'

---

7.3 获取可用模型列表 #

获取系统支持的 Embedding 和 LLM 模型列表。

端点: GET /api/v1/settings/models

认证: 不需要登录

请求方式: GET

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "embedding_models": {
      "huggingface": [
        {
          "name": "sentence-transformers/all-MiniLM-L6-v2",
          "description": "轻量级多语言模型"
        }
      ],
      "openai": [
        {
          "name": "text-embedding-ada-002",
          "description": "OpenAI Embedding 模型"
        }
      ],
      "ollama": [
        {
          "name": "nomic-embed-text",
          "description": "Ollama Embedding 模型"
        }
      ]
    },
    "llm_models": {
      "deepseek": [
        {
          "name": "deepseek-chat",
          "description": "DeepSeek 聊天模型"
        }
      ],
      "openai": [
        {
          "name": "gpt-3.5-turbo",
          "description": "OpenAI GPT-3.5"
        },
        {
          "name": "gpt-4",
          "description": "OpenAI GPT-4"
        }
      ],
      "ollama": [
        {
          "name": "llama2",
          "description": "Llama 2 模型"
        }
      ]
    }
  }
}

示例:

curl -X GET http://localhost:5000/api/v1/settings/models

8. 错误码说明 #

8.1 HTTP 状态码 #

状态码	说明
200	请求成功
400	请求参数错误
401	未认证，需要登录
403	无权限访问资源
404	资源不存在
500	服务器内部错误

8.2 响应码 #

所有 API 响应中的 code 字段对应 HTTP 状态码：

• 200: 成功
• 400: 客户端错误（参数错误、验证失败等）
• 401: 未认证
• 403: 无权限
• 404: 资源不存在
• 500: 服务器错误

8.3 常见错误 #

8.3.1 未认证 #

{
  "code": 401,
  "message": "Unauthorized",
  "data": null
}

解决方案: 先调用登录接口获取 Session Cookie。

8.3.2 无权限 #

{
  "code": 403,
  "message": "Unauthorized to access this knowledgebase",
  "data": null
}

解决方案: 确保访问的资源属于当前用户。

8.3.3 参数错误 #

{
  "code": 400,
  "message": "name is required",
  "data": null
}

解决方案: 检查请求参数，确保必填字段已提供。

8.3.4 资源不存在 #

{
  "code": 404,
  "message": "未找到知识库",
  "data": null
}

解决方案: 检查资源 ID 是否正确，资源是否已被删除。

---

9. 附录 #

9.1 流式响应处理 #

对于支持流式输出的 API（聊天相关），响应格式为 Server-Sent Events (SSE)。

事件格式:

data: <JSON数据>\n\n

结束标志:

data: [DONE]\n\n

JavaScript 处理示例:

// 使用 EventSource (仅支持 GET)
const eventSource = new EventSource('/api/v1/knowledgebases/chat');

eventSource.onmessage = (event) => {
  if (event.data === '[DONE]') {
    eventSource.close();
    return;
  }

  const data = JSON.parse(event.data);
  // 处理数据
};

// 使用 fetch + ReadableStream (支持 POST)
const response = await fetch('/api/v1/knowledgebases/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ question: '你好' })
});

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]') {
        return;
      }
      const json = JSON.parse(data);
      // 处理数据
    }
  }
}

---

文档版本: 1.0
最后更新: 2024-01-01