Skip to main content

QMind 配置数据源

为 QMind 知识库配置飞书或钉钉应用凭据、读取权限与资源授权。

本指南适用于知识库所有者和管理员。准备一篇可供试导入的文档,然后在 QMind 知识库的「添加资料(Add sources)」菜单中选择「数据源(Data sources)」。在弹窗中选择飞书或钉钉。
QMind 数据源弹窗中的钉钉和飞书入口
数据源QMind 表单字段目标资源由谁授权
飞书知识库app_id 填 App ID,app_secret 填 App Secret知识空间管理员授权给飞书应用
飞书云盘app_id 填 App ID,app_secret 填 App Secret,「云盘文件夹链接」填目标文件夹的飞书链接文件夹或文档所有者授权给飞书应用
钉钉client_id 填 Client ID(AppKey),client_secret 填 Client Secret(AppSecret),操作者 unionId 填员工的 Union ID知识库管理员授权给该操作者
应用的 API 权限决定可以调用哪些接口,资源授权决定这些接口可以读取哪些空间、文件夹和文档。密钥请从应用后台直接填入 QMind。

飞书

创建应用并开通权限

  1. 在目标文档所属的飞书组织中,打开开发者后台,创建企业自建应用。从「凭证与基础信息」复制同一个应用的 App ID 和 App Secret。飞书开发者后台 · 自建应用获取访问凭证
  2. 在「开发配置 → 权限管理」中点击「开通权限」。从飞书知识库导入新版文档时,至少需要开通以下两项应用身份权限。可复制权限标识进行搜索。
    飞书权限管理页面显示应用身份已开通查看知识库和查看新版文档权限
    从飞书云盘导入包含多种文件类型的文件夹时,建议在「权限管理」中按标识搜索并开通以下四项应用身份权限。
    • 查看云空间中文件元数据 drive:drive.metadata:readonly,用于读取根文件夹名称,以便 QMind 在「选择资源」中显示该名称。获取文件夹元数据
    • 查看新版文档 docx:document:readonly,用于读取新版飞书在线文档的正文块。
    • 查看、评论和下载云空间中所有文件 drive:drive:readonly,用于列出目标云盘文件夹中的文件和子文件夹,并下载上传到云盘的 Word、PDF 等原文件。
    • 导出云文档 drive:export:readonly,用于导出旧版飞书在线文档、独立电子表格和多维表格,也用于无法直接读取新版在线文档时的导出回退。
    飞书权限管理页面显示文件元数据、新版文档、云盘文件和云文档导出四项应用身份权限已开通
    按需开通的 API 权限 从飞书知识库或飞书云盘导入新版文档时,可根据要导入的内容开通以下应用身份权限。
    • 内嵌图片和附件。开通「下载云文档中的图片和附件」docs:document.media:download,用于下载图片和受支持的附件。下载素材
    • 内嵌电子表格。开通「查看、评论和导出电子表格」sheets:spreadsheet:readonly,用于查询工作表、读取单元格内容。获取工作表 · 读取单个范围
    • 内嵌多维表格。开通「查看、评论和导出多维表格」bitable:app:readonly,用于读取字段和记录。列出字段 · 查询记录
    • 内嵌白板。开通「查看画板节点」board:whiteboard:node:read,用于将白板作为图片导入。下载画板为图片
    • 引用的云文档标题。读取被引用文档的标题也使用 drive:drive.metadata:readonly。如果只配置飞书知识库,可按需开通此权限。获取文件元数据
    • @ 成员显示姓名。开通「获取通讯录基本信息」contact:contact.base:readonly 和「获取用户基本信息」contact:user.base:readonly,用于查询成员及读取姓名。应用的通讯录权限范围需包含被提及的成员。获取单个用户信息
    已开通的 drive:drive:readonly 也可用于下载内嵌图片和附件、读取内嵌电子表格。
  3. 启用「机器人」能力,以便资源管理员通过「添加文档应用」给应用授权。创建并发布应用版本,涉及审批时,等应用和所申请的权限生效后再测试。飞书云文档授权方式 · 飞书官方配置示例
    飞书开发者后台的「添加应用能力」页面突出显示「机器人」卡片和「添加能力」按钮

授权目标资源

  • 飞书知识库。请知识库管理员将上一步发布的飞书应用添加为目标知识库的可阅读成员。
    1. 打开飞书云文档的「知识库(Wiki)」,在目标知识库卡片上点击「设置(Settings)」。
      飞书知识库列表中目标知识库卡片上的设置按钮
    2. 打开「成员设置(Members)」,在「角色与权限」下选择「可阅读的成员(Viewer)」,点击「添加成员(Add Member)」。
      知识库成员设置中的可阅读成员角色和添加成员按钮
    3. 在弹窗中搜索飞书应用名称,选中对应应用并确认添加。
      添加可阅读成员的弹窗中显示匹配的飞书应用
    如果搜索不到应用,可将应用作为机器人添加到飞书群聊,再把该群添加为知识库的可阅读成员。飞书知识库常见问题 单篇文档需要单独授权时,在文档右上角「… → 更多 → 添加文档应用」中搜索应用并授予阅读权限。云文档授权方式
  • 飞书云盘。请文件夹所有者将目标文件夹分享给上一步发布的飞书应用。
    1. 在飞书云文档的「云盘(Drive)」中,右键点击目标文件夹,选择「分享(Share)」。
      飞书云盘文件夹右键菜单中的分享选项
    2. 在「邀请协作者(Invite collaborators)」中按名称搜索并选择飞书应用,授予阅读权限,然后确认分享。
      邀请协作者弹窗中显示匹配的飞书应用
    如果搜索不到应用,可将应用作为机器人添加到飞书群聊,再把文件夹分享给该群。飞书文件夹分享常见问题 授权后,右键点击目标文件夹,选择「复制链接(Copy Link)」,供连接 QMind 时使用。飞书云文档资源标识与授权
