> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aioagi.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Moderation API

> 通过 AIOAGI 的 OpenAI 兼容接口构建文本审核、用户输入过滤和安全分层。

Moderation API 用于识别文本中的潜在风险内容。你可以用它过滤用户输入、拦截不适合发布的内容、为聊天机器人增加安全层，并把高风险样本交给人工复核。

<Info>
  当前站内 OpenAPI 参考未单列 `POST /moderations`。如果控制台或开发者指南明确显示你的 API Key 已开通 Moderation 兼容端点，可按对应说明调用。否则，建议使用 `POST /chat/completions` 构建审核分类工作流。
</Info>

## 功能概述

文本审核适合以下场景：

* 用户输入过滤：在内容进入业务系统前先做风险判断
* 发布前审核：对评论、帖子、简介和私信进行自动检查
* 聊天机器人安全层：在请求模型前过滤高风险输入，在回复用户前检查模型输出
* 合规检查：按平台规则识别需要拦截、降级或人工复核的内容
* 风险日志：记录风险类别、分数、处理动作和请求来源

常用基础地址：

```text theme={null}
https://api.aiearth.dev/v1
https://api.aiearth.vip/v1
```

推荐工作流：

```text theme={null}
用户输入 -> 审核分类 -> 通过后进入业务逻辑或模型调用 -> 输出审核 -> 返回用户
```

## 快速开始

下面示例使用 `POST /chat/completions` 生成结构化审核结果。模型 ID 仅用于演示，请以控制台可用模型为准。

```python theme={null}
import json
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AIO_API_KEY"],
    base_url=os.environ.get("AIO_BASE_URL", "https://api.aiearth.dev/v1"),
)

moderation_prompt = """
你是内容安全审核器。请判断用户文本是否存在风险。
只输出 JSON，不要输出解释。
字段：
- flagged: boolean，是否需要拦截或人工复核
- categories: object，包含 hate, harassment, self_harm, sexual, violence, illegal, privacy
- scores: object，各类别 0 到 1 的风险分数
- action: string，取值 allow, review, block
- reason: string，简短说明
"""

text = "这是一段需要审核的用户输入。"

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": moderation_prompt},
        {"role": "user", "content": text},
    ],
    temperature=0,
)

result = json.loads(response.choices[0].message.content)
print(result)
```

## 批量审核

对多条文本做审核时，可以逐条调用，也可以把多条文本组织成数组后让模型返回数组结果。生产环境更建议分批处理，便于失败重试和日志记录。

```python theme={null}
texts = [
    "第一段待审核文本。",
    "第二段待审核文本。",
    "第三段待审核文本。",
]

batch_prompt = """
你是内容安全审核器。请审核用户提供的 JSON 数组。
返回 JSON 数组。每个元素包含 index, flagged, categories, scores, action, reason。
action 只能是 allow, review, block。
"""

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": batch_prompt},
        {"role": "user", "content": json.dumps(texts, ensure_ascii=False)},
    ],
    temperature=0,
)

results = json.loads(response.choices[0].message.content)
for item in results:
    print(item["index"], item["action"], item["reason"])
```

## 检测类别

你可以按业务规则定义审核类别。常见类别包括：

<Table>
  <thead>
    <tr>
      <th>类别</th>
      <th>说明</th>
      <th>建议动作</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>hate</code></td>
      <td>针对群体或个人的仇恨、歧视或贬损表达。</td>
      <td>高分拦截，中分复核。</td>
    </tr>

    <tr>
      <td><code>harassment</code></td>
      <td>骚扰、辱骂、威胁或恶意攻击。</td>
      <td>按社区规则拦截或限流。</td>
    </tr>

    <tr>
      <td><code>self\_harm</code></td>
      <td>自我伤害、自杀意图或相关指导。</td>
      <td>优先人工复核，并提供安全引导。</td>
    </tr>

    <tr>
      <td><code>sexual</code></td>
      <td>性相关、露骨或不适宜公开展示的内容。</td>
      <td>按年龄分级和场景处理。</td>
    </tr>

    <tr>
      <td><code>violence</code></td>
      <td>暴力、血腥、伤害威胁或鼓励暴力。</td>
      <td>高分拦截，中分复核。</td>
    </tr>

    <tr>
      <td><code>illegal</code></td>
      <td>违法活动、规避监管或明确的犯罪协助。</td>
      <td>拦截并记录风险日志。</td>
    </tr>

    <tr>
      <td><code>privacy</code></td>
      <td>泄露个人信息、密钥、账号、地址或敏感凭据。</td>
      <td>脱敏、拦截或人工复核。</td>
    </tr>
  </tbody>
</Table>

<Warning>
  类别和阈值应按你的业务、地区法规和平台规则设置。不要把模型判断当成唯一合规依据。
</Warning>

## 响应结构

建议在应用层统一使用结构化审核结果，便于拦截、审计和人工复核。

```json theme={null}
{
  "flagged": true,
  "categories": {
    "hate": false,
    "harassment": true,
    "self_harm": false,
    "sexual": false,
    "violence": false,
    "illegal": false,
    "privacy": false
  },
  "scores": {
    "hate": 0.02,
    "harassment": 0.86,
    "self_harm": 0.01,
    "sexual": 0.0,
    "violence": 0.12,
    "illegal": 0.0,
    "privacy": 0.0
  },
  "action": "review",
  "reason": "包含较强攻击性表达，建议人工复核。"
}
```

