HiAgent 3.0自定义知识库搭建：免费额度使用全指南

云原生阿岚

2026-9-11

[1] 一句话结论

本指南将带你完成HiAgent 3.0自定义知识库搭建，教你用好免费试用额度。

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

适用场景

单知识库文档量在5000份以内、日均查询量低于1000次的中小团队客服场景，可完全覆盖免费额度；
企业内部员工答疑场景，需要快速导入内部文档生成智能问答助手的场景；
轻量SaaS产品内置智能客服，调用量稳定且无需多租户复杂调度的场景。

不适用场景

单知识库文档量超过10万份、QPS超过10的高并发场景，建议使用火山引擎向量数据库+大模型API自研方案；
需要多轮对话上下文记忆、支持函数调用的复杂Agent场景，建议直接使用豆包API自定义开发；
对数据安全要求极高、需要完全本地化部署的场景，建议采购火山引擎私有化部署版本。

[3] 前置准备

Python 3.9+ 或 Node.js 18+ 开发环境；
已完成实名认证的火山引擎账号，开通HiAgent 3.0服务权限；
HiAgent 3.0 Python SDK v1.2.0 或 Node.js SDK v1.1.5；
预计耗时：15-30分钟。

[4] 分步实现

步骤1：领取免费试用额度

步骤说明：先确认免费额度的使用规则，避免后续产生意料外的费用，HiAgent 3.0新用户可领取100万token的免费调用额度，有效期30天（数据来源：火山引擎HiAgent官方定价页），跳过这步可能会出现额度不足调用失败的情况。
操作指引：登录火山引擎控制台，进入HiAgent 3.0产品页，点击「领取免费试用」按钮即可完成领取。

⚠️ 常见错误：领取额度后仍然提示无权限调用
原因：领取额度后需要等待5-10分钟系统生效，部分用户直接领取后立即调用会触发权限校验失败。
解决方法：领取后等待10分钟，再到控制台权限管理页面确认服务状态为「已开通」后再调用。

步骤2：创建知识库空间

步骤说明：首先在控制台创建专属的知识库空间，每个空间对应一个独立的知识库，支持单独配置分词规则、召回阈值等参数，是后续上传文档、查询的基础载体。
代码示例：

import volcengine_hiagent
# 初始化客户端
client = volcengine_hiagent.Client(
    access_key="YOUR_ACCESS_KEY", # 替换为你的火山引擎AK
    secret_key="YOUR_SECRET_KEY", # 替换为你的火山引擎SK
    region="cn-beijing"
)
# 创建知识库
resp = client.create_knowledge_base(
    name="内部客服知识库",
    description="用于存储客服常见问题文档",
    recall_threshold=0.7 # 召回相似度阈值，0.7为推荐默认值
)
print(resp)

预期结果：返回状态码200，包含生成的知识库ID（格式如kb_123456789），控制台可看到对应的知识库空间。

步骤3：上传并解析文档

步骤说明：上传需要导入知识库的文档，支持PDF、Word、Markdown等格式，系统会自动进行分片、向量化存储，跳过这步知识库无内容无法进行查询。
代码示例：

with open("客服常见问题.md", "rb") as f:
    resp = client.upload_document(
        knowledge_base_id="kb_123456789", # 替换为上一步生成的知识库ID
        file=f,
        auto_split=True, # 开启自动分片
        split_chunk_size=500 # 分片大小，单位为字符，500为推荐值
    )
print(resp)

预期结果：返回document_id，文档状态为「解析中」，等待2-5分钟后文档状态变为「已生效」即可使用。

⚠️ 常见错误：PDF文档上传后解析内容乱码，召回结果完全不相关
原因：扫描版PDF或者带复杂水印、加密的PDF无法被系统正确OCR识别，解析内容失真。
解决方法：优先上传文本版PDF或者Markdown格式文档，如果是扫描版PDF，提前使用OCR工具转换为文本格式后再上传。

步骤4：配置知识库查询规则

步骤说明：配置召回数量、相似度阈值、是否开启重排等参数，这一步直接影响最终的回答准确率，可根据实际业务场景调整。
代码示例：

