> ## Documentation Index
> Fetch the complete documentation index at: https://octop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 知识库 API

> 通过 HTTP 创建知识库、上传文档，让对话检索带引用的来源。

用知识库 API 创建文档集合，供专家在对话中检索。大多数人应先从[页面](https://octop.mintlify.site/zh/concepts/knowledge.md)使用；本页用于把同一流程自动化。

```text theme={null}
/api/knowledge-bases
```

已登录用户可以列出自己拥有的库，以及已**共享**的库。创建、上传和删除需要你是所有者（管理员可以管理任意库）。管理员需先在页面中启用知识库，索引才会生效。

## 创建知识库

```bash theme={null}
curl -X POST http://127.0.0.1:8088/api/knowledge-bases \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "团队手册",
    "description": "入职文档",
    "shared": true,
    "default_open": false
  }'
```

`shared` 让本实例其他已登录用户可以阅读。`default_open` 只会自动挂到**你自己的**新对话。可选 `max_documents` 设置该库文档上限（`0` 表示不限制，默认 `100`）。

## 上传文档

```bash theme={null}
curl -X POST http://127.0.0.1:8088/api/knowledge-bases/<kb_id>/documents \
  -H 'Authorization: Bearer $TOKEN' \
  -F 'upload=@handbook.pdf'
```

支持文本（`.md`、`.txt`、`.rst`、`.html`、`.json`、`.jsonl`、`.yaml`、`.csv`、`.tsv`）、表格（`.xls`、`.xlsx`、`.xlsm`），以及 `.pdf`、`.docx`、`.pptx`。开启 OCR 后还支持 `.png`、`.jpg`、`.jpeg`、`.webp` 和扫描 PDF。上传后会开始建立索引，并返回上传进度。

不上传文件、直接创建 markdown 或纯文本：

```bash theme={null}
curl -X POST http://127.0.0.1:8088/api/knowledge-bases/<kb_id>/documents/text \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "notes",
    "format": "md",
    "content": "# 欢迎\n\n团队手册写在这里。"
  }'
```

## 知识库

| 方法 | 路径 | 谁可以调用 | 作用 |
| - | - | - | - |
| `GET` | `/knowledge-bases` | 已登录 | 列出你能看到的知识库 |
| `POST` | `/knowledge-bases` | 所有者 | 创建知识库 |
| `GET` | `/knowledge-bases/default-open` | 已登录 | 会在你的新对话中默认打开的知识库 |
| `GET` | `/knowledge-bases/{kb_id}` | 已登录 | 获取单个知识库 |
| `PATCH` | `/knowledge-bases/{kb_id}` | 所有者 | 改名、共享或默认打开 |
| `DELETE` | `/knowledge-bases/{kb_id}` | 所有者 | 删除知识库 |

## 文档与文件夹

| 方法 | 路径 | 谁可以调用 | 作用 |
| - | - | - | - |
| `GET` | `/knowledge-bases/{kb_id}/documents` | 已登录 | 列出文件和文件夹 |
| `POST` | `/knowledge-bases/{kb_id}/documents` | 所有者 | 上传文件 |
| `POST` | `/knowledge-bases/{kb_id}/documents/text` | 所有者 | 创建 markdown 或纯文本 |
| `POST` | `/knowledge-bases/{kb_id}/folders` | 所有者 | 新建文件夹 |
| `PATCH` | `/knowledge-bases/{kb_id}/documents/{doc_id}` | 所有者 | 重命名文件或文件夹 |
| `GET` | `/knowledge-bases/{kb_id}/documents/{doc_id}/preview` | 已登录 | 按原排版预览 |
| `GET` | `/knowledge-bases/{kb_id}/documents/{doc_id}/file` | 已登录 | 下载原文（`attachment`）或内联预览 |
| `GET` | `/knowledge-bases/{kb_id}/documents/{doc_id}/content` | 已登录 | 读取文本内容 |
| `PUT` | `/knowledge-bases/{kb_id}/documents/{doc_id}/content` | 所有者 | 保存页面内文本编辑（会重新索引） |
| `DELETE` | `/knowledge-bases/{kb_id}/documents/{doc_id}` | 所有者 | 删除文件或文件夹 |

每人最多创建 **20** 个知识库。每个库有文档数量上限（默认 **100**，`0` 表示不限制）。上传大小遵循服务器文件上限（默认 **100** MB）。

## 启用索引（管理员）

在**知识库 → 知识库设置**中打开功能，或在选好本地/在线嵌入模型后调用这些路由：

| 方法 | 路径 | 作用 |
| - | - | - |
| `GET` | `/knowledge-bases/capability` | 功能是否已开启且可用 |
| `GET` | `/knowledge-bases/embedding-options` | 可用的本地和在线模型 |
| `PUT` | `/knowledge-bases/feature` | 启用或关闭知识库（可同时设置 OCR） |
| `GET` | `/knowledge-bases/ocr-options` | 列出 OCR 后端（本地 RapidOCR / 在线视觉模型） |
| `POST` | `/knowledge-bases/onnx-download` | 下载本地模型 |
| `GET` | `/knowledge-bases/onnx-download-status` | 下载进度 |
| `POST` | `/knowledge-bases/onnx-activate` | 切换到已下载的本地模型 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.