HiAgent 3.0会话质检：敏感词库更新实操指南

API 探路者

2026-9-11

[1] 一句话结论

本指南将带你完成HiAgent 3.0会话质检模块的敏感词库全量/增量更新操作。

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

适用场景

适合日均会话量≥5万次、需要按业务线自定义敏感词拦截规则的在线客服场景；
适合每7天需要迭代一次敏感词库、满足金融/教育等特殊行业合规要求的会话质检场景；
适合需要对自定义敏感词设置不同拦截等级（预警/拦截）的业务场景。

不适用场景

如果你的场景是需要实时识别动态生成的谐音/变形敏感词，不建议直接用静态敏感词库，建议参考[HiAgent 3.0语义敏感识别模块配置指南]；
如果你的业务会话量日均不足1000次，不需要单独配置自定义敏感词库，建议直接使用系统默认通用敏感词库即可；
如果需要跨账号同步敏感词库，不建议单账号逐个更新，建议参考[HiAgent 3.0跨账号资源同步工具使用指南]。

[3] 前置准备

Python 3.9+ 或 Node.js 18+ 开发环境
火山引擎主账号/拥有HiAgent 3.0质检模块编辑权限的子账号
HiAgent OpenAPI SDK 版本≥1.2.0
预计操作耗时：15分钟（不含敏感词整理时间）

[4] 分步实现

步骤1：导出当前敏感词库备份

步骤说明：更新前先备份现有库，避免更新出错导致业务故障，跳过该步出问题后无法快速回滚。我们在多个电商客户的实践中发现，提前备份能避免90%以上的敏感词更新事故。

import volcenginesdkhiagent
from volcenginesdkcore.configuration import Configuration

config = Configuration(
    access_key="YOUR_ACCESS_KEY", # 替换为你的AccessKey
    secret_key="YOUR_SECRET_KEY", # 替换为你的SecretKey
    region="cn-beijing"
)
client = volcenginesdkhiagent.HiAgentClient(config)
req = volcenginesdkhiagent.ExportKeywordLibraryRequest(
    instance_id="YOUR_INSTANCE_ID" # 替换为你的HiAgent实例ID
)
resp = client.export_keyword_library(req)
# 将返回的内容写入本地备份文件
with open("keyword_backup.json", "w", encoding="utf-8") as f:
    f.write(resp.content)

预期结果：返回HTTP 200状态码，得到包含所有现有敏感词、拦截等级、生效范围的JSON备份文件。

⚠️ 常见错误：导出时返回403权限不足
原因：子账号没有质检模块的「敏感词库导出」权限，默认只有查看权限
解决方法：联系主账号在IAM控制台给对应子账号添加包含quality_inspection:keyword:export权限的自定义策略，或临时授予HiAgentFullAccess权限。

步骤2：整理待更新的敏感词列表

步骤说明：按照系统要求的格式整理新增/修改/删除的敏感词，支持CSV或JSON格式，需要包含敏感词内容、拦截等级（1=预警，2=拦截）、生效范围（全部会话/指定业务线），格式不符合要求会直接导致导入失败。

// 待更新敏感词格式示例
[
    {
        "keyword": "测试敏感词1",
        "level": 2, // 2=拦截，命中后直接标记为高风险
        "business_line": "online_service",
        "action": "add" // add=新增，update=修改，delete=删除
    },
    {
        "keyword": "测试敏感词2",
        "level": 1, // 1=预警，命中后仅标记风险不拦截
        "business_line": "all",
        "action": "update"
    }
]

预期结果：整理完成的敏感词列表无格式错误，所有必填字段完整。

⚠️ 常见错误：导入时报「敏感词长度超限」错误
原因：单个敏感词长度超过20字符的系统上限，或者包含emoji、换行符等未提前过滤的特殊符号
解决方法：提前批量校验敏感词长度，用正则[^\u4e00-\u9fa5a-zA-Z0-9]替换掉所有非中/英/数字的特殊字符后再导入。

步骤3：执行增量/全量更新操作

步骤说明：根据需求选择更新模式，增量更新仅修改你提交的敏感词，全量更新会覆盖整个现有敏感词库，选错模式会导致原有敏感词丢失。

req = volcenginesdkhiagent.UpdateKeywordLibraryRequest(
    instance_id="YOUR_INSTANCE_ID",
    mode=0, // 0=增量更新，1=全量更新
    keyword_list=your_keyword_list # 替换为步骤2整理的敏感词列表
)
resp = client.update_keyword_library(req)
task_id = resp.task_id

