# 星火大模型 可定制化API 文档
# 一、服务介绍
星火定制化API ,内置丰富的标准场景,开发者能够依据自身业务领域,选取对应的偏好场景,充分释放大模型在垂类业务下的理解与任务处理能力。同时集成 RAG 和联网搜索工具,支持对公域和私域知识进行混合检索,使知识问答更加准确且个性化。
# 二、接口 Demo
部分开发语言Demo如下,其他开发语言请参照文档进行开发,欢迎大家到讯飞开放平台社区 (opens new window)交流集成经验。
可定制化API-Demo-Java (opens new window)
可定制化API-Demo-Python (opens new window)
# 三、星火大模型可定制API接口
# 接口鉴权
请参考通用URL鉴权文档 (opens new window)说明
# 3.1、接口描述
页面化策略配置完成后,通过该接口进行服务调用;除了可以支持各类场景的问答外,还可以链接本地知识库和联网检索能力,来适配各类任务需求
# 3.2、接口地址
注意:请求体中对应的domain参数为max
wss://sparkcube-api.xf-yun.com/v1/customize
# 3.3、请求参数
接口请求参数由三个部分组成:header,parameter,payload。请求参数示例及参数解释如下
{
"header": {
"app_id": "这里填写应用appid,从开放平台控制台创建的应用中获取",
"uid": "123456"
},
"parameter": {
"chat": {
"domain": "max",
"temperature": 0.5,
"top_k": 4,
"max_tokens": 8192
}
},
"payload": {
"message": {
"text": [
{
"role": "user",
"content": [
{
"type": "file",
"file": [
"file_id1",
"file_id2"
]
},
{
"type": "text",
"text": "请总结两篇文章的不同点"
}
]
},
{
"role": "assistant",
"content": "两篇文章有几个不同点......"
},
{
"role": "user",
"content": [
{
"type": "file",
"file": [
"file_id3"
]
},
{
"type": "text",
"text": "总结下这篇文章"
}
]
}
]
}
}
}
header部分
参数名称 | 类型 | 必传 | 参数要求 | 参数说明 |
---|---|---|---|---|
app_id | string | 是 | 应用appid,从开放平台控制台创建的应用中获取 | |
uid | string | 否 | 每个用户的id,非必传字段,用于后续扩展 ,"maxLength":32 |
parameter.chat部分
参数名称 | 类型 | 必传 | 参数要求 | 参数说明 |
---|---|---|---|---|
domain | string | 是 | 取值为max | 指定访问的模型版本: 指向Max版本 |
temperature | float | 否 | 取值范围 (0,1] ,默认为0.5 | 核采样阈值,用于决定结果随机性。 取值越高随机性越强即相同的问题得到的不同答案的可能性越高 |
max_tokens | int | 否 | 取值范围[1,8192],默认为4096 | 模型回答的tokens的最大长度 |
top_k | int | 否 | 取值范围[1,6],默认为4 | 从k个候选中随机选择⼀个(⾮等概率) |
payload.message.text部分
注意:1、请确保text下所有content内容累计的tokens数量在模型上下文长度的限制之内。
2、如果传入system参数,需要保证第一条是system;多轮交互需要将之前的交互历史按照system-user-assistant-user-assistant进行拼接
参数名称 | 类型 | 是否必填 | 参数说明 |
---|---|---|---|
text | List | 是 | 调用语言模型时,将当前对话信息列表作为提示输入给模型, 按照 json 数组形式进行传参。可能的消息类型包括 System message、User message、Assistant message 和 Tool message。 尽量避免在系统指令中定义工具或者工具名,可能与已有工具名称冲突,影响工具使用的效果。 |
text.role | String | 是 | Role 包括 system,user,assistant和tool |
text.content | List | 是 | 当轮消息不含有file时{"role":"user","content":[{"type":"text","text":"今合肥本周天气怎么样"}]} 当轮消息含有file时 {"role":"user","content":[{"type":"file","file":["file_id3"]},{"type":"text","text":"总结下这篇文章"}]} |
text.content.type | String | 是 | 类型 text:用户输入 、file:用户文件列表,分号分割 |
text.content.text | String | 是 | type是 text 时补充 |
text.content.file | List | 否 | type是 file时补充,文件id列表 |
# 3.4、响应参数
接口响应参数由两个部分组成:header,payload。响应参数示例及参数解释如下
# 接口为流式返回,此示例为最后一次返回结果,开发者需要将接口多次返回的结果进行拼接展示
{
"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部分
字段名 | 类型 | 字段说明 |
---|---|---|
code | int | 错误码,0表示正常,非0表示出错;详细释义可在接口说明文档最后的错误码说明了解 |
message | string | 会话是否成功的描述信息 |
sid | string | 会话的唯一id,用于讯飞技术人员查询服务端会话日志使用,出现调用错误时建议留存该字段 |
status | int | 会话状态,取值为[0,1,2];0代表首次结果;1代表中间结果;2代表最后一个结果 |
payload.choices部分
参数名称 | 类型 | 参数说明 |
---|---|---|
cus | int | 文本响应状态,取值为[0,1,2]; 0代表首个文本结果;1代表中间文本结果;2代表最后一个文本结果 |
seq | int | 返回的数据序号,取值为[0,9999999] |
content | string | AI的回答内容 |
role | string | 角色标识,固定为assistant,标识角色为AI |
index | int | 结果序号,取值为[0,10]; 当前为保留字段,开发者可忽略 |
payload.usage部分
usage | Object | 结束时返回本次模型调用的 tokens 数量统计。 |
---|---|---|
prompt_tokens | Integer | 用户输入的 tokens 数量 |
completion_tokens | Integer | 模型输出的 tokens 数量 |
total_tokens | Integer | 总 tokens 数量 |
# 3.5、Function Call说明
# 3.5.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"
]
}
}
]
}
}
}
接口请求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 | 是 | 必须返回的参数列表 | 该内容由用户定义,命中方法时必须返回的字段 |
# 3.5.2、响应参数
// 触发了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":20,"total_tokens":3}}}}
响应参数说明
字段名 | 类型 | 字段说明 |
---|---|---|
function_call | json | function call 返回结果 |
function_call.arguments | json | 客户在请求体中定义的参数及参数值 |
function_call.name | string | 客户在请求体中定义的方法名称 |
# 四、知识问答接口
# 接口鉴权
请参考http协议通用鉴权 (opens new window)说明
# 4.1、创建知识库
接口描述
上传文件前需要先创建知识库,向知识库中上传文件。
接口地址
POST https://sparkcube-api.xf-yun.com/v1/knowledge/create
请求示例
curl https://*.xf-yun.com/v1/knowledge \
-H "x-appid: $APPID" \
-d "kb_id=longctx-repo1" \
请求参数
请求头
字段名 | 类型 | 是否必传 | 含义 | 备注 | 限制 |
---|---|---|---|---|---|
x-appid | string | 是 | 应用的app_id,在控制台查看 | "maxLength":8 |
请求体
字段名 | 类型 | 是否必传 | 含义 | 备注 | 限制 |
---|---|---|---|---|---|
kb_id | string | 是 | 知识库名称 | 仅支持:中文 英文 数字 _- 需要保证唯一性,建议加上业务前缀 | 长度不超过32,合法字符 |
响应示例
{
"code": 0,
"message": "",
"sid": ""
}
响应参数
字段名 | 类型 | 必选 | 含义 |
---|---|---|---|
code | int | 是 | 错误码,0:成功,非0:失败 |
message | string | 是 | 错误描述信息 |
sid | string | 是 |
# 4.2、上传文件
接口描述
向知识库中上传文件,返回文件对应的file_id
调用星火大模型可定制API接口时,可在content对应的内容中传入file_id,针对文件内容进行问答
接口地址
POST https://sparkcube-api.xf-yun.com/v1/files
请求示例
curl https://*.xf-yun.com/v1/files
-H "x-appid: $APPID"
-d "purpose=file-extract"
-d "kb_id=longctx-repo1"
-F file="@mydata.jsonl"
请求参数
请求头
字段名 | 类型 | 是否必传 | 含义 | 备注 | 限制 |
---|---|---|---|---|---|
x-appid | string | 是 | 应用的app_id,在控制台查看 | "maxLength":8 |
请求体
注意:请求体为表单数据,采用Content-Type: multipart/form-data传输文件数据
字段名 | 类型 | 是否必传 | 含义 | 备注 | 限制 |
---|---|---|---|---|---|
purpose | string | 是 | 该文件使用功能,目前取值:文件提取(file-extract) | ||
kb_id | string | 否 | 知识库名称,当purpose为 file-extract 必传 | 通过知识库创建接口创建 |
响应示例
{
"code": 0,
"message": "",
"sid": "",
"result": {
"file_id": "file-abc123",
"object": "file",
"bytes": 120000,
"created_at": 1677610602,
"file_name": "mydata.pdf",
"purpose": "file-extract"
}
}
响应参数
字段名 | 类型 | 必选 | 含义 | 备注 | 限制 |
---|---|---|---|---|---|
code | int | 是 | 错误码,0:成功,非0:失败 | ||
message | string | 是 | 错误描述信息 | ||
sid | string | 是 | |||
result | object | 是 | 文档上传具体信息 | ||
result.file_id | string | 是 | 文档id | ||
result.file_name | string | 否 | 文档名 | ||
result.object | string | 否 | 文件类型 | ||
result.bytes | int | 否 | 文件大小 | ||
result.purpose | string | 否 | 文件使用目的 | ||
result.created_at | int | 否 | 文件创建时间 |