> For the complete documentation index, see [llms.txt](https://doc.duaer.com/zh/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.duaer.com/zh/knowledge/sources/indexing-api.md).

# 用索引 API 把没有连接器的系统接进知识库

内部 Wiki、工单系统、自己的文件服务器：注册一个自定义数据来源，用它的令牌推送文档和每篇文档的可读人员，员工就能在搜索和回答里用到它们。
## 什么时候用

Duaer 没有连接器的系统，可以由你自己的程序把文档推送进来。推送的文档和其他来源一样：能搜到、能用于回答，回答里注明出处，并且只有可读的人才能看到。

## 注册来源，拿到令牌

- 每个令牌只能写它自己的来源，不能搜索，也不能读取任何内容。Duaer 只保存令牌的哈希值。

1. 所有者或管理员打开项目的「知识库」，切到「知识来源」，在「自定义数据来源」里输入来源名称，点「添加来源」。
2. 页面上会显示令牌（以 dks_ 开头）和 API 地址，各有「复制」按钮。令牌只显示这一次，请马上保存。
3. 之后页面上只显示「令牌末四位 ……」。令牌丢了就点「重新生成令牌」，旧令牌立即失效；点「撤销」后，这个来源在生成新令牌之前无法推送。
4. 点「移除」会删除这个来源，以及它推送的所有文档和组。每个组织最多 20 个自定义来源。

## 推送一篇文档

每次请求都带上请求头 Authorization: Bearer <令牌>。同一个 id 再推送一次，就替换原来的文档。

```
curl -X PUT "https://<你的 Duaer 地址>/v1/knowledge/custom/documents/leave-policy" \
  -H "Authorization: Bearer dks_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "年假规定",
    "body": "正式员工每年 15 天年假……",
    "url": "https://wiki.example.com/leave",
    "author": "hr@example.com",
    "updatedAt": "2026-10-01T08:00:00+08:00",
    "readers": { "groups": ["HR"], "people": ["li.wen@example.com"] }
  }'
```

title：标题，最多 512 个字符。body：用来搜索和回答的正文，最多 500,000 个字符。

url（可选）：点开结果时去的地址，http 或 https。author（可选）：作者邮箱。updatedAt（可选）：ISO 格式的修改时间。

id 在路径里，最多 200 个字符，在这个来源里唯一。

## 谁能读

- readers.people：邮箱列表，最多 1,000 个。邮箱不区分大小写，按邮箱对应到 Duaer 成员。
- readers.groups：这个来源自己推送的组名，最多 100 个。
- readers.everyone：true 时组织里所有成员都能读。
- 三者可以同时用。readers 为空的文档谁也搜不到。不在组织里的人什么都搜不到。

## 推送组

组由来源自己定义：推送组名和成员邮箱，文档里写组名即可。改了组员，不用重推文档，谁能读马上跟着变。

```
curl -X PUT "https://<你的 Duaer 地址>/v1/knowledge/custom/groups/HR" \
  -H "Authorization: Bearer dks_..." \
  -H "Content-Type: application/json" \
  -d '{ "members": ["hr@example.com", "li.wen@example.com"] }'
```

这次推送的成员会替换组里原来的成员。每个组最多 5,000 人，组名最多 200 个字符。

组只属于推送它的来源：两个来源里同名的组是两个不同的组。还没推送过的组没有成员。

## 所有请求

- GET /v1/knowledge/custom：来源名称、文档数、组数。
- PUT /v1/knowledge/custom/documents/:id：创建或替换一篇文档。
- POST /v1/knowledge/custom/documents：一次创建或替换最多 100 篇，请求体是 { "documents": [...] }，每篇带自己的 id。只要有一篇不合格，整批都不写入。
- DELETE /v1/knowledge/custom/documents/:id：删除一篇文档。
- PUT /v1/knowledge/custom/groups/:name：设置一个组的成员。
- DELETE /v1/knowledge/custom/groups/:name：删除一个组。

## 错误和限制

- 401：没带令牌、令牌不对或已撤销。
- 400：文档或组不合格，message 会指出是哪个字段，例如 documents.1.readers.people.0。
- 404：要删除的文档或组不存在。
- 413：一次请求超过 16 MB。正文很长时，每次少发几篇。
- 429：同一个 IP 一分钟超过 600 次请求。
- 推送后几秒内就能搜到；用于语义搜索的向量在推送停下 5 秒后统一生成。
- 没有重新推送的文档会一直保留，要删除就用 DELETE。
## Questions

### 可以用 SCIM 同步过来的组当可读人员吗？

不可以。可读的组是来源自己推送的组，这样不依赖身份提供商，组名也和你的系统一致。

### 令牌泄露了怎么办？

在「自定义数据来源」里点「重新生成令牌」或「撤销」，旧令牌立即失效。令牌只能写这一个来源，不能读取或搜索任何内容。

## 相关

- [可以接进 Duaer 知识库的知识来源](https://doc.duaer.com/zh/knowledge/sources.md)
- [AI 搜索怎么守住文档权限：Duaer 沿用原系统的权限](https://doc.duaer.com/zh/guides/permission-aware-ai-search.md)
- [AI 回答怎么附出处、不胡编：Duaer 的做法](https://doc.duaer.com/zh/guides/ai-answers-with-citations.md)
- [管理员上线清单：把 Duaer 用到全公司](https://doc.duaer.com/zh/knowledge/set-up.md)

