# 多语种大模型Web API文档
# 1. Spark API Multi-Langs 协议描述
本协议用于描述 Spark Multi-Langs 多语种大模型集成接口协议
本API服务为多语种大模型的产品化接口，当前仅支持日、韩、俄、阿、法、西、葡、德 8种语言
# 2. 接口说明
# 2.1 请求方法和URL
url : wss://spark-api-n.xf-yun.com/v1.1/chat_multilang
domain : multilang
每次交互需要重新建立websocket连接，当完成交互时，需要请求侧主动发送close消息，完成接口的断开
如果在生成的过程中需要终止，可以直接发送websocket的close消息，关闭连接即可
# 2.2 接口Demo
参见下方demo，目前仅支持日、韩、俄、阿、法、西、葡、德 8种语言
（使用demo之前，你需要修改代码中的app_id，key和secret 鉴权参数）
Java 调用示例 (opens new window)
Python 调用示例 (opens new window)
# 2.3 接口要求
接口类型：流式 ws(s)
接口鉴权：使用签名机制进行鉴权，签名详情
# 3. 请求
# 3.1 请求协议示例
{
"header": {
"app_id": "123456",
"uid": "39769795890"
},
"parameter": {
"chat": {
"domain": "multilang"
"temperature": 0.5,
"top_k": 4,
"max_tokens": 2048,
"chat_id": "xxx",
}
},
"payload": {
"message": {
"text": [
{
"role": "user",
"content": "[多语种文本]"
}
]
}
}
}
# 3.2 请求参数
# 3.2.1 平台参数
header部分的字段介绍：
| 字段名 | 类型 | 是否必传 | 含义 |
|---|---|---|---|
| header.app_id | string | 是 | 应用appid，从开放平台控制台创建的应用中获取 |
| header.uid | string | 否 | 每个用户的id，非必传字段，用于后续扩展 |
# 3.2.2 服务特性参数
# 3.2.2.1 对话服务参数
| 字段名 | 类型 | 是否必传 | 含义 | 备注 | 默认值 |
|---|---|---|---|---|---|
| parameter.chat | object | 是 | 用于上传对话的参数信息 | ||
| parameter.chat.domain | string | 是 | 需要使用的领域 | multilang | |
| parameter.chat.temperature | float | 否 | 核采样阈值,向上调整可以增加结果的随机程度 | 取值范围 (0，1] | 0.5 |
| parameter.chat.top_k | int | 否 | 从k个中随机选择一个(非等概率) | 最小值1，最大值6。 | 4 |
| parameter.chat.max_tokens | int | 否 | 回答的tokens的最大长度 | 最小值是1, 最大值是8192。 | 8192 |
| parameter.chat.chat_id | string | 否 | 用于关联会话chat | 需要保障用户下唯一 |
# 3.2.3 请求数据
# 3.2.3.1 文本数据
payload.message.text部分
注意：
1、text下所有content累计内容 tokens需要控制在128k内。
2、如果传入system参数，需要保证第一条是system；多轮交互需要将之前的交互历史按照system-user-assistant-user-assistant进行拼接
| 字段 | 含义 | 数据类型 | 取值范围 | 默认值 | 说明 | 必填 |
|---|---|---|---|---|---|---|
| text | 文本数据 | json object array | 支持128k Token输入 | 是 |
单轮交互示例说明：
单轮交互只需要传递一个user角色的数据
[
// 用户的提问
{"role": "user", "content": "你会做什么？"}
]
多轮交互的格式示例：
多轮交互需要将之前的交互历史按照system->user->assistant->user->assistant规则进行拼接，并保证最后一条是user的当前问题。
[
// 拼接对话历史信息:
{"role": "system", "content": "你是一个聊天的人工智能助手"},
{"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 | system，user, assistant | system用于设置对话背景，user表示是用户的问题，assistant表示AI的回复 | |
| content | 文本内容 | string | -- | 该角色的对话内容 |
# 4. 响应
# 4.1 响应协议示例
# 4.1.1 结果示例
{
"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
}
},
"question_type":""
}
}
# 4.1.2 异常结果
{
"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格式解析
[
{
"content": "这是AI的回复文本",
"index": 0,
"role": "assistant"
}
]
解析：
| 字段 | 含义 | 数据类型 | 默认值 | 说明 |
|---|---|---|---|---|
| content | 回答的结果 | string | -- | -- |
| index | 结果序号，在多候选中使用 | int | 0 | -- |
| role | 角色 | string | assistant | assistant说明这是AI的回复 |
# 4.3.2 payload.usage.text格式解析
{
"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. 错误码列表
| 错误码 | 错误信息 |
|---|---|
| 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 | 授权错误：并发流控超限。并发路数超过授权路数限制。（联系我们提高限制） |
| 10020 | 语种不支持 |
在这篇文章中：
