Docs
文档目录

内容审核

内容审核(Moderation)是 Agentbase 2.10.0 基于阿里云内容安全(Green MultiModalGuard)构建的写入链路多模态合规风控引擎。它在业务数据落库与文件落盘的关键路径上,对数据库表(Database Table)的字符串字段文本与对象存储桶(Storage Bucket)上传的图片对象(image/*)实施自动化内容安全审查,支持同步前置审核(pre)、异步后置审核(post)与长短文本混合分流审核(hybrid),并提供平台级/项目级双层凭据回退、存储侧失败关闭(Fail-Closed)清理、未发布内容读隔离以及 30 日审核调用统计与全量审计日志。

内容审核页(沿用已登记截图)

界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。

功能概述

在企业对外提供智能客服工单提交、用户社区评论或知识库图片附件上传服务(如生产样板项目 企业智能客服与知识中台 enterprise-ai-hub-210 中的工单表 customer_tickets 与多媒体存储桶 agent_multimedia_bucket)时,防范涉政、色情、暴恐、违禁及辱骂等违规内容进入生产数据库和对象存储是企业合规的刚性底线。

Agentbase Moderation 无需业务研发人员在每个接口中手动编写第三方内容安全 SDK 调用代码,直接在底层数据面网关与存储引擎上实现透明门禁:

  1. 双域精准覆盖(数据库文本 + 存储桶图片):

    • Database 文本审核:针对开启审核的数据表,在单行新增或更新时自动提取所有字符串类型字段的文本内容送审。

    • Storage 图片审核:针对开启审核的存储桶,在上传 MIME 类型为 image/* 的图片文件时自动生成时效性签名 URL 送审,并严格执行 Fail-Closed(失败关闭) 策略——一旦判定违规或审核服务异常,立即物理删除已上传图片字节。

  2. 三模审核策略与审核二期异步状态机(2.9.0 / 2.10.0):

    • pre(同步前置模式):先完成同步审核,通过(pass)后才允许落库或落盘;违规(block / review)直接拦截拒绝写入。

    • post(异步后置模式)与 hybrid(长短文本混合分流模式):写入先持久化并标记为审核中(checking),后台异步完成审核;未正式发布(published)前对非创建者严格执行读隔离,并支持违规转人工复核(quarantined)或私密扣留(private_hold)及周期任务自愈。

  3. 双层凭据优先级与模型网关解耦:支持在项目内配置企业自有的阿里云 Green AK/SK 与端点(加密保存不回显),未配置时自动整对回退使用平台级统一凭据;且与模型网关(LLM Gateway)的大模型推理凭据完全物理隔离。

核心功能视图控制台路由路径覆盖能力与配置项所需权限 / 角色边界
Moderation 首页(概览与凭据)/console/project-{region}-{project}/moderation查看近 30 天调用总量(拆分平台凭据 vs 项目凭据调用);切换凭据模式、配置阿里云 AK/SK、超时(1–10s)、日志保留天数(1–365 天)与单图大小上限(1–20 MB)查看:任意项目成员;修改项目凭据:projects.write(owner/admin/developer/editor)
Moderation 全局日志页/console/project-{region}-{project}/moderation/logs · .../logs/{log}按资源类型(表/桶)、资源 ID、审核结果(pass/blocked/review/error)与时间范围检索;查看命中风险标签(Labels)、置信度与建议动作任意项目成员可读(日志仅记录受限文件名与 ≤2000 字符文本预览,不存原始图片字节)
数据表级审核配置与日志/databases/database-{db}/table-{table}/moderation为指定数据表开启文本审核,选择模式(pre / post / hybrid)与违规转人工复核开关,查看该表专属审核日志数据库表写权限
存储桶级审核配置与日志/storage/bucket-{bucket}/moderation为指定存储桶开启图片(image)审核,查看该桶专属审核日志存储桶写权限

核心概念与架构

下图展示了数据库文本写入与存储桶图片上传在经过 Agentbase 内容审核引擎时的凭据解析顺序、同步前置(pre)门禁、存储侧 Fail-Closed 物理清理以及异步后置(post / hybrid)状态机与读隔离架构:

内容审核:流程示意,不是运行截图

流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。

查看流程图大图

1. 四种单次审核判定结果与系统动作对照表

无论底层调用阿里云 Green MultiModalGuard 返回何种详细分类,Agentbase 都会将其归一为以下四种标准判定结果,并在审核日志中完整记录命中的风险标签(Labels)、置信度(Confidence)与模型建议动作(Suggestion:pass / review / block / mask):

审核结果标识含义说明pre 同步前置模式下的数据库写入行为存储桶(Storage image/*)上传行为(Fail-Closed)
pass(通过)未检测到违规风险或置信度低于拦截阈值正常放行:数据行成功写入 OceanBase 表正常保留:图片文件完成上传并持久化至存储桶
block(拦截)明确命中高危涉政、色情、暴恐或违禁词拒绝写入:接口直接报错拦截,数据不落库删除清理:拒绝请求并立即物理删除已上传的图片文件副本
review(人工复核)审核模型判定疑似违规、建议人工复核按拦截处理:保守策略下不放行疑似违规内容(二期异步模式下进入待复核/隔离态)删除清理:按拦截处理,立即物理删除已上传图片
error(错误)凭据无效、网络超时(>设定秒数)或图片超出单图大小上限保守拦截:安全优先,审核服务异常时不放行未审写入删除清理:Fail-Closed 机制强制删除未完成审核的上传对象

2. 审核二期:异步后置(post)、混合分流(hybrid)与文档审核状态机

在平台管理员开启审核二期开关的环境中(若平台未开启二期开关,配置为 post 或 hybrid 的资源会自动安全回退为等同于 pre 的同步前置审核),数据表文本审核支持异步状态流转:

核心属性或状态值枚举值 / 默认值精确业务语义与读写可见性规则
审核模式(mode)pre · post · hybrid• pre:保存前同步检查;
• post:先落库保存,后台异步送审;
• hybrid:按平台配置的文本长度阈值自动分流——短文本留在同步路径即时返回,超长文本转入异步路径避免阻塞写入响应。
违规转人工复核开关requireManualReviewOnViolation(默认 true)• 开启(true)时:违规记录进入 quarantined(已拦截) 隔离态等待复核;
• 关闭(false)时:违规记录进入 private_hold(审核异常),作为仅创建者本人可见的私密扣留。
moderationStatus 状态流转checking → pending → published / quarantined / private_hold / action_error数据表行内直观展示中文状态徽标(审核中 / 待审核 / 已拦截 / 审核异常 / 审核失败);对于偶发网络抖动导致卡在 checking 的记录,平台内置周期巡检任务按当前配置语义自动重判自愈,无需人工干预。
未发布内容读隔离与事件延后针对非 published 状态的所有记录处于 checking、pending、quarantined、private_hold 的数据行对非创建者完全隐藏(查询列表与 total 总数同步扣减修正);唯有状态流转为 published(已发布)后才对其他授权用户可见,且 Realtime、Functions 事件与 Webhooks 也在发布通过后才补发。

角色、入口与关联关系

1. 资源级配置状态语义与覆盖范围边界

在为具体数据表或存储桶开启内容审核时,资源配置对象(/v1/moderation-configs)具有以下三种运行状态:

覆盖范围明确边界:

2. 内容审核凭据与模型 Provider 凭据的严格区分

在企业配置过程中,切勿将 Moderation(内容审核凭据) 与 Models(LLM Gateway 模型推理凭据) 混淆。两者对接的云服务、鉴权协议与配置入口完全独立:

对比维度内容审核凭据(Moderation Credentials)模型 Provider 凭据(LLM Gateway Providers)
控制台配置入口项目侧边栏 Moderation(内容审核) 首页配置表单项目侧边栏 模型(/llm-gateway) → Providers
对接的目标云服务阿里云内容安全(Green MultiModalGuard)大模型推理服务(如阿里云百炼 DashScope dashscope-prod、OpenAI、Anthropic 等)
必填凭据字段阿里云内容安全 HTTPS 审核端点(Endpoint) + AccessKey ID / AccessKey Secret(AK/SK 对)模型推理 Base URL + API Key(如 <DASHSCOPE_API_KEY>) + 模型能力目录
隔离原则专门用于数据表写路径与存储桶图片上传风控,不可用于大模型对话或向量化专门用于 Chat、Embedding、Rerank、Vision 推理,不可用于内容审核

功能详解与操作指南

1. 配置项目级内容审核凭据与高级风控参数

  1. 登录 Console 并进入项目 企业智能客服与知识中台(enterprise-ai-hub-210),在左侧边栏点击 Moderation(内容审核)(路径 /console/project-default-enterprise-ai-hub-210/moderation,如图 1 所示)。

  2. 审阅顶部近 30 天审核用量卡片:

    • 页面上方展示三项关键统计:近 30 天审核调用总量、平台凭据调用量与项目自定义凭据调用量,并标注当前生效的凭据来源徽标。

  3. 选择凭据模式并配置参数(底层对应 PATCH /v1/projects/{projectId}/moderation):

    • 在配置表单中,可在 「使用平台凭据(Use platform credentials)」 与 「使用项目自定义凭据(Use custom project credentials)」 之间切换。

    • 整对解析与回退规则:当配置了项目自定义凭据时,优先使用项目自有凭据;当项目未配置自有凭据(或主动清除重设)时,系统以整对平台凭据自动回退,绝不会将项目的 AK 与平台的 Endpoint 进行跨层级混拼。

    • 若选择使用项目自定义凭据,请按表填写以下字段:

配置表单字段取值范围 / 约束默认值与生产配置建议
Endpoint(审核服务端点)合法的 https:// 阿里云内容安全接入地址例如 https://green-cip.cn-shanghai.aliyuncs.com(受平台 SSRF 守卫校验,禁止内网地址)。
AccessKey ID & Secret阿里云具备 Green 内容安全权限的 RAM 子账号 AK/SK保存后服务端加密存储、界面单向掩码不回显;支持随时点击清除后重新输入新密钥对。
Timeout(审核超时时间)1 ~ 10 秒(整数)建议设为 3 ~ 5 秒,防止外部网络抖动长时间阻塞数据库写入或图片上传。
Log retention(审核日志保留天数)1 ~ 365 天(整数)建议生产环境设为 90 或 180 天,满足合规审计回溯要求。
Max image size(单图大小上限)1 ~ 20 MB(整数)设定允许送审的单张图片最大体积(如 10 MB);超出该上限的图片上传将在 Fail-Closed 机制下被直接拦截并清理。

2. 为业务数据表与存储桶逐资源开启审核开关

完成项目级凭据确认后,需前往具体需要保护的数据表(如客户工单表 customer_tickets)或存储桶(如 agent_multimedia_bucket)开启资源级审核配置(底层对应 /v1/moderation-configs 系列端点):

A. 开启数据表(Database Table)文本审核

  1. 点击左侧边栏 Databases → 进入数据库 enterprise_biz_db → 点击数据表 customer_tickets → 切换到表详情顶部的 Moderation 页签(路径 .../table-customer_tickets/moderation)。

  2. 打开该表的文本审核开关(内容类型固定为 text)。

  3. 选择审核模式:

    • 默认选择 pre(保存前同步检查):任何包含违规词汇的工单提交都会在写入时被直接拦截。

    • 若平台已开启审核二期能力,可按需选择 post(异步后置审核) 或 hybrid(长短文本混合分流),并勾选是否开启 违规时转人工复核(requireManualReviewOnViolation)。

  4. 保存后,可在数据表的 Rows(数据行) 列表中直观看到每条记录的审核状态徽标,并在表的 Moderation 页签下查看仅属于该表的审核拦截日志。

B. 开启存储桶(Storage Bucket)图片审核

  1. 点击左侧边栏 Storage → 点击进入目标存储桶(如 agent_multimedia_bucket) → 切换到桶详情顶部的 Moderation 页签(路径 /storage/bucket-agent_multimedia_bucket/moderation)。

  2. 打开该存储桶的图片审核开关(内容类型固定为 image)并保存。

  3. 验证 Fail-Closed 行为:此后任何向该存储桶上传的 image/* 图片都会经由短时效签名 URL 送交 MultiModalGuard 检测;若图片包含违规内容、体积超过设定的 Max image size(1–20 MB)或审核调用超时,系统不仅返回上传失败错误,还会自动删除已落地的文件对象,确保存储桶内零违规残留。

3. 查询与审计内容审核日志(Moderation Logs)

当终端用户反馈“工单提交被拒”或“图片上传失败”时,管理员可通过全局或资源级审核日志在 1 分钟内定位拦截原因:

  1. 进入项目侧边栏 Moderation → Logs 页签(路径 /console/project-default-enterprise-ai-hub-210/moderation/logs,对应接口 /v1/moderation-logs)。

  2. 使用顶部组合筛选栏缩小范围:

    • 资源类型(Resource type):选择数据表(Table)或存储桶(Bucket)。

    • 资源 ID(Resource ID):输入如 customer_tickets 或 agent_multimedia_bucket。

    • 审核结果(Result):筛选 pass(通过)、blocked(拦截)、review(复核拦截)或 error(调用异常)。

    • 时间范围(Time range):框定发生拦截的时间段。

  3. 点开任意一条拦截记录进入日志详情页(/moderation/logs/{log}),核对以下关键取证字段:

    • 基础上下文:时间戳、所属资源类型与 ID、内容类型(text / image)、底层 Provider 与阿里云请求 ID(Request ID)。

    • 隐私安全内容预览:文本审核展示不超过 2000 字符的截断文本预览;图片审核仅记录受限的文件名预览,绝不在日志中存储原始图片字节、Base64 编码或完整内部对象路径,严格保护用户数据隐私。

    • 判定依据:命中的风险 Labels(标签)、Confidence(置信度分值)、Suggestion(模型建议动作:pass / review / block / mask) 以及具体的错误信息。

常见问题与排障

Q1:为什么在存储桶开启图片审核后,上传 PDF 文档或 MP4 视频没有触发审核记录,而上传一张 15 MB 的高清 PNG 图片却直接报错且桶里找不到文件?

原因与排查步骤:

  1. PDF / 视频未触发审核:Agentbase Storage 内容审核的作用对象严格限定为 MIME 类型匹配 image/* 的图片文件;PDF 文档、Markdown 文件、音频与视频不在图片审核覆盖范围内,会按普通文件流程上传。

  2. 15 MB 图片上传报错且文件消失:检查项目 Moderation 配置表单中的 单图大小上限(Max image size,范围 1–20 MB)。若当前上限设为默认的 10 MB,上传 15 MB 图片会触发超限判定;根据存储侧 Fail-Closed(失败关闭) 语义,凡是被拦截、超限或审核异常的图片,系统都会立即将已上传的对象物理清除,不会在桶内保留未审副本。只需将单图大小上限调高至 20 MB(或压缩图片体积)后重新上传即可。

Q2:开启了审核二期的 post(异步后置)模式后,为什么用户 A 刚提交的评论自己刷新能看到,但用户 B 却看不到,而且也没触发 Webhook?

原因与排查步骤: 这是审核二期未发布内容读隔离(Read Isolation)的预期安全机制:

Q3:我在“模型(LLM Gateway)”页面已经配好了阿里云 DashScope 的 API Key,为什么开启 Moderation 内容审核时还是报错凭据无效?

原因与排查步骤: 内容审核凭据与模型网关凭据是两套完全独立、互不复用的配置:

相关文档