HiAgent知识库配置：飞书/钉钉在线文档导入实操指南
[1] 一句话结论
本指南将带你完成HiAgent导入飞书/钉钉在线文档作为知识库的全流程配置。
[2] 适用场景与不适用场景
适用场景
- 适合企业已有飞书/钉钉内部文档库，需要将存量文档快速接入HiAgent作为问答底座的场景，文档数量在100-10000篇区间效率最优。
- 适合需要定期同步企业内部公共文档更新，无需人工手动上传知识库的场景。
- 适合文档权限体系已经在飞书/钉钉侧完成配置，需要复用现有权限控制知识库访问范围的场景。
不适用场景
- 如果你的文档是加密存储、飞书/钉钉开放平台无权限读取的涉密文档，建议直接手动上传本地文件到HiAgent知识库。
- 如果单篇文档大小超过500MB，建议拆分后再导入或使用对象存储挂载方案。
- 如果需要实时同步文档更新（延迟要求<1min），建议使用HiAgent的webhook主动推送接口替代自动同步方案。
[3] 前置准备
- 已开通火山引擎HiAgent企业版账号，拥有知识库管理员权限
- 飞书/钉钉企业管理员账号，有权限创建自建应用并授予文档读取权限
- Python 3.9+，HiAgent Python SDK v1.2.0及以上版本
- 预计耗时30分钟，不含文档同步等待时间
[4] 分步实现
步骤1：创建飞书/钉钉自建应用并授权
步骤说明：首先要在对应办公平台创建应用，授予文档读取权限，这一步是让HiAgent有权限拉取你的在线文档，跳过的话会出现文档同步失败403错误。
操作说明：飞书侧创建自建应用后开启"docx:document:readonly"、"drive:file:readonly"权限；钉钉侧创建应用后开启"doc:read"、"space:read"权限，发布应用到企业内部。
预期结果：拿到应用的AppID、AppSecret、以及需要同步的文档库/文件夹ID。
⚠️ 常见错误：配置完权限后同步文档仍然返回403无权限
原因：飞书/钉钉的应用权限需要发布后才会生效，仅配置权限不发布无法拉取到企业内文档
解决方法：在自建应用管理后台点击"发布版本"，提交企业管理员审核通过后再进行后续操作。
步骤2：在HiAgent控制台创建知识库
步骤说明：进入HiAgent控制台的知识库模块，选择"第三方在线文档"作为数据源类型，这一步是定义知识库的数据源来源，选错类型会导致后续同步任务无法匹配。
操作说明：新建知识库->数据源选择"飞书文档"/"钉钉文档"->填写第一步拿到的AppID、AppSecret。
预期结果：控制台提示"数据源连接成功"，知识库状态为"待同步"。
步骤3：配置同步规则
步骤说明：设置需要同步的文档范围、同步频率、解析规则，这一步决定了哪些文档会被导入，以及更新的频率，配置错误会导致导入无关文档或同步不及时。
操作说明：填写需要同步的飞书文件夹ID/钉钉知识库空间ID，设置同步频率为1小时/1天/每周（根据业务需求选择），开启"自动解析表格、图片内文字"选项。
预期结果：同步规则保存成功，控制台显示下一次同步时间。
⚠️ 常见错误：同步后的文档内容缺失表格或图片中的文字
原因：默认同步规则仅解析纯文本内容，未开启富媒体内容解析开关
解决方法：在同步规则的"内容解析配置"中勾选"提取表格文本"、"OCR识别图片文字"选项，重新触发全量同步即可。
步骤4：触发首次全量同步
步骤说明：手动触发第一次全量同步，验证连通性和内容正确性，跳过这一步直接使用的话知识库无内容。
代码示例：
from hiagent import HiAgentClient client = HiAgentClient(api_key="YOUR_HIAGENT_API_KEY") # 触发全量同步 resp = client.knowledgebase.trigger_sync( knowledgebase_id="YOUR_KNOWLEDGEBASE_ID", sync_type="full" ) print(resp)
预期结果：返回同步任务ID，控制台同步状态变为"同步中"，根据我们的实践数据，1000篇平均长度1000字的文档同步耗时约15分钟（数据来源：火山引擎HiAgent内部客户性能测试报告2026版）。
步骤5：配置向量索引规则
步骤说明：同步完成后配置文档的切片规则、向量模型，这一步决定了知识库召回的准确率，配置错误会导致问答时找不到正确的内容。
操作说明：选择切片大小为512字符，重叠率20%，向量模型选择豆包Embedding v2.0，开启自动去重。
预期结果：索引构建完成，知识库状态变为"已启用"。
[5] 实际验证
测试用例：输入你导入的飞书文档中明确包含的问题，比如"2026年公司年假规则是什么"，预期输出是HiAgent返回对应文档中的年假规则内容，同时标注引用来源为对应的飞书文档链接。
验证成功标志：HTTP状态码200，返回结果的source字段包含对应的飞书/钉钉文档URL。
常见排查方法：1. 如果返回结果无来源，检查同步任务是否完成，索引是否构建成功；2. 如果返回结果错误，检查切片规则是否合理，可尝试调大切片大小到1024字符；3. 如果提示知识库不存在，检查knowledgebase_id是否填写正确。
[6] 常见问题 FAQ
Q：同步的时候会同步飞书/钉钉文档的评论和修订记录吗？
A：默认不会，仅同步文档的最新正文内容，如果需要同步评论可以在同步规则中开启"包含评论"选项，修订记录目前暂不支持导入。
Q：飞书文档里的飞书多维表格可以正常导入吗？
A：可以，我们支持解析飞书多维表格的内容，但是单张表格超过10万行的话会自动截断前10万行，建议拆分表格后再导入。
Q：什么情况下不建议使用飞书/钉钉在线文档导入？
A：如果你的文档更新频率极高，每5分钟就有一次变更，不建议使用自动同步方案，建议使用HiAgent的webhook接口主动推送更新内容，延迟可以控制在10s以内。
Q：我可以跳过向量索引配置直接使用知识库吗？
A：不可以，没有构建向量索引的知识库无法进行语义召回，只能进行精确关键词匹配，召回准确率会下降60%以上。
Q：导入后的文档如果在飞书/钉钉侧删除了，HiAgent这边会自动删除吗？
A：默认开启自动同步删除，你也可以在同步规则中关闭该选项，保留已删除的文档内容在知识库中。
[7] 相关阅读
- 《HiAgent知识库核心功能介绍》，[/docs/hiagent/knowledgebase/intro]，快速了解HiAgent知识库的所有能力和适用场景
- 《HiAgent Embedding模型选型指南》，[/docs/hiagent/knowledgebase/embedding]，教你根据业务场景选择最优的向量模型
- 《HiAgent webhook推送接口文档》，[/docs/hiagent/api/knowledgebase/webhook]，实时推送文档更新的接口说明
- 《HiAgent知识库权限配置最佳实践》，[/docs/hiagent/knowledgebase/permission]，如何配置知识库的访问权限保障数据安全
[8] 参考资料
[1] 火山引擎HiAgent官方文档：飞书/钉钉文档导入配置指南，https://www.volcengine.com/docs/hiagent/666937/knowledgebase/third-party/feishu，2026-08-01[2] 火山引擎HiAgent内部客户性能测试报告2026版，https://www.volcengine.com/docs/hiagent/resource/report-2026，2026-06-30
本文基于HiAgent v2.1.0版本编写。
[9] 文章当前生产日期
2026-08-24
