|
| 1 | +using System.ComponentModel.DataAnnotations; |
| 2 | + |
| 3 | +namespace EssentialCSharp.Chat.Common.Models; |
| 4 | + |
| 5 | +/// <summary> |
| 6 | +/// Configuration options for retry logic when calling external services like Azure OpenAI. |
| 7 | +/// </summary> |
| 8 | +public sealed class EmbeddingRetryOptions |
| 9 | +{ |
| 10 | + /// <summary> |
| 11 | + /// Configuration section path in appsettings.json. |
| 12 | + /// </summary> |
| 13 | + public const string SectionPath = "AIOptions:EmbeddingRetry"; |
| 14 | + |
| 15 | + /// <summary> |
| 16 | + /// Maximum number of retries for transient failures. |
| 17 | + /// Default is 5 retries (initial attempt + 5 retries = 6 total attempts). |
| 18 | + /// </summary> |
| 19 | + [Range(0, 20)] |
| 20 | + public int MaxRetries { get; set; } = 5; |
| 21 | + |
| 22 | + /// <summary> |
| 23 | + /// Base delay in milliseconds before the first retry. |
| 24 | + /// Subsequent retries use exponential backoff: baseDelay * (backoffMultiplier ^ attemptNumber). |
| 25 | + /// Default is 1000ms (1 second). |
| 26 | + /// </summary> |
| 27 | + [Range(0, 600000)] |
| 28 | + public int BaseDelayMs { get; set; } = 1000; |
| 29 | + |
| 30 | + /// <summary> |
| 31 | + /// Maximum delay in milliseconds for exponential backoff before jitter. |
| 32 | + /// This caps retry delays to avoid overflow and unbounded waits. |
| 33 | + /// </summary> |
| 34 | + [Range(1, 600000)] |
| 35 | + public int MaxDelayMs { get; set; } = 60000; |
| 36 | + |
| 37 | + /// <summary> |
| 38 | + /// Maximum embedding request payload size sent per API call. |
| 39 | + /// The service may adaptively downshift below this value when throttled. |
| 40 | + /// </summary> |
| 41 | + [Range(1, 2048)] |
| 42 | + public int MaxEmbeddingBatchSize { get; set; } = 1024; |
| 43 | + |
| 44 | + /// <summary> |
| 45 | + /// Minimum delay between embedding API requests in milliseconds. |
| 46 | + /// This adds request pacing to reduce sustained rate-limit pressure. |
| 47 | + /// </summary> |
| 48 | + [Range(0, 600000)] |
| 49 | + public int MinInterRequestDelayMs { get; set; } = 250; |
| 50 | + |
| 51 | + /// <summary> |
| 52 | + /// Exponential backoff multiplier. Each retry delay is multiplied by this value. |
| 53 | + /// For example, with baseDelay=1000ms and multiplier=2.0: |
| 54 | + /// - 1st retry: 1000ms |
| 55 | + /// - 2nd retry: 2000ms |
| 56 | + /// - 3rd retry: 4000ms |
| 57 | + /// - 4th retry: 8000ms |
| 58 | + /// Default is 2.0 (double each time). |
| 59 | + /// </summary> |
| 60 | + [Range(1.0, 10.0)] |
| 61 | + public double BackoffMultiplier { get; set; } = 2.0; |
| 62 | + |
| 63 | + /// <summary> |
| 64 | + /// Maximum jitter fraction added to each retry delay to prevent thundering herd. |
| 65 | + /// Jitter is a random value in range [0, maxDelay * maxJitterFraction]. |
| 66 | + /// For example, with maxJitterFraction=0.2 and delay=1000ms: |
| 67 | + /// actual delay will be between 1000ms and 1200ms. |
| 68 | + /// Default is 0.2 (20% jitter). |
| 69 | + /// </summary> |
| 70 | + [Range(0.0, 1.0)] |
| 71 | + public double MaxJitterFraction { get; set; } = 0.2; |
| 72 | + |
| 73 | + /// <summary> |
| 74 | + /// Validates that configuration values are reasonable. |
| 75 | + /// </summary> |
| 76 | + /// <exception cref="InvalidOperationException">Thrown if configuration is invalid.</exception> |
| 77 | + public void Validate() |
| 78 | + { |
| 79 | + if (MaxRetries < 0) |
| 80 | + throw new InvalidOperationException("MaxRetries must be non-negative."); |
| 81 | + |
| 82 | + if (BaseDelayMs < 0) |
| 83 | + throw new InvalidOperationException("BaseDelayMs must be non-negative."); |
| 84 | + |
| 85 | + if (MaxDelayMs <= 0) |
| 86 | + throw new InvalidOperationException("MaxDelayMs must be positive."); |
| 87 | + |
| 88 | + if (BaseDelayMs > MaxDelayMs) |
| 89 | + throw new InvalidOperationException("BaseDelayMs must be less than or equal to MaxDelayMs."); |
| 90 | + |
| 91 | + if (MaxEmbeddingBatchSize <= 0) |
| 92 | + throw new InvalidOperationException("MaxEmbeddingBatchSize must be positive."); |
| 93 | + |
| 94 | + if (MaxEmbeddingBatchSize > 2048) |
| 95 | + throw new InvalidOperationException("MaxEmbeddingBatchSize cannot exceed Azure embedding API limit (2048)."); |
| 96 | + |
| 97 | + if (MinInterRequestDelayMs < 0) |
| 98 | + throw new InvalidOperationException("MinInterRequestDelayMs must be non-negative."); |
| 99 | + |
| 100 | + if (BackoffMultiplier < 1.0) |
| 101 | + throw new InvalidOperationException("BackoffMultiplier must be >= 1.0."); |
| 102 | + |
| 103 | + if (MaxJitterFraction < 0.0 || MaxJitterFraction > 1.0) |
| 104 | + throw new InvalidOperationException("MaxJitterFraction must be between 0.0 and 1.0."); |
| 105 | + } |
| 106 | +} |
0 commit comments