大模型应用防火墙
大模型应用防火墙
文档指南
请输入
- 文档首页
大模型应用防火墙常见问题大模型应用防火墙常见问题
复制全文
下载 pdf大模型应用防火墙常见问题
文档反馈
问问助手本文列举您在使用大模型应用防火墙过程中可能会遇到的问题及对应的解决方案。
计费相关
如何选择计费模式？
如果您的业务使用量相对稳定，希望成本固定可控，我们推荐您选择包年包月模式；如果您的业务尚处在起步阶段，使用量波动较大，或者您希望先体验产品，我们推荐您选择按量付费模式。
文本检测和代答的计费次数如何计算？
文本内容按照 token 数量折算计费次数：
- 不超过 1,000 个 token，计为 1 次。
- 超过 1,000 个 token，每增加 1,000 个 token 计为 1 次，不足 1,000 个 token 的部分向上取整。
例如：
- 800 个 token 计为 1 次。
- 1,200 个 token 计为 2 次。
检测或代答内容对应的 token 是什么？
您可以将 token 理解为大模型处理语言时的基本单位，一个 token 可能对应一个汉字、一个词、一个词的一部分或一个标点符号，实际 token 数量取决于大模型的分词策略。
图片和文档如何计算检测用量？
- 图片按照张数计算，每张图片计为 1 次。
- 文档本身不单独计费。系统解析文档后，分别计算其中的文本 token 数量和图片张数。
如何查看每条送检或代答内容对应的计费次数？
支持多模态混合检测吗？
超过 QPS 或 QPM 上限后会发生什么？
当实际请求速率超过已购套餐或按量付费服务规格时，超出部分不执行安全检测，并直接放行。建议根据业务峰值预留容量，并通过监控及时调整服务规格。
权限
如何授予子账号权限？
为保障主账号的安全性并实现最小权限管理，我们强烈建议您使用子账号（IAM 用户）来操作大模型应用防火墙。主账号管理员可以为子账号授予精确的权限，如控制台的只读权限、完整的管理权限或仅允许通过 SDK 调用服务。
具体操作步骤如下：
- 登录火山引擎 IAM 控制台。
- 在左侧导航栏中，选择用户管理 > 用户，然后单击新建用户。
- 选择通过用户名创建，然后填写用户信息，并根据需要选择至少一种访问方式：
- 编程访问：为用户分配 Access Key，允许用户通过 API 访问服务（调用 SDK 时需要）。
- 控制台访问：为用户分配密码，允许用户通过控制台访问服务（控制台操作时需要）。
-
- 单击下一步，为该用户授予权限。在搜索框中，查找并勾选您需要的防火墙相关策略。
- 只读权限：LLMShieldReadOnlyAccess，仅允许用户登录控制台查看，不允许用户创建或修改相关资源。
- 可读写权限：LLMShieldFullAccess，允许用户登录控制台查看，并且允许用户管理资源（例如新增、修改策略等）。
- SDK 调用权限：LLMShieldProtectSdkAccess，允许用户使用 AK/SK 调用 SDK 访问服务。
- 详细的权限策略说明请参考大模型应用防火墙服务相关权限有哪些？
-
- 确认权限配置无误后，单击下一步直至创建完成。
- 请妥善保存生成的密码和 Access Key 信息。
大模型应用防火墙服务相关权限有哪些？
注意
- 如果您需要通过子账号调用大模型应用防火墙 SDK，遵循权限最小化原则，建议为该子账号至少授予以下权限策略：AccessKeySelfManageAccess 和 LLMShieldProtectSdkAccess。
- 由于功能升级，如果您的账号购买过旧版本实例，现需购买新版本实例，请联系技术支持申请加入白名单；加白后需额外配置WAFFullAccess权限策略，以确保相关功能可以正常使用。
如何获取 AK 和 SK？
- 访问火山引擎 API访问密钥 页面。
- 在密钥列表查看已有 Access Key ID （AK）和 Secret Access Key（SK），或者单击创建 Access Key 创建新的密钥。
-
如何判断我的控制台或实例是新版还是旧版？
您可以通过以下方式判断当前控制台或实例是否具备新版功能：
- 控制台提示信息
- 旧版本提示信息：
-
- 新版本提示信息：
-
- 实例信息
- 旧版本实例信息：
-
- 新版本实例信息：
-
资产管理
服务没有部署在火山引擎上，可以使用大模型应用防火墙服务吗？
如何获取大模型应用防火墙的回源 IP 地址段？
如何验证 CNAME 转发是否生效？
- 修改本地 host 文件。
- 在本地 host 文件最后一行添加大模型应用防火墙 IP 地址和防护域名，使本地对防护源站的请求经过 CNAME 地址。
-
- 验证修改是否成功。
- 使用终端命令 ping 防护域名，如果解析 IP 为 hosts 文件中绑定的大模型应用防火墙 IP，则修改成功。
-
- 验证接入配置是否生效。
- 验证网站接入配置是否生效，在本地直接访问被防护的域名，如果正常访问则说明配置成功。
需要验证 CNAME 接入是否生效，如何获取大模型应用防火墙的 IP 地址？
- 登录大模型应用防火墙控制台。
- 在顶栏选择实例所属地域。
- 在左侧导航选择资产管理。
- 选择对应资产。
- 单击高级筛选。
- 设置接入方式为流量接入。
- 单击资产名称。
-
- 在基本信息页面，获取 CNAME 值。
-
- 运行本地终端命令程序，运行ping <复制的 CNAME 值>。
- 下图以 Mac OS 为例说明。
- ①：复制的 CNAME 值。
- ②：大模型应用防火墙 IP 地址。
-
攻击详情
攻击详情列表中命中的“系统-禁止 APIKEY 外的访问”规则是什么？
- 原因：“系统-禁止 APIKEY 外的访问”规则是系统内置的黑名单规则，该规则会拦截所有非 APIKEY 方式的访问请求。因此，如果您的业务通过火山引擎方舟平台接入，且使用了 AK/SK 方式调用，就会命中该黑名单规则，从而导致请求被拦截。
- 解决方案：建议获取 APIKEY 后，再进行调用。获取方式参考如何获取 APIKEY？
如何获取 APIKEY？
- 登录大模型应用防火墙控制台。
- 在顶栏选择实例所属地域。
- 在左侧导航选择资产管理。
- 单击高级筛选，选择接入方式为方舟平台与机器学习平台。
-
- 在列表中单击对应防护网站，查看网站基本信息。
- 获取方舟应用 API Key，将其填入到方舟 SDK 初始化配置中。
-
防护策略
开启拦截后会影响到正常业务吗？
大模型应用防火墙对正常业务请求不会触发拦截动作，如果担心开启防护会影响正常业务，可以选择先开启“观察”模式，该模式下会记录所有命中检测规则的攻击日志，并上报到日志管理页面。您可以在该页面确认“观察”类型的事件日志，如果持续一段时间内都没有出现误报，则可以将“观察”模式切换为“拦截”模式，开启拦截后，所有命中检测规则的攻击流量都会被拦截。
防护策略开关关闭后，大模型应用防火墙还会记录日志吗？
如果所有防护功能都没有开启，则仅进行流量转发，不会拦截或者记录上报攻击行为，因此不会有日志生成。
配置访问管控策略时，为什么选不到我需要的域名？
访问控制策略对通过 SDK 方式接入的域名暂不生效。因此您在配置访问管控策略时，无法选择对应域名。
为什么配置了自定义词库却没生效？
通过 SDK 方式接入的防护域名，如何配置防护策略？
SDK 调用返回结果的 Action 是什么含义？
通过 SDK 检查提示词或响应内容是否合规时，返回的 Action 指请求命中的执行动作，其说明如下：
支持多模态混合检测吗？
自定义防护
如何替换已有模型能力？
大模型应用防火墙支持在不改变现有规则配置（例如规则关联的资产和检测分类）的前提下，平滑地替换当前模型。当您需要更新或替换样本内容时，可以创建一个新模型，将其关联至原有的检测分类，并使用测试资产进行灰度测试。待测试结果符合预期后，直接发布该模型，即可完成切换。主要操作步骤如下：
- 创建：创建一个新的防护模型。
- 上传新的样本集。
- 将原有检测分类关联至新样本内容。
- 部署：待模型自动训练完成后，进行部署操作。
- 测试：待部署完成后，使用测试资产进行灰度测试，校验新模型的防护效果。
- 发布：确认符合预期后，发布新模型。
- 下线原模型：将原有模型取消发布，确保您的防护资产由最新模型防护。
如何扩充现有模型能力
如果您希望在现有检测分类基础上，增加新的检测能力（例如在违规荐股分类的基础上，增加承诺收益分类），则可以参考创建流程，准备相关样本数据并部署一个新的模型。
如何进行灰度测试？
在将自定义模型能力全面应用到生产环境之前，进行小范围的灰度测试至关重要。灰度测试的推荐步骤如下：
- 创建测试资产：创建一个测试资产用于验证模型检测和规则配置效果。
- 启用观察模式：在自定义模型发布前，为测试资产关联测试属性的检测分类，并将执行动作配置为“观察”。
- 收集与分析日志：运行一段时间（例如 1-3 天），在“攻击日志”中仔细查看所有命中的请求。重点关注那些您认为是正常业务的“误报”日志。
- 策略调优：
- 如果存在误报，分析原因，可能是因为样本内容过于宽泛，或者需要更详尽的白样本。
- 如果存在漏报（已知的攻击未被识别），请先确认规则开关是否都为启用状态，再进一步确认黑样本内容是否足够充分。
-
- 切换至拦截/安全代答模式：当误报率降低到可接受的水平后，切换执行动作，并逐步扩大策略生效的资产范围，直至全量覆盖。
自定义词库升级
如果您使用的自定义词库为旧版本（页面左上方会出现升级提示信息），可以参考以下内容了解升级相关问题。
不升级会有什么影响吗？
旧版词库已经不支持继续编辑，会影响对自定义词库的高效管控及使用体验。建议尽快升级至新版词库。
新旧版本词库的差异是什么？
旧版词库中，正向词库和负向词库全局生效；而新版词库具备更丰富的匹配方式（支持正则匹配）和更精细灵活的生效范围（支持按资产维度生效）。 以下是两者的主要区别：
怎么升级？升级后旧词库怎么处理？
升级的具体操作路径如下，我们会保障升级过程中的平滑迁移，确保您的自定义词库功能不受影响。升级完成后，您的旧版词库将被继续保留，但不支持编辑。
- 在自定义词库页面左上角，单击升级词库。
-
- 将正负向词库分别映射到不同的自定义检测分类上。
说明
如无自定义检测分类，您可以单击新建分类直接创建。
-
- 确认后，单击升级词库。
- 旧版词库升级为新词库后，系统会自动创建自定义词库和自定义规则：
- 词库变化：按照原词库属性和开关状态生成新的自定义词库。例如原有 4 个正向词库 A、B、C、D，其中 A、B 为开启状态，C、D 为关闭状态，则词库 A 和 B 自动聚合为新词库 E，词库 C 和 D 自动聚合为新词库 F。负向词库同理。
- 规则变化：系统会根据旧词库映射的检测分类自动创建针对不同资产生效的自定义检测规则，并通过规则的执行动作来决定命中该词库的内容将被放行（旧版正向词库）还是拦截（旧版负向词库）。
-
- 确认自定义规则的启用状态。
注意
自定义检测规则的全局开关和对应的规则都为开启状态时，自定义规则才能生效。
-
新增资产如何使用自定义词库？
当您完成词库切换后，其内容将不再针对全局资产生效。因此，如果您有新增资产需要匹配自定义词库内容，请为资产创建一条新的自定义检测规则并关联词库对应的自定义检测分类。
为什么自定义词库升级之后新的规则没有生效？
如果您原词库关联的自定义规则为关闭状态，升级之后，对应规则仍保持关闭。请检查升级后的自定义规则启用状态。
注意
自定义检测规则的全局开关和对应的规则都为开启状态时，自定义规则才能生效。
SDK 报错排查
Windows 系统中，安装 Python SDK 出现报错“Failed building wheel for volcengine-python-sdk”。
- 原因：Windows 系统有最长路径限制，导致安装过程中出现该问题。
- 解决方案：
- 按下Win+R，输入regedit打开注册表编辑器。
- 设置\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem 路径下的变量LongPathsEnabled为1即可。
调用 SDK 时出现报错“Service is not configure”。
- 原因：找不到账号配置的相关策略，导致无法调用 SDK 服务。
- 解决方案：确保已经在大模型应用防火墙控制台添加了相关防护域名信息。接入操作详情请参见资产接入方式说明。
业务通过火山引擎方舟平台接入，调用方舟 SDK 时出现 404 报错。
- 报错示例：
-
- 原因：方舟 SDK 接入后，初始化的 base_url 路由配置错误，导致方舟的访问请求无法正常路由至大模型应用防火墙。例如使用https://<大模型应用防火墙接入点域名>/api/v3/chat/completions，而正确的路径为https://<大模型应用防火墙接入点域名>/api/v3/。
- 解决方案：修改方舟 SDK 的 base_url 设置，如下图所示。
-
最近更新时间：2026.07.29 15:30:42
这个页面对您有帮助吗？
有用
有用
无用
无用