AgentbaseDocs
文档目录

内容审核

内容审核(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 调用代码,直接在底层数据面网关与存储引擎上实现透明门禁:

核心功能视图控制台路由路径覆盖能力与配置项所需权限 / 角色边界
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)状态机与读隔离架构:

flowchart TB
    subgraph CredResolution["第一步:审核凭据整对解析 (Credential Resolution)"]
        ProjCred["项目自定义凭据 (优先)<br/>阿里云 Green HTTPS 端点 + AK/SK<br/>+ 超时(1-10s) / 日志保留(1-365d) / 单图上限(1-20MB)"]
        PlatCred["平台级默认凭据 (回退)<br/>平台管理员统一配置 (整对回退, 绝不混拼字段)"]
        ProjCred -- "未配置自有凭据时整对回退" --> PlatCred
    end

    subgraph SyncPrePath["模式 A:同步前置审核 (mode = pre,默认写前门禁) / Storage 图片上传"]
        WriteReq["收到表文本写入 或 Bucket image/* 上传"] --> CallGreen["调用阿里云 Green MultiModalGuard"]
        CallGreen --> Verdict{"审核判定结果?"}
        Verdict -- "pass (通过)" --> Persist["允许落库 / 保留存储图片对象"]
        Verdict -- "block (拦截) / review (人工复核) / error (异常或超限)" --> Reject["Database: 直接拒绝写入请求<br/>Storage: Fail-Closed 立即物理删除已上传图片对象"]
    end

    subgraph AsyncPostPath["模式 B:审核二期异步状态机 (mode = post / hybrid,需平台开启二期开关)"]
        AsyncWrite["写入先持久化 -> moderationStatus = checking (审核中)<br/>(hybrid 模式下短文本走同步 pre, 超长文本走异步)"]
        AsyncWrite --> ReadIso["读隔离生效:<br/>未发布前对非创建者隐藏 + 修正列表总数 + 延后触发事件"]
        ReadIso --> AsyncJudge{"异步审核结果?"}
        AsyncJudge -- "通过" --> Published["moderationStatus = published (已发布)<br/>对全体授权用户可见 + 补发 Realtime/Functions/Webhook 事件"]
        AsyncJudge -- "违规 (requireManualReviewOnViolation=true)" --> Quarantined["moderationStatus = quarantined (已拦截隔离态)<br/>或 pending (待人工复核)"]
        AsyncJudge -- "违规 (requireManualReviewOnViolation=false)" --> PrivateHold["moderationStatus = private_hold (审核异常)<br/>仅创建者本人可见的私密扣留"]
        AsyncJudge -- "调用失败 / 卡在 checking" --> SelfHeal["action_error -> 平台周期任务按当前配置语义自动重判自愈"]
    end

    CredResolution --> SyncPrePath
    CredResolution --> AsyncPostPath

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:保存前同步检查;<br/>• post:先落库保存,后台异步送审;<br/>• hybrid:按平台配置的文本长度阈值自动分流——短文本留在同步路径即时返回,超长文本转入异步路径避免阻塞写入响应。
违规转人工复核开关requireManualReviewOnViolation(默认 true)• 开启(true)时:违规记录进入 **quarantined(已拦截)** 隔离态等待复核;<br/>• 关闭(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. 配置项目级内容审核凭据与高级风控参数

配置表单字段取值范围 / 约束默认值与生产配置建议
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)文本审核

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

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

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

常见问题与排障

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

原因与排查步骤:

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

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

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

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

相关文档