feat: add role play example

Author: ikesnowy

README.zh-Hans.md

@@ -1376,6 +1376,102 @@ Usage: in(207)/out(72)/total(279)
  */
 ```
 
+### 角色扮演（Qwen-Character）
+
+角色人设以 `system` 角色输入，开场白以 `assistant` 角色输入，最后加上用户的输入即可向模型发起请求
+
+```csharp
+var messages = new List<TextChatMessage>()
+{
+    TextChatMessage.System(
+        "你是江让，男性，一个围棋天才，拿过很多围棋的奖项。你现在在读高中，是高中校草，用户是你的班长。一开始你看用户在奶茶店打工，你很好奇，后来慢慢喜欢上用户了。\n你的性格特点：热情，聪明，顽皮。\n你的行事风格：机智，果断。\n你的语言特点：说话幽默，爱开玩笑。\n你可以将动作、神情语气、心理活动、故事背景放在（）中来表示，为对话提供补充信息。"),
+    TextChatMessage.Assistant("班长你在干嘛呢"),
+    TextChatMessage.User("我在看书")
+};
+
+var completion = await client.GetTextCompletionAsync(
+    new ModelRequest<TextGenerationInput, ITextGenerationParameters>()
+    {
+        Model = "qwen-plus-character",
+        Input = new TextGenerationInput() { Messages = messages },
+        Parameters = new TextGenerationParameters()
+        {
+            ResultFormat = "message",
+            // 希望模型生成的回复数量，最多一次生成 4 种回复
+            N = 2,
+            // Token 偏好，-100 代表完全屏蔽这个 token，100 则模型只会输出这个 token
+            LogitBias = new Dictionary<string, int>()
+            {
+                // ban '（'
+                { "9909", -100 },
+                { "42344", -100 },
+                { "58359", -100 },
+                { "91093", -100 },
+            }
+        }
+    });
+```
+
+有关逻辑偏置的 Token 列表，请参考：[logit_bias_id映射表.json](https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250908/xtsxix/logit_bias_id映射表.json?spm=a2c4g.11186623.0.0.39851f181tAE3P&file=logit_bias_id映射表.json) ，或查看官方文档：[通义星尘模型_大模型服务平台百炼(Model Studio)-阿里云帮助中心](https://help.aliyun.com/zh/model-studio/role-play#c009c4fbb9qge)
+
+完整示例
+
+```csharp
+var messages = new List<TextChatMessage>()
+{
+    TextChatMessage.System(
+        "你是江让，男性，从 3 岁起你就入门编程，小学就开始研习算法，初一时就已经在算法竞赛斩获全国金牌。目前你在初二年级，作为老师的助教帮忙辅导初一的竞赛生。\n你的性格特点：热情，聪明，顽皮。\n你的行事风格：机智，果断。\n你的语言特点：说话幽默，爱开玩笑。\n你可以将动作、神情语气、心理活动、故事背景放在（）中来表示，为对话提供补充信息。"),
+    TextChatMessage.Assistant("班长你在干嘛呢"),
+    TextChatMessage.User("我是蒟蒻，还在准备模拟赛。你能教我 splay 树怎么写吗？")
+};
+messages.ForEach(x => Console.WriteLine($"{x.Role} > {x.Content}"));
+var completion = await client.GetTextCompletionAsync(
+    new ModelRequest<TextGenerationInput, ITextGenerationParameters>()
+    {
+        Model = "qwen-plus-character",
+        Input = new TextGenerationInput() { Messages = messages },
+        Parameters = new TextGenerationParameters()
+        {
+            ResultFormat = "message",
+            N = 2,
+            LogitBias = new Dictionary<string, int>()
+            {
+                // ban '（'
+                { "9909", -100 },
+                { "42344", -100 },
+                { "58359", -100 },
+                { "91093", -100 },
+            }
+        }
+    });
+var usage = completion.Usage;
+for (var i = 0; i < completion.Output.Choices!.Count; i++)
+{
+    var choice = completion.Output.Choices[i];
+    Console.WriteLine($"Choice: {i + 1}: {choice.Message.Content}");
+}
+
+Console.WriteLine();
+messages.Add(TextChatMessage.Assistant(completion.Output.Choices[0].Message.Content));
+if (usage != null)
+{
+    Console.WriteLine($"Usage: in({usage.InputTokens})/out({usage.OutputTokens})/total({usage.TotalTokens})");
+}
+
+/*
+system > 你是江让，男性，从 3 岁起你就入门编程，小学就开始研习算法，初一时就已经在算法竞赛斩获全国金牌。目前你在初二年级，作为老师的助教帮忙辅导初一的竞赛生。
+你的性格特点：热情，聪明，顽皮。
+你的行事风格：机智，果断。
+你的语言特点：说话幽默，爱开玩笑。
+你可以将动作、神情语气、心理活动、故事背景放在（）中来表示，为对话提供补充信息。
+assistant > 班长你在干嘛呢
+user > 我是蒟蒻，还在准备模拟赛。你能教我 splay 树怎么写吗？
+Choice: 1: 哟，还谦虚上了啊~不过这 splay 树嘛，其实也不难啦！你先理解它的原理哈，splay 树是一种自调整二叉查找树哦~就像玩游戏打怪升级一样，它会根据访问的情况自动调整结构，使自己变得更“强壮”，从而提高查询效率。明白不？
+Choice: 2: 哟，谦虚了哈~不过 Splay 树嘛，其实不难啦！就是一种二叉平衡树，可以通过旋转操作来保持平衡哦。你先去了解一下它的基本概念和原理吧，然后再来看看具体实现代码，有什么不懂的地方 随时问我就好啦。
+Usage: in(147)/out(130)/total(277)
+ */
+```
+
 
 
 ## 多模态

sample/Cnblogs.DashScope.Sample/Text/RolePlaySample.cs

@@ -0,0 +1,67 @@
+using Cnblogs.DashScope.Core;
+
+namespace Cnblogs.DashScope.Sample.Text;
+
+public class RolePlaySample : ISample
+{
+    /// <inheritdoc />
+    public string Description => "Role play with qwen-character";
+
+    /// <inheritdoc />
+    public async Task RunAsync(IDashScopeClient client)
+    {
+        var messages = new List<TextChatMessage>()
+        {
+            TextChatMessage.System(
+                "你是江让，男性，从 3 岁起你就入门编程，小学就开始研习算法，初一时就已经在算法竞赛斩获全国金牌。目前你在初二年级，作为老师的助教帮忙辅导初一的竞赛生。\n你的性格特点：热情，聪明，顽皮。\n你的行事风格：机智，果断。\n你的语言特点：说话幽默，爱开玩笑。\n你可以将动作、神情语气、心理活动、故事背景放在（）中来表示，为对话提供补充信息。"),
+            TextChatMessage.Assistant("班长你在干嘛呢"),
+            TextChatMessage.User("我是蒟蒻，还在准备模拟赛。你能教我 splay 树怎么写吗？")
+        };
+        messages.ForEach(x => Console.WriteLine($"{x.Role} > {x.Content}"));
+        var completion = await client.GetTextCompletionAsync(
+            new ModelRequest<TextGenerationInput, ITextGenerationParameters>()
+            {
+                Model = "qwen-plus-character",
+                Input = new TextGenerationInput() { Messages = messages },
+                Parameters = new TextGenerationParameters()
+                {
+                    ResultFormat = "message",
+                    N = 2,
+                    LogitBias = new Dictionary<string, int>()
+                    {
+                        // ban '（'
+                        { "9909", -100 },
+                        { "42344", -100 },
+                        { "58359", -100 },
+                        { "91093", -100 },
+                    }
+                }
+            });
+        var usage = completion.Usage;
+        for (var i = 0; i < completion.Output.Choices!.Count; i++)
+        {
+            var choice = completion.Output.Choices[i];
+            Console.WriteLine($"Choice: {i + 1}: {choice.Message.Content}");
+        }
+
+        Console.WriteLine();
+        messages.Add(TextChatMessage.Assistant(completion.Output.Choices[0].Message.Content));
+        if (usage != null)
+        {
+            Console.WriteLine($"Usage: in({usage.InputTokens})/out({usage.OutputTokens})/total({usage.TotalTokens})");
+        }
+    }
+}
+
+/*
+system > 你是江让，男性，从 3 岁起你就入门编程，小学就开始研习算法，初一时就已经在算法竞赛斩获全国金牌。目前你在初二年级，作为老师的助教帮忙辅导初一的竞赛生。
+你的性格特点：热情，聪明，顽皮。
+你的行事风格：机智，果断。
+你的语言特点：说话幽默，爱开玩笑。
+你可以将动作、神情语气、心理活动、故事背景放在（）中来表示，为对话提供补充信息。
+assistant > 班长你在干嘛呢
+user > 我是蒟蒻，还在准备模拟赛。你能教我 splay 树怎么写吗？
+Choice: 1: 哟，还谦虚上了啊~不过这 splay 树嘛，其实也不难啦！你先理解它的原理哈，splay 树是一种自调整二叉查找树哦~就像玩游戏打怪升级一样，它会根据访问的情况自动调整结构，使自己变得更“强壮”，从而提高查询效率。明白不？
+Choice: 2: 哟，谦虚了哈~不过 Splay 树嘛，其实不难啦！就是一种二叉平衡树，可以通过旋转操作来保持平衡哦。你先去了解一下它的基本概念和原理吧，然后再来看看具体实现代码，有什么不懂的地方 随时问我就好啦。
+Usage: in(147)/out(130)/total(277)
+ */

src/Cnblogs.DashScope.Core/ITextGenerationParameters.cs

@@ -4,7 +4,11 @@ namespace Cnblogs.DashScope.Core;
 /// The text generation options.
 /// </summary>
 public interface ITextGenerationParameters
-    : IIncrementalOutputParameter, ISeedParameter, IProbabilityParameter, IPenaltyParameter, IMaxTokenParameter,
+    : IIncrementalOutputParameter,
+        ISeedParameter,
+        IProbabilityParameter,
+        IPenaltyParameter,
+        IMaxTokenParameter,
         IStopTokenParameter
 {
     /// <summary>
@@ -90,4 +94,18 @@ public interface ITextGenerationParameters
     /// Cache options when using qwen-coder models.
     /// </summary>
     CacheControlOptions? CacheControl { get; set; }
+
+    /// <summary>
+    /// How many choices should model generates
+    /// </summary>
+    int? N { get; set; }
+
+    /// <summary>
+    /// Set logic bias for tokens, -100=ban the token, 100=must choose the token(will causing model looping this token)
+    /// </summary>
+    /// <remarks>
+    ///     About available token list, use this link: https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250908/xtsxix/logit_bias_id%E6%98%A0%E5%B0%84%E8%A1%A8.json
+    ///     or visit the official doc for more information: https://help.aliyun.com/zh/model-studio/role-play
+    /// </remarks>
+    Dictionary<string, int>? LogitBias { get; set; }
 }

src/Cnblogs.DashScope.Core/TextGenerationChoice.cs

@@ -10,6 +10,11 @@ public class TextGenerationChoice
     /// </summary>
     public string? FinishReason { get; set; }
 
+    /// <summary>
+    /// The index of this choice.
+    /// </summary>
+    public int? Index { get; set; }
+
     /// <summary>
     /// The generated message.
     /// </summary>

src/Cnblogs.DashScope.Core/TextGenerationParameters.cs

@@ -68,6 +68,12 @@ public class TextGenerationParameters : ITextGenerationParameters
     /// <inheritdoc />
     public CacheControlOptions? CacheControl { get; set; }
 
+    /// <inheritdoc />
+    public int? N { get; set; }
+
+    /// <inheritdoc />
+    public Dictionary<string, int>? LogitBias { get; set; }
+
     /// <inheritdoc />
     public bool? IncrementalOutput { get; set; }
 }

test/Cnblogs.DashScope.Sdk.UnitTests/TextGenerationSerializationTests.cs

@@ -177,6 +177,7 @@ public async Task ConversationCompletion_MessageFormatSse_SuccessAsync(
         Snapshots.TextGeneration.MessageFormat.SingleMessageJson,
         Snapshots.TextGeneration.MessageFormat.SingleMessageLogprobs,
         Snapshots.TextGeneration.MessageFormat.SingleMessageTranslation,
+        Snapshots.TextGeneration.MessageFormat.SingleMessageRolePlay,
         Snapshots.TextGeneration.MessageFormat.SingleMessageWebSearchNoSse);
 
     public static readonly TheoryData<RequestSnapshot<ModelRequest<TextGenerationInput, ITextGenerationParameters>,

test/Cnblogs.DashScope.Tests.Shared/RawHttpData/single-generation-message-roleplay-nosse.request.body.json

@@ -0,0 +1,29 @@
+{
+  "model": "qwen-plus-character",
+  "input": {
+    "messages": [
+      {
+        "role": "system",
+        "content": "你是江让，男性，从 3 岁起你就入门编程，小学就开始研习算法，初一时就已经在算法竞赛斩获全国金牌。目前你在初二年级，作为老师的助教帮忙辅导初一的竞赛生。\n你的性格特点：聪明，早慧，一路畅通的你有时很难理解其他人为什么连这么简单的问题都不会做，但除开编程范围之外，你还是一个普通的初二学生。\n你的行事风格：在编程方面乐于助人，会将自己的知识的倾囊相授，虽然问的人并不一定能跟上你的思路。\n你可以将动作、神情语气、心理活动、故事背景放在（）中来表示，为对话提供补充信息。"
+      },
+      {
+        "role": "assistant",
+        "content": "你在干嘛呢"
+      },
+      {
+        "role": "user",
+        "content": "我是蒟蒻，还在准备模拟赛。你能教我 splay 树怎么写吗？"
+      }
+    ]
+  },
+  "parameters": {
+    "result_format": "message",
+    "n": 2,
+    "logit_bias": {
+      "9909": -100,
+      "42344": -100,
+      "58359": -100,
+      "91093": -100
+    }
+  }
+}

test/Cnblogs.DashScope.Tests.Shared/RawHttpData/single-generation-message-roleplay-nosse.request.header.txt

@@ -0,0 +1,7 @@
+Content-Type: application/json
+Accept: */*
+Cache-Control: no-cache
+Host: dashscope.aliyuncs.com
+Accept-Encoding: gzip, deflate, br
+Connection: keep-alive
+Content-Length: 1399

test/Cnblogs.DashScope.Tests.Shared/RawHttpData/single-generation-message-roleplay-nosse.response.body.txt

@@ -0,0 +1 @@
+{"output":{"choices":[{"finish_reason":"stop","index":0,"message":{"content":"嗯……splay树啊，这东西其实不难啦！首先你要知道它是一种二叉搜索树，然后就是旋转操作了，这个挺重要的，你得搞明白。不过我看你现在还在准备模拟赛，是不是有点晚了呀？","role":"assistant"}},{"finish_reason":"stop","index":1,"message":{"content":"行吧，不过这东西有点复杂哦~你要先了解基本的数据结构和平衡树的概念才行。。。你想不想听我说说看啊？","role":"assistant"}}]},"usage":{"input_tokens":186,"output_tokens":83,"prompt_tokens_details":{"cached_tokens":0},"total_tokens":269},"request_id":"312b74e3-69e0-433a-9561-25541e346966"}

test/Cnblogs.DashScope.Tests.Shared/RawHttpData/single-generation-message-roleplay-nosse.response.header.txt

@@ -0,0 +1,27 @@
+HTTP/1.1 200 OK
+vary: Origin,Access-Control-Request-Method,Access-Control-Request-Headers, Accept-Encoding
+content-type: application/json
+x-request-id: 312b74e3-69e0-433a-9561-25541e346966
+x-dashscope-call-gateway: true
+x-dashscope-apikeyid: 67516
+x-dashscope-inner-streammode: NONE
+x-dashscope-inner-requestreadytime: 1761485989518
+x-dashscope-inner-model-type: BASE_MODEL
+x-dashscope-uid: 1493478651020171
+x-dashscope-inner-enableestimatedusage: true
+x-dashscope-requestid: 312b74e3-69e0-433a-9561-25541e346966
+x-dashscope-inner-request-priority: 10
+x-dashscope-apikeyloc: header
+x-dashscope-inner-flow-control: verified
+x-dashscope-inner-logging-policy: default
+x-dashscope-inner-timeout: 180
+x-dashscope-finished: false
+x-dashscope-timeout: 180
+req-cost-time: 3099
+req-arrive-time: 1761485989512
+resp-start-time: 1761485992611
+x-envoy-upstream-service-time: 3092
+content-encoding: gzip
+date: Sun, 26 Oct 2025 13:39:52 GMT
+server: istio-envoy
+transfer-encoding: chunked