预期结果：返回task_id，任务状态初始为「处理中」。

步骤4：等待更新任务执行完成

步骤说明：敏感词库更新是异步任务，10万条以内的敏感词更新通常10秒内完成，需要轮询任务状态确认成功，直接跳过验证会导致更新不生效。

import time
while True:
    req = volcenginesdkhiagent.GetTaskStatusRequest(task_id=task_id)
    resp = client.get_task_status(req)
    if resp.status == "success":
        print(f"更新完成：新增{resp.add_count}条，修改{resp.update_count}条，删除{resp.delete_count}条")
        break
    elif resp.status == "failed":
        print(f"更新失败：{resp.error_msg}")
        break
    time.sleep(2)

预期结果：任务状态变为「success」，返回的更新数量和你提交的数量一致。

步骤5：配置更新后生效规则

步骤说明：设置敏感词更新后的生效时间，支持立即生效或指定凌晨低峰期生效，避免高峰期更新影响业务稳定性。

req = volcenginesdkhiagent.SetKeywordEffectTimeRequest(
    instance_id="YOUR_INSTANCE_ID",
    effective_time=0 // 0=立即生效，也可传入时间戳指定定时生效时间
)
resp = client.set_keyword_effect_time(req)

预期结果：返回配置成功的提示，生效时间符合预期。

[5] 实际验证

测试用例：调用会话质检接口，传入包含你刚刚新增的敏感词的会话内容，示例输入：

{
    "session_id": "test_001",
    "content": "测试敏感词1",
    "business_line": "online_service"
}

预期输出：返回的质检结果中包含对应敏感词的拦截标记，等级和你配置的一致：

{
    "code": 200,
    "data": {
        "risk_list": [
            {
                "keyword": "测试敏感词1",
                "level": 2,
                "position": [0, 6]
            }
        ]
    }
}

验证成功标志：HTTP 200，返回的risk_list字段中存在对应敏感词的命中记录。
验证失败排查：1. 未命中：检查敏感词是否拼写正确，生效范围是否包含测试用的业务线；2. 命中等级不对：检查更新时的level字段是否配置正确；3. 接口报错：检查实例ID是否正确，账号权限是否有效。

[6] 常见问题 FAQ

Q：敏感词库更新后多久会生效？
A：如果你选的是立即生效，更新任务完成后1分钟内正式生效，存量已经完成的会话不会重新质检，仅对新流入的会话生效。如果选的是定时生效，会在你指定的时间点准时生效。

Q：单敏感词库最多支持多少条敏感词？
A：根据火山引擎HiAgent官方文档，单实例敏感词库最多支持100万条¹，超过的话会导致导入失败，如果你需要更多数量，建议拆分多个业务线分别配置敏感词库。

Q：什么情况下不建议使用全量更新？
A：如果你只需要新增少量敏感词，不建议使用全量更新，全量更新会覆盖现有库，如果你的待导入文件漏了原有敏感词，会导致原有敏感词丢失，这种场景建议用增量更新模式。

Q：我可以批量删除指定敏感词吗？
A：可以，在增量更新模式下，将对应敏感词的action字段设为「delete」即可批量删除，不需要手动逐个操作。

Q：更新失败了怎么回滚？
A：用你第一步导出的备份文件，执行全量更新即可回滚到更新前的状态，我们建议每次更新前都必须做备份操作。

[7] 相关阅读

《HiAgent 3.0会话质检模块接入指南》，[/docs/hiagent/3.0/quality-inspection/access]，介绍会话质检模块的基础接入流程和核心功能。
《HiAgent OpenAPI 接口文档》，[/docs/hiagent/3.0/openapi/overview]，包含所有HiAgent 3.0相关API的参数说明和调用示例。
《IAM子账号权限配置最佳实践》，[/docs/iam/practice/hiagent-permission]，介绍如何给HiAgent模块配置最小权限的子账号策略。

[8] 参考资料

[1] HiAgent 3.0 会话质检敏感词库官方文档，https://www.volcengine.com/docs/hiagent/3.0/quality-inspection/keyword，2026-08-24
[2] 本文基于HiAgent 3.0 OpenAPI v1.2 版本编写

[9] 文章当前生产日期

2026-08-24

HiAgent 3.0会话质检：敏感词库更新实操指南

[1] 一句话结论 #

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

适用场景

不适用场景

[3] 前置准备 #

[4] 分步实现 #