如何避免Cosmos .NET SDK批量执行超出预配吞吐量？

针对手动预配吞吐量的NoSQL Cosmos DB容器，使用v3 .NET SDK批量Upsert时出现429错误的问题，以下是高效且不超配额的解决方法：

• 调整批量执行模式的并发参数
  批量模式默认高并发会导致RU瞬间突增，通过BulkExecutionOptions限制并发数，让RU消耗平稳落在预配额度内：

  var bulkOptions = new BulkExecutionOptions
  {
      MaxConcurrency = 15, // 根据预配RU调整，比如1000RU可设10-20
      MaxConcurrencyPerPartitionKey = 5
  };
  await container.UpsertItemsAsync(documents, bulkOptions);
  

  建议根据实际压测结果微调并发值，避免峰值超支。

• 客户端侧实现速率限流
  基于预配RU和单文档Upsert的RU消耗，计算每秒允许的操作数，用速率限制组件控制提交频率：

  // 假设预配1000RU，单文档Upsert需10RU，每秒最多处理100个
  var rateLimiter = new TokenBucketRateLimiter(new TokenBucketRateLimiterOptions
  {
      TokenLimit = 100,
      ReplenishmentPeriod = TimeSpan.FromSeconds(1),
      TokensPerPeriod = 100
  });
  
  foreach (var doc in documents)
  {
      using var lease = await rateLimiter.AcquireAsync(1);
      await container.UpsertItemAsync(doc);
  }
  

  若结合批量模式，需让批量并发数和限流速率匹配，避免冲突。

• 精准估算单文档RU消耗
  先测试单个文档Upsert的实际RU，再计算每次批量提交的最大文档数：

  var testResponse = await container.UpsertItemAsync(testDocument);
  double ruPerItem = testResponse.RequestCharge;
  // 留15%余量避免波动
  int maxBatchSize = (int)((预配RU值 * 0.85) / ruPerItem);
  

  按这个批次大小拆分文档后批量提交，确保单次批量的RU消耗不超配额。

• 自定义重试策略限制重试次数
  默认重试策略可能加剧RU消耗，自定义策略限制重试次数和间隔：

  var client = new CosmosClient(connectionString, new CosmosClientOptions
  {
      RetryPolicy = new ControlledRetryPolicy()
  });
  
  class ControlledRetryPolicy : CosmosRetryPolicy
  {
      private int _retryCount = 0;
      public override Task<RetryPolicyResult> ShouldRetryAsync(Exception exception, CancellationToken cancellationToken)
      {
          if (exception is CosmosException cosmosEx && cosmosEx.StatusCode == System.Net.HttpStatusCode.TooManyRequests)
          {
              if (_retryCount < 2) // 限制最多重试2次
              {
                  _retryCount++;
                  return Task.FromResult(RetryPolicyResult.RetryWithDelay(TimeSpan.FromMilliseconds(600)));
              }
          }
          return Task.FromResult(RetryPolicyResult.DoNotRetry);
      }
  }
  

  避免无限制重试导致RU持续超支，同时给Cosmos DB留恢复时间。

• 按分区键拆分批量请求
  若文档跨多个分区键，批量模式会并行处理不同分区导致RU总和超支。将文档按分区键分组，逐个分区提交批量请求：

  var partitionGroups = documents.GroupBy(doc => doc.PartitionKeyField);
  foreach (var group in partitionGroups)
  {
      await container.UpsertItemsAsync(group, new BulkExecutionOptions { MaxConcurrencyPerPartitionKey = 4 });
  }
  

  这样每个分区的RU消耗会更平稳，避免跨分区并发带来的峰值。

• 关闭批量模式的额外优化特性
  若开启了EnableRUPerMinuteUsage，可尝试关闭；如果文档ID是自定义生成的，设置DisableAutomaticIdGeneration = true，减少批量模式下的额外RU消耗。

内容的提问来源于stack exchange，提问作者gonzaleznicolas