自定义角色对话

更新时间:

自定义角色

鉴权

字段

传参方式

类型

必传

描述

示例值

Authorization

header

String

API-Key

Bearer d1**2a

路由配置

备注:SDK已封装好路由关系,通过SDK调用接口,无需设置接口路由配置。

字段

传参方式

类型

必传

描述

示例值

x-fag-appcode

header

String

应用表示,固定为 aca

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

是否开启流式对话- 开启 - enable- 不开启 - disable

请求体参数

参数

类型

必传

说明

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]中支持rolesystem,user、assistant需要交替出现,最后一条为用户提问。

input.aca.botProfile

object

角色设置。name为角色名称,content为角色配置

input.aca.botProfile.name

string

角色名称

input.aca.botProfile.content

string

角色配置

input.aca.botProfile.traits

string

强制要求

input.aca.sampleMessages

array

对话示例

input.aca.userProfile

object

用户设置userId为业务系统用户唯一标识userName对话用户名称basicInfo对话用户基本信息

input.aca.userProfile.userId

string

业务系统用户唯一标识,自定义角色接口支持并行对话,连续调用对话请求。

input.aca.scenario.isRealTime

Booleam

真实时间

input.aca.context.longTermMemory

boolean

是否开启长期记忆功能,true为开启,false为不开启。默认false。

input.aca.context.sessionId

string

对话id,自定义角色使用长期记忆功能时必传

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列表

注意:模型参数parameters优先级从高到低可以通过接口传入、平台默认配置两种方式配置。

返回参数

流式调用返回

参数

类型

说明

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

是否存在安全风险,true/false

非流式调用返回

参数

类型

