LanguageModelRateLimitingPlugin

藉由在可設定的時間範圍內追蹤提示和完成權杖耗用量，模擬語言模型 API 的權杖型速率限制。

外掛程式實例定義

{
  "name": "LanguageModelRateLimitingPlugin",
  "enabled": true,
  "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll",
  "configSection": "languageModelRateLimitingPlugin",
  "urlsToWatch": [
    "https://api.openai.com/*",
    "http://localhost:11434/*"
  ]
}

Configuration example

{
  "languageModelRateLimitingPlugin": {
    "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v1.0.0/languagemodelratelimitingplugin.schema.json",
    "promptTokenLimit": 5000,
    "completionTokenLimit": 5000,
    "resetTimeWindowSeconds": 60,
    "whenLimitExceeded": "Throttle",
    "headerRetryAfter": "retry-after"
  }
}

Configuration properties

自訂回應設定

當 whenLimitExceeded 設定為 Custom時，您可以在個別的 JSON 檔案中定義自訂回應：

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v1.0.0/languagemodelratelimitingplugin.customresponsefile.schema.json",
  "statusCode": 429,
  "headers": [
    {
      "name": "retry-after",
      "value": "@dynamic"
    },
    {
      "name": "content-type",
      "value": "application/json"
    }
  ],
  "body": {
    "error": {
      "message": "You have exceeded your token quota. Please wait before making additional requests.",
      "type": "insufficient_quota",
      "code": "token_quota_exceeded"
    }
  }
}

自訂回應屬性

運作方式

LanguageModelRateLimitingPlugin 的運作方式如下：

1. 攔截 OpenAI API 請求： 監控包含 OpenAI 兼容請求主體的已配置 URL 的 POST 請求
2. 追蹤權杖消耗：剖析回應以擷取 prompt_tokens 和 completion_tokens 從使用情況區段擷取
3. Enforcing limits: Maintains running totals of consumed tokens within the configured time window
4. 提供節流回應：超過限制時，傳回標準節流回應或自訂回應

支援的要求類型

該插件支持 OpenAI 完成和聊天完成請求：

• Completion requests: Requests with a prompt property
• 聊天完成要求：具有屬性的要求messages

Token tracking

權杖消耗量會針對以下情況單獨追蹤：

• Prompt tokens: Input tokens consumed by the request
• Completion tokens: Output tokens generated by the response

當超過任一限制時，後續要求會受到節流，直到時間範圍重設為止。

時間範圍行為

• 權杖限制會在設定後重設 resetTimeWindowSeconds
• 重設計時器會在處理第一個要求時啟動
• 當時間範圍到期時，提示和完成權杖計數器都會重設為其設定的限制

預設節流回應

當 whenLimitExceeded 設定為 Throttle時，外掛程式會傳回標準 OpenAI 相容的錯誤回應：

{
  "error": {
    "message": "You exceeded your current quota, please check your plan and billing details.",
    "type": "insufficient_quota",
    "param": null,
    "code": "insufficient_quota"
  }
}

回應包括：

• HTTP狀態碼： 429 Too Many Requests
• retry-after 標頭，直到權杖限制重設為止的秒數
• CORS 標頭 當原始請求包含 Origin 標頭時

Use cases

LanguageModelRateLimitingPlugin 適用於：

• 測試基於令牌的速率限制： 模擬您的應用程式在語言模型提供者強制執行令牌配額時的行為方式
• 開發成本模擬： 在達到實際 API 限制之前了解開發過程中的代幣消耗模式
• Resilience testing: Verify that your application properly handles token limit errors and implements appropriate retry logic
• 本地 LLM 測試： 使用不強制執行自己限制的本地語言模型（如 Ollama）測試令牌限制場景

Example scenarios

案例 1：基本權杖限制

{
  "languageModelRateLimitingPlugin": {
    "promptTokenLimit": 1000,
    "completionTokenLimit": 500,
    "resetTimeWindowSeconds": 300
  }
}

此設定允許在 5 分鐘內最多允許 1,000 個提示權杖和 500 個完成權杖。

案例 2：自訂錯誤回應

{
  "languageModelRateLimitingPlugin": {
    "promptTokenLimit": 2000,
    "completionTokenLimit": 1000,
    "resetTimeWindowSeconds": 60,
    "whenLimitExceeded": "Custom",
    "customResponseFile": "custom-token-error.json"
  }
}

此配置使用自訂回應檔，在超過記號限制時提供特殊化的錯誤訊息。

Next step