bert协议文档

## **1、请求地址**

默认请求地址如下：[http(s)://xingchen.cn-huabei-2.xf-yun.com/v1/private/serverceID](https://xingchen.cn-huabei-2.xf-yun.com/v1/private/serverceID)

备注：serverceID不同服务而定，例如xf5ed701a，微调平台发布服务后会自动生成。
具体查询地址微调主页-服务管控-serverceid

## **2、接口鉴权**
参照通用鉴权方式
详见如下地址-鉴权说明章节
https://www.xfyun.cn/doc/spark/http_url_authentication.html#_1-%E9%89%B4%E6%9D%83%E8%AF%B4%E6%98%8E

## **3、请求协议**

### **3.1请求协议示例**
请求参数
```
{
	"header": {
		"app_id": "123456",
		"uid": "123456",
		"did": "123456",
		"imei": "123456",
		"imsi": "123456",
		"mac": "123456",
		"net_type": "wifi",
		"net_isp": "CMCC",
		"status": 3,
		"request_id": null,
		"res_id": ""
	},
	"parameter": {
		"cls": {
			"score": {
				"encoding": "utf8",
				"compress": "raw",
				"format": "json"
			}
		}
	},
	"payload": {
		"messages": {
		"encoding": "utf8",
		"compress": "raw",
		"format": "json",
		"status": 3,
		"text": ""
		}
	}
}
```
字段解释如下：
|字段|含义|类型|说明|
|--|--|--|--|
|header|协议头部|Object|协议头部，用于描述平台特性的参数。|
|parameter|能力参数|Object|AI 特性参数，用于控制 AI 引擎特性的开关。|
|cls|服务别名|Object|  |
|score|响应数据控制|Object|数据格式预期，用于描述返回结果的编码等相关约束，不同的数据类型，约束维度亦不相同，此 object 与响应结果存在对应关系。|
|payload|输入数据段|Object|数据段，携带请求的数据。|
|messages|输入数据|Object|输入数据|

Payload中messages-text示例：
```
{"messages":[{"content": "Java 写一个计时器", "role": "user", "index":0}]}
```
### **3.2请求参数及含义说明**
**header部分**
|字段|含义|类型|说明|是否必传|
|--|--|--|--|--|
|app_id|在平台申请的app id信息，[点击申请](https://in.iflyaicloud.com/console/home)|string|"maxLength":50|是|
|uid|请求用户服务返回的uid，用户及设备级别个性化功能依赖此参数|string|"maxLength":50|否|
|did|请求方确保唯一的设备标志，设备级别个性化功能依赖此参数|string|"maxLength":50|否|
|imei|设备imei信息|string|"maxLength":50|否|
|imsi|设备imsi信息|string|"maxLength":50|否|
|mac|设备mac信息|string|"maxLength":50|否|
|net_type|网络类型，可选值为wifi、2G、3G、4G、5G|string|wifi、2G、3G、4G、5G|否|
|net_isp|运营商信息，可选值为CMCC、CUCC、CTCC、other|string|CMCC、CUCC、CTCC、other|否|
|request_id|客户端请求的会话唯一标识|string|"maxLength":64|否|
|res_id|个性化资源ID|string|"maxLength":1024|否|
|status|请求状态，可选值为：3-一次传完|int|3|是|

**score部分**
|字段|含义|数据类型|取值范围|默认值|说明|必填|
|--|--|--|--|--|--|--|
|encoding|文本编码|string|utf8, gb2312, gbk|utf8|取值范围可枚举|否|
|compress|文本压缩格式|string|raw, gzip|raw|取值范围可枚举|否|
|format|文本格式|string|plain, json, xml|json|取值范围可枚举|否|

**messages部分**
|字段|含义|数据类型|取值范围|默认值|说明|必填|
|--|--|--|--|--|--|--|
|encoding|文本编码|string|utf8, gb2312, gbk|utf8|取值范围可枚举|否|
|compress|文本压缩格式|string|raw, gzip|raw|取值范围可枚举|否|
|format|文本格式|string|plain, json, xml|json|取值范围可枚举|否|
|status|数据状态|int|3:一次性传完|3|取值范围为：3（一次传完）|否|
|text|文本数据|string|最小尺寸:1B, 最大尺寸:1048576B||需base64编码，文本大小：0-1M|是|

### **3.3请求数据及含义说明**

**示例：**
```
{
	"messages": [
		{
			"content": null,
			"role": null
		}
	]
}
```
**解析：**
|字段|含义|数据类型|取值范围|默认值|说明|
|--|--|--|--|--|--|
|messages|消息|array|--|[]|--|
|content|文本内容|string|`字符长度1 ~ 4069000的字符串`|--|--|
|role|角色|string|`user: 用户` `assistant: 助手`|--|--|

## **4、响应协议**

### **4.1响应协议示例**
```
{
	"header": {
		"code": 0,
		"message": "success",
		"sid": "ase000704fa@dx16ade44e4d87a1c802"
	},
	"payload": {
		"score": {
			"encoding": "utf8",
			"compress": "raw",
			"format": "json",
			"text": ""
		}
	}
}
```
|字段|含义|类型|说明|
|--|--|--|--|
|header|协议头部|Object|协议头部，用于描述平台特性的参数|
|payload|响应数据块|Object|数据段，携带响应的数据。|
|score|响应数据块|Object|输出数据，如下|

### **4.2响应参数及含义说明**
|字段|含义|类型|是否必选|
|--|--|--|--|
|code|返回码，0表示成功，其它表示异常|int|是|
|message|错误描述|string|是|
|sid|本次会话的id|string|是|

|字段|含义|数据类型|取值范围|默认值|说明|必填|
|--|--|--|--|--|--|--|
|encoding|文本编码|string|utf8, gb2312, gbk|utf8|取值范围可枚举|否|
|compress|文本压缩格式|string|raw, gzip|raw|取值范围可枚举|否|
|format|文本格式|string|plain, json, xml|json|取值范围可枚举|否|
|text|文本数据|string|最小尺寸:1B, 最大尺寸:1048576B| |需base64编码，文本大小：0-1M|是|

### **4.3响应数据及含义说明**

**示例：**
```
{
	"category_scores": {
		"A分类": null,
		"B分类": null,
		"C分类": null,
		"D分类": null,
	}
}
```
备注：其中A分类、B分类、C分类、D分类根据训练集中分类结果来定，每个训练集不同，分类结果不同
|字段|含义|数据类型|取值范围|默认值|说明|
|--|--|--|--|--|--|
|category_scores|分类得分|object|--|--|--|
|A分类||float|`min: -1 ~ max: 1`|--|--|
|B分类||float|`min: -1 ~ max: 1`|--|--|
|C分类||float|`min: -1 ~ max: 1`|--|--|
|D分类||float|`min: -1 ~ max: 1`|--|--|
# stable_diffusion图片生成Web API文档

### 1 请求地址

```
https://xingchen-api.cn-huabei-1.xf-yun.com/v2.1/tti
```

### 2 接口鉴权

参考[http协议通用鉴权](https://www.xfyun.cn/doc/spark/http_url_authentication.html)

### 3 接口请求

#### 请求参数

```json
{
 "header": {
 "app_id": "12345",
 "uid": "12345"
 "patch_id":["123456"]
 },
 "parameter": {
 "chat": {
 "domain": "<your-service-id>",
 "width":768,
 "height":768,
 "seed":42,
 "num_inference_steps":20,
 "guidance_scale":5.0,
 "scheduler":"Euler",
 }
 },
 "payload": {
 "message": {
 "text": [
 {"role": "user", "content": "Draw a mountain."}
 ]
 },
 "negative_prompts":{
 "text":"black and white"
 }
 }
}
```

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

**header部分**

| 参数名称 | 类型   | 必传 | 参数要求   | 参数说明                                    |
| -------- | ------ | ---- | ---------- | :------------------------------------------ |
| app_id   | string | 是   |            | 应用appid，从开放平台控制台创建的应用中获取 |
| uid      | string | 否   | 最大长度32 | 每个用户的id，用于区分不同用户              |
| patch_id      | string | 否   |  | 非全量训练的模型需要传入patch_id，可从平台网页获取              |

**parameter.chat部分**

| 参数名称    | 类型   | 必传 | 参数要求                  | 参数说明                                                     |
| ----------- | ------ | ---- | ------------------------- | :----------------------------------------------------------- |
| domain      | string | 是   | 取值为用户服务的serviceId | serviceId可从星辰网页获取                                    |
| width | int  | 是   | 选取平台支持的分辨率    | 图片的宽度 |
| height       | int    | 是   | 选取平台支持的分辨率      | 图片的高度 |
| seed | int  | 是   | 范围0~INT_MAX    | 产生图片的随机种子 |
| num_inference_steps       | int    | 是   | 范围0~50      | 产生图片的步长数 |
| guidance_scale | float  | 是   | 值范围0~20.0    | 提示词相关度，越大越相关 |
| scheduler | string  | 是   | 默认值'DPM++ 2M Karras'    | 调度器 |

分辨率可支持的有768x768 1024x1024 576x1024 768x1024 1024x576 1024x768
scheduler支持的有'DPM++ 2M Karras','DPM++ SDE Karras','DDIM','Euler a','Euler'

**payload部分**

| 参数名称 | 类型   | 必传 | 参数要求                              | 参数说明                                    |
| -------- | ------ | ---- | ------------------------------------- | ------------------------------------------- |
| message.text.role     | string | 是   | 取值为"user"                | user表示是用户的问题 |
| message.text.content  | string | 是   | 不得超过1024个字符 | 文本内容，图片生成指令    |
| message.negative_prompts  | string | 否   | 不得超过1024个字符 | 在进行文本生成时，可以提供一些负面或反向的示例，以帮助模型生成更符合期望的输出 |

### 4 接口响应

返回参数示例：
成功
```json
{
    "header": {
        "code": 0,
        "message": "Success",
        "sid": "cht000704fa@dx16ade44e4d87a1c802",
        "status": 0
    },
    "payload": {
        "choices": {
            "status": 2,
            "seq": 0,
            "text": [
                {
                  "content": "base64",                     
                  "index": 0,
                  "role": "assistant"
                }
            ]
        }
    }
}
```

异常
```json
{
  "header": {
      "code": 10003,     
      "message": "xxxx", 
      "sid": "cht00120013@dx181c8172afb0001102",
      "status": 2,
  }
}
```

返回参数说明:

**header部分**
| 字段名  | 类型   | 字段说明                                                     |
| ------- | ------ | ------------------------------------------------------------ |
| code    | int    | 错误码，0表示正常，非0表示出错；详细释义可在接口说明文档最后的错误码说明了解 |
| message | string | 会话是否成功的描述信息                                       |
| sid     | string | 会话的唯一id，用于讯飞技术人员查询服务端会话日志使用,出现调用错误时建议留存该字段 |
| status  | int    | 会话的状态 ，文生图场景下为2 |

**payload.choices部分**

| 字段名  | 类型   | 字段说明                                                     |
| ------- | ------ | ------------------------------------------------------------ |
| status  | int    | 数据状态 ，0:开始, 1:开始, 2:结束（表示文本响应结束） |
| seq     | int    | 返回的数据序号，取值为[0,9999999]                            |
| text.content | string | 返回的base64图片结果，默认分辨率512*512                   |
| text.role    | string | 角色标识，固定为assistant，标识角色为AI                      |
| text.index   | int    | 结果序号，在多候选中使用         |

**错误码列表**

| 错误码   | 错误信息                |
|-------|---------------------|
| 0     | 成功                  |
| 10003 | 用户的消息格式有错误          |
| 10004 | 用户数据的schema错误       |
| 10005 | 用户参数值有错误            |
| 10008 | 服务容量不足              |
| 10021 | 输入审核不通过             |
| 10022 | 模型生产的图片涉及敏感信息，审核不通过 |
# 精调服务_HTTP协议

## 1. 接口说明

协议 ：HTTP
请求方法：POST
默认请求地址如下：

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

部分模型因为部署原因可能略有差异，具体可参考**服务管控** > **模型服务列表**右侧调用信息。技术咨询可直接提交[工单](https://console.xfyun.cn/workorder/commit)

## 2. 接口请求

### 2.1 请求示例

下面是一个 HTTP 请求的 Python Demo 示例：

```python
from openai import OpenAI

api_key = "<从服务管控页面获取 对应服务的APIKey>" # 请替换为您的 API Key 
api_base = "http://maas-api.cn-huabei-1.xf-yun.com/v1"

client = OpenAI(api_key=api_key,base_url=api_base)

try:
 response = client.chat.completions.create(
 model="<从服务管控获取要访问服务的modelID>",
 messages=[{"role": "user", "content": "你好"}],
 stream=False,
 temperature=0.7,
 max_tokens=4096,
 extra_headers={"lora_id": "0"}, # 调用微调大模型时,对应替换为模型服务卡片上的resourceId
 stream_options={"include_usage": True},
 extra_body={"search_disable": False, "show_ref_label": True} 
 )
 # 只对支持深度思考的模型才有此字段
 print(response.choices[0].message.reasoning_content)
 # 只对支持联网检索的模型，开启检索返回信源列表时才有此字段
 print(response.choices[0].message.plugins_content)
 print(response.choices[0].message.content)
 
except Exception as e:
 print(f"Error: {e}")
```

**注意**：在使用demo之前，请务必替换 `api_key` 为您的API Key。

如果想使用 HTTP 请求的 流式输出，请参考如下实例：

```python
from openai import OpenAI

api_key = "<从服务管控页面获取 对应服务的APIKey>" # 请替换为您的 API Key 
api_base = "http://maas-api.cn-huabei-1.xf-yun.com/v1"

client = OpenAI(api_key=api_key,base_url=api_base)

try:
 response = client.chat.completions.create(
 model="<从服务管控获取要访问服务的modelID>",
 messages=[{"role": "user", "content": "你好"}],
 stream=True,
 temperature=0.7,
 max_tokens=4096,
 extra_headers={"lora_id": "0"}, # 调用微调大模型时,对应替换为模型服务卡片上的resourceId
 stream_options={"include_usage": True},
 extra_body={"search_disable": False, "show_ref_label": True} 
 )

full_response = ""
    for chunk in response:
        # 只对支持深度思考的模型才有此字段
        if hasattr(chunk.choices[0].delta, 'reasoning_content') and chunk.choices[0].delta.reasoning_content is not None:
            reasoning_content = chunk.choices[0].delta.reasoning_content
            print(reasoning_content, end="", flush=True)  # 实时打印思考模型输出的思考过程每个片段

# 只对支持联网检索的模型，开启检索返回信源列表时才有此字段
        if hasattr(chunk.choices[0].delta, 'plugins_content') and chunk.choices[
            0].delta.plugins_content is not None:
            plugins_content = chunk.choices[0].delta.plugins_content
            print(plugins_content, end="", flush=True)  # 实时打印联网检索信源结果的每个片段
        
        if hasattr(chunk.choices[0].delta, 'content') and chunk.choices[0].delta.content is not None:
            content = chunk.choices[0].delta.content
            print(content, end="", flush=True)  # 实时打印每个片段
            full_response += content
    
    print("\n\n ------完整响应：", full_response)    
except Exception as e:
    print(f"Error: {e}")
```

**注意**：在使用demo之前，请务必替换 `api_key` 为您的API Key。

###  2.2 请求参数

| 参数           | 类型    | 是否必填 | 要求                                                 | 说明                                                         |
| -------------- | ------- | -------- | ---------------------------------------------------- | ------------------------------------------------------------ |
| model          | string  | 是       |                                                      | 指定要调用的对话生成模型ID                                   |
| messages       | array   | 是       | `[{"role": "user", "content":"用户输入内容"}]`       | 表示对话上下文的消息列表，支持多轮对话交互。其中，`role` 用于标识消息发送方（例如 `user` 表示用户、`assistant` 表示模型回复），`content` 则为实际文本内容。 |
| stream         | boolean | 否       | 取值为 `true` 或 `false`，默认值为 `false`           | 指定是否采用流式响应模式。若设置为 `true`，系统将逐步返回生成的回复内容；否则，将一次性返回完整响应 |
| temperature    | float   | 否       | 取值为`[0,1]`,默认值为`0.7`                          | 核采样阈值。用于决定结果随机性，取值越高随机性越强即相同的问题得到的不同答案的可能性越高 |
| max_tokens     | int     | 否       | 取值为`[1,8192]`，默认值为`2048`                     | 限制生成回复的最大 token 数量，DeepSeek-R1和DeepSeek-V3 最大可支持到 32768 |
| extra_headers  | object  | 否       | 默认值为`{"lora_id": "0"}`                           | 通过传递 `lora_id` 加载特定的LoRA模型，调用微调大模型时，对应设置为模型服务卡片上的resourceId                        |
| extra_body     | object  | 否       |` {"search_disable": False, "show_ref_label": True, "enable_thinking": False}` | 控制联网检索相关功能，**仅DeepSeek-R1和DeepSeek-V3支持该功能**。`search_disable`关闭联网检索功能，取值：[true,false]；默认值：true，输出内容是否结合联网检索结果会根据输入文本自动判断。`show_ref_label`展示检索信源信息，取值：[true,false]；默认值：false，开启联网检索功能后当该参数设置为true且触发了联网检索功能时，会在响应数据中新增返回检索信源列表；否则仅返回大模型回复结果。`enable_thinking`切换思考模式，该参数**仅Qwen3 MOE系列模型支持**。取值：[true,false]；默认值：false，支持在单一模型内无缝切换思考模式（用于复杂的逻辑推理、数学和编程）和非思考模式（用于高效、通用的对话） |
| stream_options | object  | 否       | 默认值为`{"include_usage": True}`                    | 针对流式响应模式的扩展配置，如控制是否在响应中包含API调用统计信息等附加数据。 |

####  2.2.1 `messages` 参数说明

messages 参数用于传递对话内容，包括用户输入和 AI 回复

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

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

```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": "你会做什么？"}
]
```

## 3. 接口响应

### 3.1 响应示例

#### 3.1.1 成功响应示例
关闭联网检索或不返回检索信源时，返回结构如下：

```python
Response: ChatCompletion(
    id='cht000b920a@dx194e0205ccbb8f3700',
    choices=[
        Choice(
            finish_reason='stop',
            index=0,
            logprobs=None,
            message=ChatCompletionMessage(
                content='大模型回复',
                refusal=None,
                role='assistant',
                audio=None,
                function_call=None,
                tool_calls=None
            )
        )
    ],
    created=1738927005,
    model=None,
    object='chat.completion',
    service_tier=None,
    system_fingerprint=None,
    usage=CompletionUsage(
        completion_tokens=42,
        prompt_tokens=44,
        total_tokens=86,
        completion_tokens_details=None,
        prompt_tokens_details=None
    )

```
开启联网检索且返回检索信源是，返回结构如下：
```python
ChatCompletion(
    id='cht000b8e42@dx19590107ba3b8f2700', 
    choices=[
        Choice(
            finish_reason='stop', 
            index=0, 
            logprobs=None, 
            message=ChatCompletionMessage(
                content='大模型回复', 
                refusal=None, 
                role='assistant', 
                audio=None, 
                function_call=None, 
                tool_calls=None, 
                reasoning_content='', 
                plugins_content=[
                    {
                        'name': 'ifly_search', 
                        'content': '[{"index":1,"url":"https://xxx.com/xxx/doc.html","title":"信源标题"}]'
                    }
                ]
            )
        )
    ], 
    created=1741878776, 
    model='xdeepseekv3', 
    object='chat.completion', 
    service_tier=None, 
    system_fingerprint=None, 
    usage=CompletionUsage(
        completion_tokens=346, 
        prompt_tokens=1124, 
        total_tokens=1470, 
        completion_tokens_details=None, 
        prompt_tokens_details=None
    )
)
```

#### 3.1.2 异常结果示例

```json
Error: Error code: 403 - {'error': {'message': '该令牌无权使用模型：xqwen257bxxx (request id: 2025020809381060443349905703260)', 'type': 'one_api_error'}}
```

### 3.2 响应数据参数

字段说明如下：

| 字段名                                                | 类型   | 字段说明                                                     |
| ----------------------------------------------------- | ------ | ------------------------------------------------------------ |
| id                                                    | string | 唯一标识符，标识本次对话调用的唯一ID，用于跟踪和调试         |
| choices                                               | array  | 包含模型生成回复候选项的数组                                 |
| &nbsp;&nbsp;•finish_reason                            | string | 指示回复生成结束的原因，如`"stop"`                           |
| &nbsp;&nbsp;•index                                    | int    | 回复候选项在数组中的索引位置，从0开始                        |
| &nbsp;&nbsp;•logprobs                                 | object | 如启用token概率日志，则返回具体信息                          |
| &nbsp;&nbsp;•message                                  | object | 描述回复消息内容的对象，其内部字段如下                       |
| &nbsp;&nbsp;&nbsp;&nbsp;◦content                      | string | 模型生成的回复文本内容                                       |
| &nbsp;&nbsp;&nbsp;&nbsp;◦reasoning_content            | string | 模型生成的思考文本内容(支持深度思考的模型才有此字段)         |
| &nbsp;&nbsp;&nbsp;&nbsp;◦plugins_content              | array  | 联网检索的信源结果列表(支持联网检索的模型才有此字段)         |
| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;◦name | string | 联网检索插件名称ifly_search等                                |
| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;◦name | string | 联网检索插件结果，此为信源结果列表，`index`序号，`url`信源地址，`title`信源标题 |
| &nbsp;&nbsp;&nbsp;&nbsp;◦refusal                      | object | 模型拒绝回答时返回拒绝信息                                   |
| &nbsp;&nbsp;&nbsp;&nbsp;◦role                         | string | 消息发送方，通常为`"assistant"`                              |
| &nbsp;&nbsp;&nbsp;&nbsp;◦audio                        | object | 如支持语音回复则返回音频数据                                 |
| &nbsp;&nbsp;&nbsp;&nbsp;◦function_call                | objec  | 模型调用外部函数时返回调用信息                               |
| &nbsp;&nbsp;&nbsp;&nbsp;◦tool_calls                   | object | 模型调用工具时返回调用详情，                                 |
| created                                               | int    | 响应生成时间的Unix时间戳（秒级）                             |
| model                                                 | string | 实际调用的模型名称                                           |
| object                                                | string | 表示响应对象类型                                             |
| service_tier                                          | string | 表示调用所属的服务层级                                       |
| system_fingerprint                                    | string | 系统指纹或配置标识                                           |
| usage                                                 | object | 包含token使用统计信息，其内部字段如下：                      |
| &nbsp;&nbsp;•completion_tokens                        | int    | 回复文本消耗的token数量                                      |
| &nbsp;&nbsp;•prompt_tokens                            | int    | 输入prompt消耗的token数量                                    |
| &nbsp;&nbsp;•total_tokens                             | int    | prompt与回复消耗token数量的总和                              |
| &nbsp;&nbsp;•completion_tokens_details                | object | 回复生成过程中token的详细统计信息，若无则为`null`            |
| &nbsp;&nbsp;•prompt_tokens_details                    | object | prompt部分token的详细统计信息                                |

##  4 . 错误码列表

| 错误码                                 | 原因                                      | 解决方案                                                |
| -------------------------------------- | ----------------------------------------- | ------------------------------------------------------- |
| 401-无效的身份验证                     | 身份验证无效。                            | 确保使用正确的API密钥及请求组织。                       |
| 401-提供的API密钥不正确                | 请求的API密钥不正确。                     | 检查所用API密钥是否正确，清除浏览器缓存或生成新的密钥。 |
| 403-不支持的国家、地区或领土           | 您正在从不支持的国家、地区或领土访问API。 | 请参考相关页面获取更多信息。                            |
| 429-请求速率限制已达上限               | 您发送请求过快。                          | 控制请求频率，阅读速率限制指南。                        |
| 429-超出当前配额，请检查计划和计费详情 | 您的额度已用尽或已达到每月最高消费限制。  | 购买更多额度或了解如何提高使用限制。                    |
| 500-服务器处理请求时发生错误           | 服务器内部出现问题。                      | 稍后重试请求；若问题持续，请联系我们查看状态页面。      |
| 503-引擎当前过载，请稍后重试           | 服务器流量过大。                          | 稍候重试您的请求。                                      |
# 精调服务_WebSocket协议
本文档旨在帮助开发者快速对接大模型 Web API 服务，详细描述接口调用方法、请求/响应参数、鉴权方式、WebSocket 连接管理及错误码信息。技术咨询可直接提交[工单](https://console.xfyun.cn/workorder/commit)

## 1. 接口概述

### 1.1 请求地址

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

```
wss://maas-api.cn-huabei-1.xf-yun.com/v1.1/chat
```
**说明**：部分模型因部署配置不同，其请求地址可能略有差异，具体可参考**服务管控**>**模型服务列表**右侧调用信息

### 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（调用微调大模型时必传） 
[demo python语言](https://openres.xfyun.cn/xfyundoc/2025-02-25/2440a0cc-11f3-46e7-920b-f49714f54003/1740484845579/python_ws_demo.zip) 
[demo java语言](https://openres.xfyun.cn/xfyundoc/2025-02-09/d8c9a423-5c0d-40e3-8480-a51045bb8e43/1739115838803/Java_demo.zip)

## 2. 接口请求

### 2.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",
            "tools":[
                {
                    "type": "web_search",
                    "web_search": {
                        "enable": True,
                        "show_ref_label": False,
                        "search_mode": "normal"
                    }
                }
            ]
        }
    },
    "payload": {
        "message": {
            "text": [
                {
                    "role": "system",
                    "content": "你是星火认知大模型"
                },
                {
                    "role": "user",
                    "content": "今天的天气"  
                }
            ]
        }
    }
}
```

###  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,32768]；默认值：2048 | 限制生成回复的最大 token 数量，max_tokens的限制需要满足`输入promptToken + 设置参数max_tokens <= 32768 - 1`,参数设置过大可能导致回答中断，请酌情调整，建议取值16384以下 |
| chat_id | string | 否 | 用于关联用户会话 | | 需保障用户下的唯一性 |
| tools | array | 否 | 通过该参数控制工具使用 | 工具列表 |
| tools.type | string | 是 | 可选值：web_search | 当前工具列表中，仅支持联网搜索工具； |
| tools.web_search | object | 否 | | |
| tools.web_search.enable | bool | 否，默认关闭（false） | true or false | enable：是否开启搜索功能，设置为true,模型会根据用户输入判断是否触发联网搜索，false则完全不触发； |
| tools.web_search.show_ref_label | bool | 否，默认关闭（false） | true or false | show_ref_label 开关控制触发联网搜索时是否返回信源信息（仅在enable为true时生效） 如果开启，则先返回搜索结果，之后再返回模型回复内容 |
| tools.web_search.search_mode | string | 否，默认标准搜索（normal） | deep/normal | search_mode 控制联网搜索策略（仅在enable为true时生效） normal：标准搜索模式，模型引用搜索返回的摘要内容回答问题 deep：深度搜索模式，模型引用搜索返回的全文内容，回复的更准确；同时会带来额外的token消耗 |
| enable_thinking | boolean | 否 | 是否切换思考模式 | 取值：[true,false]；默认值：true | **该参数仅Qwen3系列模型支持**。支持在单一模型内无缝切换思考模式（用于复杂的逻辑推理、数学和编程）和非思考模式（用于高效、通用的对话） |

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

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

| 字段 | 类型  | 是否必传 | 含义  | 限制 | 备注 |
| ---- | ----- | ---- | ---- | ---- | ---- |
| text | json object array | 是  | 文本数据 | 受Token限制，有效内容不能超过8192Token |   |

**单轮交互**：
仅传递一条用户消息：
```json
[
    {"role": "user", "content": "你会做什么？"}  
]
```

**多轮交互**：
按 `user -> assistant -> user -> assistant` 顺序传递历史记录，最后一条为当前问题：

```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|说明这是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 表示当前的回复疑似敏感，结果文本可以给用户展示。服务会在返回**全部结果**后再返回该错误码，如果继续提问可能会导致被审核拦截。建议在收到该错误码后提示用户涉及敏感信息，并禁掉对话框，禁止用户继续提问。

如果需要调整内容审核的严格程度、敏感词等信息，请联系我们技术支持。
# 大模型微调平台数据集格式说明

更新时间：2024.09.09 16:00:00

大模型微调平台支持**文本生成、文生图、图像分类**等**多模态**微调任务，以下为各类微调任务所需数据的**详细格式说明**：

# 一、文本生成数据格式说明

当前平台支持**星火大模型**以及第三方**开源大模型**，数据集支持**Alpaca格式**和**ShareGPT格式**，涵盖了行业**所有主流的数据格式**，以下为**详细格式说明**：

## 1.Alpaca格式说明
在Alpaca格式下的**指令监督微调**中，**instruction**列对应的内容会与**input**列对应的内容**拼接**后作为**人类指令**，即人类指令为**instruction\input**。而**output**列对应的内容为**模型回答**。如果指定，**system**列对应的内容将被作为**系统提示词**。**history**列是由**多个字符串二元组**构成的**列表**，分别代表历史消息中**每轮对话的指令和回答**。

>**注:** **历史消息**中的**回答内容**也会被**用于模型学习**。

```
[
  {
	"instruction": "人类指令（必填）",
	"input": "人类输入（选填）",
	"output": "模型回答（必填）",
	"system": "系统提示词（选填）",
	"history": [
	  ["第一轮指令（选填）", "第一轮回答（选填）"],
	  ["第二轮指令（选填）", "第二轮回答（选填）"]
	]
  }
]
```

- 对于上述格式的数据，dataset_info.json中的数据集描述应为：
```
"数据集名称": {
 "file_name": "data.json",
	"columns": {
	"prompt": "数据集代表提示词的表头名称（默认：instruction）",
	"query": "数据集代表请求的表头名称（默认：input）",
	"response": "数据集代表回答的表头名称（默认：output）",
	"system": "数据集代表系统提示的表头名称（默认：system）",
	"history": "数据集代表历史对话的表头名称（默认：history）"
 }
}
```
- Alpaca格式数据具体示例如下：
```
 {
	"instruction": "描述一个可以从人工智能技术中受益的医疗应用。",
	"input": "",
	"output": "用于帮助医生诊断疾病的人工智能辅助诊断系统可以被视为一个可以从人工智能技术中受益的医疗应用。这种系统通过使用深度学习算法来分析患者的病史、临床数据和医学影像资料，能够为医生提供准确的诊断建议。\n\n例如，人工智能技术可以用来分析X光片、 CT扫描和MRI扫描图像，帮助医生诊断肺炎，肿瘤，中风等疾病。此外，通过分析大量患者数据，人工智能系统能够找出患病风险较高的人群并预测潜在健康问题，从而为预防性医疗提供有力支持。\n\n这类人工智能系统不仅能够提高诊断准确性，还能帮助医生节约时间，让他们能够更好地关注患者的治疗。因此，人工智能辅助诊断系统是一个可以从人工智能技术中受益的医疗应用，具有广阔的发展前景。",
	"system": "",
	"history": ""
 }
```
## 2.ShareGPT 格式说明
相比Alpaca格式的数据集，**ShareGPT格式**支持**更多的角色种类**，例如**human、gpt、observation、function**等。它们构成一个对象列表呈现在**conversations**列中。
>**注:** 其中**human**和**observation必须**出现在**奇数位置**，**gpt**和**function**必须出现在**偶数位置**。
```
[
 {
	"conversations": [
	 {
		"from": "human",
		"value": "人类指令"
	 },
	 {
		"from": "function_call",
		"value": "工具参数"
	 },
	 {
		"from": "observation",
		"value": "工具结果"
	 },
	 {
		"from": "gpt",
		"value": "模型回答"
	 }
	]（必填）,
	"system": "系统提示词（选填）",
	"tools": "工具描述（选填）"
 }
]
```
- 对于上述格式的数据，dataset_info.json中的数据集描述应为：
```
"数据集名称": {
 "file_name": "data.json",
 "formatting": "sharegpt",
 "columns": {
	"messages": "数据集代表消息列表的表头名称（默认：conversations）",
	"system": "数据集代表系统提示的表头名称（默认：system）",
	"tools": "数据集代表工具描述的表头名称（默认：tools）"
 },
 "tags": {
	"role_tag": "消息中代表发送者身份的键名（默认：from）",
	"content_tag": "消息中代表文本内容的键名（默认：value）",
	"user_tag": "消息中代表用户的 role_tag（默认：human）",
	"assistant_tag": "消息中代表助手的 role_tag（默认：gpt）",
	"observation_tag": "消息中代表工具返回结果的 role_tag（默认：observation）",
	"function_tag": "消息中代表工具调用的 role_tag（默认：function_call）",
	"system_tag": "消息中代表系统提示的 role_tag（默认：system）"
 }
}
```
- ShareGPT格式数据具体示例如下：
```
 {
	"conversations": [
	 {
		"from": "human",
		"value": "你好，我出生于1990年5月15日。你能告诉我我今天几岁了吗？"
	 },
	 {
		"from": "function_call",
		"value": "{\"name\": \"calculate_age\", \"arguments\": {\"birthdate\": \"1990-05-15\"}}"
	 },
	 {
		"from": "observation",
		"value": "{\"age\": 31}"
	 },
	 {
		"from": "gpt",
		"value": "根据我的计算，你今天31岁了。"
	 }
	],
	"tools": "[{\"name\": \"calculate_age\", \"description\": \"根据出生日期计算年龄\", \"parameters\": {\"type\": \"object\", \"properties\": {\"birthdate\": {\"type\": \"string\", \"description\": \"出生日期以YYYY-MM-DD格式表示\"}}, \"required\": [\"birthdate\"]}}]"
 }
```
## 3.推理集格式说明
在**文本生成任务**中，**推理集**用于**检测模型微调效果**，平台支持**jsonl格式**和**csv格式**。
- jsonl格式文件要求如下:
> 1. **jsonl文件**内每条**数据格式**要求为 **{“input”:“你的问题”，“target”:“回答内容”}**。
> 2. 每一行表示一组数据，**每组数据**中的**input和target加起来之和**字符数**不超过4000个字符(包括中英文、数字、符号等)**，超出部分将被截断。
> 3. 支持**文本文件类型为JSONL**，**编码**仅支持**UTF-8**，单次上传**限制1个文件**。
> 4. 训练集数量**spark pro≥1500条**，**sparklite≥100条**，**文件<500M**;**测试集数量范围为10-200条**。
- jsonl具体数据格式示例如下：
```
{"input":"买房银行贷款贷多少年。","target":"1、个人住房贷款最长为30年；2、个人商业贷款最长期限为10年。"}
```
- csv格式文件要求如下:
> 1. 文件内单组数据**表格一行代表一组数据**，**第一列为input**，**第二列为target**。
> 2. **每一行表示一组数据**，**每组数据**中的**input和target加起来之和**字符数**不超过4000个字符(包括中英文、数字、符号等)**，超出部分将被截断。
> 3. 支持**文本文件类型为 csv**，**编码**仅支持**UTF-8**，单次上传**限制1个文件**。
> 4. 训练集数量**spark pro≥1500条**，**sparklite>100条**，**文件<500M**;**测试集数量范围为10-200条**。

- csv具体数据格式示例如下：

|input |target |
|--------------------------------| ------------------------------|
|大润发住房公积金贷二手房能贷多少钱。|各地公积金政策有所不同，建议通过官网查询或者咨询当地公积金管理中心，官方电话是12#29。 |
|...|... |

# 二、文生图数据格式说明

当前平台支持第三方**Stable-Diffusion模型**，微调数据集为**图片+Prompt**，图片格式支持**jpg、jpeg、png、bmp**等，**Prompt**为**jsonl格式**，**图片比例为1：1**，单张图片大小需**限制在4MB**以内，一个数据集总图片数**不少于20张**，**不大于1000张**，仅支持**zip压缩**上传。

![](http://xfyun-doc.xfyun.cn/lc-sp-2-1726294488417.png)
- 具体数据格式示例如下：

|000.jpeg |metadata.jsonl |
|--------------------------------| ------------------------------|
|![](http://xfyun-doc.xfyun.cn/lc-sp-1-1726294481512.jpg)|{"file_name": "000.jpeg", "text": "a drawing of a green pokemon with red eyes"} |
|...|...|
> 注: **Prompt**支持**中文和英文**两种语言，**英文Prompt**效果**更佳**。

# 三、图像分类数据格式说明
当前平台支持第三方**Vision Transformer（ViT）模型**，微调数据集为**图片**，图片格式支持**jpg、jpeg、png、bmp**等，图片大小在**4M内**，一个数据集总图片数**不少于100张**，**不大于20000张**，压缩包**不大于500M**，压缩包内应**至少包含两个文件夹**，**文件夹名为标签名**需以**英文命名**，**图片文件可中英文命名**仅支持**zip压缩**上传。

![](http://xfyun-doc.xfyun.cn/lc-sp-3-1726294491534.png)
- 具体数据格式示例如下：

| lily|peony|... |
|----------------|--------------------------------| ------------------------------|
|![](http://xfyun-doc.xfyun.cn/lc-sp-4-1726294495080.jpg)|![](http://xfyun-doc.xfyun.cn/lc-sp-5-1726294498564.jpg)|... |
|...|... |... |

# 图片分类 WebAPI文档

- 注意：文中的\<service-id\>表示需要修改成自己训练后的服务ID，不带尖括号
- 部分开发语言demo如下，其他开发语言请参照文档进行开发，也欢迎热心的开发者到 [讯飞开放平台社区](https://developer.xfyun.cn/) 分享你们的demo。

[图片分类 demo python语言](https://xfyun-doc.xfyun.cn/lc-sp-lc-sp-imageclassification%20demo-1715396640465-1733709937370.zip)

#### 接口地址

```
https://xingchen.cn-huabei-2.xf-yun.com/v1/private/<service-id>
```

#### 请求协议

```
{
 "header": {
 "app_id": "123456",
 "uid": "",
 "did": "",
 "imei": "",
 "imsi": "",
 "mac": "",
 "net_type": "wifi",
 "net_isp": "CMCC",
 "status": 3,
 "request_id": null,
 "res_id": ""
 },
 "parameter": {
 "<service-id>": {
 "atp_patch_id": "0",
 "result": {
 "encoding": "utf8",
 "compress": "raw",
 "format": "plain"
 }
 }
 },
 "payload": {
 "image": {
 "encoding": "jpg",
 "image": "",
 "status": 3
 }
 }
}
```

#### 协议**结构说明**

### 请求参数

#### 平台参数

#### 服务特性参数

**响应数据参数**

result 段的参数（默认返回）

| 字段     | 含义         | 数据类型 | 取值范围         | 默认值 | 说明           | 必填 |
| :------- | :----------- | :------- | :--------------- | :----- | :------------- | :--- |
| encoding | 文本编码     | string   | utf8, gb2312     | utf8   | 取值范围可枚举 | 否   |
| compress | 文本压缩格式 | string   | raw, gzip        | raw    | 取值范围可枚举 | 否   |
| format   | 文本格式     | string   | plain, json, xml | plain  | 取值范围可枚举 | 否   |

#### 请求数据

image

| 字段     | 含义     | 数据类型 | 取值范围                                             | 默认值 | 说明                      | 必填 |
| :------- | :------- | :------- | :--------------------------------------------------- | :----- | :------------------------ | :--- |
| encoding | 图像编码 | string   | jpg:jpg格式, jpeg:jpeg格式, png:png格式, bmp:bmp格式 | jpg    | 图像编码                  | 否   |
| image    | 图像数据 | string   | 最小尺寸:0B, 最大尺寸:4194304B                       |        | 图像数据，base64          | 是   |
| status   | 数据状态 | int      | 3:一次性传完                                         | 3      | 取值范围为：3（一次传完） | 否   |

## 响应

### 响应协议示例

```
{
    "header": {
        "code": 0,
        "message": "success",
        "sid": "ase000704fa@dx16ade44e4d87a1c802"
    },
    "payload": {
        "result": {
            "encoding": "utf8",
            "compress": "raw",
            "format": "json",
            "status": 3,
            "text": ""
        }
    }
}
```

**协议结构说明**

### 响应参数

####  平台参数

| 字段    | 含义                            | 类型   | 是否必选 |
| :------ | :------------------------------ | :----- | :------- |
| code    | 返回码，0表示成功，其它表示异常 | int    | 是       |
| message | 错误描述                        | string | 是       |
| sid     | 本次会话的id                    | string | 是       |

#### 响应数据参数

result（默认返回）

| 字段     | 含义         | 数据类型 | 取值范围                     | 默认值 | 说明                      | 必填 |
| :------- | :----------- | :------- | :--------------------------- | :----- | :------------------------ | :--- |
| encoding | 文本编码     | string   | utf8, gb2312                 | utf8   | 取值范围可枚举            | 否   |
| compress | 文本压缩格式 | string   | raw, gzip                    | raw    | 取值范围可枚举            | 否   |
| format   | 文本格式     | string   | plain, json, xml             | json   | 取值范围可枚举            | 否   |
| status   | 数据状态     | int      | 3:一次性传完                 | 3      | 取值范围为：3（一次传完） | 否   |
| text     | 文本数据     | string   | 最小长度:0, 最大长度:1000000 |        |                           | 是   |

#### 错误码列表

| 错误码           | 错误描述                                         | 说明                         | 处理策略                                                                                                                     |
|---------------|----------------------------------------------|----------------------------|--------------------------------------------------------------------------------------------------------------------------|
| 10009         | input invalid data                           | 输入数据非法                     | 检查输入数据                                                                                                                   |
| 10010         | service license not enough                   | 没有授权许可或授权数已满               | 提交工单                                                                                                                     |
| 10019         | service read buffer timeout, session timeout | session超时                  | 检查是否数据发送完毕但未关闭连接                                                                                                         |
| 10043         | Syscall AudioCodingDecode error              | 音频解码失败                     | 检查aue参数，如果为speex，请确保音频是speex音频并分段压缩且与帧大小一致                                                                               |
| 10114         | session timeout                              | session 超时                 | 会话时间超时，检查是否发送数据时间超过了60s                                                                                                  |
| 10139         | invalid param                                | 参数错误                       | 检查参数是否正确                                                                                                                 |
| 10160         | parse request json error                     | 请求数据格式非法                   | 检查请求数据是否是合法的json                                                                                                         |
| 10161         | parse base64 string error                    | base64解码失败                 | 检查发送的数据是否使用base64编码了                                                                                                     |
| 10163         | param validate error:...                     | 参数校验失败                     | 具体原因见详细的描述                                                                                                               |
| 10200         | read data timeout                            | 读取数据超时                     | 检查是否累计10s未发送数据并且未关闭连接                                                                                                    |
| 10222         | context deadline exceeded                    | 1.上传的数据超过了接口上限； 2.SSL证书无效； | 1.检查接口上传的数据（文本、音频、图片等）是否超越了接口的最大限制，可到相应的接口文档查询具体的上限； 2. 请将log导出发到工单：https://console.xfyun.cn/workorder/commit；           |
| 10223         | RemoteLB: can't find valued addr             | lb 找不到节点                   | 提交工单                                                                                                                     |
| 10313         | invalid appid                                | appid和apikey不匹配            | 检查appid是否合法                                                                                                              |
| 10317         | invalid version                              | 版本非法                       | 请到控制台提交工单联系技术人员                                                                                                          |
| 10700         | not authority                                | 引擎异常                       | 按照报错原因的描述，对照开发文档检查输入输出，如果仍然无法排除问题，请提供sid以及接口返回的错误信息，到控制台提交工单联系技术人员排查。                                                    |
| 11200         | auth no license                              | 功能未授权                      | 请先检查appid是否正确，并且确保该appid下添加了相关服务。若没问题，则按照如下方法排查。 1. 确认总调用量是否已超越限制，或者总次数授权已到期，若已超限或者已过期请联系商务人员。 2. 查看是否使用了未授权的功能，或者授权已过期。 |
| 11201         | auth no enough license                       | 该APPID的每日交互次数超过限制          | 根据自身情况提交应用审核进行服务量提额，或者联系商务购买企业级正式接口，获得海量服务量权限以便商用。                                                                       |
| 11503         | server error :atmos return an error data     | 服务内部响应数据错误                 | 提交工单                                                                                                                     |
| 11502         | server error: too many datas in resp         | 服务配置错误                     | 提交工单                                                                                                                     |
| 100001~100010 | WrapperInitErr                               | 调用引擎时出现错误                  | 请根据message中包含的errno前往 5.2引擎错误码 查看对应的说明及处理策略                                                                              |

# 图像理解_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（调用微调大模型时必传） 
[图像理解demo python语言](https://openres.xfyun.cn/xfyundoc/2025-05-15/f0bf753a-c395-403d-a17b-29d698c5ecd3/1747275337416/sparkAPI_WS_Olm.py.zip)

## 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  | 授权错误：并发流控超限。并发路数超过授权路数限制。（联系我们提高限制） |