星火认知大模型Web API文档
1. 接口说明
注意： 该接口可以正式使用。如您需要申请使用，请点击前往产品页面 。
Tips：
- 计费包含接口的输入和输出内容
- 1tokens 约等于1.5个中文汉字 或者 0.8个英文单词
- 星火V1.5支持[搜索]内置插件；星火V2.0和V3.0支持[搜索]、[天气]、[日期]、[诗词]、[字词]、[股票]六个内置插件
- 星火V3.0 现已支持 Function Call 功能。
#1.1 请求地址
Tips: 星火大模型API当前有V1.5、V2.0和V3.0三个版本，三个版本独立计量tokens。
星火大模型V1.5请求地址，对应的domain参数为general：
ws(s)://spark-api.xf-yun.com/v1.1/chat
星火大模型V2请求地址，对应的domain参数为generalv2：
ws(s)://spark-api.xf-yun.com/v2.1/chat
星火大模型V3请求地址，对应的domain参数为generalv3：
ws(s)://spark-api.xf-yun.com/v3.1/chat
#1.2 接口鉴权
#1.3 接口请求
#1.3.1 请求参数
# 参数构造示例如下
{
"header": {
"app_id": "12345",
"uid": "12345"
},
"parameter": {
"chat": {
"domain": "general",
"temperature": 0.5,
"max_tokens": 1024,
}
},
"payload": {
"message": {
# 如果想获取结合上下文的回答，需要开发者每次将历史问答信息一起传给服务端，如下示例
# 注意：text里面的所有content内容加一起的tokens需要控制在8192以内，开发者如有较长对话需求，需要适当裁剪历史信息
"text": [
{"role": "user", "content": "你是谁"} # 用户的历史问题
{"role": "assistant", "content": "....."} # AI的历史回答结果
# ....... 省略的历史对话
{"role": "user", "content": "你会做什么"} # 最新的一条问题，如无需上下文，可只传最新一条问题
]
}
}
}
接口请求字段由三个部分组成：header，parameter, payload。 字段解释如下
header部分
| 参数名称 | 类型 | 必传 | 参数要求 | 参数说明 |
|---|---|---|---|---|
| app_id | string | 是 | 应用appid，从开放平台控制台创建的应用中获取 | |
| uid | string | 否 | 最大长度32 | 每个用户的id，用于区分不同用户 |
parameter.chat部分
| 参数名称 | 类型 | 必传 | 参数要求 | 参数说明 |
|---|---|---|---|---|
| domain | string | 是 | 取值为[general,generalv2,generalv3] | 指定访问的领域,general指向V1.5版本,generalv2指向V2版本,generalv3指向V3版本 。注意：不同的取值对应的url也不一样！ |
| temperature | float | 否 | 取值为[0,1],默认为0.5 | 核采样阈值。用于决定结果随机性，取值越高随机性越强即相同的问题得到的不同答案的可能性越高 |
| max_tokens | int | 否 | V1.5取值为[1,4096] V2.0取值为[1,8192]，默认为2048。 V3.0取值为[1,8192]，默认为2048。 | 模型回答的tokens的最大长度 |
| 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的对话内容 |
#1.4 接口响应
# 接口为流式返回，此示例为最后一次返回结果，开发者需要将接口多次返回的结果进行拼接展示
{
"header":{
"code":0,
"message":"Success",
"sid":"cht000cb087@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大小 |
#2.Function Call说明
注：当前仅V3.0 版本支持了该功能
#2.1接口请求
#2.1.1 请求示例
# 参数构造示例如下,仅在原本生成的基础上，增加了functions.text字段，用于方法的注册
{
"header": {
"app_id": appid,
"uid": "1234"
},
"parameter": {
"chat": {
"domain": domain,
"random_threshold": 0.5,
"max_tokens": 2048,
"auditing": "default"
}
},
"payload": {
"message": {
"text": [
{"role": "user", "content": ""} # 用户的提问
]
},
"functions": {
"text": [
{
"name": "天气查询",
"description": "天气插件可以提供天气相关信息。你可以提供指定的地点信息、指定的时间点或者时间段信息，来检索诗词库，精准检索到天气信息。",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "地点，比如北京。"
},
"date": {
"type": "string",
"description": "日期。"
}
},
"required": [
"location"
]
}
},
{
"name": "税率查询",
"description": "税率查询可以查询某个地方的个人所得税率情况。你可以提供指定的地点信息、指定的时间点，精准检索到所得税率。",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "地点，比如北京。"
},
"date": {
"type": "string",
"description": "日期。"
}
},
"required": [
"location"
]
}
}
]
}
}
}
#2.1.2参数说明
接口请求payload.functions字段解释如下：
| 参数名称 | 类型 | 必传 | 参数要求 | 参数说明 |
|---|---|---|---|---|
| text | array | 是 | 列表形式，列表中的元素是json格式 | 元素中包含name、description、parameters属性 |
| name | string | 是 | function名称 | 用户输入命中后，会返回该名称 |
| description | string | 是 | function功能描述 | 描述function功能即可，越详细越有助于大模型理解该function |
| parameters | json | 是 | function参数列表 | 包含type、properties、required字段 |
| parameters.type | string | 是 | 参数类型 | |
| parameters.properties | string | 是 | 参数信息描述 | 该内容由用户定义，命中该方法时需要返回哪些参数 |
| properties.x.type | string | 是 | 参数类型描述 | 该内容由用户定义，需要返回的参数是什么类型 |
| properties.x.description | string | 是 | 参数详细描述 | 该内容由用户定义，需要返回的参数的具体描述 |
| parameters.required | array | 是 | 必须返回的参数列表 | 该内容由用户定义，命中方法时必须返回的字段 |
#2.2接口响应
#2.2.1示例如下
// 触发了function_call的情况下，只会返回一帧结果，其中status 为2
{"header":{"code":0,"message":"Success","sid":"cht000b41d5@dx18b851e6931b894550","status":2},"payload":{"choices":{"status":2,"seq":0,"text":[{"content":"","role":"assistant","content_type":"text","function_call":{"arguments":"{\"datetime\":\"今天\",\"location\":\"合肥\"}","name":"天气查询"},"index":0}]},"usage":{"text":{"question_tokens":3,"prompt_tokens":3,"completion_tokens":0,"total_tokens":3}}}}
#2.2.2返回字段说明
| 字段名 | 类型 | 字段说明 |
|---|---|---|
| function_call | json | function call 返回结果 |
| function_call.arguments | json | 客户在请求体中定义的参数及参数值 |
| function_call.name | string | 客户在请求体中定义的方法名称 |
#3. 调用示例
注: demo只是一个简单的调用示例，不适合直接放在复杂多变的生产环境使用
最后修改时间： 1 年前