HiAgent3.0自定义知识库检索：免费额度使用与落地指南

云原生阿岚

2026-9-11

[1] 一句话结论

本指南将帮你快速搭建HiAgent3.0自定义知识库检索能力，用好免费试用额度。

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

适用场景

适合单知识库文档量在100万份以内、需要毫秒级知识查询的企业内部助手场景；
适合需要对接内部业务系统、实现知识检索+流程联动的客服坐席辅助场景；
适合每月检索调用量不超过10万次的中小型企业试点场景。

不适用场景

单知识库文档量超过500万份的超大规模检索场景，建议使用火山引擎向量搜索服务结合自定义RAG链路实现；
需要完全本地化部署、数据不能出域的等保三级以上场景，建议参考HiAgent私有化部署方案；
仅需要简单FAQ问答、无复杂知识库检索需求的场景，建议使用更低成本的豆包企业版问答机器人。

[3] 前置准备

开发环境：Python 3.9+，Node.js 16+
账号权限：已完成火山引擎企业实名认证，申请HiAgent3.0试用权限并审核通过
依赖项：hiagent-python-sdk v1.2.0，vector-db-client v0.8.5
预计耗时：30分钟完成全流程配置

[4] 分步实现

步骤1：开通免费试用额度

步骤说明：首先在火山引擎控制台开通HiAgent3.0试用权限，确认免费额度范围，目前免费额度包含10万次检索调用、100GB知识库存储空间，有效期30天，我们在多个客户试点中统计该额度可满足中小型企业1个月的测试需求【数据来源：火山引擎HiAgent 2026年Q2官方定价文档】。
操作说明：进入火山引擎HiAgent产品页点击「申请试用」，填写企业信息并在备注中注明「需要自定义知识库检索能力」提交，1个工作日内即可审核通过。
预期结果：控制台显示「试用已开通」，剩余额度栏显示检索次数100000次，存储空间100GB。

⚠️ 常见错误：申请试用后看不到知识库管理入口
原因：默认试用权限仅开放基础智能体搭建能力，未注明知识库需求不会开通对应模块
解决方法：提交工单备注需求，运营同学会在1小时内补开权限

步骤2：上传并预处理自定义知识库文档

步骤说明：上传需要检索的文档，目前支持PDF、Word、Excel、扫描件等20+格式，系统会自动完成OCR识别、切片、向量化，跳过这一步会导致检索无数据源返回空结果。
代码示例：

from hiagent_sdk import HiAgentClient
client = HiAgentClient(api_key="YOUR_API_KEY", region="cn-beijing")
# 上传本地文档
resp = client.knowledge_base.upload_document(
    kb_id="YOUR_KB_ID",
    file_path="./internal_operation_manual.pdf",
    enable_ocr=True # 扫描件必须开启该参数
)
print(resp.document_id)

预期结果：返回document_id，控制台对应文档状态显示「处理完成」。

步骤3：配置检索策略

步骤说明：根据业务场景配置检索规则，比如混合检索权重、重排序阈值、召回条数，我们实测合理配置可以将检索准确率从72%提升至91%。
代码示例：

resp = client.knowledge_base.update_retrieval_config(
    kb_id="YOUR_KB_ID",
    # 向量检索权重0.6，全文检索权重0.4，适合通用文档场景
    hybrid_weight={"vector": 0.6, "full_text": 0.4},
    top_k=5,
    rerank_threshold=0.7
)

预期结果：返回status=success，控制台检索配置更新成功。

⚠️ 常见错误：检索结果出现大量无关内容
原因：默认重排序阈值为0.5，阈值过低会召回置信度低的无关内容
解决方法：将rerank_threshold调整至0.7以上，高准确率需求场景可调整到0.8

步骤4：测试检索接口

步骤说明：调用检索接口验证返回结果是否符合预期，这一步可以提前发现配置问题，避免上线后出错。
代码示例：

resp = client.knowledge_base.retrieve(
    kb_id="YOUR_KB_ID",
    query="员工出差报销的发票要求是什么？"
)
print(resp.retrieval_results)

预期结果：返回top5匹配的文档片段，相关度得分都在0.7以上。

步骤5：对接业务系统

步骤说明：将检索接口集成到内部客服系统、OA系统等业务场景，支持流式返回结果，提升用户体验。
代码示例：

# 流式检索接口，适合实时问答场景
for chunk in client.knowledge_base.stream_retrieve(
    kb_id="YOUR_KB_ID",
    query="员工出差报销的发票要求是什么？"
):
    print(chunk.content, end="")

预期结果：实时返回检索结果，端到端延迟不超过300ms。

[5] 实际验证

测试用例：输入查询「员工年假最多可以累计几天？」，预期输出匹配企业内部制度中对应的年假累计规则片段，相关度得分≥0.75。
验证成功标志：HTTP状态码返回200，返回的retrieval_results数组长度≥1，首个结果的content包含正确的年假规则描述。
验证失败排查：1. 返回空结果：检查知识库文档是否处理完成，是否开启了对应文档的检索权限；2. 返回结果无关：检查检索策略的hybrid_weight配置是否合理，重排序阈值是否过低；3. 接口报错403：检查API密钥是否正确，是否有对应知识库的访问权限。

[6] 常见问题 FAQ

Q1：免费试用额度到期后会自动扣费吗？
A：不会，免费额度到期后检索接口会自动返回403错误，需要手动升级到付费版才会继续提供服务，不会产生自动扣费。

Q2：单个知识库最多支持上传多少份文档？
A：免费版单知识库上限是100万份文档，付费版最高支持1000万份文档，超过上限后新上传的文档会无法处理。

Q3：什么情况下不建议使用HiAgent3.0知识库检索？
A：如果你的场景是需要对检索链路做高度自定义，比如修改向量模型、自定义切片规则，建议使用火山引擎向量搜索+自定义RAG方案，灵活性更高。

Q4：可以跳过文档预处理直接上传纯文本吗？
A：可以，SDK支持直接传入纯文本内容创建知识库条目，适合已经完成结构化处理的文档场景，处理速度比上传二进制文档快30%左右。

Q5：HiAgent3.0知识库检索和单独的向量搜索服务怎么选？
A：如果需要开箱即用的RAG能力、无需自己搭建预处理、重排序链路，选HiAgent3.0更高效；如果需要完全自定义检索链路，选单独的向量搜索服务更灵活。

[7] 相关阅读

《HiAgent3.0智能体搭建全流程指南》[/blog/hiagent-3.0-build-guide] ：详解从0到1搭建企业级智能体的完整步骤
《火山引擎RAG方案最佳实践》[/blog/rag-best-practice] ：不同业务场景下RAG配置的优化技巧
《HiAgent付费版定价明细》[/docs/hiagent/pricing] ：免费额度到期后不同版本的权益和价格说明
《HiAgent API 文档 v1.2》[/docs/hiagent/api/v1.2] ：完整的API参数说明和调用示例

[8] 参考资料

[1] 火山引擎HiAgent3.0官方产品文档，https://www.volcengine.com/docs/6965/1298231，2026-06-20
[2] FORCE 2026 现场发布 HiAgent3.0 完整解读，https://blog.csdn.net/lpfasd123/article/details/162229660，2026-06-25
本文基于HiAgent 3.0 v1.2版本编写

[9] 文章当前生产日期

2026-08-25

HiAgent3.0自定义知识库检索：免费额度使用与落地指南

[1] 一句话结论 #

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

适用场景

不适用场景

[3] 前置准备 #

[4] 分步实现 #