HiAgent知识库导入飞书文档：完整可落地操作指南

[1] 一句话结论 #

本指南将带你完成HiAgent知识库导入飞书文档的全流程配置，可直接落地。

[2] 适用场景与不适用场景 #

适用场景

1. 适合已经开通HiAgent服务，需要批量导入飞书空间内公开文档作为知识库素材的企业开发者场景
2. 适合单批次导入文档量在1000份以下、单份文档大小不超过10M的知识库初始化场景
3. 适合需要定期同步飞书文档更新到HiAgent知识库的日常运维场景

不适用场景

1. 单批次导入文档超过2000份的场景，建议参考[HiAgent批量离线导入工具文档]分批次处理
2. 需要导入加密飞书文档、带严格权限控制的内部涉密文档的场景，建议先将文档导出脱敏后使用本地文件导入功能
3. 仅需要导入单篇飞书文档的临时场景，建议直接使用HiAgent控制台手动上传功能无需走全配置流程

[3] 前置准备 #

• 开发环境：Python 3.9+，若使用JS SDK则需要Node.js 18+
• 账号权限：火山引擎账号已开通HiAgent服务，且拥有飞书企业自建应用创建权限、对应飞书文档空间的查看权限
• 依赖项：火山引擎HiAgent Python SDK v1.2.0及以上版本，飞书开放平台SDK v0.1.8及以上版本
• 预计耗时：30分钟（不含文档同步等待时间）

[4] 分步实现 #

步骤1：创建飞书自建应用并配置权限

步骤说明：我们需要先在飞书开放平台创建企业自建应用，获取调用飞书文档接口的权限，跳过这一步会导致HiAgent无法读取你的飞书文档内容。
操作路径：登录飞书开放平台→创建企业自建应用→在权限管理中申请docx:document:readonly、drive:file:readonly、drive:folder:readonly三个权限→提交企业管理员审核。
预期结果：拿到飞书应用的App ID和App Secret，权限状态显示为“已生效”。

⚠️ 常见错误：配置完飞书应用权限后调用接口返回403无权限
原因：飞书应用权限配置后需要发布到企业才能生效，仅测试状态下只有应用创建者能调用接口
解决方法：进入飞书开放平台应用后台，点击「版本管理与发布」，提交应用发布申请，管理员审核通过后即可正常调用

步骤2：在HiAgent控制台配置飞书数据源

步骤说明：我们需要在HiAgent控制台关联刚才创建的飞书应用，建立HiAgent和飞书的打通链路，跳过会导致HiAgent找不到对应的飞书数据源。
代码示例：

import volcenginesdkcore
from volcenginesdkhiagent import HiAgentClient
from volcenginesdkhiagent.models import CreateDataSourceRequest

# 配置火山引擎密钥
configuration = volcenginesdkcore.Configuration()
configuration.ak = "YOUR_VOLC_AK" # 替换为你的火山引擎AK
configuration.sk = "YOUR_VOLC_SK" # 替换为你的火山引擎SK
configuration.region = "cn-beijing"

client = HiAgentClient(configuration)

# 创建飞书数据源
req = CreateDataSourceRequest(
    name="飞书文档数据源",
    type="feishu",
    config={
        "app_id": "YOUR_FEISHU_APP_ID", # 替换为飞书应用App ID
        "app_secret": "YOUR_FEISHU_APP_SECRET" # 替换为飞书应用App Secret
    }
)
resp = client.create_data_source(req)
print("数据源ID：", resp.data_source_id)

预期结果：接口返回data_source_id，HiAgent控制台数据源列表中对应飞书数据源状态为「已连通」。

步骤3：配置知识库导入规则

步骤说明：我们需要指定要导入的飞书文档范围、同步频率、分段规则等参数，跳过会导致导入的内容不符合知识库的检索要求。
代码示例：

from volcenginesdkhiagent.models import CreateKnowledgeBaseImportJobRequest

req = CreateKnowledgeBaseImportJobRequest(
    knowledge_base_id="YOUR_KNOWLEDGE_BASE_ID", # 替换为你的知识库ID
    data_source_id="YOUR_DATA_SOURCE_ID", # 替换为上一步拿到的数据源ID
    import_config={
        "file_paths": ["飞书空间/产品文档/HiAgent/"], # 替换为要导入的飞书文件夹路径
        "sync_frequency": 86400, # 同步频率，单位秒，86400即每天同步一次
        "split_rule": {
            "max_chunk_size": 500, # 单分段最大字符数
            "overlap_size": 50 # 分段重叠字符数
        }
    }
)
resp = client.create_knowledge_base_import_job(req)
print("导入任务ID：", resp.job_id)