回到 QMind,选择「飞书」,将数据类型选为「知识库」或「云盘」,填写连接名称、app_id 和 app_secret。新建云盘数据源时,将复制的飞书文件夹链接粘贴到「云盘文件夹链接」。 点击「测试连接」。对于飞书云盘,QMind 会从链接中提取 folder_token,并检查应用能否读取该文件夹。测试通过后,在「选择资源」中展开目标知识库或云盘文件夹,选择要同步的内容。
飞书知识库连接表单中的数据类型、app_id 和 app_secret 字段

钉钉

  1. 在目标知识库所属的钉钉组织中创建企业内部应用,在应用详情中取得同一个应用的 Client ID(AppKey) 和 Client Secret(AppSecret)。钉钉开放平台 · 企业内部应用凭证说明
    钉钉开放平台的应用凭证页面
  2. 在钉钉开发者后台打开「权限管理」。导入知识库中的在线文档需要以下三项权限。可按权限名称搜索,并核对权限点 code。
    • 知识库读权限 Wiki.Workspace.Read,用于列出操作者可以访问的知识库。
    • 知识库节点读权限 Wiki.Node.Read,用于列出知识库中的文件夹和文档。
    • 企业存储文件读权限 Storage.File.Read,用于读取在线文档的正文块。钉钉知识库相关接口与权限
    如果还要导入知识库目录中上传的 Office、PDF 等文件,再开通以下两项权限。
    钉钉权限管理页面显示在线文档读取所需的三项权限和上传文件下载所需的两项权限
    开通权限后,发布应用并确认权限已生效。
  3. 将你自己的钉钉 Union ID 填入 QMind 的「操作者 unionId」。获取操作者 Union ID
  4. 回到 QMind,选择「钉钉」,填写连接名称及三个凭据字段,点击「保存并测试连接」。测试会列出操作者可访问的知识库并尝试读取文档。首次测试可以准备一篇操作者可读的在线文档,便于验证目录和正文读取。
钉钉连接表单中的 client_id、client_secret 和操作者 unionId 字段

获取操作者 Union ID

1. 获取 User ID

方法一:通过 dws

dws 是钉钉工作台命令行工具(DingTalk Workspace CLI),可在电脑终端中查询自己的用户信息。首次使用时,请按官方指南完成安装。也可以使用下方「方法二」请企业管理员查询。dws 官方介绍与安装指南 安装后,在终端运行以下命令,按提示打开浏览器,用自己的钉钉账号登录并授权。
dws auth login --format json
登录成功后,直接复制返回结果中的 user_id,即下图红框标出的值。
dws 登录成功后返回的 JSON 中用红框标出 user_id 字段
已经登录的用户,也可以运行以下命令,复制返回的 userId。
dws profile list --format json
dws profile list 返回的账号信息中用红框标出 userId 字段

方法二:通过企业管理员后台查询

请企业管理员登录钉钉管理后台,进入「通讯录 → 成员管理」,找到你的账号,复制「员工UserID」列中的值。
钉钉管理后台的通讯录成员管理页面中用红框标出员工UserID

2. 获取 Union ID

请使用已开通「成员信息读权限」qyapi_get_member 的应用。
  1. 打开钉钉开放平台的查询用户详情页面,点击「API 调试」。
    钉钉查询用户详情文档中的 API 调试入口
  2. 在调试台选择已创建的应用,点击「获取 Token」,自动填入 access_token。将上一步获取的 User ID 填入请求体的 userid,点击「发起调试」。
    钉钉 API 调试台中获取 Token、填写 userid、发起调试和查看 unionid 的步骤
  3. 调试成功后,复制响应中的 result.unionid,填入 QMind 的「操作者 unionId」。
请先在钉钉里打开目标文档。如果要同步附件,再确认自己可以下载附件。知识库文档成员操作

首次导入与排查

通过连接测试后,在「选择资源」里先勾选一份小文档或一个小目录。点击「继续」,选择同步模式后点击「导入」。提交后回到资料树,等文档处理完成,再用正文中的一句话验证是否可以检索。
现象从哪里查起
「保存并测试连接」报错,但显示「已配置凭据」「已配置凭据」表示连接已保存。点击「替换凭据」,从同一应用复制一对有效凭据,再测试。飞书可在官方调试台验证应用是否能获取租户访问凭证。钉钉还需检查 unionId、应用权限及是否至少有一篇可读文档。
连接通过,但找不到目标空间、目录或文件飞书检查应用能否列出目标空间或文件夹,以及目标文档是否已授权给该应用。钉钉检查填写的操作者能否打开目标资源,并核对应用的目录读取权限。
「选择资源」显示飞书云盘根文件夹的标识QMind 读不到文件夹名称时会显示 folder_token。检查飞书应用是否已开通 drive:drive.metadata:readonly,权限生效后重新测试连接。
能选择文档,导入后部分文件缺失用一份可正常读取的在线文档和一份失败文件对照检查。分别确认正文读取、附件下载权限及对应文件类型的支持情况。
资料树已有文档,但搜索不到查看资料处理状态,等处理完成后再搜索。