> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 知识库 API

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

```text
/api/knowledge-bases
```

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

## 创建知识库

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

`shared` 让本实例其他已登录用户可以阅读。`default_open` 只会自动挂到**你自己的**新对话。`max_documents` 设置该知识库的文档数量上限。省略时默认 **100**，填 `0` 表示不限制，最大可填 **10000**。

## 上传文档

```bash
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
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}`      | 所有者   | 改名、共享、默认打开或修改 `max_documents` |
| `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`                    | 所有者   | 新建文件夹                                                                                                                 |
| `POST`   | `/knowledge-bases/{kb_id}/documents/{doc_id}/rename`  | 所有者   | 重命名文件或文件夹（请求体 `new_name`）                                                                                             |
| `POST`   | `/knowledge-bases/{kb_id}/documents/{doc_id}/move`    | 所有者   | 移动文件或文件夹（`target_folder`，空字符串表示根目录）。文件夹会连同内容一起移动。移到自己里面返回 `KNOWLEDGE_MOVE_INVALID`。同名冲突返回 `KNOWLEDGE_MOVE_NAME_TAKEN` |
| `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` 表示不限制，最大可填 **10000**。上传大小遵循服务器文件上限（默认 **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`        | 切换到已下载的本地模型                     |