## 兼容 `/moderations` 端点

如果你的控制台或开发者指南明确显示已开通 OpenAI 兼容 Moderation 端点，可以使用 AIOAGI 基础地址调用：

```text theme={null}
POST https://api.aiearth.dev/v1/moderations
```

示例：

```python theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.aiearth.dev/v1",
)

response = client.moderations.create(
    model="omni-moderation-latest",
    input="这是一段需要审核的文本内容。",
)

result = response.results[0]
print(result.flagged)
print(result.categories)
print(result.category_scores)
```

<Warning>
  是否支持 `/moderations`、默认模型、类别字段和计费方式请以控制台和开发者指南为准。若接口不可用，请使用上文的 `POST /chat/completions` 审核分类方案。
</Warning>

## 实用示例

### 用户输入过滤

在调用文本生成 API 前先审核用户输入。

```python theme={null}
def moderate_text(text):
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {"role": "system", "content": moderation_prompt},
            {"role": "user", "content": text},
        ],
        temperature=0,
    )
    return json.loads(response.choices[0].message.content)

def handle_user_message(text):
    result = moderate_text(text)
    if result["action"] == "block":
        return "这条内容无法处理，请修改后再提交。"
    if result["action"] == "review":
        return "这条内容需要人工复核。"
    return "审核通过，可以进入后续处理。"
```

### 聊天机器人安全层

对输入和输出分别审核。

```python theme={null}
def safe_chat(user_text):
    input_result = moderate_text(user_text)
    if input_result["flagged"]:
        return "抱歉，这个请求暂时无法处理。"

    answer = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": user_text}],
    ).choices[0].message.content

    output_result = moderate_text(answer)
    if output_result["flagged"]:
        return "抱歉，生成结果需要复核，暂时无法展示。"

    return answer
```

### 自定义阈值

不同类别可以设置不同阈值。

```python theme={null}
THRESHOLDS = {
    "hate": 0.7,
    "harassment": 0.75,
    "self_harm": 0.4,
    "sexual": 0.8,
    "violence": 0.7,
    "illegal": 0.5,
    "privacy": 0.35,
}

def decide_action(scores):
    high_risk = [key for key, value in scores.items() if value >= THRESHOLDS[key]]
    if high_risk:
        return "block"
    if any(value >= 0.3 for value in scores.values()):
        return "review"
    return "allow"
```

## 最佳实践

### 多层防护

* 用户输入进入业务逻辑前审核一次
* 模型输出返回用户前审核一次
* 高风险类别设置更低阈值
* 对高价值用户操作增加人工复核
* 保留风险日志，用于追踪误判和优化规则

### 记录违规日志

记录必要字段，避免保存不必要的敏感信息。

```json theme={null}
{
  "request_id": "mod-20260515-001",
  "user_id": "user_123",
  "action": "review",
  "categories": ["harassment"],
  "scores": {
    "harassment": 0.86
  },
  "created_at": "2026-05-15T08:00:00+08:00"
}
```

### 优雅处理

给用户明确、简短的提示，不要展示内部分类、分数或安全策略细节。

```text theme={null}
这条内容暂时无法发布，请修改后再提交。
```

## 注意事项

* 审核模型可能出现误判和漏判，关键场景需要人工复核
* 不同业务对同一类别的阈值可能不同
* 不要把 API Key 暴露在前端、移动端包体或公开仓库中
* 日志中应避免记录完整敏感文本，必要时先脱敏
* 法律、医疗、金融等高风险场景需要结合专业合规流程

## 常见问题

<AccordionGroup>
  <Accordion title="AIOAGI 是否一定支持 `/moderations`？" icon="circle-question">
    请以控制台和开发者指南为准。当前站内 OpenAPI 未单列该端点，所以本文默认提供基于 `POST /chat/completions` 的审核分类方案。
  </Accordion>

  <Accordion title="审核是否会消耗额度？" icon="coins">
    如果使用 `POST /chat/completions` 构建审核分类，会按所选模型计费。若使用专用 `/moderations` 端点，请以控制台和开发者指南的计费说明为准。
  </Accordion>

  <Accordion title="如何减少误判？" icon="sliders">
    可以调低模型输出随机性、固定 JSON 结构、按类别设置阈值、引入业务规则，并把中风险结果交给人工复核。
  </Accordion>

  <Accordion title="可以审核图片或音频吗？" icon="image">
    本页聚焦文本审核。多模态审核能力是否可用，请以控制台和开发者指南显示的模型和接口说明为准。
  </Accordion>
</AccordionGroup>

## 相关文档

<CardGroup cols={2}>
  <Card title="文本生成 API" icon="messages">
    可在导航中的 **文本 API** 分组查看文本生成指南，并使用 `POST /chat/completions` 构建审核分类器。
  </Card>

  <Card title="Embedding API" icon="chart-scatter">
    可在导航中的 **文本 API** 分组查看 Embedding 指南，并为语义搜索、RAG 和文本分类生成向量。
  </Card>

  <Card title="快速开始" icon="rocket" href="/quickstart">
    完成 API Key、端点和第一次模型调用。
  </Card>

  <Card title="开发者指南" icon="book-open-cover" href="https://aiearthdev.apifox.cn/">
    核对当前模型、端点和参数支持情况。
  </Card>
</CardGroup>