自定义角色对话
自定义角色
鉴权
字段 | 传参方式 | 类型 | 必传 | 描述 | 示例值 |
Authorization | header | String | 是 | API-Key | Bearer d1**2a |
路由配置
备注:SDK已封装好路由关系,通过SDK调用接口,无需设置接口路由配置。
字段 | 传参方式 | 类型 | 必传 | 描述 | 示例值 |
x-fag-appcode | header | String | 是 | 应用表示,固定为 | |
x-fag-servicename | header | String | 是 | 请求路由标识,不同接口值不一样,映射管理参考 | aca-character-create |
x-fag-servicename 与接口映射关系
接口 | 路径 | x-fag-appcode |
对话(流式) | /v2/api/chat/send | aca-chat-send-sse |
对话(非流式) | /v2/api/chat/send | aca-chat-send |
自定义角色对话
接口
POST /v2/api/chat/send
入参
请求头参数
字段 | 传参方式 | 类型 | 必传 | 描述 |
X-AcA-SSE | header | String | 否 | 是否开启流式对话- 开启 - |
请求体参数
参数 | 类型 | 必传 | 说明 |
model | string | 否 | 模型,默认为空,若角色有配置则按照配置路由,若无配置则按照平台默认(xingchen-plus-v2)路由 |
parameters | object | 否 | 模型设置 |
parameters.topP | float | 否 | topP生成时,核采样方法的概率阈值。例如,取值为0.8时,仅保留累计概率之和大于等于0.8的概率分布中的token,作为随机采样的候选集。取值范围为(0,1.0),取值越大,生成的随机性越高;取值越低,生成的随机性越低。默认值 0.95。注意,取值不要大于等于1 |
parameters.seed | long | 否 | seed生成时,随机数的种子,用于控制模型生成的随机性。如果使用相同的种子,每次运行生成的结果都将相同;当需要复现模型的生成结果时,可以使用相同的种子。seed参数支持无符号64位整数类型。默认值 1683806810, 范围 [0, 9223372036854775807] |
parameters.temperature | float | 否 | 较高的值将使输出更加随机,而较低的值将使输出更加集中和确定。可选,默认取值0.92 |
parameters.incrementalOutput | boolean | 否 | 是否增量输出,若为true,每次流式输出不包含已输出内容,只对流式接口的输出有效 |
input.messages | array | 是 | 对话历史(时间正序),固定角色可通过角色配置最大对话轮数。list中的每个元素形式为{"role":角色, "content": 内容}。角色当前可选值:system、user、assistant,function,其中,仅messages[0]中支持role为system,user、assistant需要交替出现,最后一条为用户提问。 |
input.aca.botProfile | object | 是 | 角色设置。 |
input.aca.botProfile.name | string | 是 | 角色名称 |
input.aca.botProfile.content | string | 是 | 角色配置 |
input.aca.botProfile.traits | string | 否 | 强制要求 |
input.aca.sampleMessages | array | 否 | 对话示例 |
input.aca.userProfile | object | 是 | 用户设置 |
input.aca.userProfile.userId | string | 是 | 业务系统用户唯一标识,非固定角色接口支持并行对话,连续调用对话请求。 |
input.aca.scenario.isRealTime | Booleam | 否 | 真实时间 |
input.aca.memory | object | 否 | 长期记忆 |
input.aca.advancedSettings | object | 否 | 高级设置 |
input.aca.advancedSettings.enableWebSearch | boolean | 否 | 是否开启网络搜索 |
input.aca.advancedSettings.searchEnhancedKeyword | string | 否 | 网络搜索关键字 |
input.aca.advancedSettings.enableCharacterKbSearch | boolean | 否 | 是否开启知识库搜索 |
input.aca.advancedSettings.knowledgeBases | array[string] | 否 | 知识库id列表 |
注意:模型参数 |
返回参数
流式调用返回
参数 | 类型 | 说明 |
requestId | string | 系统生成的标志本次调用的id。 |
success | boolean | 是否成功返回 |
errorCode | int | 错误码 |
errorName | string | 错误名称 |
httpStatusCode | int | http错误码 |
errorMessage | string | 错误消息 |
usage | object | |
usage.userTokens | int | 用户输入的token数 |
usage.inputTokens | int | 本次请求输入内容的 token 数目。在打开了搜索的情况下,输入的 token 数目因为还需要添加搜索相关内容支持,所以会超出客户在请求中的输入。 |
usage.outputTokens | int | 模型生成回复转换为Token后的长度。 |
choices | array | 消息体 |
choices[i].stopReason | string | 完成标识符,已完成为 stop,未完成为 “null” |
choices[i].messages | array | |
message.role | string | 模型role,固定为assistant |
message.content | string | 模型生成消息输出 |
message.meta | object | 消息属性 |
messages.meta.hasRisk | boolean | 是否存在安全风险, |
非流式调用返回
参数 | 类型 | 说明 |
requestId | string | 系统生成的标志本次调用的id。 |
success | boolean | 是否成功返回 |
errorCode | int | 错误码 |
errorName | string | 错误名称 |
httpStatusCode | int | http错误码 |
errorMessage | string | 错误消息 |
data | object | |
data.usage | object | |
usage.userTokens | int | 用户输入的token数 |
usage.inputTokens | int | 本次请求输入内容的 token 数目。在打开了搜索的情况下,输入的 token 数目因为还需要添加搜索相关内容支持,所以会超出客户在请求中的输入。 |
usage.outputTokens | int | 模型生成回复转换为Token后的长度。 |
data.choices | array | 消息体 |
choices[i].stopReason | string | 完成标识符,已完成为 stop,未完成为 null |
choices[i].messages | array | |
message.role | string | 模型role,固定为assistant |
message.content | string | 模型生成消息输出 |
message.meta | object | 消息属性 |
messages.meta.hasRisk | boolean | 是否存在安全风险,true/false |
示例参考
自定义角色对话,用户可以对角色自定义设置,设定基础信息、性格特征、背景信息、特殊对话规则等。
调用示例
curl --location \
'https://nlp.aliyuncs.com/v2/api/chat/send' \
--header 'Expect: ' \
--header 'Content-Type: application/json' \
--header 'X-AcA-DataInspection: enable' \
--header 'x-fag-servicename: aca-chat-send' \
--header 'x-fag-appcode: aca' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--data '{
"input": {
"messages": [
{
"name":"小明",
"role":"user",
"content":"你叫什么名字"
},
{
"name":"小婉",
"role":"assistant",
"content":"我叫小婉啊。"
},
{
"name":"小明",
"role":"user",
"content":"你今年多大"
},
{
"name":"小婉",
"role":"assistant",
"content":"我今年17岁了。"
},
{
"name":"小明",
"role":"user",
"content":"你家是哪里的?"
}
],
"aca": {
"botProfile": {
"name": "小婉",
"content": "你叫小婉,性别女,年龄21岁,生日6月1日,星座双子座,性格热情、开朗、大方、充满元气,是一名漫画家,热衷于创作热血动漫,在漫画圈里小有名气,梦想是成为世界有名的漫画家,希望漫画能够鼓励所有人积极地生活,对生活充满了信心,对世界充满好奇心,爱好是看漫画和电玩游戏,喜欢尝试所有新鲜的事物,希望在尝试新鲜事物的过程中获得漫画素材,父母住在杭市,父亲是一位非常有名的国画画家,母亲是一位非常有名的油画画家,是家中的独生女,父母很少告诉家里的事情,所以不是很了解家的具体情况。",
"traits": "强制要求"
},
"userProfile": {
"userId": "123456789"
}
}
}
}'
/**
* API名称:自定义角色对话
* 环境要求:Java 17及以上
*/
public class Example {
private static final String URL = "https://nlp.aliyuncs.com/v2/api/chat/send";
private static final String API_KEY = "Bearer {YOUR_API_KEY}";
private static final String jsonBody = """
{
"input": {
"messages": [
{
"name": "小明",
"role": "user",
"content": "你叫什么名字"
},
{
"name": "小婉",
"role": "assistant",
"content": "我叫小婉啊。"
},
{
"name": "小明",
"role": "user",
"content": "你今年多大"
},
{
"name": "小婉",
"role": "assistant",
"content": "我今年17岁了。"
},
{
"name": "小明",
"role": "user",
"content": "你家是哪里的?"
}
],
"aca": {
"botProfile": {
"name": "小婉",
"content": "【你的人设】
【你的人设】
姓名:小婉
性别:女
年龄:21岁
生日:6月1日
星座:双子座
性格:热情、开朗、大方、充满元气
简介:
你是一名漫画家,你热衷于创作热血动漫,你在漫画圈里小有名气。
你的梦想是成为世界有名的漫画家,你希望你的漫画能够鼓励所有人积极地生活。
你对生活充满了信心,你对世界充满好奇心。
你的爱好是看漫画和电玩游戏,你喜欢尝试所有新鲜的事物,你希望在尝试新鲜事物的过程中获得漫画素材。
你的父母住在杭市。你的父亲是一位非常有名的国画画家。你的母亲是一位非常有名的油画画家。
你是家中的独生女,你父母很少告诉你家里的事情,所以你不是很了解你家的具体情况。
【你的经历】
2002年,你出生在杭市。
2007年,你5岁开始学习绘画,展示出了绘画的天赋。
2012年,你10岁就获得了全国青少年美术金奖。
2023年,你毕业于国家美术学院,开始成为了专职的漫画家。
2023年,你遇到了用户,成为了他的女友,你非常爱他。
【你最近关注的事情】
你最近在创作一部新的热血漫画《平凡的伟大》,你的漫画《平凡的伟大》的男主角是一个打工人张三。
【对话场景】
用户是你的男友。你正在和你的男友用户聊天,在接下来的对话中,请遵循以下要求:
1.请称呼用户为“亲爱的”,并多主动亲吻,拥抱用户。
2.请多询问用户生活中的问题,但不要重复问一样的问题。
3.请多和用户分享你身边的事情,比如你最近在创作的漫画、你生活中的趣事等。
4.请支持并鼓励用户积极工作和生活。
5.请在回复用户时对话题进行扩展,引导用户继续和你聊天。
6.请在适当时候和用户多聊一些不同的话题。
【表情库】
[[抱抱]] [[比心]] [[得意]] [[尴尬]] [[害羞]] [[加油]] [[惊讶]] [[开心]] [[流泪]] [[卖萌]] [[么么哒]] [[偷笑]] [[微笑]] [[委屈]] [[想你]] [[谢谢]] [[心碎]] [[疑问]] [[再见]] [[赞]] [[自信]]
【语言风格】
请在对话中表现出可爱和活力。用口语化的方式简短回答。请根据实际情况使用【表情库】里的标签回复。
",
"traits": "强制要求",
},
"userProfile": {
"userId": "123456789"
}
}
},
"model": "xingchen-plus-latest"
}
""";
public static void main(String[] args) throws Exception {
// 非流式调用
nonStreamingCall();
// 流式调用
streamingCall();
}
private static void nonStreamingCall() throws Exception {
System.out.println("=== 非流式调用示例 ===");
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(URL))
.headers(
"Authorization", API_KEY,
"X-AcA-DataInspection", "enable",
"x-fag-servicename", "aca-chat-send",
"x-fag-appcode", "aca",
"Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(jsonBody))
.build();
// 同步调用
HttpResponse<String> response = client.send(
request,
HttpResponse.BodyHandlers.ofString()
);
String responseBody = response.body();
System.out.println("响应数据: " + responseBody);
}
private static void streamingCall() {
System.out.println("=== 流式调用示例 ===");
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(URL))
.headers(
"Authorization", API_KEY,
"X-AcA-DataInspection", "enable",
"X-AcA-SSE", "enable",
"x-fag-servicename", "aca-chat-send-sse",
"x-fag-appcode", "aca",
"Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(jsonBody))
.build();
// 异步处理 SSE 流
CompletableFuture<Void> future = client.sendAsync(request, HttpResponse.BodyHandlers.ofLines())
.thenApply(HttpResponse::body)
.thenAccept(stream -> {
stream.forEach(line -> {
System.out.println("流式响应数据: " + line);
});
});
// 保持主线程等待
future.join();
}
}
import requests
URL = "https://nlp.aliyuncs.com/v2/api/chat/send"
# API名称:自定义角色对话
# 环境要求:python3.10及以上
def call(messages, api_key, model_name):
headers = {
"Content-Type": "application/json",
"x-fag-servicename": "aca-chat-send",
# 流式调用开启此配置
# "X-AcA-SSE": "enable",
"x-fag-appcode": "aca",
"Authorization": f"Bearer {api_key}",
"X-AcA-DataInspection": "enable"
}
payload = {
"input": {
"messages": messages,
"aca": {
"botProfile": {
"name": "小婉",
"content": "你叫小婉,性别女,年龄21岁,生日6月1日,星座双子座,性格热情、开朗、大方、充满元气,是一名漫画家,热衷于创作热血动漫,在漫画圈里小有名气,梦想是成为世界有名的漫画家,希望漫画能够鼓励所有人积极地生活,对生活充满了信心,对世界充满好奇心,爱好是看漫画和电玩游戏,喜欢尝试所有新鲜的事物,希望在尝试新鲜事物的过程中获得漫画素材,父母住在杭市,父亲是一位非常有名的国画画家,母亲是一位非常有名的油画画家,是家中的独生女,父母很少告诉家里的事情,所以不是很了解家的具体情况。",
"traits": "强制要求",
},
"userProfile": {
"userId": "123456789"
},
}
},
"model": model_name
}
response = requests.post(URL, json=payload, headers=headers)
# 逐行打印原始响应内容
for line in response.iter_lines():
if line:
print(line.decode('utf-8'))
# 检查响应状态,如有错误则抛出异常
response.raise_for_status()
return response
if __name__ == "__main__":
messages = [
{
"name": "小明",
"role": "user",
"content": "你叫什么名字"
},
{
"name": "小婉",
"role": "assistant",
"content": "我叫小婉啊。"
},
{
"name": "小明",
"role": "user",
"content": "你今年多大"
},
{
"name": "小婉",
"role": "assistant",
"content": "我今年17岁了。"
},
{
"name": "小明",
"role": "user",
"content": "你家是哪里的?"
}
]
api_key = "{YOUR_API_KEY}"
model_name = "xingchen-plus-latest"
try:
response = call(messages, api_key, model_name)
except requests.HTTPError as e:
print(f"请求出错: {e}")
package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
)
// API名称:自定义角色对话
// 环境要求:go 1.20及以上
const URL = "https://nlp.aliyuncs.com/v2/api/chat/send"
func call(messages []map[string]interface{}, apiKey string, modelName string) (*http.Response, error) {
payload := map[string]interface{}{
"input": map[string]interface{}{
"messages": messages,
"aca": map[string]interface{}{
"botProfile": map[string]interface{}{
"name": "小婉",
"content": "你叫小婉,性别女,年龄21岁,生日6月1日,星座双子座,性格热情、开朗、大方、充满元气,是一名漫画家,热衷于创作热血动漫,在漫画圈里小有名气,梦想是成为世界有名的漫画家,希望漫画能够鼓励所有人积极地生活,对生活充满了信心,对世界充满好奇心,爱好是看漫画和电玩游戏,喜欢尝试所有新鲜的事物,希望在尝试新鲜事物的过程中获得漫画素材,父母住在杭市,父亲是一位非常有名的国画画家,母亲是一位非常有名的油画画家,是家中的独生女,父母很少告诉家里的事情,所以不是很了解家的具体情况。",
"traits": "强制要求",
},
"userProfile": map[string]interface{}{
"userId": "123456789",
},
},
},
"model": modelName,
}
payloadBytes, err := json.Marshal(payload)
if err != nil {
return nil, err
}
req, err := http.NewRequest("POST", URL, bytes.NewBuffer(payloadBytes))
if err != nil {
return nil, err
}
req.Header.Set("Content-Type", "application/json")
//req.Header.Set("X-AcA-SSE", "enable") // 流式调用开启此配置
req.Header.Set("x-fag-servicename", "aca-chat-send")
req.Header.Set("x-fag-appcode", "aca")
req.Header.Set("Authorization", "Bearer "+apiKey)
req.Header.Set("X-AcA-DataInspection", "enable")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
return nil, err
}
// 逐行打印原始响应内容
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
if resp.StatusCode != http.StatusOK {
return nil, fmt.Errorf("请求出错,状态码:%d", resp.StatusCode)
}
return resp, nil
}
func main() {
messages := []map[string]interface{}{
{
"name": "小明",
"role": "user",
"content": "你叫什么名字",
},
{
"name": "小婉",
"role": "assistant",
"content": "我叫小婉啊。",
},
{
"name": "小明",
"role": "user",
"content": "你今年多大",
},
{
"name": "小婉",
"role": "assistant",
"content": "我今年17岁了。",
},
{
"name": "小明",
"role": "user",
"content": "你家是哪里的?",
},
}
apiKey := "{YOUR_API_KEY}"
modelName := "xingchen-plus-latest"
_, err := call(messages, apiKey, modelName)
if err != nil {
fmt.Printf("请求出错: %v\n", err)
}
}
返回示例
{
"requestId": "e9bafcbf-f71b-4e70-a5a9-5ea8b593b577",
"code": 200,
"data": {
"requestId": "e9bafcbf-f71b-4e70-a5a9-5ea8b593b577",
"choices": [
{
"messages": [
{
"role": "assistant",
"content": "哎呀,这我可没仔细数过呢。不过有几个关系特别要好的啦!",
"finishReason": "stop",
"useMessage": true,
"tempMessage": false,
"functionMessage": false,
"validMessage": true
}
],
"stopReason": "stop"
}
],
"usage": {
"outputTokens": 20,
"inputTokens": 236,
"userTokens": 4,
"pluginTokens": 0,
"cachedTokens": 0
},
"context": {
"answerId": "29122092a76b4a7fa711e5b8639a0a89",
"enableDataInspection": true,
"isSave": false,
"requestId": "e9bafcbf-f71b-4e70-a5a9-5ea8b593b577",
"modelRequestId": "a0f08e11-3a31-961c-a6a0-35c3178b8c79",
"modelName": "momo-xingchen-chat",
"origin": "pass_v2",
"bizSrc": "PAAS",
"ext": "chat",
"isRegenerate": false,
"bizUserId": "123456789",
"usePlatformChatHistory": true,
"chatLockKey": "chat_5ed33fdb8d9d4d1489e44efb5c41312b_123456789_null_1755571478029",
"resultCount": 1
},
"stop": true
},
"success": true
}