# 星火大模型 可定制化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 文件创建时间
咨询
建议
体验
中心