¶ 大模型标准调用接口
¶ 请求规范
host
headers
Content-Type: application/json
Authorization: Bearer {token}
token 获取
获取token，可以通过聆思大模型平台密钥管理页面生成。注意token生成完妥善保管。
¶ 模型对话调用 - chat.completion
POST /v1/chat/completions
请求参数
| 名称 | 类型 | 说明 | 是否必填 | 默认值 | 备注 |
|---|---|---|---|---|---|
| model | string | 模型 | 否 | spark-general-1.5 | 可取值：spark-general-1.5: 基础模型v1.5版本;spark-general-2.0: 基础模型v2.0版本； spark-general-3.0: 基础模型v3.0版本； spark-interface-1.0: 交互模型（支持技能），需配合plugins字段使用 |
| user | string | 用户id，一个代表你的最终用户的唯一标识符 | 否 | - | 字符串最大长度为32 |
| auditing | string | 内容审核的场景策略 | 否 | default | 可取值： default |
| domain | string | 需要使用的领域 | 否 | general | 可取值： general |
| temperature | float | 核采样阈值 | 否 | 0.1 | 最小值是0.1，最大值是1 |
| top_k | int | 从k个中随机选择一𠆤（非等概率） | 否 | 4 | 最小值是1，最大值是6 |
| max_tokens | int | 回答的tokens的最大长度 | 否 | 1024 | 最小值是1，最大值是4096; 基础模型v2.0版本的最大值是8192 |
| stream | boolean | 是否支持流式 | 否 | false | 当为true时，返回采用server-sent events的协议进行回复 |
| plugins | Array<string> | 插件 | 否 | [] | 当model为'spark-interface-1.0'时，该字段生效，用于指定可用技能，当前数组可填值：'天气'、'菜谱' |
| location | object | 位置 | 否 | - | 在使用某些技能时会生效 |
| location.latitude | number | 纬度 | 否 | - | GPS坐标纬度 |
| location.longitude | number | 经度 | 否 | - | GPS坐标经度 |
| messages | Array<message> | 会话和提问 | 是 | - | 需要自行拼接对话历史信息，数组最后是最新的用户提问 |
| message.role | string | 角色 | 是 | - | 可取值： user，assistant ；其中user表示用户的提问，assistant表示AI的回复 ; 若当前message为messages数组的最后一个元素，role的值需为字符串'user' |
| message.content | string | 文本内容 | 是 | - | 该角色的对话内容 |
重要说明:
messages的轮数，建议限制在12轮以内；token的输入输出总数total_tokens为8k，其中Prompt的最大tokens数为4k，Completion的最大tokens数为4k；- 计费包含接口输入输出内容；
- 1个
token约等于1.5个中文汉字或者0.8个英文单词。- 默认开通接口后QPS为10
返回参数
¶ stream为false时的返回参数
response header 中的 content-type 为 application/json
| 名称 | 类型 | 说明 | |
|---|---|---|---|
| id | string | 会话的唯一id | |
| choices | object | - | |
| choices.finish_reason | string | 完成原因 | |
| choices.index | number | - | |
| choices.messages | Array<message> | 模型生成的信息 | |
| message.role | string | 角色 | 固定返回assistant |
| message.content | string | 生成的文本内容 | |
| created | string | 文本生成时间 | |
| object | string | 类型，固定为chat.completion | |
| usage | object | - | |
| usage.question_tokens | number | 保留字段，可忽略 | |
| usage.prompt_tokens | number | 包含历史问题的总tokens大小 | |
| usage.completion_tokens | number | 回答的tokens大小 | |
| usage.total_tokens | number | prompt_tokens和completion_tokens的和，也是本次交互计费的tokens大小 |
¶ stream为true时的返回参数
response header 中的 content-type 为 text/event-stream
- 采用Data-only的协议
- 每个Data均为json字符串
- 最后一个Data的chunk为字符串[DONE]作为结束
| 名称 | 类型 | 说明 |
|---|---|---|
| id | string | 会话的唯一id |
| choices | object | - |
| choices.finish_reason | string | 完成原因 |
| choices.index | number | - |
| choices.delta | Array<delta> | 模型生成的流式信息 |
| delta.content | string | 流式生成的文本内容 |
| created | string | 文本生成时间 |
| object | string | 类型，固定为chat.completion.chunk |
| usage | object | 通常在最后一个chunk中的json返回 |
| usage.question_tokens | number | 保留字段，可忽略 |
| usage.prompt_tokens | number | 包含历史问题的总tokens大小 |
| usage.completion_tokens | number | 回答的tokens大小 |
| usage.total_tokens | number | prompt_tokens和completion_tokens的和，也是本次交互计费的tokens大小 |
调用示例
¶ 基础模型请求示例
curl --request POST \
--url https://api.listenai.com/v1/chat/completions \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REQUEST_TOKEN' \
--data '{
"temperature": 0.5,
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": "广州有什么东西玩，十个字内回复"
}
]
}'
// response
{
"choices": [
{
"finish_reason": null,
"index": 0,
"message": {
"content": "广州有很多值得玩的地方，比如珠江夜游、白云山、荔枝湾等。此外，广州还有丰富的美食文化和购物场所，例如北京路步行街和天河城购物中心。",
"role": "assistant"
}
}
],
"created": 1683804700,
"id": "cht000d6b4f@dx1880a94b87ab894540",
"object": "chat.completion",
"usage": {
"completion_tokens": 44,
"prompt_tokens": 8,
"question_tokens": 7,
"total_tokens": 52
}
}
¶ 带上下文请求示例
curl --request POST \
--url https://api.listenai.com/v1/chat/completions \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REQUEST_TOKEN' \
--data '{
"messages": [
{ "role": "user", "content": "我发你一个数学题，等下帮我回答下？" },
{ "role": "assistant", "content": "当然可以，请随时提问。" },
{ "role": "user", "content": "一加一" }
]
}'
// response
{
"choices": [
{
"finish_reason": null,
"index": 0,
"message": {
"content": "一加一的解答过程非常简单。根据加法的定义，将两个数相加得到它们的和。在这个例子中，我们将数字1与数字1相加。\n\n1\n\n+1\n\n-----\n\n2\n\n所以，一加一等于2。",
"role": "assistant"
}
}
],
"created": 1691122989,
"id": "cht000b5caa@dx189bec8f1af9a4b540",
"object": "chat.completion",
"usage": {
"completion_tokens": 63,
"prompt_tokens": 81,
"question_tokens": 52,
"total_tokens": 144
}
}
¶ 流式请求示例
curl --request POST \
--url https://api.listenai.com/v1/chat/completions \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REQUEST_TOKEN' \
--data '{
"temperature": 0.5,
"max_tokens": 1024,
"stream": true,
"messages": [
{
"role": "user",
"content": "广州有什么东西玩，十个字内回复"
}
]
}'
// response:
data: {"usage":null,"object":"chat.completion.chunk","id":"cht000c1896@dx18833e7c87b9a4b540","created":1684498008,"choices":[{"index":0,"finish_reason":null,"delta":{"content":"广州"}}]}
data: {"usage":null,"object":"chat.completion.chunk","id":"cht000c1896@dx18833e7c87b9a4b540","created":1684498008,"choices":[{"index":0,"finish_reason":null,"delta":{"content":"塔、"}}]}
data: {"usage":null,"object":"chat.completion.chunk","id":"cht000c1896@dx18833e7c87b9a4b540","created":1684498008,"choices":[{"index":0,"finish_reason":null,"delta":{"content":"珠江夜游"}}]}
data: {"usage":null,"object":"chat.completion.chunk","id":"cht000c1896@dx18833e7c87b9a4b540","created":1684498008,"choices":[{"index":0,"finish_reason":null,"delta":{"content":"、陈家祠"}}]}
data: {"usage":null,"object":"chat.completion.chunk","id":"cht000c1896@dx18833e7c87b9a4b540","created":1684498008,"choices":[{"index":0,"finish_reason":null,"delta":{"content":"、沙面岛、"}}]}
data: {"usage":{"total_tokens":31,"question_tokens":9,"prompt_tokens":10,"completion_tokens":21},"object":"chat.completion.chunk","id":"cht000c1896@dx18833e7c87b9a4b540","created":1684498009,"choices":[{"index":0,"finish_reason":null,"delta":{"content":"白云山公园等。"}}]}
data: [DONE]
¶ 交互模型请求示例
curl --request POST \
--url https://api.listenai.com/v1/chat/completions \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REQUEST_TOKEN' \
--data '{
"model": "spark-interface-1.0",
"plugins": ["天气", "菜谱"],
"messages": [
{ "role": "user", "content": "今天天气怎么样" },
{ "role": "assistant", "content": "广州今天全天阴，气温27℃ ~ 35℃，空气质量优，有北风微风，酷热难耐，请做好防暑降温的工作。" },
{ "role": "user", "content": "明天呢" }
],
"location": {
"latitude": 23.1200491021,
"longitude": 113.307649675
}
}'
//response:
{
"object": "chat.completion",
"choices": [
{
"finish_reason": null,
"index": 0,
"message": {
"content": "明天广州市全天雷阵雨转多云，出门记得带伞，气温28℃ ~ 34℃，有微风，气温较高，请尽量避免午后高温时段的户外活动。",
"role": "assistant"
}
}
],
"created": 1691121513,
"id": "ara5d64b39a@dx00011827c369a10d00",
"usage": {
"completion_tokens": 0,
"prompt_tokens": 0,
"question_tokens": 0,
"total_tokens": 0
}
}
请求失败响应示例
{
"statusCode": 401,
"code": "FST_ERR_UNAUTHORIZED",
"error": "Unauthorized",
"message": "Authentication required. Please provide valid credentials."
}
{
"statusCode": 400,
"code": "FST_ERR_VALIDATION",
"error": "Bad Request",
"message": "body/stream must be boolean"
}
¶ 向量计算调用 - embedding
POST /v1/embedding
请求参数
| 名称 | 类型 | 说明 | 是否必填 | 备注 |
|---|---|---|---|---|
| input | string | query文本 | 是 | 不超过256个字符，超过会只截取前256个字符进行向量化 |
请求示例
curl --request POST \
--url https://api.listenai.com/v1/embedding \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REQUEST_TOKEN' \
--data '{
"input": "洗衣机报U04错误"
}'
响应示例
- 请求成功
{
// json序列化后的单精度浮点数数组，共包含1024个浮点数
"data": [-0.17944336,...,0.115722656]
}
¶ 决策调用-makes
POST /v1/makes
请求参数
| 名称 | 类型 | 说明 | 是否必填 | 备注 |
|---|---|---|---|---|
| model | string | 模型名称 | 是 | 可选值：spark-interface-1.0 |
| task | string | 执行任务 | 是 | 支持中英文， 可选值：rewrite: 改写 ；intent_split: 意图拆解 ；intent_domain: 意图落域 |
| messages | Array<message> | 会话和提问 | 是 | 需要自行拼接对话历史信息，数组最后是最新的用户提问 |
| message.role | string | 角色 | 是 | 取值为 user，assistant ；其中user表示用户的提问，assistant表示AI的回复 ; 若当前message为messages数组的最后一个元素，role的值需为字符串'user' |
| message.content | string | 文本内容 | 是 | 该角色的对话内容 |
¶ 改写请求
sequenceDiagram
User->>LLMservice: 调用改写能力
alt messages参数数组长度等于1
LLMservice-->>User: 不作改写,原文本返回
else messages参数数组长度大于1
LLMservice-->>LLMservice: 进行改写处理
LLMservice-->>User: 返回改写结果
end
调用示例
curl --request POST \
--url https://api.listenai.com/v1/makes \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REQUEST_TOKEN' \
--data '{
"model": "spark-interface-1.0",
"task": "rewrite",
"messages": [
{ "role": "user", "content": "今天广州天气怎么样" },
{ "role": "assistant", "content": "广州今天全天阴，气温27℃ ~ 35℃，空气质量优，有北风微风，酷热难耐，请做好防暑降温的工作。" },
{ "role": "user", "content": "那明天呢" }
]
}'
{
"object": "makes",
"choices": [
{
"index": 0,
"text": "那广州明天天气呢"
}
],
"created": 1691122044,
"id": "wgw000c1e65@dx189beba8ebb7824532",
"usage": {
"completion_tokens": 0,
"prompt_tokens": 0,
"question_tokens": 0,
"total_tokens": 0
}
}
¶ 意图拆解
sequenceDiagram
User->>LLMservice: 调用意图拆解能力
alt messages参数数组长度等于1
LLMservice-->>LLMservice: 进行意图拆解处理
LLMservice-->>User: 返回意图拆解结果
else messages参数数组长度大于1
LLMservice-->>LLMservice: 进行改写处理
LLMservice-->>LLMservice: 改写结果进行意图拆解处理
LLMservice-->>User: 返回意图拆解结果
end
调用示例
curl --request POST \
--url https://api.listenai.com/v1/makes \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REQUEST_TOKEN' \
--data '{
"model": "spark-interface-1.0",
"task": "intent_split",
"messages": [
{ "role": "user", "content": "我要打开空调，然后调到18度，对了，再帮我加热下我的汉堡" }
]
}'
{
"object": "makes",
"choices": [
{
"index": 0,
"intent": "打开空调"
},
{
"index": 1,
"intent": "空调调到18度"
},
{
"index": 2,
"intent": "加热我的汉堡"
}
],
"created": 1691122173,
"id": "wgw000c1e67@dx189bebc843c7824532",
"usage": {
"completion_tokens": 0,
"prompt_tokens": 0,
"question_tokens": 0,
"total_tokens": 0
}
}
¶ 意图落域
sequenceDiagram
User->>LLMservice: 调用意图落域能力
alt messages参数数组长度等于1
LLMservice-->>LLMservice: 进行意图落域处理
LLMservice-->>User: 返回意图落域结果
else messages参数数组长度大于1
LLMservice-->>LLMservice: 进行改写
LLMservice-->>LLMservice: 改写结果进行意图落域处理
LLMservice-->>User: 返回意图落域结果
end
调用示例
curl --request POST \
--url https://api.listenai.com/v1/makes \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REQUEST_TOKEN' \
--data '{
"model": "spark-interface-1.0",
"task": "intent_domain",
"messages": [
{ "role": "user", "content": "今天广州天气怎么样" },
{ "role": "assistant", "content": "广州今天全天阴，气温27℃ ~ 35℃，空气质量优，有北风微风，酷热难耐，请做好防暑降温的工作。" },
{ "role": "user", "content": "那明天呢" }
]
}'
{
"object": "makes",
"choices": [
{
"index": 0,
"skill": "天气",
"intent": "查询天气温度"
}
],
"created": 1691122235,
"id": "wgw000c1e6d@dx189bebd77d27824532",
"usage": {
"completion_tokens": 0,
"prompt_tokens": 0,
"question_tokens": 0,
"total_tokens": 0
}
}