# 开源大模型Web API文档
# 1 请求地址
默认请求地址如下
wss://maas-api.cn-huabei-1.xf-yun.com/v1.1/chat
部分模型因为部署原因可能略有差异,具体可参考服务管控中的模型服务列表右侧调用信息。
# 2 接口鉴权
参考通用URL鉴权文档 (opens new window)
# 3 接口请求
# 请求参数
{
"header": {
"app_id": "12345",
"uid": "12345"
"patch_id": "[<your-resource-id>]"
},
"parameter": {
"chat": {
"domain": "<your-service-id>",
"temperature": 0.5
}
},
"payload": {
"message": {
# 如果想获取结合上下文的回答,需要开发者每次将历史问答信息一起传给服务端,如下示例
# 注意:text里面的所有content内容加一起的tokens需要控制在8192以内,开发者如有较长对话需求,需要适当裁剪历史信息
"text": [
{"role": "user", "content": "你会做什么"} # 最新的一条问题,如无需上下文,可只传最新一条问题
]
}
}
}
说明:
- 示例中的<your-service-id>表示需要修改成自己训练后的serviceId,不带尖括号
- 示例中的<your-resource-id>表示需要修改成自己训练后的resourceId,不带尖括号
接口请求字段由三个部分组成:header,parameter, payload。 字段解释如下
header部分
参数名称 | 类型 | 必传 | 参数要求 | 参数说明 |
---|---|---|---|---|
app_id | string | 是 | 应用appid,从开放平台控制台创建的应用中获取 | |
uid | string | 否 | 最大长度32 | 每个用户的id,用于区分不同用户 |
patch_id | string | 否 | 调用微调大模型时必传,否则不传。对应resourceid |
parameter.chat部分
参数名称 | 类型 | 必传 | 参数要求 | 参数说明 |
---|---|---|---|---|
domain | string | 是 | 取值为用户服务的serviceId | serviceId可从星辰网页获取 |
temperature | float | 否 | 取值为[0,1],默认为0.5 | 核采样阈值。用于决定结果随机性,取值越高随机性越强即相同的问题得到的不同答案的可能性越高 |
top_k | int | 否 | 取值为[1,6],默认为4 | 从k个候选中随机选择⼀个(⾮等概率) |
chat_id | string | 否 | 需要保障用户下的唯一性 | 用于关联用户会话 |
payload.message.text部分
注:text下所有content累计内容 tokens需要控制在8192内
参数名称 | 类型 | 必传 | 参数要求 | 参数说明 |
---|---|---|---|---|
role | string | 是 | 取值为[user,assistant] | user表示是用户的问题,assistant表示AI的回复 |
content | string | 是 | 所有content的累计tokens需控制8192以内 | 用户和AI的对话内容 |
# 4 接口响应
# 接口为流式返回,此示例为最后一次返回结果,开发者需要将接口多次返回的结果进行拼接展示
{
"header":{
"code":0,
"message":"Success",
"sid":"olm000cb087@dx18793cd421fb894542",
"status":2
},
"payload":{
"choices":{
"status":2,
"seq":0,
"text":[
{
"content":"我可以帮助你的吗?",
"role":"assistant",
"index":0
}
]
},
"usage":{
"text":{
"question_tokens":4,
"prompt_tokens":5,
"completion_tokens":9,
"total_tokens":14
}
}
}
}
接口返回字段分为两个部分,header,payload。字段解释如下
header部分
字段名 | 类型 | 字段说明 |
---|---|---|
code | int | 错误码,0表示正常,非0表示出错;详细释义可在接口说明文档最后的错误码说明了解 |
message | string | 会话是否成功的描述信息 |
sid | string | 会话的唯一id,用于讯飞技术人员查询服务端会话日志使用,出现调用错误时建议留存该字段 |
status | int | 会话状态,取值为[0,1,2];0代表首次结果;1代表中间结果;2代表最后一个结果 |
payload.choices部分
字段名 | 类型 | 字段说明 |
---|---|---|
status | int | 文本响应状态,取值为[0,1,2]; 0代表首个文本结果;1代表中间文本结果;2代表最后一个文本结果 |
seq | int | 返回的数据序号,取值为[0,9999999] |
content | string | AI的回答内容 |
role | string | 角色标识,固定为assistant,标识角色为AI |
index | int | 结果序号,取值为[0,10]; 当前为保留字段,开发者可忽略 |
payload.usage部分(在最后一次结果返回)
字段名 | 类型 | 字段说明 |
---|---|---|
question_tokens | int | 保留字段,可忽略 |
prompt_tokens | int | 包含历史问题的总tokens大小 |
completion_tokens | int | 回答的tokens大小 |
total_tokens | int | prompt_tokens和completion_tokens的和,也是本次交互计费的tokens大小 |
# 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 | 授权错误:并发流控超限。并发路数超过授权路数限制。(联系我们提高限制) |
在这篇文章中: