> For the complete documentation index, see [llms.txt](https://docs.ggwp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ggwp.com/chinese-simplified/api-wen-dang-liao-tian/biao-zhun-tao-can/cong-liao-tian-api-v2-qian-yi-dao-v3.md).

# 从聊天 API v2 迁移到 v3

Chat API v3 是针对新集成当前推荐的版本。现有使用 v2 的集成可以继续使用旧版端点，但我们建议迁移到 v3，以使用最新的类别分类法、严重程度模型和响应结构。

### 端点变更

将请求 URL 从 v2 端点更新为 v3 端点。

| 版本     | 端点                      |
| ------ | ----------------------- |
| v2 旧版  | `POST /chat/v2/message` |
| v3 当前版 | `POST /chat/v3/message` |

基础 URL 保持不变：

```
https://api.ggwp.com
```

### 请求体兼容性

核心请求体没有变化。你可以继续发送相同的必填字段：

```json
{
  "session_id": "match_7765",
  "message": "到处都是他妈的弱智",
  "user_id": "user989"
}
```

以下可选字段也仍受支持：

* `username`
* `timestamp`
* `language`
* `message_index`
* `message_url`
* `metadata`

### 配置变更

如果你通过以下方式传递按请求配置： `x-api-config` 头，请将配置键更新为 v3 的类别名称。

| v2 配置键          | v3 配置键                 |
| --------------- | ---------------------- |
| `identity_hate` | `identity_harm`        |
| `profanity`     | `offensive_language`   |
| `link_sharing`  | `links`                |
| `self_harm`     | `self_harm_incitement` |
| `age_concern`   | `age_disclosure`       |

v3 还引入了其他类别，包括：

* `extremism`
* `gameplay_criticism`
* `real_threat`
* `sexual_harassment`
* `sexual_violence`

在 v3 中，大多数类别支持相同的敏感度等级：

```
关闭、低、中、高
```

敏感度决定会屏蔽哪些严重程度级别：

<table><thead><tr><th width="202.21875">敏感度</th><th>行为</th></tr></thead><tbody><tr><td><code>关闭</code></td><td>不过滤该类别</td></tr><tr><td><code>低</code></td><td>仅过滤高严重程度内容</td></tr><tr><td><code>中</code></td><td>过滤中和高严重程度内容</td></tr><tr><td><code>高</code></td><td>过滤低、中和高严重程度内容</td></tr></tbody></table>

> 注：v3 在各类别之间更一致地使用基于严重程度的敏感度。某些 v2 类别之前使用 `开启` / `关闭`，例如 `drugs`, `spam`, `scam`，以及 `solicitation`，现在使用 `关闭`, `低`, `中`，或 `高`.

### 默认配置变更

如果你不传递以下 `x-api-config` 头，或者如果你的账户未配置自定义的入驻时设置，v3 可能会应用与 v2 不同的默认过滤行为。

在 v2 中，某些类别默认被禁用或设置为较低敏感度，包括：

```json
{
  "solicitation": "关闭",
  "scam": "关闭",
  "age_concern": "关闭",
  "minor_safety": "低",
  "pii": "中"
}
```

在这些文档中显示的 v3 默认配置将所有受支持类别设置为 `高` 敏感度：

```json
{
  "age_disclosure": "高",
  "drugs": "高",
  "extremism": "高",
  "gameplay_criticism": "高",
  "identity_harm": "高",
  "links": "高",
  "minor_safety": "高",
  "offensive_language": "高",
  "pii": "高",
  "real_threat": "高",
  "scam": "高",
  "self_harm_incitement": "高",
  "sexual_content": "高",
  "sexual_harassment": "高",
  "sexual_violence": "高",
  "solicitation": "高",
  "spam": "高",
  "verbal_abuse": "高",
  "violence": "高"
}
```

这意味着如果不检查配置就从 v2 迁移到 v3，可能会导致更严格的过滤行为。

在将生产流量切换到 v3 之前，请检查当前的 v2 配置，并且：

1. 在你的 GGWP 账户中配置等效设置，或者
2. 传入一个明确的 `x-api-config` 头，并使用你期望的 v3 敏感度设置。

如果你当前依赖 v2 默认值，我们建议在正式上线前，使用具有代表性的类生产流量测试 v3。

### 响应变更

最大的迁移变更在于 `message_details`.

在 v2 中，类别检测会作为单独的布尔字段返回：

```json
{
  "violence": false,
  "verbal_abuse": true,
  "profanity": true,
  "identity_hate": true
}
```

在 v3 中，类别检测会作为结构化的 `flagged_categories` 数组返回：

```json
{
  "flagged_categories": [
    {
      "category": "identity_harm",
      "category_severity": "medium"
    },
    {
      "category": "offensive_language",
      "category_severity": "high"
    }
  ]
}
```

如果你当前检查的是 v2 的布尔字段，请改为读取 `message_details.flagged_categories`.

### 字段映射

| v2 字段                              | v3 字段                                                                     | 备注                    |
| ---------------------------------- | ------------------------------------------------------------------------- | --------------------- |
| `message_details.identity_hate`    | `message_details.flagged_categories[].category == "identity_harm"`        | 类别已重命名                |
| `message_details.profanity`        | `message_details.flagged_categories[].category == "offensive_language"`   | 类别已重命名                |
| `message_details.link`             | `message_details.flagged_categories[].category == "links"`                | 类别已重命名                |
| `message_details.self_harm`        | `message_details.flagged_categories[].category == "self_harm_incitement"` | 类别已重命名                |
| `message_details.age_concern`      | `message_details.flagged_categories[].category == "age_disclosure"`       | 类别已重命名                |
| `message_details.custom`           | `message_details.custom_flag`                                             | 字段已重命名                |
| `message_details.replaced_message` | v3 中不返回                                                                   | 如果已使用，请移除依赖           |
| 单个类别布尔值                            | `flagged_categories`                                                      | v3 返回一个类别检测列表         |
| 单个布尔值无法提供类别级严重程度                   | `flagged_categories[].category_severity`                                  | v3 包含类别特定严重程度         |
| 没有顶层 confidence 字段                 | `message_details.confidence`                                              | v3 为整体检测新增 confidence |

### 严重程度变更

v2 消息严重程度使用：

```
无、低、中、高
```

v3 支持更广泛的消息级严重程度等级：

```
无、极低、低、中、高、极高、自定义
```

如果你的应用会将严重程度值映射到内部操作，请更新解析逻辑以处理新增值。

### 玩家和对话摘要变更

主要结构保持不变：

* `player_details`
* `conversation_summary`
* `recommendations`

但是，v3 简化了一些汇总字段。如果你的集成依赖以下 v2 字段，请确认它们在你的工作流中是否仍然需要：

* `player_details.incident_types_detected`
* `player_details.incidents_by_severity`
* `conversation_summary.incident_types_detected`
* `conversation_summary.incidents_by_severity`

### 推荐迁移步骤

1. **更新端点**\
   将请求从 `/chat/v2/message` 改为 `/chat/v3/message`.
2. **检查默认配置行为**\
   v3 默认值可能比 v2 默认值更严格。如果你当前依赖 v2 默认设置，请在上线前配置等效的 v3 设置。
3. **更新配置键**\
   将 v2 类别键重命名为对应的 v3 键，并添加你想配置的任何新的 v3 类别。
4. **更新响应解析**\
   将对单个类别布尔值的检查替换为对 `message_details.flagged_categories`.
5. **更新严重程度处理**\
   确保你的应用支持扩展后的 v3 严重程度值。
6. **使用代表性流量进行测试**\
   在切换生产流量之前，对安全、边界和违规消息比较 v2 和 v3 的输出。
7. **逐步推出**\
   先从预发布环境或受限的生产流量开始，在验证下游解析和审核行为后再完全迁移。

```
```