HiAgent包年包月套餐：自定义知识库上传实操指南
[1] 一句话结论
本指南将带你完成HiAgent包年包月套餐下自定义知识库的全流程上传操作。
[2] 适用场景与不适用场景
适用场景
- 适合购买了HiAgent包年包月套餐，需要将企业内部静态文档导入作为智能体回答依据的内部客服、运维助手场景；
- 适合单知识库总容量在500GB以内，日均检索调用量不超过1万次的企业内部知识查询场景；
- 适合知识库文件以TXT/DOCX/PDF/XLSX/CSV为主，不需要实时同步数据源的静态知识库场景。
不适用场景
- 如果你的场景是需要实时对接业务数据库动态更新知识库内容，建议参考火山引擎DataAgent数据智能体方案；
- 如果你的单知识库容量超过500GB，建议拆分多个知识库或升级为按量付费套餐；
- 如果需要支持扫描件OCR解析、复杂版式文件识别的场景，建议搭配火山引擎TextIn服务先完成文件解析后再上传。
[3] 前置准备
- 已购买HiAgent包年包月套餐，且账号拥有对应工作空间的管理员权限；
- 使用Chrome 100+/Edge 100+版本浏览器即可操作，无额外开发环境要求；
- 待上传文件已转换为平台支持的格式（TXT/DOCX/PDF/XLSX/CSV），单文件大小不超过500MB（数据来源：火山引擎HiAgent官方文档v3.0）；
- 预计操作耗时：15-30分钟（依文件数量多少而定）。
[4] 分步实现
步骤1：预处理知识库文件
步骤说明：首先对待上传的文件进行清洗，删除冗余的页眉页脚、水印、广告内容，扫描类文件先转为可编辑的文字版，保证文件内容完整可读。这一步是后续向量化准确率的基础，跳过会导致知识库检索匹配度下降30%以上。
预期结果：所有待上传文件格式符合要求，无加密、损坏情况，内容无冗余噪声。
⚠️ 常见错误：上传的PDF文件是加密扫描件，上传后解析内容全是乱码
原因：平台默认只支持文字版PDF解析，不自带OCR识别能力，无法识别扫描件中的图片内容
解决方法：先使用TextIn等OCR工具将扫描件转为可编辑文字版PDF，去除密码保护后再上传。
步骤2：创建自定义知识库
步骤说明：登录HiAgent控制台，进入已购买包年包月套餐对应的工作空间，在左侧菜单栏找到「知识库管理」模块，点击「新建知识库」，填写知识库名称、分类标签，设置访问权限（仅工作空间内可见/公开给全企业）。跳过这一步没有文件上传的目标容器，无法进行后续操作。
预期结果：知识库创建成功，自动跳转至知识库详情页，页面显示当前知识库已使用容量、文件数量等信息。
步骤3：批量导入知识库文件
步骤说明：在知识库详情页点击「导入文件」，选择「本地上传」方式，批量选择预处理好的文件，也可以选择对接火山引擎TOS对象存储批量导入云端文件。包年包月套餐默认单批次上传文件上限为100个，不要一次性上传超过限制的文件。
预期结果：文件全部上传完成后，列表中显示所有文件状态为「待处理」，无上传失败的提示。
⚠️ 常见错误：批量上传120个文件时出现20个文件上传失败，重试也无效
原因：包年包月套餐默认单批次上传文件上限为100个，超过会触发流量限制，导致超出部分上传失败
解决方法：分批次上传，每批次文件数量不超过100个，也可以联系客服临时提升单批次上传配额。
步骤4：配置向量化处理规则
步骤说明：文件上传完成后，点击「启动处理」，配置语义分片策略，建议选择「按文档标题层级切分」，分片大小设置为512字符，选择默认的bge-large-zh-v1.5 Embedding模型，启动向量化任务。这一步是将文件内容转换为语义向量的核心步骤，跳过的话知识库内容无法被智能体检索到。
预期结果：向量化任务执行完成后，所有文件状态更新为「已生效」，页面显示处理完成的分片数量。
步骤5：挂载知识库到智能体
步骤说明：进入需要关联知识库的智能体配置页面，在「技能配置」-「知识库关联」模块，选择刚创建完成的自定义知识库，设置知识库检索权重（建议设置为0.7，优先返回知识库内容），保存配置。跳过这一步智能体不会主动调用该知识库的内容。
预期结果：智能体配置页面显示已关联的知识库名称，状态为「已生效」。
[5] 实际验证
测试用例：在智能体测试窗口输入查询语句（该内容必须存在于你上传的知识库文件中，例如「请查询2025年公司员工年假规定」），点击发送。
验证成功标志：智能体返回的内容与知识库中对应的内容一致，且返回结果底部标注知识来源为你创建的自定义知识库，接口返回HTTP状态码200。
常见排查方法：
- 如果返回结果不是知识库内容，先检查智能体配置中是否将知识库检索优先级设置为高于通用大模型；
- 如果返回结果来源不对，检查向量化任务是否全部完成，文件状态是否为「已生效」；
- 如果完全检索不到对应内容，检查语义分片策略是否设置过大，导致相关内容被拆分到不同分片丢失了上下文，可将分片大小调整为256字符重新处理。
[6] 常见问题 FAQ
Q1：包年包月套餐的自定义知识库容量上限是多少？
A1：不同档位包年包月套餐的知识库容量不同，最低档为50GB，最高档为500GB，你可以在控制台「套餐详情」页查看具体容量，超出后将无法继续上传文件。
Q2：我可以跳过向量化步骤直接挂载知识库吗？
A2：不可以，向量化是将文件内容转换为语义向量的必要步骤，没有向量化的知识库无法被智能体检索到，必须等待向量化任务全部完成后再挂载。
Q3：什么情况下不建议使用自定义知识库本地上传功能？
A3：如果你的知识库内容需要每小时更新一次以上，不建议使用本地上传的方式，建议使用知识库API实时写入内容，避免频繁上传文件占用太多操作成本。
Q4：PDF文件上传后解析效果差怎么办？
A4：首先确认你的PDF是文字版而非扫描版，其次可以在上传前删除PDF中的页眉页脚、水印等冗余内容，也可以调整语义分片策略，按标题层级切分提升解析准确率。
Q5：我上传的文件可以删除或修改吗？
A5：可以，在知识库详情页找到对应文件即可执行删除、重新上传操作，修改后需要重新执行向量化任务，新内容会在10分钟内生效。
[7] 相关阅读
- 《HiAgent知识库管理官方手册》，[/docs/86760/2075114]，了解知识库的所有功能说明和参数配置细节。
- 《HiAgent包年包月套餐规格说明》，[/docs/86760/2488915]，查看不同档位套餐的容量、调用量等限制规则。
- 《TextIn+HiAgent打造合同审计智能体教程》，[/blog/156342579]，学习如何处理复杂版式文件上传到知识库。
[8] 参考资料
[1] 火山引擎HiAgent知识库管理官方文档，https://www.volcengine.com/docs/86760/2075114?lang=zh，2026-08-24[2] HiAgent智能体平台使用手册，https://nic.cdu.edu.cn/info/1035/2344.htm，2026-08-24
本文基于火山引擎HiAgent v3.0版本编写。
[9] 文章当前生产日期
2026-08-24
