图像理解_WebSocket协议

# 图像理解_WebSocket协议

本文档旨在帮助开发者快速对接大模型 Web API 服务，详细描述接口调用方法、请求/响应参数、鉴权方式、WebSocket 连接管理及错误码信息。

## 1. 接口概述

### 1.1 请求地址

传输协议：支持 ws/wss，为确保数据安全，建议使用 wss
默认请求地址如下：

```
ws://maas-api.cn-huabei-1.xf-yun.com/v1.1/vl
```

**说明**：部分模型因部署配置不同，其请求地址可能略有差异，具体可参考**服务管控**>**模型服务列表**右侧调用信息

### 1.2 接口要求

接口类型：流式 WebSocket 接口
接口对接：需要按照文档标准的方法进行对接，服务仅支持文档明确描述的功能，未提及的功能可能导致兼容性问题

### 1.3 鉴权方式

鉴权机制：使用签名机制进行鉴权，签名详情参考[通用URL鉴权文档](https://www.xfyun.cn/doc/spark/general_url_authentication.html)

### 1.4 请求demo

在使用demo之前，请修改代码中的app_id、key、secret （用于签名鉴权）以及patch_id（调用微调大模型时必传）<br>
[图像理解demo python语言](https://openres.xfyun.cn/xfyundoc/2025-05-15/f0bf753a-c395-403d-a17b-29d698c5ecd3/1747275337416/sparkAPI_WS_Olm.py.zip) <br>

## 2. 接口请求

### 2.1 请求示例

以下示例展示了一个完整的请求结构，为方便阅读image_url中base64示例经过裁剪：

```json
{
    "header": {
        "app_id": "123456",
        "uid": "39769795890",
        "patch_id":["xxx"]  // 调用微调大模型时必传,否则不传。对应为模型服务卡片上的resourceId
    },
    "parameter": {
        "chat": {
            "domain": "xqwen2d5s32bvl",  // 调用微调大模型时，对应为模型服务卡片上的serviceid
            "temperature": 0.5,
            "top_k": 4,
            "max_tokens": 2048,
            "auditing": "default",
            "chat_id":"xxx"
        }
    },
    "payload": {
        "message": {
                "text":[  
                    {  
                        "role": "user",  
                        "content": [  
                        {  
                            "type": "text",  
                            "text": "比较这些图片的区别："  
                        },  
                        {  
                            "type": "image_url",  
                            "image_url": {  
                                "url": "https://img1.baidu.com/it/u=2677259946,4075061101&fm=253&fmt=auto&app=138&f=PNG?w=45&h=45"  
                            }  
                        },  
                        {  
                            "type": "image_url",  
                            "image_url": {  
                                "url": "https://img1.baidu.com/it/u=2677259946,4075061101&fm=253&fmt=auto&app=138&f=PNG?w=45&h=45"  
                            }  
                        },   
                        {  
                            "type": "image_url",  
                            "image_url": {
                                    "url": "data:image/jpeg;base64,/9j/4W/+RXhpZgAASUkqAAgAAAANAA4BAgAgAAAAqgAAAA8BAgAGAAAAygAAABABAgANAAAA0AAAABIBAwABAAAACAAAABoBBQABAAAA3gAAABsBBQABAAAA5gAAACgBAwABAAAAAgAAADIBAgAUAAAA7gAAADsBAgABAAAAAAAAABMCAwABAAA

}  
                            },  
                            {  
                                "type": "text",  
                                "text": "它看起来开心吗？"  
                            },   
                        ]  
                    } 
                ]  
        }
    }
}
```

###  2.2 请求参数

接口请求字段由三个部分组成：header，parameter, payload。 字段解释如下：

#### 2.2.1 **Header**参数（平台参数）

| 字段     | 类型   | 是否必传 | 含义                                               | 限制         | 备注 |
| -------- | ------ | -------- | -------------------------------------------------- | ------------ | ---- |
| app_id   | string | 是       | 应用的app_id，需要在平台申请                       | maxLength:8  |      |
| uid      | string | 否       | 每个用户的id，非必传字段，用于后续扩展             | maxLength:32 |      |
| patch_id | array  | 否       | 调用用户微调大模型时必传，对应resourceid，否则不传 | maxLength:32 |      |

#### 2.2.2 **Parameter**参数（服务特性参数）

#####  2.2.2.1 对话服务参数（**parameter.chat**）

| 字段           | 类型    | 是否必传 | 含义                                                         | 限制                              | 备注                                                         |
| -------------- | ------- | -------- | ------------------------------------------------------------ | --------------------------------- | ------------------------------------------------------------ |
| domain         | string  | 是       | 取值为用户服务的modelId                                    |                                   | modelId可从星辰网页获取                                    |
| temperature    | float   | 否       | 核采样阈值 | 取值：[0,1]；默认值：0.5          | 用于决定结果随机性，取值越高随机性越强即相同的问题得到的不同答案的可能性越高                                                           |
| top_k          | int     | 否       | 从k个候选中随机选择一个（非等概率）                          | 取值：[1, 6]；默认值：4           | 无                                                           |
| max_tokens     | int     | 否       | 回答的tokens的最大长度                                       | 取值：[1,8192]；默认值：2048      | 无                                                           |
| chat_id        | string  | 否       | 用于关联用户会话                                             |                                   | 需保障用户下的唯一性                                         |

####  2.2.3 **payload**参数（请求数据）

**payload.message** 中的 **text** 字段为文本数据，类型为 JSON 数组； **image_url**字段为图片，类型为string图片，示例如下：

| 字段 | 类型              | 是否必传 | 含义     | 限制                                   | 备注 |
| ---- | ----------------- | -------- | -------- | -------------------------------------- | ---- |
| text | json object array | 是       | 文本数据 | 受Token限制，有效内容不能超过8192Token |      |
| image_url| string            | 是       | 图片数据 | 支持url和base64格式                    |     |

**单轮交互**：
仅传递一条用户消息：

```json
[
    {"role": "user", "content": "你会做什么？"}  
]
```

**多轮交互**：
按 `user -> assistant -> user -> assistant` 顺序传递历史记录，最后一条为当前问题；图像理解大模型中，user可发送图片文件：：

```json
[
    {"role": "user", "content": "你好"},
    {"role": "assistant", "content": "你好！"},
    {"role": "user", "content": "你是谁？"},
    {"role": "assistant", "content": "我是 Spark API。"},
    {"role": "user", "content": "你会做什么？"}
]
```

**字段说明：**

| 字段    | 类型   | 是否必传 | 含义     | 限制                            | 备注                                                         |
| ------- | ------ | -------- | -------- | ------------------------------- | ------------------------------------------------------------ |
| role    | string | 是       | 角色     | 取值范围：system,user,assistant | **通过system设置对话背景信息，user表示用户的问题，assistant表示AI的回复** |
| content | string | 是       | 文本内容 | 无                              | 该角色的对话内容                                             |

## 3. 接口响应

### 3.1 响应示例

#### 3.1.1 成功响应示例

**在不返回检索信源的情况下，大模型流式返回结构如下：**

```json
{
    "header": {
        "code": 0,
        "message": "Success",
        "sid": "cht000704fa@dx16ade44e4d87a1c802",
        "status": 0
    },
    "payload": {
        "choices": {
            "status": 2,
            "seq": 0,
            "text": [
                {
                    "content": "xxxxs",
                    "index": 0,
                    "role": "assistant"
                }
            ]
        },
        "usage": {
            "text": {
                "completion_tokens": 0,
                "question_tokens": 0,
                "prompt_tokens": 0,
                "total_tokens": 0
            }
        }
    }
}
```

> 注意： WebSocket模式中，接口为流式返回，此示例为最后一次返回结果，开发者需要将接口多次返回的结果进行拼接展示。

**在返回检索信源的情况下，在大模型返回结果之前会先返回检索信源，结构如下：**

~~~json
{
    "header": {
        "code": 0,
        "message": "Success",
        "sid": "cht000b79a4@dx190da456b5db80a560",
        "status": 1
    },
    "payload": {
        "plugins": {
            "text": [
                {
                    "name": "ifly_search",
                    "content": "[{\"index\":1,\"url\":\"https://baike.baidu.com/item/%E6%9B%B9%E6%93%8D/6772\",\"title\":\"曹操（中国东汉末年权臣，曹魏政权的奠基者）_百度百科\"},{\"index\":2,\"url\":\"https://zhidao.baidu.com/question/437349472.html\",\"title\":\"曹操是哪一年出生的？ - 百度知道\"},{\"index\":3,\"url\":\"http://www.lidaishi.com/default.aspx?did=130019\",\"title\":\"曹操的一生事迹简介-历代史历史网\"},{\"index\":4,\"url\":\"https://zhidao.baidu.com/question/374585705.html\",\"title\":\"曹操生于哪一年? - 百度知道\"},{\"index\":5,\"url\":\"https://baike.baidu.hk/item/%E6%9B%B9%E6%93%8D/6772\",\"title\":\"曹操（中國東漢末年權臣，曹魏政權的奠基者）_百度百科\"}]",
                    "content_type": "text",
                    "content_meta": null,
                    "role": "tool",
                    "status": "finished",
                    "invoked": {
                        "namespace": "ifly_search",
                        "plugin_id": "ifly_search",
                        "plugin_ver": "",
                        "status_code": 200,
                        "status_msg": "Success",
                        "type": "local"
                    }
                }
            ]
        }
    }
}
~~~

####  3.1.2 异常结果示例

```json
{
    "header": {
        "code": 10110,     // 错误码(重要)
        "message": "xxxx", // 错误描述信息(重要)
        "sid": "cht00120013@dx181c8172afb0001102",
        "status": 2
    }
}
```

### 3.2 响应参数说明

#### 3.2.1 **header**参数

| 字段    | 类型   | 含义         | 备注                                                         |
| ------- | ------ | ------------ | ------------------------------------------------------------ |
| code    | int    | 服务错误码   | 0表示正常，非0表示出错                                       |
| sid     | string | 会话的sid    |                                                              |
| status  | int    | 会话的状态   | 取值[0，1，2]，**其中0表示第一个结果, 1表示中间结果, 2表示最后一个结果** |
| message | string | 返回消息描述 | 错误码的描述信息                                             |

#### 3.2.2 响应数据参数

**文本响应**（字段choices，默认返回）：

| 字段   | 类型              | 是否必传 | 含义     | 取值范围                | 默认值 | 说明              |
| ------ | ----------------- | -------- | -------- | ----------------------- | ------ | ----------------- |
| status | int               | 是       | 数据状态 | 0:开始,1:进行中,2:结束  |        | 2表示文本响应结束 |
| seq    | int               | 是       | 数据序号 | 最小值:0,最大值:9999999 |        | 数据序号          |
| text   | json object array | 是       | 文本结果 |                         |        | 是一个JSON数组    |

**token消耗信息**（字段 usage，仅在最终响应时返回）：

| 字段       | 类型        | 是否必传 | 含义     | 取值范围 | 默认值 | 说明 |
| ---------- | ----------- | -------- | -------- | -------- | ------ | ---- |
| usage.text | json object | 是       | 文本数据 |          |        |      |

### 3.3 响应数据解析

#### 3.3.1 payload.choices.text格式解析

```json
[
    {
        "content": "这是AI的回复文本",
        "index": 0,
        "role": "assistant"
    }
]
```

| 字段              | 类型   | 是否必传 | 含义                                                 | 取值范围  | 默认值    | 说明             |
| ----------------- | ------ | -------- | ---------------------------------------------------- | --------- | --------- | ---------------- |
| content           | string | 是       | 回答的结果                                           |           |           |                  |
| reasoning_content | string | 是       | 模型生成的思考文本内容(支持深度思考的模型才有此字段) |           |           |                  |
| index             | int    | 是       | 结果序号                                             |           | 0         | 在多候选中使用   |
| role              | string | 是       | 角色                                                 | assistant | assistant | 说明这是AI的回复 |

#### 3.3.2 payload.usage.text格式解析

示例：

```json
{
    "prompt_tokens": 0,
    "question_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
}
```

| 字段              | 类型 | 是否必传 | 含义                     | 说明                                    |
| ----------------- | ---- | -------- | ------------------------ | --------------------------------------- |
| completion_tokens | int  | 是       | 回答tokens大小           |                                         |
| question_tokens   | int  | 是       | 问题不带历史的tokens大小 | 单轮情况下，此数值会略小于prompt_tokens |
| prompt_tokens     | int  | 是       | 问题总tokens大小         |                                         |
| total_tokens      | int  | 是       | 问题和回答的tokens大小   |                                         |

#### 3.3.3 结果格式补充说明

模型返回的结果除了普通文本之外，可能还包含以下标记语言，建议集成方做好适配：

-   markdown（表格、列表等）
-   latex（数学公式）

## 4. 连接管理

### 4.1 建立连接

此协议对应的接口为长连接接口，连接建立之后可以进行长时间的交互，**用户交互完成之后应该主动关闭连接**。

建立连接需要满足以下条件：

-   必须符合 websocket 协议规范（rfc6455）
-   若在 60 秒内无数据交互，服务端将主动断开连接，请确保在交互结束后主动关闭连接

### 4.2 关闭连接

正常交互结束后，客户端可以通过websocket协议发送Close类型消息关闭连接。
**建议用户在使用完毕之后，主动关闭websocket连接，不要故意长时间的占用ws连接资源！**

参考GoLand代码如下：

```go
// 用户侧关闭连接
closeInfo := websocket.FormatCloseMessage(websocket.CloseNormalClosure, "close ws conn")
_ = conn.WriteControl(websocket.CloseMessage, closeInfo, time.Now().Add(2*time.Second))
_ = conn.Close()
```

**提示**：除正常交互外，以下情况也会导致连接断开：

- 客户端连续 60 秒未发送数据；
- 服务升级、熔断等特殊情况下，API 可能主动断开连接，需要业务集成时，请确保做好异常处理。

##  5. 错误码说明

###  5.1 错误码列表

| 错误码 | 错误信息                                                     |
| ------ | ------------------------------------------------------------ |
| 0      | 成功                                                         |
| 10000  | 升级为ws出现错误                                             |
| 10001  | 通过ws读取用户的消息 出错                                    |
| 10002  | 通过ws向用户发送消息 出错                                    |
| 10003  | 用户的消息格式有错误                                         |
| 10004  | 用户数据的schema错误                                         |
| 10005  | 用户参数值有错误                                             |
| 10006  | 用户并发错误：当前用户已连接，同一用户不能多处同时连接。     |
| 10007  | 用户流量受限：服务正在处理用户当前的问题，需等待处理完成后再发送新的请求。（必须要等大模型完全回复之后，才能发送下一个问题） |
| 10008  | 服务容量不足，联系服务商                                     |
| 10009  | 和引擎建立连接失败                                           |
| 10010  | 接收引擎数据的错误                                           |
| 10011  | 向引擎发送数据的错误                                         |
| 10012  | 引擎内部错误                                                 |
| 10013  | 用户问题涉及敏感信息，审核不通过，拒绝处理此次请求。         |
| 10014  | 回复结果涉及到敏感信息，审核不通过，后续结果无法展示给用户。（建议清空当前结果，并给用户提示/警告：该答案涉及到敏感/政治/恐怖/色情/暴力等方面，不予显示/回复） |
| 10015  | appid在黑名单中                                              |
| 10016  | appid授权类的错误。比如：未开通此功能，未开通对应版本，token不足，并发超过授权等等。（联系我们开通授权或提高限制） |
| 10018  | 用户在5分钟内持续发送ping消息，但并没有实际请求数据，会返回该错误码并断开ws连接。短链接使用无需关注 |
| 10019  | 该错误码表示返回结果疑似敏感，建议拒绝用户继续交互           |
| 10110  | 服务忙，请稍后再试。                                         |
| 10163  | 请求引擎的参数异常，引擎的schema检查不通过                   |
| 10222  | 引擎网络异常                                                 |
| 10223  | LB找不到引擎节点                                             |
| 10907  | token数量超过上限。对话历史+问题的字数太多，需要精简输入。   |
| 11200  | 授权错误：该appId没有相关功能的授权或者业务量超过限制（联系我们开通授权或提高限制） |
| 11201  | 授权错误：日流控超限。超过当日最大访问量的限制。（联系我们提高限制） |
| 11202  | 授权错误：秒级流控超限。秒级并发超过授权路数限制。（联系我们提高限制） |
| 11203  | 授权错误：并发流控超限。并发路数超过授权路数限制。（联系我们提高限制） |

###  5.2 内容审核说明

当返回10013或者10014错误码时，代码内容审核判断当前问题或回复的信息涉及敏感信息。返回错误的同时，在header.message字段中会携带当前的敏感提示语。

-   10013 表示用户的问题涉及敏感信息，服务侧拒绝处理此次请求。
-   10014 表示回复结果中涉及敏感信息，后续结果不可以展示给用户。
-   10019 表示当前的回复疑似敏感，结果文本可以给用户展示。服务会在返回**全部结果**后再返回该错误码，如果继续提问可能会导致被审核拦截。建议在收到该错误码后提示用户涉及敏感信息，并禁掉对话框，禁止用户继续提问。

如果需要调整内容审核的严格程度、敏感词等信息，请联系我们技术支持。
# 星火微调服务Web API文档

## 1. Spark API 协议描述

本协议用于描述 Spark 大模型集成接口协议。技术咨询可直接提交[工单](https://console.xfyun.cn/workorder/commit)

**本API服务为AI 大模型的产品化接口，支持内容审核，快速修复等功能**

**每次交互需要重新建立websocket连接，当完成交互时，需要请求侧主动发送close消息，完成接口的断开。**

**如果在生成的过程中需要终止，可以直接发送websocket的close消息，关闭连接即可**

## 2. 接口说明

### 2.1 请求方法和URL

传输协议 ：ws(s) ,为提高安全性，强烈推荐wss

默认请求地址如下：

```
wss://maas-api.cn-huabei-1.xf-yun.com/v1.1/chat
```

其中 spark lite instruct 的请求地址如下：

```
wss://spark-api-n.xf-yun.com/v1.1/chat
```

部分模型因为部署原因可能略有差异，具体可参考**服务管控**中的模型服务列表右侧调用信息。

### 2.2 接口Demo

参见多种语言demo，目前已支持的语言：

（使用demo之前，请修改代码中的app_id，key，secret 鉴权参数以及patch_id）

[demo python语言](https://xfyun-doc.xfyun.cn/lc-sp-Python_demo-1704954863692.zip)
[demo java语言](https://xfyun-doc.xfyun.cn/lc-sp-Java_demo-1704954843934.zip)

### 2.3 接口要求

接口类型：流式 ws(s)

接口鉴权：使用签名机制进行鉴权，签名详情参照鉴权说明

接口对接：需要按照文档标准的方法进行对接，服务仅保障文档内描述功能。

## 3. 请求

### 3.1 请求协议示例

```json
{
    "header": {
        "app_id": "123456",
        "uid": "39769795890"
        "patch_id":["xxx"]  //调用微调大模型时必传,否则不传。对应为模型服务卡片上的resourceId
    },
    "parameter": {
        "chat": {
            "domain": "patch",  //调用微调大模型时，对应为模型服务卡片上的serviceid
            "temperature": 0.5,
            "top_k": 4,
            "max_tokens": 2048,
            "auditing": "default",
            "chat_id":"xxx"
        }
    },
    "payload": {
        "message": {
            "text": [
                {
                    "role": "system",
                    "content": "你是星火认知大模型"
                },
                {
                    "role": "user",
                    "content": "今天的天气"
                }
            ]
        }
    }
}
```

### 3.2 请求参数

#### 3.2.1 平台参数

header部分的字段介绍：

| 字段名          | 类型   | 是否必传 | 含义                                                     | 备注 | 限制           |
| --------------- | ------ | -------- | -------------------------------------------------------- | ---- | -------------- |
| header.app_id   | string | 是       | 应用的app_id，需要在平台申请                             |      | "maxLength":8  |
| header.uid      | string | 否       | 每个用户的id，非必传字段，用于后续扩展                   |      | "maxLength":32 |
| header.patch_id | array  | 否       | 调用用户微调大模型时必传（发布的resourceId），否则不传。 |      | "maxLength":32 |

#### 3.2.2 服务特性参数

##### 3.2.2.1 对话服务参数

| 字段名                         | 类型   | 是否必传 | 含义                                      | 备注                                                | 默认值 |
| ------------------------------ | ------ | -------- | ----------------------------------------- | --------------------------------------------------- | ------ |
| parameter.chat                 | object | 是       | 用于上传对话的参数信息                    |                                                     |        |
| parameter.chat.domain          | string | 是       | 需要使用的领域                            | 通用模型：general，其他领域具体值联系接口提供方。   |        |
| parameter.chat.temperature     | float  | 否       | 核采样阈值,向上调整可以增加结果的随机程度 | 取值范围 (0，1]                                     | 0.5    |
| parameter.chat.top_k           | int    | 否       | 从k个中随机选择一个(非等概率)             | 最小值1，最大值6。                                  | 4      |
| parameter.chat.max_tokens      | int    | 否       | 回答的tokens的最大长度                    | 最小值是1, 最大值是4096。                           | 2048   |
| parameter.chat.suppress_plugin | string | 否       | 用于关闭云端搜索                          | 目前传固定值，字符串格式： {"knowledge", "medical"} |        |

#### 3.2.3 请求数据

##### 3.2.3.1 文本数据

payload.message段的参数：

| 字段 | 含义     | 数据类型          | 取值范围                               | 默认值 | 说明 | 必填 |
| :--- | :------- | :---------------- | :------------------------------------- | :----- | :--- | :--- |
| text | 文本数据 | json object array | 受Token限制，有效内容不能超过8192Token |        |      | 是   |

**单轮交互示例说明：**

单轮交互只需要传递一个user角色的数据

```json
[
    // 用户的提问
    {"role": "user", "content": "你会做什么？"}
]
```

**多轮交互的格式示例：**

多轮交互需要将之前的交互历史按照user->assistant->user->assistant规则进行拼接，并保证最后一条是user的当前问题。

```json
[
    // 拼接对话历史信息:
    {"role": "user", "content": "你好"},              // 用户第一个问题   role是user,表示是用户的提问
    {"role": "assistant", "content": "你好！"},        // AI的第一个回复  role是assistant，表示是AI的回复
    {"role": "user", "content": "你是谁？"},           // 用户第二个问题
    {"role": "assistant", "content": "我是Spark API。"},  // AI的第二个回复
    // ...... 对话历史信息

// 用户最新的提问
    {"role": "user", "content": "你会做什么？"}
]
```

**字段解析：**

| 字段    | 含义     | 数据类型 | 取值范围        | 默认值 | 说明                                            |
| :------ | :------- | :------- | :-------------- | :----- | :---------------------------------------------- |
| role    | 角色     | string   | user, assistant |        | **user表示是用户的问题，assistant表示AI的回复** |
| content | 文本内容 | string   | --              |        | 该角色的对话内容                                |

## 4. 响应

### 4.1 响应协议示例

#### 4.1.1 结果示例

```json
{
    "header": {
        "code": 0,
        "message": "Success",
        "sid": "cht000704fa@dx16ade44e4d87a1c802",
        "status": 0
    },
    "payload": {
        "choices": {
            "status": 2,
            "seq": 0,
            "text": [
                {
                    "content": "xxxxs",
                    "index": 0,
                    "role": "assistant"
                }
            ]
        },
        "usage": {
            "text": {
                "completion_tokens": 0,
                "question_tokens": 0,
                "prompt_tokens": 0,
                "total_tokens": 0
            }
        }
    }
}
```

注意：插件结果和大模型结果会交替返回。

#### 4.1.2 异常结果

```json
{
    "header": {
        "code": 10110,     // 错误码(重要)
        "message": "xxxx", // 错误描述信息(重要)
        "sid": "cht00120013@dx181c8172afb0001102",
        "status": 2,
    }
}
```

### 4.2 响应参数

#### 4.2.1 平台参数

header部分的字段介绍：

| 字段名         | 类型   | 含义         | 备注                                                         |
| -------------- | ------ | ------------ | ------------------------------------------------------------ |
| header.code    | int    | 服务错误码   | 0表示正常，非0表示出错                                       |
| header.sid     | string | 会话的sid    |                                                              |
| header.status  | int    | 会话的状态   | 取值[0，1，2]， 其中**0表示第一个结果, 1表示中间结果, 2表示最后一个结果** |
| header.message | string | 返回消息描述 | 错误码的描述信息                                             |

#### 4.2.2 响应数据参数

**文本响应：**

choices（默认返回）

| 字段   | 含义     | 数据类型          | 取值范围                 | 默认值 | 说明                | 必填 |
| :----- | :------- | :---------------- | :----------------------- | :----- | :------------------ | :--- |
| status | 数据状态 | int               | 0:开始, 1:开始, 2:结束   |        | 2表示文本响应结束   | 是   |
| seq    | 数据序号 | int               | 最小值:0, 最大值:9999999 |        | 数据序号            | 是   |
| text   | 文本结果 | json object array |                          |        | 是一个**json 数组** | 是   |

**token消耗响应：**

usage（**最后一个结果时，才会有该字段**）

| 字段               | 含义     | 数据类型    | 取值范围 | 默认值 | 说明 | 必填 |
| :----------------- | :------- | :---------- | :------- | :----- | :--- | :--- |
| payload.usage.text | 文本数据 | json object |          |        |      |      |

**插件信息响应：**

plugins（仅触发插件时返回）

| 字段 | 含义     | 数据类型    | 取值范围 | 默认值 | 说明 | 必填 |
| :--- | :------- | :---------- | :------- | :----- | :--- | :--- |
| text | 文本数据 | json object |          |        |      |      |

### 4.3 响应数据解析

#### 4.3.1 payload.choices.text格式解析

```json
[
    {
        "content": "这是AI的回复文本",
        "index": 0,
        "role": "assistant"
    }
]
```

**解析：**

| 字段    | 含义                     | 数据类型 | 默认值    | 说明                      |
| :------ | :----------------------- | :------- | :-------- | :------------------------ |
| content | 回答的结果               | string   | --        | --                        |
| index   | 结果序号，在多候选中使用 | int      | 0         | --                        |
| role    | 角色                     | string   | assistant | assistant说明这是AI的回复 |

#### 4.3.2 payload.usage.text格式解析

```json
{
    "prompt_tokens": 0,
    "question_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
}
```

**解析：**

| 字段              | 含义                     | 数据类型 | 默认值 | 说明                                    |
| :---------------- | :----------------------- | :------- | :----- | :-------------------------------------- |
| completion_tokens | 回答tokens大小           | int      | --     | --                                      |
| question_tokens   | 问题不带历史的tokens大小 | int      | --     | 单轮情况下，此数值会略小于prompt_tokens |
| prompt_tokens     | 问题总tokens大小         | int      | --     | --                                      |
| total_tokens      | 问题和回答的tokens大小   | int      | --     | --                                      |

#### 4.3.4 结果格式补充说明

模型结果除了普通文本类型，为了满足排版需求，会出现以下的标记语言，建议集成方进行适配：

- markdown（表格、列表等）
- latex（数学公式）

## 5. 使用方式

### 5.1 连接管理

#### 5.1.1 建立ws连接

此协议对应的接口为长连接接口，连接建立之后可以进行长时间的交互，**用户交互完成之后应该主动关闭连接**。

建立连接需要满足以下条件：

- 必须符合 websocket 协议规范（rfc6455）
- 需要按照要求进行[签名请求](https://www.xfyun.cn/doc/spark/(http:/integration-aiui.openspeech.cn/doc/aiui/1_aipaas/auth.html#握手-鉴权))
- 如果用户在60秒内没有交互数据，服务侧会主动断开。因此也建议用户在交互完成之后，主动关闭连接。

#### 5.1.2 关闭ws连接

正常交互结束后，客户端可以通过websocket协议发送Close类型消息关闭连接。

**【建议用户在使用完毕之后，主动关闭websocket连接，不要故意长时间的占用ws连接资源！】**

参考GoLand代码如下：

```text
// 用户侧关闭连接
closeInfo := websocket.FormatCloseMessage(websocket.CloseNormalClosure, "close ws conn")
_ = conn.WriteControl(websocket.CloseMessage, closeInfo, time.Now().Add(2*time.Second))
_ = conn.Close()
```

除了正常交互连接断开之外，触发以下场景也会将连接断开

- 当用户持续持续60s空闲状态，不发送任何数据时，服务侧会主动断开连接。因此也建议用户在交互完成之后，主动关闭连接。
- 在服务进行升级、熔断等情况下，API可能会主动断开已完成交互连接，需要业务集成时，注意异常处理。

### 5.2 内容审核说明

当返回10013或者10014错误码时，代码内容审核判断当前问题或回复的信息涉及敏感信息。返回错误的同时，在header.message字段中会携带当前的敏感提示语。

- 10013 表示用户的问题涉及敏感信息，服务侧拒绝处理此次请求。
- 10014 表示回复结果中涉及敏感信息，后续结果不可以展示给用户。
- 10019 表示当前的回复疑似敏感，结果文本可以给用户展示。服务会在返回**全部结果**后再返回该错误码，如果继续提问可能会导致被审核拦截。建议在收到该错误码后提示用户涉及敏感信息，并禁掉对话框，禁止用户继续提问。

如果需要调整内容审核的严格程度、敏感词等信息，请联系我们。

## 6. 错误码列表

| 错误码 | 错误信息                                                     |
| ------ | ------------------------------------------------------------ |
| 0      | 成功                                                         |
| 10000  | 升级为ws出现错误                                             |
| 10001  | 通过ws读取用户的消息 出错                                    |
| 10002  | 通过ws向用户发送消息 出错                                    |
| 10003  | 用户的消息格式有错误                                         |
| 10004  | 用户数据的schema错误                                         |
| 10005  | 用户参数值有错误                                             |
| 10006  | 用户并发错误：当前用户已连接，同一用户不能多处同时连接。     |
| 10007  | 用户流量受限：服务正在处理用户当前的问题，需等待处理完成后再发送新的请求。 （必须要等大模型完全回复之后，才能发送下一个问题） |
| 10008  | 服务容量不足，联系服务商                                     |
| 10009  | 和引擎建立连接失败                                           |
| 10010  | 接收引擎数据的错误                                           |
| 10011  | 向引擎发送数据的错误                                         |
| 10012  | 引擎内部错误                                                 |
| 10013  | 用户问题涉及敏感信息，审核不通过，拒绝处理此次请求。         |
| 10014  | 回复结果涉及到敏感信息，审核不通过，后续结果无法展示给用户。（建议清空当前结果，并给用户提示/警告：该答案涉及到敏感/政治/恐怖/色情/暴力等方面，不予显示/回复） |
| 10015  | appid在黑名单中                                              |
| 10016  | appid授权类的错误。比如：未开通此功能，未开通对应版本，token不足，并发超过授权 等等。 （联系我们开通授权或提高限制） |
| 10018  | 用户在5分钟内持续发送ping消息，但并没有实际请求数据，会返回该错误码并断开ws连接。短链接使用无需关注 |
| 10019  | 该错误码表示返回结果疑似敏感，建议拒绝用户继续交互           |
| 10110  | 服务忙，请稍后再试。                                         |
| 10163  | 请求引擎的参数异常 引擎的schema 检查不通过                   |
| 10222  | 引擎网络异常                                                 |
| 10223  | LB找不到引擎节点                                             |
| 10907  | token数量超过上限。对话历史+问题的字数太多，需要精简输入。   |
| 11200  | 授权错误：该appId没有相关功能的授权 或者 业务量超过限制（联系我们开通授权或提高限制） |
| 11201  | 授权错误：日流控超限。超过当日最大访问量的限制。（联系我们提高限制） |
| 11202  | 授权错误：秒级流控超限。秒级并发超过授权路数限制。（联系我们提高限制） |
| 11203  | 授权错误：并发流控超限。并发路数超过授权路数限制。（联系我们提高限制） |