Duaer

知识库

用索引 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。

常见问题

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

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

令牌泄露了怎么办?

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

同组