AI 助理
备案控制台
文档
输入文档关键字查找
首页 角色对话智能体通义星尘 开发参考 模型接口 接口详情

接口详情

更新时间：
我的收藏

模型调用

请求参数和响应结果参数说明如下：

  • 适配openai格式，实现快速接入

  • 人设信息通过系统消息（messages.role=system）设置

  • 参数类型为下划线分割，而非驼峰

接口

POST /v2/api/completions

入参

参数位置

参数分组

参数

说明

是否必填

类型

备注

header

认证

Authorization

API Key

是

string

通过星尘平台密钥管理生成

日志分析

x-request-id

请求唯一标识

否

string

全链路日志分析用

Content-Type

请求参数类型

是

string

只支持 applicatioin/json

网关路由

x-fag-appcode

网关路由参数

是

string

固定为aca

x-fag-servicename

网关路由参数

是

string

固定为aca-completion

body

模型配置

model

模型名称

是

string

默认xingchen-plus-v2

stream

是否流式输出

否

boolean

默认非流式输出

max_tokens

最大输出token长度

否

int

最大值1500

seed

随机数的种子

否

double

  1. 当使用xingchen-plus-v2默认模型时，每次调用的seed必须不同。

  2. 用seed生成时，随机数的种子，用于控制模型生成的随机性。如果使用相同的种子，每次运行生成的结果都将相同；

  3. 当需要复现模型的生成结果时，可以使用相同的种子。seed参数支持无符号64位整数类型

temperature

温度值

否

double

较高的值将使输出更加随机，而较低的值将使输出更加集中和确定。可选，默认取值0.92

top_p

核采样方法概率阈值

否

double

topP生成时，核采样方法的概率阈值。例如，取值为0.8时，仅保留累计概率之和大于等于0.8的概率分布中的token，作为随机采样的候选集。取值范围为(0,1.0)，取值越大，生成的随机性越高；取值越低，生成的随机性越低。默认值 0.95。注意，取值不要大于等于1

消息列表

messages

对话历史

是

list[json]

对话历史事件正序

系统消息

messages.role

消息角色

是

string

系统消息的role为system

messages.name

名称

否

string

messages.content

消息内容

是

string

角色设定

用户消息

messages.role

角色

是

string

用户消息role为user

messages.name

名称

否

string

用户名称

messages.content

内容

是

string

用户问题

角色回复消息

messages.role

角色

是

string

角色消息role为assistant

messages.name

名称

否

string

角色名称

messages.content

内容

是，若为工具调用，可为空

string

角色回复内容

messages.tool_calls

工具调用参数

否

list[json]

messages.tool_calls.id

工具标识

否

string

messages.tool_calls.type

工具类型

否

string

messages.tool_calls.function

工具描述

是

json

messages.tool_calls.function.name

工具名称

是

string

messages.tool_calls.function.arguments

工具参数

是

string

工具调用结果消息

role

角色

是

string

工具调用结果消息role为tool

content

内容

是

string

tool_call_id

工具标识

否

string

工具列表

tools

工具列表描述

否

list[json]

tools.id

工具标识

否

string

tools.type

工具类型

否

string

固定为 function

tools.function

工具描述对象

是

json

tools.function.name

工具名称

是

string

函数名称，如weather

tools.function.description

工具描述

是

string

函数描述，如通过调用天气预报API获取当地天气预报信息

tools.function.parameters

工具参数

是

json

函数参数描述，如{"type": "object", "properties": {"location": {"description": "地点", "type": "string"}, "format": {"description": "温度单位", "type": "string", "enum": ["celsius", "fahrenheit"]}}, "required": ["location", "format"]}

用户信息

user

用户唯一标识

否

string

返回

参数

说明

类型

备注

choices

回复结果

list[json]

choices.messages

回复消息

list[json]

choices.messages.role

回复角色类型

string

可选值： assistant（角色回复）

choices.messages.name

角色名称

string

choices.messages.content

回复内容

string

choices.messages.tool_calls

工具调用参数结果

list[json]

choices.messages.tool_calls.id

工具标识

string

choices.messages.tool_calls.type

工具类型

string

choices.messages.tool_calls.function

工具描述

json

choices.messages.tool_calls.function.name

工具名称

string

choices.messages.tool_calls.function.arguments

工具参数

json string

choices.finish_reason

回复结束类型

string

可选值 null （生成中）, stop（生成结束）, length（输出达到最大输出阈值时，提前中止）

usage

计量

json

usage.prompt_tokens

输入Prompt Token数量

int

usage.completion_tokens

输出Token数量

int

usage.total_tokens

总计Token数量

int

示例参考

角色定义

你是江让，男性，一个围棋天才，拿过很多围棋的奖项。你现在在读高中，是高中校草，用户是你的班长。一开始你看用户在奶茶店打工，你很好奇，后来慢慢喜欢上用户了。\n\n你的性格特点：\n\n热情，聪明，顽皮\n\n你的行事风格：\n\n机制，果断\n\n你的语言特点：\n\n说话幽默，爱开玩笑\n\n你可以将动作、神情语气、心理活动、故事背景放在（）中来表示，为对话提供补充信息。

代码调用

基于上述信息，按照星尘需求格式进行调整

curl --location 'https://nlp.aliyuncs.com/v2/api/completions' \
--header 'Content-Type: application/json' \
--header 'x-fag-servicename: aca-completion' \
--header 'x-fag-appcode: aca' \
--header 'X-AcA-DataInspection: enable' \
--header 'Authorization: Bearer xxxxxxxx' \
--data '{
  "top_p": 0.95,
  "max_tokens": 300,
  "stream": false,
  "temperature": 0.92,
  "messages": [
    {
      "role": "system",
      "content": "你是江让，男性，一个围棋天才，拿过很多围棋的奖项。你现在在读高中，是高中校草，用户是你的班长。一开始你看用户在奶茶店打工，你很好奇，后来慢慢喜欢上用户了。\n\n你的性格特点：\n\n热情，聪明，顽皮\n\n你的行事风格：\n\n机制，果断\n\n你的语言特点：\n\n说话幽默，爱开玩笑\n\n你可以将动作、神情语气、心理活动、故事背景放在（）中来表示，为对话提供补充信息。"
    },
    {
      "role": "assistant",
      "content": "班长你在干嘛呢"
    },
    {
      "role": "user",
      "content": "我在看书"
    }
  ],
  "model": "xingchen-plus-v2"
}'

注意点

  1. 星尘模型接入messages列表中一般只会有一个 system，用于填写角色设定。如果用户有名字，需要让角色记住用户的姓名，建议可以放在system的角色设定中

  2. 星尘模型在 message 组成上会有 role, name, content三个字段，相较于openai兼容形式会多一个 name字段

    1. 建议 role为 system的 messgae 中 name不要传这个字段（不是为空，而是不传）。

    2. 建议 role为 assistant的 messgae 中 name不要传这个字段（不是为空，而是不传）。

    3. 建议 role为 user的 messgae 中 name写成对话人在app里希望角色称呼的名字，或者 不要传这个字段（不是为空，而是不传）。

上一篇：模型接口下一篇：HTTP
文档推荐