HiAgent 3.0：自定义知识库导入指南及试用政策说明

[1] 一句话结论 #

本指南介绍HiAgent 3.0试用政策，教你完成自定义知识库数据导入。

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

适用场景

1. 适合企业搭建智能客服场景，需要导入历史工单、产品手册等数据构建专属问答库的场景。
2. 适合工业设备运维场景，需要导入设备说明书、故障处理记录等搭建运维智能体的场景。
3. 适合单批次知识库导入量不超过5000份文档、日查询量在1万次以内的中小规模落地场景。

不适用场景

1. 如果你需要单批次导入超过10万份的超大规模非结构化文档，不建议直接使用平台自带导入工具，建议联系火山引擎技术团队申请定制化离线导入方案。
2. 如果你的场景是实时同步业务数据库的增量数据到知识库，不建议使用手动上传功能，建议参考【DataAgent数据同步工具】实现增量同步。
3. 如果你是个人开发者仅需搭建个人知识库助理，不建议使用HiAgent 3.0，建议使用豆包个人版知识库功能。

[3] 前置准备 #

• 开发环境要求：网页端操作只需Chrome 100+版本浏览器，调用API导入需Python 3.8+ / Node.js 16+
• 账号与权限要求：已完成火山引擎企业账号实名认证，且拥有HiAgent 3.0的管理员操作权限
• 依赖项与SDK版本：如需调用API导入，需安装火山引擎Python SDK v0.1.2及以上版本
• 预计耗时：单批次100份以内文档导入操作全程约15分钟

[4] 分步实现 #

步骤1：申请试用权限并登录控制台

步骤说明：首先需要确认你拥有HiAgent 3.0的访问权限，目前官方没有公开统一免费试用额度，需要联系企业服务团队申请专属试用权益，试用期间可体验最高1000份文档的知识库导入权限，该数据来自2026年火山引擎HiAgent官方运营政策¹。
操作：访问火山引擎HiAgent控制台，使用企业账号登录。
预期结果：成功进入控制台首页，可看到“知识库管理”菜单入口。

⚠️ 常见错误：登录后看不到“知识库管理”菜单
原因：你的账号没有被分配对应的管理员权限，或者试用申请还未通过审核
解决方法：先在控制台的“权限管理”模块确认自己的角色，若权限缺失联系企业账号管理员授权，若试用未通过可提交工单催促审核进度。

步骤2：创建专属知识库

步骤说明：每个知识库是独立的数据集，支持单独配置权限、检索规则，不同业务场景的知识库建议分开创建，避免检索串扰。
操作：进入“知识库管理”页面，点击“新建知识库”，填写知识库名称、描述，选择知识库类型（文档库/问答库/结构化库）。
预期结果：知识库创建成功，进入知识库详情页，可看到“导入数据”按钮。

步骤3：准备待导入的数据源

步骤说明：不同类型的知识库支持的导入格式不同，提前清洗数据能大幅提升后续的解析准确率。文档库支持PDF/Word/Markdown格式，问答库支持CSV格式（列名必须为question、answer），结构化库支持CSV/JSON格式。
操作：按照对应格式要求清洗数据，删除加密文档、损坏文件，扫描版PDF建议提前OCR处理为可编辑文本。
预期结果：所有待导入文件符合格式要求，单个文件大小不超过50MB。

⚠️ 常见错误：CSV格式的问答库导入后内容乱码
原因：CSV文件的编码不是UTF-8，或者列名不符合系统要求
解决方法：将CSV文件重新保存为UTF-8无BOM格式，确认第一行列名严格为question和answer，不要有多余列。

步骤4：执行数据导入操作

步骤说明：支持手动上传和API批量导入两种方式，小批量数据建议用可视化界面操作，大批量数据建议调用API导入效率更高。
操作：
手动上传：点击“导入数据”，选择“本地上传”，拖拽文件到上传区域，点击“开始导入”。
API导入：调用import_structured_data接口，示例代码如下：

import volcengine.hiagent
from volcengine.hiagent.models.import_structured_data_request import ImportStructuredDataRequest

