Merge pull request #110 from cnblogs/update-docs

feat: update readme doc and samples

Author: ikesnowy

README.md

@@ -1,18 +1,18 @@
 [English](https://github.com/cnblogs/dashscope-sdk/blob/main/README.md) | 简体中文
 
+# Cnblogs.DashScopeSDK
+
 [![NuGet Version](https://img.shields.io/nuget/v/Cnblogs.DashScope.AI?style=flat&logo=nuget&label=Cnblogs.DashScope.AI)](https://www.nuget.org/packages/Cnblogs.DashScope.AI)
 [![NuGet Version](https://img.shields.io/nuget/v/Cnblogs.DashScope.Sdk?style=flat&logo=nuget&label=Cnblogs.DashScope.Sdk&link=https%3A%2F%2Fwww.nuget.org%2Fpackages%2FCnblogs.DashScope.Sdk)](https://www.nuget.org/packages/Cnblogs.DashScope.Sdk)
 [![NuGet Version](https://img.shields.io/nuget/v/Cnblogs.DashScope.AspNetCore?style=flat&logo=nuget&label=Cnblogs.DashScope.AspNetCore&link=https%3A%2F%2Fwww.nuget.org%2Fpackages%2FCnblogs.DashScope.AspNetCore)](https://www.nuget.org/packages/Cnblogs.DashScope.AspNetCore)
 
-# Cnblogs.DashScopeSDK
-
 由博客园维护并使用的非官方灵积（百炼）服务 SDK。
 
 使用前注意：当前项目正在积极开发中，小版本也可能包含破坏性更改，升级前请查看对应版本 Release Note 进行迁移。
 
-# 快速开始
+## 快速开始
 
-## 使用 `Microsoft.Extensions.AI` 接口
+### 使用 `Microsoft.Extensions.AI` 接口
 
 安装 NuGet 包 `Cnblogs.DashScope.AI`
 
@@ -22,7 +22,7 @@ var completion = await client.CompleteAsync("hello");
 Console.WriteLine(completion)
 ```
 
-## 控制台应用
+### 控制台应用
 
 安装 NuGet 包 `Cnblogs.DashScope.Sdk`。
 
@@ -34,7 +34,7 @@ var completion = await client.GetQWenCompletionAsync(QWenLlm.QWenMax, prompt);
 Console.WriteLine(completion.Output.Text);
 ```
 
-## ASP.NET Core 应用
+### ASP.NET Core 应用
 
 安装 NuGet 包 `Cnblogs.DashScope.AspNetCore`。
 
@@ -64,70 +64,22 @@ public class YourService(IDashScopeClient client)
 }
 ```
 
-# 支持的 API
+## 支持的 API
 
-- 通用文本向量 - `GetTextEmbeddingsAsync()`
-- 通义千问（`qwen-turbo`， `qwen-max` 等） - `GetQWenCompletionAsync()` 和 `GetQWenCompletionStreamAsync()`
-- DeepSeek 系列模型（`deepseek-r1`，`deepseek-v3` 等） - `GetDeepSeekChatCompletionAsync()` 和 `GetDeepSeekChatCompletionStreamAsync()`
-- 百川开源大模型 - `GetBaiChuanTextCompletionAsync()`
-- LLaMa2 大语言模型 - `GetLlama2TextCompletionAsync()`
-- 通义千问 VL 和通义千问 Audio(`qwen-vl-max`， `qwen-audio`) - `GetQWenMultimodalCompletionAsync()` 和 `GetQWenMultimodalCompletionStreamAsync()`
-- 通义万相系列
-    - 文生图 - `CreateWanxImageSynthesisTaskAsync()` 和 `GetWanxImageSynthesisTaskAsync()`
-    - 人像风格重绘 - `CreateWanxImageGenerationTaskAsync()` 和 `GetWanxImageGenerationTaskAsync()`
-    - 图像背景生成 - `CreateWanxBackgroundGenerationTaskAsync()` 和 `GetWanxBackgroundGenerationTaskAsync()`
-- 适用于 QWen-Long 的文件 API `UploadFileAsync()` 和 `DeleteFileAsync`
-- 应用调用 `GetApplicationResponseAsync` 和 `GetApplicationResponseStreamAsync()`
-- 其他使用相同 Endpoint 的模型
+- [对话](#对话) - QWen3, DeepSeek 等，支持推理/工具调用/网络搜索/翻译等场景
+- [多模态](#多模态) - QWen-VL，QVQ 等，支持推理/视觉理解/OCR/音频理解等场景
+- [语音合成](#语音合成) - CosyVoice，Sambert 等，支持 TTS 等应用场景
+- [图像生成](#图像生成) - wanx2.1 等，支持文生图，人像风格重绘等应用场景
+- [应用调用](#应用调用)
+- [文本向量](#文本向量)
 
-# 示例
-
-查看 [快照文件](./test/Cnblogs.DashScope.Tests.Shared/Utils/Snapshots.cs) 获得 API 调用参数示例.
-
-查看 [测试](./test) 获得更多 API 使用示例。
-
-## 文本生成
+### 对话
 
 使用 `dashScopeClient.GetTextCompletionAsync` 和 `dashScopeClient.GetTextCompletionStreamAsync` 来直接访问文本生成接口。
 
-相关文档：https://help.aliyun.com/zh/model-studio/user-guide/text-generation/
-
-```csharp
-var completion = await dashScopeClient.GetTextCompletionAsync(
-            new ModelRequest<TextGenerationInput, ITextGenerationParameters>
-            {
-                Model = "your-model-name",
-                Input = new TextGenerationInput { Prompt = prompt },
-                Parameters = new TextGenerationParameters()
-                {
-                    // control parameters as you wish.
-                    EnableSearch = true
-                }
-            });
-
-var completions = dashScopeClient.GetTextCompletionStreamAsync(
-            new ModelRequest<TextGenerationInput, ITextGenerationParameters>
-            {
-                Model = "your-model-name",
-                Input = new TextGenerationInput { Messages = [TextChatMessage.System("you are a helpful assistant"), TextChatMessage.User("How are you?")] },
-                Parameters = new TextGenerationParameters()
-                {
-                    // control parameters as you wish.
-                    EnableSearch = true,
-                    IncreamentalOutput = true
-                }
-            });
-```
-
-## 单轮对话
+针对通义千问和 DeekSeek，我们提供了快捷方法进行调用： `GetQWenChatCompletionAsync` /`GetDeepSeekChatCompletionAsync`
 
-```csharp
-var prompt = "你好"
-var completion = await client.GetQWenCompletionAsync(QWenLlm.QWenMax, prompt);
-Console.WriteLine(completion.Output.Text);
-```
-
-## 多轮对话
+相关文档：https://help.aliyun.com/zh/model-studio/user-guide/text-generation/
 
 ```csharp
 var history = new List<ChatMessage>
@@ -144,7 +96,7 @@ var completion = await client.GetQWenChatCompletionAsync(QWenLlm.QWenMax, histor
 Console.WriteLine(completion.Output.Choices[0].Message.Content); // The number is 42
 ```
 
-## 推理
+#### 推理
 
 使用推理模型时，模型的思考过程可以通过 `ReasoningContent` 属性获取。
 
@@ -157,9 +109,7 @@ var completion = await client.GetDeepSeekChatCompletionAsync(DeepSeekLlm.DeepSee
 Console.WriteLine(completion.Output.Choices[0]!.Message.ReasoningContent);
 ```
 
-### QWen3
-
-使用 `TextGenerationParameters.EnableThinking` 决定是否使用模型的推理能力。
+对于支持的模型（例如 qwen3），可以使用 `TextGenerationParameters.EnableThinking` 决定是否使用模型的推理能力。
 
 ```csharp
 var stream = dashScopeClient
@@ -174,7 +124,7 @@ var stream = dashScopeClient
                 });
 ```
 
-## 工具调用
+#### 工具调用
 
 创建一个可供模型使用的方法。
 
@@ -241,9 +191,9 @@ Console.WriteLine(completion.Output.Choice[0].Message.Content) // 现在浙江
 
 当模型认为应当调用工具时，返回消息中 `ToolCalls` 会提供调用的详情，本地在调用完成后可以把结果以 `tool` 角色返回。
 
-## 上传文件（QWen-Long）
+#### 上传文件（qwen-long）
 
-需要先提前将文件上传到 DashScope 来获得 Id。
+使用长上下文模型时，需要先提前将文件上传到 DashScope 来获得 Id。
 
 ```csharp
 var file = new FileInfo("test.txt");
@@ -272,7 +222,162 @@ Console.WriteLine(completion.Output.Choices[0].Message.Content);
 var deletionResult = await dashScopeClient.DeleteFileAsync(uploadedFile.Id);
 ```
 
-## 应用调用
+### 多模态
+
+使用 `dashScopeClient.GetMultimodalGenerationAsync` 和 `dashScopeClient.GetMultimodalGenerationStreamAsync` 来访问多模态文本生成接口。
+
+相关文档：[多模态_大模型服务平台百炼(Model Studio)-阿里云帮助中心](https://help.aliyun.com/zh/model-studio/multimodal)
+
+#### 视觉理解/推理
+
+使用 `MultimodalMessage.User()` 可以快速创建对应角色的消息。
+
+媒体内容可以通过公网 URL 或者 `byte[]` 传入。
+
+```csharp
+var image = await File.ReadAllBytesAsync("Lenna.jpg");
+var response = dashScopeClient.GetMultimodalGenerationStreamAsync(
+    new ModelRequest<MultimodalInput, IMultimodalParameters>()
+    {
+        Model = "qvq-plus",
+        Input = new MultimodalInput()
+        {
+            Messages =
+            [
+                MultimodalMessage.User(
+                [
+                    MultimodalMessageContent.ImageContent(image, "image/jpeg"),
+                    MultimodalMessageContent.TextContent("她是谁？")
+                ])
+            ]
+        },
+        Parameters = new MultimodalParameters { IncrementalOutput = true, VlHighResolutionImages = false }
+    });
+
+// output
+var reasoning = false;
+await foreach (var modelResponse in response)
+{
+    var choice = modelResponse.Output.Choices.FirstOrDefault();
+    if (choice != null)
+    {
+        if (choice.FinishReason != "null")
+        {
+            break;
+        }
+
+        if (string.IsNullOrEmpty(choice.Message.ReasoningContent) == false)
+        {
+            if (reasoning == false)
+            {
+                reasoning = true;
+                Console.WriteLine("<think>");
+            }
+
+            Console.Write(choice.Message.ReasoningContent);
+            continue;
+        }
+
+        if (reasoning)
+        {
+            reasoning = false;
+            Console.WriteLine("</think>");
+        }
+
+        Console.Write(choice.Message.Content[0].Text);
+    }
+}
+```
+
+### 语音合成
+
+通过 `dashScopeClient.CreateSpeechSynthesizerSocketSessionAsync()` 来创建一个语音合成会话。
+
+**注意：使用 using 语句来自动释放会话，或者手动 Dispose 会话，尽量不要重用会话。**
+
+相关文档：[语音合成-CosyVoice_大模型服务平台百炼(Model Studio)-阿里云帮助中心](https://help.aliyun.com/zh/model-studio/cosyvoice-large-model-for-speech-synthesis)
+
+```csharp
+using var tts = await dashScopeClient.CreateSpeechSynthesizerSocketSessionAsync("cosyvoice-v2");
+var taskId = await tts.RunTaskAsync(
+    new SpeechSynthesizerParameters { Voice = "longxiaochun_v2", Format = "mp3" });
+await tts.ContinueTaskAsync(taskId, "博客园");
+await tts.ContinueTaskAsync(taskId, "代码改变世界");
+await tts.FinishTaskAsync(taskId);
+var file = new FileInfo("tts.mp3");
+using var stream = file.OpenWrite();
+await foreach (var b in tts.GetAudioAsync())
+{
+    stream.WriteByte(b);
+}
+
+stream.Close();
+
+var tokenUsage = 0;
+await foreach (var message in tts.GetMessagesAsync())
+{
+    if (message.Payload.Usage?.Characters > tokenUsage)
+    {
+        tokenUsage = message.Payload.Usage.Characters;
+    }
+}
+
+Console.WriteLine($"audio saved to {file.FullName}, token usage: {tokenUsage}");
+break;
+```
+
+### 图像生成
+
+#### 文生图
+
+我们针对通义万相提供了快捷 API `dashScopeClient.CreateWanxImageSynthesisTaskAsync()` 和 `GetWanxImageSynthesisTaskAsync()`。
+
+图片生成需要数秒到数十秒不等，对于 HTTP 请求来说太长，需要通过任务方式生成。
+
+先使用 `CreateWanxImageSynthesisTaskAsync()` 创建任务，再轮询 `GetWanxImageSynthesisTaskAsync()` 检查任务完成状态。
+
+相关文档：[通义万相2.1文生图V2版API参考_大模型服务平台百炼(Model Studio)-阿里云帮助中心](https://help.aliyun.com/zh/model-studio/text-to-image-v2-api-reference)
+
+```csharp
+var prompt = Console.ReadLine();
+var task = await dashScopeClient.CreateWanxImageSynthesisTaskAsync(
+    WanxModel.WanxV21Turbo,
+    prompt,
+    null,
+    new ImageSynthesisParameters { Style = ImageStyles.OilPainting });
+Console.WriteLine($"Task({task.TaskId}) submitted, checking status...");
+var watch = Stopwatch.StartNew();
+while (watch.Elapsed.TotalSeconds < 120)
+{
+    var result = await dashScopeClient.GetWanxImageSynthesisTaskAsync(task.TaskId);
+    Console.WriteLine($"{watch.ElapsedMilliseconds}ms - Status: {result.Output.TaskStatus}");
+    if (result.Output.TaskStatus == DashScopeTaskStatus.Succeeded)
+    {
+        Console.WriteLine($"Image generation finished, URL: {result.Output.Results![0].Url}");
+        return;
+    }
+
+    if (result.Output.TaskStatus == DashScopeTaskStatus.Failed)
+    {
+        Console.WriteLine($"Image generation failed, error message: {result.Output.Message}");
+        return;
+    }
+
+    await Task.Delay(500);
+}
+
+Console.WriteLine($"Task timout, taskId: {task.TaskId}");
+```
+
+#### 人像风格重绘和图像背景生成
+
+与文生图类似，先创建任务，再轮询状态。
+
+人像风格重绘 - `CreateWanxImageGenerationTaskAsync` 和 `GetWanxImageGenerationTaskAsync`
+
+图像背景生成 - `CreateWanxBackgroundGenerationTaskAsync` 和 `GetWanxBackgroundGenerationTaskAsync`
+
+### 应用调用
 
 `GetApplicationResponseAsync` 用于进行应用调用。
 
@@ -339,3 +444,25 @@ var request =
 var response = await client.GetApplicationResponseAsync("your-application-id", request);
 Console.WriteLine(response.Output.Text);
 ```
+
+### 文本向量
+
+使用 `GetTextEmbeddingsAsync` 来调用文本向量接口。
+
+相关文档：[通用文本向量同步接口API详情_大模型服务平台百炼(Model Studio)-阿里云帮助中心](https://help.aliyun.com/zh/model-studio/text-embedding-synchronous-api)
+
+```csharp
+var text = Console.ReadLine();
+var response = await dashScopeClient.GetTextEmbeddingsAsync(
+    TextEmbeddingModel.TextEmbeddingV4,
+    [text],
+    new TextEmbeddingParameters() { Dimension = 512, });
+var array = response.Output.Embeddings.First().Embedding;
+Console.WriteLine("Embedding");
+Console.WriteLine(string.Join('\n', array));
+Console.WriteLine($"Token usage: {response.Usage?.TotalTokens}");
+```
+
+查看 [快照文件](./test/Cnblogs.DashScope.Tests.Shared/Utils/Snapshots.cs) 获得 API 调用参数示例.
+
+查看 [测试](./test) 获得更多 API 使用示例。

README.zh-Hans.md

@@ -17,6 +17,9 @@
     <None Update="test.txt">
       <CopyToOutputDirectory>Always</CopyToOutputDirectory>
     </None>
+    <None Update="Lenna.jpg">
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    </None>
   </ItemGroup>
 
   <ItemGroup>