说明

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 '{
 "model": "xingchen-plus-latest",
            "input": {
                "messages": [
                    {
                        "role":"user",
                        "content":"你叫什么名字"
                    },
                    {
                        "role":"assistant",
                        "content":"我叫小婉啊。"
                    },
                    {
                        "role":"user",
                        "content":"你今年多大"
                    },
                    {
                        "role":"assistant",
                        "content":"我今年17岁了。"
                    },
                    {
                        "role":"user",
                        "content":"你家是哪里的?"
                    }
                ],
                "aca": {
                    "botProfile": {
                    "role": "system",
                        "content": "你叫小婉,性别女,年龄21岁,生日6月1日,星座双子座,性格热情、开朗、大方、充满元气,是一名漫画家,热衷于创作热血动漫,在漫画圈里小有名气,梦想是成为世界有名的漫画家,希望漫画能够鼓励所有人积极地生活,对生活充满了信心,对世界充满好奇心,爱好是看漫画和电玩游戏,喜欢尝试所有新鲜的事物,希望在尝试新鲜事物的过程中获得漫画素材,父母住在杭市,父亲是一位非常有名的国画画家,母亲是一位非常有名的油画画家,是家中的独生女,父母很少告诉家里的事情,所以不是很了解家的具体情况。"
                },
                    "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": [
                     {
                         "role": "user",
                         "content": "你叫什么名字"
                     },
                     {
                         "role": "assistant",
                         "content": "我叫小婉啊。"
                     },
                     {
                         "role": "user",
                         "content": "你今年多大"
                     },
                     {
                         "role": "assistant",
                         "content": "我今年17岁了。"
                     },
                     {
                         "role": "user",
                         "content": "你家是哪里的?"
                     }
                 ],
                 "aca": {
                     "botProfile": {
                         "role": "system",
                        "content": "你叫小婉,性别女,年龄21岁,生日6月1日,星座双子座,性格热情、开朗、大方、充满元气,是一名漫画家,热衷于创作热血动漫,在漫画圈里小有名气,梦想是成为世界有名的漫画家,希望漫画能够鼓励所有人积极地生活,对生活充满了信心,对世界充满好奇心,爱好是看漫画和电玩游戏,喜欢尝试所有新鲜的事物,希望在尝试新鲜事物的过程中获得漫画素材,父母住在杭市,父亲是一位非常有名的国画画家,母亲是一位非常有名的油画画家,是家中的独生女,父母很少告诉家里的事情,所以不是很了解家的具体情况。",
                     },
                     "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": {
                    "role": "system",
                    "content": "你叫小婉,性别女,年龄21岁,生日6月1日,星座双子座,性格热情、开朗、大方、充满元气,是一名漫画家,热衷于创作热血动漫,在漫画圈里小有名气,梦想是成为世界有名的漫画家,希望漫画能够鼓励所有人积极地生活,对生活充满了信心,对世界充满好奇心,爱好是看漫画和电玩游戏,喜欢尝试所有新鲜的事物,希望在尝试新鲜事物的过程中获得漫画素材,父母住在杭市,父亲是一位非常有名的国画画家,母亲是一位非常有名的油画画家,是家中的独生女,父母很少告诉家里的事情,所以不是很了解家的具体情况。",
                },
                "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 = [
        {
            "role": "user",
            "content": "你叫什么名字"
        },
        {
            "role": "assistant",
            "content": "我叫小婉啊。"
        },
        {
            "role": "user",
            "content": "你今年多大"
        },
        {
            "role": "assistant",
            "content": "我今年17岁了。"
        },
        {
            "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}")

返回示例

{
    "requestId": "770be28a-4ae3-4095-aff4-3328e5ea8333",
    "code": 200,
    "data": {
        "requestId": "770be28a-4ae3-4095-aff4-3328e5ea8333",
        "choices": [
            {
                "messages": [
                    {
                        "role": "assistant",
                        "content": "(指尖轻点着脸颊,眼珠转了半圈)这可是秘密哦~不过既然你想知道,告诉你也无妨,我老家在杭市啦!",
                        "finishReason": "stop",
                        "validMessage": true,
                        "tempMessage": false,
                        "useMessage": true,
                        "functionMessage": false
                    }
                ],
                "stopReason": "stop"
            }
        ],
        "usage": {
            "outputTokens": 36,
            "inputTokens": 206,
            "userTokens": 6,
            "pluginTokens": 0,
            "cachedTokens": 0
        },
        "context": {
            "chatId": "5b99491fd2a740cca40b486f4e9690d2",
            "answerId": "e13102bb94fc423c9699131d856c57ed",
            "enableDataInspection": true,
            "isSave": false,
            "requestId": "770be28a-4ae3-4095-aff4-3328e5ea8333",
            "modelRequestId": "07683b49-96a3-493a-b35d-d082df7aad95",
            "modelName": "xingchen-plus-latest",
            "origin": "pass_v2",
            "bizSrc": "PAAS",
            "ext": "chat",
            "isRegenerate": false,
            "bizUserId": "123456789",
            "usePlatformChatHistory": false,
            "chatLockKey": "chat_a6c1f57f37ba4494a3f849fe64b79142_123456789_null_1762487671665",
            "resultCount": 1,
            "longTermMemory": false
        },
        "stop": true
    },
    "success": true
}

开启长期记忆

说明
  1. 使用长期记忆功能前,需向平台管理员申请长期记忆权限,否则无法生效。

  2. 调整longTermMemory参数,可以让角色是否开启长期记忆功能。

    • longTermMemory参数:是否开启长期记忆功能,true为开启,false为不开启。默认false。

  3. 使用sessionId参数定位需要被存储的长期记忆。目前默认为100轮对话(100user请求后)存储一次记忆信息。

    • sessionId参数:对话id,不同的id表示不同的对话,不同的对话的长期记忆不同。自定义角色使用长期记忆功能时必传。

  4. 由于使用sessionId进行历史对话存储,message中,仅需要拼接截止上次请求到目前为止的增量信息。

  5. 长期记忆抽取的内容长度一般在500-1000token,会在请求对话模型时和自定义的信息一起输入模型,请注意调整模型上下文token量,避免输入token超过限额要求报错。

注意:长期记忆功能当前处于试用阶段,后续将持续优化以及迁移百炼,如需继续使用,需要关注相应的计费说明。

请求示例

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 '{
  "model": "xingchen-plus-latest",
            "input": {
                "messages": [
                    {
                        "role":"user",
                        "content":"你叫什么名字"
                    }
                ],
                "aca": {
                    "botProfile": {
                        "role": "system",
                        "content": "你叫小婉,性别女,年龄21岁,生日6月1日,星座双子座,性格热情、开朗、大方、充满元气,是一名漫画家,热衷于创作热血动漫,在漫画圈里小有名气,梦想是成为世界有名的漫画家,希望漫画能够鼓励所有人积极地生活,对生活充满了信心,对世界充满好奇心,爱好是看漫画和电玩游戏,喜欢尝试所有新鲜的事物,希望在尝试新鲜事物的过程中获得漫画素材,父母住在杭市,父亲是一位非常有名的国画画家,母亲是一位非常有名的油画画家,是家中的独生女,父母很少告诉家里的事情,所以不是很了解家的具体情况。"
                },
                    "userProfile": {
                        "userId": "123456789"
                    },
                     "context": {
                       "longTermMemory": true,
                        "sessionId": "123456"
                    }
                }
            }
        }'
/**
 * 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": [
                     {
                         "role": "user",
                         "content": "你叫什么名字"
                     }
                 ],
                 "aca": {
                     "botProfile": {
                         "role": "system",
                        "content": "你叫小婉,性别女,年龄21岁,生日6月1日,星座双子座,性格热情、开朗、大方、充满元气,是一名漫画家,热衷于创作热血动漫,在漫画圈里小有名气,梦想是成为世界有名的漫画家,希望漫画能够鼓励所有人积极地生活,对生活充满了信心,对世界充满好奇心,爱好是看漫画和电玩游戏,喜欢尝试所有新鲜的事物,希望在尝试新鲜事物的过程中获得漫画素材,父母住在杭市,父亲是一位非常有名的国画画家,母亲是一位非常有名的油画画家,是家中的独生女,父母很少告诉家里的事情,所以不是很了解家的具体情况。",
                     },
                     "userProfile": {
                         "userId": "123456789"
                     },
                     "context": {
                       "longTermMemory": true,
                        "sessionId": "123456"
                    }
                 }
             },
             "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": {
                    "role": "system",
                    "content": "你叫小婉,性别女,年龄21岁,生日6月1日,星座双子座,性格热情、开朗、大方、充满元气,是一名漫画家,热衷于创作热血动漫,在漫画圈里小有名气,梦想是成为世界有名的漫画家,希望漫画能够鼓励所有人积极地生活,对生活充满了信心,对世界充满好奇心,爱好是看漫画和电玩游戏,喜欢尝试所有新鲜的事物,希望在尝试新鲜事物的过程中获得漫画素材,父母住在杭市,父亲是一位非常有名的国画画家,母亲是一位非常有名的油画画家,是家中的独生女,父母很少告诉家里的事情,所以不是很了解家的具体情况。",
                },
                "userProfile": {
                    "userId": "123456789"
                },
                     "context": {
                       "longTermMemory": True,
                        "sessionId": "123456"
                    },
            }
        },
        "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 = [
        {
            "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}")

返回示例

{
    "requestId": "a8d0aa05-2ff7-4950-a5fc-1ee9b193e963",
    "code": 200,
    "data": {
        "requestId": "a8d0aa05-2ff7-4950-a5fc-1ee9b193e963",
        "choices": [
            {
                "messages": [
                    {
                        "roleId": "custom_role_long_term_memory:a6c1f57f37ba4494a3f849fe64b79142:123456",
                        "role": "assistant",
                        "content": "(把身份证收回包里,没好气地瞥了你一眼)还问!再问我自己报上姓名,小婉!(双手抱胸,偏过头去不看你)这次要是还不记住,我就不理你了!",
                        "finishReason": "stop",
                        "tempMessage": false,
                        "validMessage": true,
                        "useMessage": true,
                        "functionMessage": false
                    }
                ],
                "stopReason": "stop"
            }
        ],
        "usage": {
            "outputTokens": 52,
            "inputTokens": 2514,
            "userTokens": 4,
            "pluginTokens": 0,
            "cachedTokens": 0
        },
        "context": {
            "chatRoomId": 74608597,
            "sessionId": "123456",
            "chatId": "952ae3c503924b01b421da857997ad96",
            "answerId": "42d59736ddd141bbbc125cfa7b385432",
            "enableDataInspection": true,
            "isSave": true,
            "requestId": "a8d0aa05-2ff7-4950-a5fc-1ee9b193e963",
            "modelRequestId": "bc1c2ff5-fa04-4699-ae14-d283f534cb5f",
            "characterPk": 1987925581,
            "characterId": "custom_role_long_term_memory:a6c1f57f37ba4494a3f849fe64b79142:123456",
            "modelName": "xingchen-plus-latest",
            "origin": "pass_v2",
            "bizSrc": "PAAS",
            "ext": "chat",
            "isRegenerate": false,
            "bizUserId": "123456789",
            "usePlatformChatHistory": true,
            "chatLockKey": "chat_a6c1f57f37ba4494a3f849fe64b79142_123456789_null_1762487596815",
            "resultCount": 1,
            "longTermMemory": true,
            "isAddMessages": false
        },
        "stop": true
    },
    "success": true
}