client = volcengine.hiagent.Client()
client.set_ak("YOUR_ACCESS_KEY") # 替换为你的AccessKey
client.set_sk("YOUR_SECRET_KEY") # 替换为你的SecretKey

req = ImportStructuredDataRequest()
req.knowledge_base_id = "YOUR_KNOWLEDGE_BASE_ID" # 替换为你的知识库ID
req.file_path = "./data.csv" # 替换为你的本地文件路径
resp = client.import_structured_data(req)
print(resp)

预期结果：上传完成后显示导入进度，100份文档约3-5分钟完成解析和向量化，导入完成后可在“文档管理”页面看到所有导入的文件。

步骤5：验证导入结果并配置检索规则

步骤说明：导入完成后需要验证解析效果，配置分类标签、相似度阈值等参数，确保后续检索准确率符合预期。
操作：随机抽取3-5份导入的文档，查看系统解析后的分段内容是否正确，配置知识库的检索相似度阈值（建议设置为0.7-0.8），添加分类标签。
预期结果：所有导入文档解析正常，检索规则配置完成。

[5] 实际验证 #

测试用例：在控制台的“知识库测试”模块，输入一个导入的文档中包含的问题，比如你导入了产品手册，输入“XX产品的保修期限是多久”。
预期输出：返回的答案与手册内容一致，且来源标注为你导入的对应文档，HTTP状态码为200。
验证成功标志：返回结果匹配度≥90%，且来源正确。
验证失败常见原因及排查方法：

1. 返回结果不相关：检查待查询内容是否确实存在于导入的文档中，可适当调低相似度阈值。
2. 来源标注错误：检查是否多个知识库中存在相似内容，可调整知识库的检索优先级。
3. 无返回结果：检查导入任务是否已全部完成，文档是否解析失败，可在“导入记录”中查看失败原因。

[6] 常见问题 FAQ #

Q1：HiAgent 3.0的免费试用额度具体是多少？
A1：目前官方没有公开统一的免费试用额度，企业用户可以联系火山引擎企业服务团队申请专属试用权益，通常试用期间可获得最高1000份文档的知识库导入额度，以及10万次的知识库调用额度，有效期为1个月。

Q2：导入的文档支持哪些格式？扫描版PDF可以直接导入吗？
A2：目前支持PDF、Word、Markdown、CSV、JSON格式的文件导入，扫描版PDF如果没有做OCR处理，系统无法识别内容，建议提前将扫描版PDF转换为可编辑文本格式后再导入。

Q3：什么情况下不建议使用HiAgent 3.0的知识库功能？
A3：如果你的场景是个人使用，仅需要存储个人笔记、搭建个人知识库助理，不建议使用HiAgent 3.0，其定位是企业级产品，成本更高，功能也更复杂，个人用户建议使用豆包个人版知识库。

Q4：导入失败的文档可以重新导入吗？会重复占用额度吗？
A4：导入失败的文档不会占用知识库额度，你可以排查失败原因调整文件后重新导入，已经导入成功的文档如果删除后重新导入，会再次占用额度。

Q5：知识库导入的数据可以导出吗？
A5：目前支持导出你导入的原始文件，以及系统生成的问答对数据，向量数据暂时不支持导出。

[7] 相关阅读 #

1. 《HiAgent 3.0智能体搭建全流程指南》，[/docs/hiagent/12345]，从零教你搭建完整的企业级智能体
2. 《DataAgent数据同步工具使用教程》，[/docs/dataagent/67890]，教你实现业务数据增量同步到HiAgent知识库
3. 《HiAgent知识库检索调优最佳实践》，[/blog/hiagent-optimize]，提升知识库检索准确率的实用技巧
4. 《HiAgent 3.0定价说明》，[/docs/hiagent/pricing]，详细了解HiAgent 3.0的收费标准

[8] 参考资料 #

[1] 火山引擎HiAgent官方使用手册，https://www.volcengine.com/docs/86760/1868704，2026-08-20
[2] FORCE 2026 HiAgent 3.0发布解读，https://blog.csdn.net/lpfasd123/article/details/162229660，2026-06-24
本文基于HiAgent 3.0 v2.1版本编写。

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

2026-08-25