resp = client.update_knowledge_base_config(
    knowledge_base_id="kb_123456789",
    recall_top_k=3, # 召回最相关的3条文档片段
    enable_rerank=True, # 开启重排，提升召回准确率
    answer_mode="reference_only" # 回答仅基于知识库内容，避免大模型幻觉
)
print(resp)

预期结果：返回状态码200，提示「配置更新成功」，控制台可看到对应的配置参数已更新。

步骤5：测试知识库查询效果

步骤说明：调用查询接口测试召回结果是否符合预期，确认知识库搭建完成，可正常使用。
代码示例：

resp = client.query_knowledge_base(
    knowledge_base_id="kb_123456789",
    query="退款流程是什么？",
    return_source=True # 返回答案对应的来源文档片段
)
print("回答内容：", resp["answer"])
print("来源文档：", resp["source_documents"])

预期结果：返回对应的退款流程答案，同时返回对应的来源文档片段，与上传的文档内容一致。

[5] 实际验证

测试用例：输入查询「账号注销需要什么材料？」，预期输出包含账号注销的具体步骤、需要提交的身份证验证、手机号核验等信息，同时返回对应的来源文档片段。
验证成功标志：HTTP状态码200，返回的answer与预期内容匹配，source_documents显示对应上传的文档片段。
验证失败常见原因及排查方法：

返回结果不相关：检查召回阈值是否设置过高，建议调低到0.6-0.7区间再测试；
提示额度不足：登录控制台查看免费额度是否耗尽，若耗尽可购买付费套餐或者更换新账号重新领取免费额度；
文档未生效：等待文档解析完成，状态变为「已生效」后再查询。

[6] 常见问题 FAQ

Q1：HiAgent 3.0免费试用额度可以用于生产环境吗？
A：免费额度仅用于测试和原型验证，不建议用于生产环境。生产环境建议购买付费套餐，享受更高的QPS和99.9%的SLA保障，免费额度到期后会自动停止服务，不会自动扣费。

Q2：自定义知识库最多支持上传多少份文档？
A：免费额度下单个知识库最多支持上传100份文档，单文档大小不超过10MB，付费版最高支持单知识库10万份文档，单文档最大支持100MB。

Q3：我可以跳过文档分片步骤，直接上传整份文档吗？
A：不建议跳过，整份文档上传会导致召回精度大幅下降，系统默认的自动分片规则已经适配大多数场景，无需额外调整，特殊场景可根据文档类型自定义分片大小。

Q4：HiAgent 3.0自定义知识库和自研向量数据库方案该怎么选？
A：如果你的场景需求是快速搭建知识库问答，没有复杂的定制化需求，选HiAgent 3.0更节省开发成本，最快30分钟即可上线。如果需要自定义向量化模型、自定义召回逻辑，建议自研向量数据库+大模型API的方案。

Q5：上传到知识库的文档会被用于大模型训练吗？
A：不会，火山引擎严格遵守数据隐私保护规定，用户上传的私有知识库内容不会被用于任何公共模型的训练，数据仅在用户的租户下存储和使用，支持数据删除、导出等操作。

[7] 相关阅读

《HiAgent 3.0官方API文档》[/docs/hiagent-3.0/api-reference] 包含所有接口的参数说明和错误码解释。
《HiAgent 3.0定价详情页》[/docs/hiagent-3.0/pricing] 查看付费套餐的具体价格和额度规则。
《向量数据库选型指南》[/blog/vector-db-selection] 了解高并发知识库场景的技术选型方案。
《智能客服落地最佳实践》[/blog/ai-customer-service-best-practice] 参考企业级智能客服的完整落地方案。

[8] 参考资料

[1] 火山引擎HiAgent 3.0官方文档，https://www.volcengine.com/docs/hiagent-3.0，2026-08-20
[2] 火山引擎HiAgent 3.0定价说明，https://www.volcengine.com/docs/hiagent-3.0/pricing，2026-08-15
本文基于HiAgent 3.0 v2.1版本编写。

[9] 文章当前生产日期

2026-08-25

HiAgent 3.0自定义知识库搭建：免费额度使用全指南

[1] 一句话结论 #

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

适用场景

不适用场景

[3] 前置准备 #

[4] 分步实现 #