Merge pull request #6 from cnblogs/use-interface-for-extensionablity

feat: make parameters as interface to allow extension parameters

Author: ikesnowy

src/Cnblogs.DashScope.Sdk/BackgroundGenerationParameters.cs

@@ -3,20 +3,14 @@
 /// <summary>
 /// The parameters of background generation task.
 /// </summary>
-public class BackgroundGenerationParameters
+public class BackgroundGenerationParameters : IBackgroundGenerationParameters
 {
-    /// <summary>
-    /// The number of images to be generated.
-    /// </summary>
+    /// <inheritdoc />
     public int? N { get; set; }
 
-    /// <summary>
-    /// Range at [0, 999], controls the distance from generated image to reference image.
-    /// </summary>
+    /// <inheritdoc />
     public int? NoiseLevel { get; set; }
 
-    /// <summary>
-    /// Range at [0,1]. When RefImageUrl and RefPrompt are both set, controls the percentage of ref prompt weight.
-    /// </summary>
+    /// <inheritdoc />
     public float? RefPromptWeight { get; set; }
 }

src/Cnblogs.DashScope.Sdk/BaiChuan/BaiChuanTextGenerationApi.cs

@@ -33,7 +33,7 @@ public static Task<ModelResponse<TextGenerationOutput, TextGenerationTokenUsage>
         string prompt)
     {
         return client.GetTextCompletionAsync(
-            new ModelRequest<TextGenerationInput, TextGenerationParameters>
+            new ModelRequest<TextGenerationInput, ITextGenerationParameters>
             {
                 Model = llm,
                 Input = new TextGenerationInput { Prompt = prompt },
@@ -73,7 +73,7 @@ public static Task<ModelResponse<TextGenerationOutput, TextGenerationTokenUsage>
         string? resultFormat = null)
     {
         return client.GetTextCompletionAsync(
-            new ModelRequest<TextGenerationInput, TextGenerationParameters>
+            new ModelRequest<TextGenerationInput, ITextGenerationParameters>
             {
                 Model = llm,
                 Input = new TextGenerationInput { Messages = messages },

src/Cnblogs.DashScope.Sdk/BatchGetEmbeddingsParameters.cs

@@ -3,7 +3,7 @@
 /// <summary>
 /// Optional parameter of batch get embeddings request.
 /// </summary>
-public class BatchGetEmbeddingsParameters
+public class BatchGetEmbeddingsParameters : IBatchGetEmbeddingsParameters
 {
     /// <summary>
     /// Text type of input. Use <see cref="TextTypes"/> to get available options. Defaults to 'document'.

src/Cnblogs.DashScope.Sdk/DashScopeClientCore.cs

@@ -33,7 +33,7 @@ public DashScopeClientCore(HttpClient httpClient)
 
     /// <inheritdoc />
     public async Task<ModelResponse<TextGenerationOutput, TextGenerationTokenUsage>> GetTextCompletionAsync(
-        ModelRequest<TextGenerationInput, TextGenerationParameters> input,
+        ModelRequest<TextGenerationInput, ITextGenerationParameters> input,
         CancellationToken cancellationToken = default)
     {
         var request = BuildRequest(HttpMethod.Post, ApiLinks.TextGeneration, input);
@@ -44,7 +44,7 @@ public async Task<ModelResponse<TextGenerationOutput, TextGenerationTokenUsage>>
 
     /// <inheritdoc />
     public IAsyncEnumerable<ModelResponse<TextGenerationOutput, TextGenerationTokenUsage>> GetTextCompletionStreamAsync(
-        ModelRequest<TextGenerationInput, TextGenerationParameters> input,
+        ModelRequest<TextGenerationInput, ITextGenerationParameters> input,
         CancellationToken cancellationToken = default)
     {
         var request = BuildSseRequest(HttpMethod.Post, ApiLinks.TextGeneration, input);
@@ -53,7 +53,7 @@ public IAsyncEnumerable<ModelResponse<TextGenerationOutput, TextGenerationTokenU
 
     /// <inheritdoc />
     public async Task<ModelResponse<MultimodalOutput, MultimodalTokenUsage>> GetMultimodalGenerationAsync(
-        ModelRequest<MultimodalInput, MultimodalParameters> input,
+        ModelRequest<MultimodalInput, IMultimodalParameters> input,
         CancellationToken cancellationToken = default)
     {
         var request = BuildRequest(HttpMethod.Post, ApiLinks.MultimodalGeneration, input);
@@ -62,7 +62,7 @@ public async Task<ModelResponse<MultimodalOutput, MultimodalTokenUsage>> GetMult
 
     /// <inheritdoc />
     public IAsyncEnumerable<ModelResponse<MultimodalOutput, MultimodalTokenUsage>> GetMultimodalGenerationStreamAsync(
-        ModelRequest<MultimodalInput, MultimodalParameters> input,
+        ModelRequest<MultimodalInput, IMultimodalParameters> input,
         CancellationToken cancellationToken = default)
     {
         var request = BuildSseRequest(HttpMethod.Post, ApiLinks.MultimodalGeneration, input);
@@ -71,7 +71,7 @@ public IAsyncEnumerable<ModelResponse<MultimodalOutput, MultimodalTokenUsage>> G
 
     /// <inheritdoc />
     public async Task<ModelResponse<TextEmbeddingOutput, TextEmbeddingTokenUsage>> GetEmbeddingsAsync(
-        ModelRequest<TextEmbeddingInput, TextEmbeddingParameters> input,
+        ModelRequest<TextEmbeddingInput, ITextEmbeddingParameters> input,
         CancellationToken cancellationToken = default)
     {
         var request = BuildRequest(HttpMethod.Post, ApiLinks.TextEmbedding, input);
@@ -83,7 +83,7 @@ public async Task<ModelResponse<TextEmbeddingOutput, TextEmbeddingTokenUsage>> G
     /// <inheritdoc />
     public async
         Task<ModelResponse<BatchGetEmbeddingsOutput, TextEmbeddingTokenUsage>> BatchGetEmbeddingsAsync(
-            ModelRequest<BatchGetEmbeddingsInput, BatchGetEmbeddingsParameters> input,
+            ModelRequest<BatchGetEmbeddingsInput, IBatchGetEmbeddingsParameters> input,
             CancellationToken cancellationToken = default)
     {
         var request = BuildRequest(HttpMethod.Post, ApiLinks.TextEmbedding, input, isTask: true);
@@ -94,7 +94,7 @@ Task<ModelResponse<BatchGetEmbeddingsOutput, TextEmbeddingTokenUsage>> BatchGetE
 
     /// <inheritdoc />
     public async Task<ModelResponse<ImageSynthesisOutput, ImageSynthesisUsage>> CreateImageSynthesisTaskAsync(
-        ModelRequest<ImageSynthesisInput, ImageSynthesisParameters> input,
+        ModelRequest<ImageSynthesisInput, IImageSynthesisParameters> input,
         CancellationToken cancellationToken = default)
     {
         var request = BuildRequest(HttpMethod.Post, ApiLinks.ImageSynthesis, input, isTask: true);
@@ -173,7 +173,7 @@ public async Task<DashScopeTaskOperationResponse> CancelTaskAsync(
 
     /// <inheritdoc />
     public async Task<ModelResponse<TokenizationOutput, TokenizationUsage>> TokenizeAsync(
-        ModelRequest<TextGenerationInput, TextGenerationParameters> input,
+        ModelRequest<TextGenerationInput, ITextGenerationParameters> input,
         CancellationToken cancellationToken = default)
     {
         var request = BuildRequest(HttpMethod.Post, ApiLinks.Tokenizer, input);
@@ -191,7 +191,10 @@ public async Task<ModelResponse<ImageGenerationOutput, ImageGenerationUsage>> Cr
     }
 
     /// <inheritdoc />
-    public async Task<ModelResponse<BackgroundGenerationOutput, BackgroundGenerationUsage>> CreateBackgroundGenerationTaskAsync(ModelRequest<BackgroundGenerationInput, BackgroundGenerationParameters> input, CancellationToken cancellationToken = default)
+    public async Task<ModelResponse<BackgroundGenerationOutput, BackgroundGenerationUsage>>
+        CreateBackgroundGenerationTaskAsync(
+            ModelRequest<BackgroundGenerationInput, IBackgroundGenerationParameters> input,
+            CancellationToken cancellationToken = default)
     {
         var request = BuildRequest(HttpMethod.Post, ApiLinks.BackgroundGeneration, input, isTask: true);
         return (await SendAsync<ModelResponse<BackgroundGenerationOutput, BackgroundGenerationUsage>>(

src/Cnblogs.DashScope.Sdk/IBackgroundGenerationParameters.cs

@@ -0,0 +1,22 @@
+namespace Cnblogs.DashScope.Sdk;
+
+/// <summary>
+/// The parameters of background generation task.
+/// </summary>
+public interface IBackgroundGenerationParameters
+{
+    /// <summary>
+    /// The number of images to be generated.
+    /// </summary>
+    public int? N { get; }
+
+    /// <summary>
+    /// Range at [0, 999], controls the distance from generated image to reference image.
+    /// </summary>
+    public int? NoiseLevel { get; }
+
+    /// <summary>
+    /// Range at [0,1]. When RefImageUrl and RefPrompt are both set, controls the percentage of ref prompt weight.
+    /// </summary>
+    public float? RefPromptWeight { get; }
+}

src/Cnblogs.DashScope.Sdk/IBatchGetEmbeddingsParameters.cs

@@ -0,0 +1,6 @@
+namespace Cnblogs.DashScope.Sdk;
+
+/// <summary>
+/// Optional parameter of batch get embeddings request.
+/// </summary>
+public interface IBatchGetEmbeddingsParameters : ITextEmbeddingParameters;

src/Cnblogs.DashScope.Sdk/IDashScopeClient.cs

@@ -12,7 +12,7 @@ public interface IDashScopeClient
     /// <param name="cancellationToken">The cancellation token to use.</param>
     /// <returns>The completion result.</returns>
     Task<ModelResponse<TextGenerationOutput, TextGenerationTokenUsage>> GetTextCompletionAsync(
-        ModelRequest<TextGenerationInput, TextGenerationParameters> input,
+        ModelRequest<TextGenerationInput, ITextGenerationParameters> input,
         CancellationToken cancellationToken = default);
 
     /// <summary>
@@ -22,7 +22,7 @@ Task<ModelResponse<TextGenerationOutput, TextGenerationTokenUsage>> GetTextCompl
     /// <param name="cancellationToken">The cancellation token to use.</param>
     /// <returns></returns>
     IAsyncEnumerable<ModelResponse<TextGenerationOutput, TextGenerationTokenUsage>> GetTextCompletionStreamAsync(
-        ModelRequest<TextGenerationInput, TextGenerationParameters> input,
+        ModelRequest<TextGenerationInput, ITextGenerationParameters> input,
         CancellationToken cancellationToken = default);
 
     /// <summary>
@@ -31,7 +31,7 @@ IAsyncEnumerable<ModelResponse<TextGenerationOutput, TextGenerationTokenUsage>>
     /// <param name="input">The raw input payload for completion.</param>
     /// <param name="cancellationToken">The cancellation token to use.</param>
     Task<ModelResponse<MultimodalOutput, MultimodalTokenUsage>> GetMultimodalGenerationAsync(
-        ModelRequest<MultimodalInput, MultimodalParameters> input,
+        ModelRequest<MultimodalInput, IMultimodalParameters> input,
         CancellationToken cancellationToken = default);
 
     /// <summary>
@@ -41,7 +41,7 @@ Task<ModelResponse<MultimodalOutput, MultimodalTokenUsage>> GetMultimodalGenerat
     /// <param name="cancellationToken">The cancellation token to use.</param>
     /// <returns></returns>
     IAsyncEnumerable<ModelResponse<MultimodalOutput, MultimodalTokenUsage>> GetMultimodalGenerationStreamAsync(
-        ModelRequest<MultimodalInput, MultimodalParameters> input,
+        ModelRequest<MultimodalInput, IMultimodalParameters> input,
         CancellationToken cancellationToken = default);
 
     /// <summary>
@@ -51,7 +51,7 @@ IAsyncEnumerable<ModelResponse<MultimodalOutput, MultimodalTokenUsage>> GetMulti
     /// <param name="cancellationToken">The cancellation token to use.</param>
     /// <returns></returns>
     Task<ModelResponse<TextEmbeddingOutput, TextEmbeddingTokenUsage>> GetEmbeddingsAsync(
-        ModelRequest<TextEmbeddingInput, TextEmbeddingParameters> input,
+        ModelRequest<TextEmbeddingInput, ITextEmbeddingParameters> input,
         CancellationToken cancellationToken = default);
 
     /// <summary>
@@ -62,7 +62,7 @@ Task<ModelResponse<TextEmbeddingOutput, TextEmbeddingTokenUsage>> GetEmbeddingsA
     /// <returns></returns>
     Task<ModelResponse<BatchGetEmbeddingsOutput, TextEmbeddingTokenUsage>>
         BatchGetEmbeddingsAsync(
-            ModelRequest<BatchGetEmbeddingsInput, BatchGetEmbeddingsParameters> input,
+            ModelRequest<BatchGetEmbeddingsInput, IBatchGetEmbeddingsParameters> input,
             CancellationToken cancellationToken = default);
 
     /// <summary>
@@ -72,7 +72,7 @@ Task<ModelResponse<TextEmbeddingOutput, TextEmbeddingTokenUsage>> GetEmbeddingsA
     /// <param name="cancellationToken">The cancellation token to use.</param>
     /// <returns></returns>
     Task<ModelResponse<ImageSynthesisOutput, ImageSynthesisUsage>> CreateImageSynthesisTaskAsync(
-        ModelRequest<ImageSynthesisInput, ImageSynthesisParameters> input,
+        ModelRequest<ImageSynthesisInput, IImageSynthesisParameters> input,
         CancellationToken cancellationToken = default);
 
     /// <summary>
@@ -126,7 +126,7 @@ Task<DashScopeTaskList> ListTasksAsync(
     /// <param name="cancellationToken">The cancellation token to use.</param>
     /// <returns></returns>
     Task<ModelResponse<TokenizationOutput, TokenizationUsage>> TokenizeAsync(
-        ModelRequest<TextGenerationInput, TextGenerationParameters> input,
+        ModelRequest<TextGenerationInput, ITextGenerationParameters> input,
         CancellationToken cancellationToken = default);
 
     /// <summary>
@@ -147,6 +147,6 @@ Task<ModelResponse<ImageGenerationOutput, ImageGenerationUsage>> CreateImageGene
     /// <returns></returns>
     public Task<ModelResponse<BackgroundGenerationOutput, BackgroundGenerationUsage>>
         CreateBackgroundGenerationTaskAsync(
-            ModelRequest<BackgroundGenerationInput, BackgroundGenerationParameters> input,
+            ModelRequest<BackgroundGenerationInput, IBackgroundGenerationParameters> input,
             CancellationToken cancellationToken = default);
 }

src/Cnblogs.DashScope.Sdk/IImageSynthesisParameters.cs

@@ -0,0 +1,27 @@
+namespace Cnblogs.DashScope.Sdk;
+
+/// <summary>
+/// Optional parameters for image synthesis task.
+/// </summary>
+public interface IImageSynthesisParameters
+{
+    /// <summary>
+    /// Generated image style, defaults to '&lt;auto&gt;'. Use <see cref="ImageStyles"/> to get all available options.
+    /// </summary>
+    public string? Style { get; }
+
+    /// <summary>
+    /// Generated image size, defaults to 1024*1024. Another options are: 1280*720 and 720*1280.
+    /// </summary>
+    public string? Size { get; }
+
+    /// <summary>
+    /// Number of images requested. Max number is 4, defaults to 1.
+    /// </summary>
+    public int? N { get; }
+
+    /// <summary>
+    /// Seed for randomizer, max at 4294967290. Once set, generated image will use seed, seed+1, seed+2, seed+3 depends on <see cref="N"/>.
+    /// </summary>
+    public uint? Seed { get; }
+}

src/Cnblogs.DashScope.Sdk/IIncrementalOutputParameter.cs

@@ -0,0 +1,12 @@
+namespace Cnblogs.DashScope.Sdk;
+
+/// <summary>
+/// Marks parameter accepts incremental output.
+/// </summary>
+public interface IIncrementalOutputParameter
+{
+    /// <summary>
+    /// Enable stream output. Defaults to false.
+    /// </summary>
+    public bool? IncrementalOutput { get; }
+}

src/Cnblogs.DashScope.Sdk/IMultimodalParameters.cs

@@ -0,0 +1,6 @@
+namespace Cnblogs.DashScope.Sdk;
+
+/// <summary>
+/// Optional parameters for multi-model generation request.
+/// </summary>
+public interface IMultimodalParameters : IProbabilityParameter, ISeedParameter, IIncrementalOutputParameter;

src/Cnblogs.DashScope.Sdk/Internals/IProbabilityParameter.cs renamed to src/Cnblogs.DashScope.Sdk/IProbabilityParameter.cs

@@ -1,6 +1,9 @@
-namespace Cnblogs.DashScope.Sdk.Internals;
+namespace Cnblogs.DashScope.Sdk;
 
-internal interface IProbabilityParameter
+/// <summary>
+/// Marks parameter accepts top_p and top_k options.
+/// </summary>
+public interface IProbabilityParameter
 {
     /// <summary>
     /// The probability threshold during generation, defaults to 0.8 when null.

src/Cnblogs.DashScope.Sdk/ISeedParameter.cs

@@ -0,0 +1,12 @@
+namespace Cnblogs.DashScope.Sdk;
+
+/// <summary>
+/// Marks parameter supports seed option.
+/// </summary>
+public interface ISeedParameter
+{
+    /// <summary>
+    /// The seed for randomizer, defaults to 1234 when null.
+    /// </summary>
+    public ulong? Seed { get; }
+}

src/Cnblogs.DashScope.Sdk/ITextEmbeddingParameters.cs

@@ -0,0 +1,12 @@
+namespace Cnblogs.DashScope.Sdk;
+
+/// <summary>
+/// The optional parameters for text embedding.
+/// </summary>
+public interface ITextEmbeddingParameters
+{
+    /// <summary>
+    /// The text type("query" or "document"). Defaults to "document".
+    /// </summary>
+    public string? TextType { get; }
+}

src/Cnblogs.DashScope.Sdk/ITextGenerationParameters.cs

@@ -0,0 +1,45 @@
+namespace Cnblogs.DashScope.Sdk;
+
+/// <summary>
+/// The text generation options.
+/// </summary>
+public interface ITextGenerationParameters : IIncrementalOutputParameter, ISeedParameter, IProbabilityParameter
+{
+    /// <summary>
+    /// The format of the result message, must be <c>text</c> or <c>message</c>.
+    /// </summary>
+    /// <remarks>
+    /// <c>text</c> - original text format.
+    /// <para><c>message</c> - OpenAI compatible message format</para>
+    /// </remarks>
+    public string? ResultFormat { get; }
+
+    /// <summary>
+    /// The maximum number of tokens the model can generate.
+    /// </summary>
+    /// <remarks>
+    /// Default and maximum number of tokens is 1500(qwen-turbo) or 2000(qwen-max, qwen-max-1201, qwen-max-longcontext, qwen-plus).
+    /// </remarks>
+    public int? MaxTokens { get; }
+
+    /// <summary>
+    /// Increasing the repetition penalty can reduce the amount of repetition in the model’s output. A value of 1.0 indicates no penalty, with the default set at 1.1.
+    /// </summary>
+    public float? RepetitionPenalty { get; }
+
+    /// <summary>
+    /// Controls the diversity of generations. Lower temperature leads to more consistent result.
+    /// </summary>
+    /// <remarks>Must be in [0,2), defaults to 0.85.</remarks>
+    public float? Temperature { get; }
+
+    /// <summary>
+    /// Stop generation when next token or string is in given range.
+    /// </summary>
+    public TextGenerationStop? Stop { get; }
+
+    /// <summary>
+    /// Enable internet search when generation. Defaults to false.
+    /// </summary>
+    public bool? EnableSearch { get; }
+}