# 星火大模型可定制化API 文档

# 一、服务介绍

星火定制化API ，内置丰富的标准场景，开发者能够依据自身业务领域，选取对应的偏好场景，充分释放大模型在垂类业务下的理解与任务处理能力。同时集成 RAG 和联网搜索工具，支持对公域和私域知识进行混合检索，使知识问答更加准确且个性化。技术咨询可直接提交工单 (opens new window)

# 二、接口 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	否	文件创建时间

在这篇文章中：

# 星火大模型 可定制化API 文档

# 一、服务介绍

# 二、接口 Demo

# 三、星火大模型可定制API接口

# 接口鉴权

# 3.1、接口描述

# 3.2、接口地址

# 3.3、请求参数

# 3.4、响应参数

# 3.5、Function Call说明

# 3.5.1、请求参数

# 3.5.2、响应参数

# 四、知识问答接口

# 接口鉴权

# 4.1、创建知识库

# 4.2、上传文件

# 星火大模型可定制化API 文档