自定义角色对话

更新时间:

自定义角色

鉴权

字段

传参方式

类型

必传

描述

示例值

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

注意:模型参数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 '{
            "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
}