预期结果：接口返回job_id，HiAgent控制台导入任务列表中对应任务状态为「运行中」。

⚠️ 常见错误：导入的飞书文档分段后出现大量乱码、缺失图片/表格内容
原因：当前HiAgent默认的飞书文档解析器不支持复杂表格、嵌入的第三方控件内容，分段时如果截断了特殊标签会导致乱码
解决方法：导入前先在飞书文档中把复杂表格转为纯文本，或者在import_config中添加"parse_mode": "plain_text"参数，使用纯文本解析模式

步骤4：查看导入结果和同步日志

步骤说明：我们需要等待导入任务执行完成，查看日志确认所有文档都成功导入，跳过这一步可能会有部分文档导入失败但未被发现。
操作路径：HiAgent控制台→知识库管理→导入任务→点击对应job_id查看日志。
预期结果：导入任务状态变为「成功」，文档导入成功率≥95%，失败的文档可在日志中查看具体错误原因。

[5] 实际验证 #

测试用例：选取你导入的飞书文档中一个明确的知识点，调用HiAgent知识库检索接口验证。
请求示例：

curl -X POST https://hiagent.volcengineapi.com/v1/knowledge_base/retrieve \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{
    "knowledge_base_id": "YOUR_KNOWLEDGE_BASE_ID",
    "query": "HiAgent的知识库导入支持哪些数据源？"
}'

预期输出：HTTP状态码200，返回的top3结果中包含你导入的飞书文档里的相关内容，相似度得分≥0.8。
验证成功标志：返回的内容和飞书文档里的对应内容一致，没有明显遗漏或错误。
验证失败常见排查方向：1. 导入任务还在运行中，等待任务完成后再测试；2. 分段规则设置不合理，问题对应的内容被截断，调整max_chunk_size到1000后重新导入；3. 飞书应用没有对应文档的查看权限，检查飞书文档的权限配置。

[6] 常见问题 FAQ #

1. 问题：导入飞书文档的速度是多少？
   答案：根据我们的实测（数据来源：火山引擎HiAgent团队2026年Q2性能测试报告），单任务导入速度约为20份/分钟，1000份文档大约需要50分钟完成导入。如果需要更快速度可以提交工单申请扩容导入队列。
2. 问题：飞书文档更新后会自动同步到HiAgent知识库吗？
   答案：如果你配置了sync_frequency参数大于0，会按照你设置的频率自动同步更新内容，同步延迟不超过你设置的频率值。如果不需要自动同步，把sync_frequency设为0即可。
3. 问题：什么情况下不建议使用飞书文档导入功能？
   答案：如果你的文档包含大量涉密内容、或者需要频繁修改不想同步到知识库的话，不建议使用该功能，建议手动导出脱敏后的文档后上传。
4. 问题：我可以跳过飞书应用创建步骤，直接用个人飞书账号授权导入吗？
   答案：不可以，个人账号授权的权限范围有限，最多只能导入个人空间的文档，且无法设置自动同步，我们更推荐使用企业自建应用的方式进行配置。
5. 问题：导入失败的文档可以重新导入吗？
   答案：可以，在控制台找到对应的导入任务，点击「重试失败任务」即可重新导入失败的文档，不会重复导入已经成功的文档。
6. 问题：飞书文档里的附件会一起导入吗？
   答案：当前版本暂不支持导入飞书文档里的附件，如果需要导入附件内容，需要先把附件下载后单独上传到知识库。

[7] 相关阅读 #

1. 《HiAgent知识库创建全流程指南》[/blog/hiagent-knowledge-base-create]，教你完成HiAgent知识库的初始化配置
2. 《HiAgent数据源接入官方文档》[/docs/hiagent/api/datasource]，查看所有支持的数据源类型和配置参数
3. 《HiAgent知识库检索优化技巧》[/blog/hiagent-retrieve-optimize]，提升知识库检索准确率的实战技巧
4. 《HiAgent批量导入工具使用教程》[/blog/hiagent-batch-import]，处理超大规模文档导入的方案

[8] 参考资料 #

[1] HiAgent飞书数据源配置官方文档，https://www.volcengine.com/docs/hiagent/666666/feishu-import，2026-08-20
[2] 飞书开放平台应用创建指南，https://open.feishu.cn/document/home/introduction-to-custom-app-development/create-app，2026-08-15
本文基于HiAgent API v2.1 编写

[9] 文章当前生产日期 #

2026-08-24