Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .env.prod.example
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,11 @@ AI_PROVIDER=none
# to AI_MODEL.
#AI_VISION=1
#AI_VISION_MODEL=qwen-3.5-vl
# Per-user rate limit for AI calls (staff exempt). Format "N/minute|hour|day";
# "off" disables. The alt-text suggestion has its own, lower limit. Counted
# per backend process, so with several workers the effective limit is higher.
#AI_THROTTLE_RATE=120/hour
#AI_VISION_THROTTLE_RATE=30/hour
#AI_TIMEOUT=30
#AI_MAX_TOKENS=2000
# Set to 0 for models that don't support the "disable thinking" hint.
Expand Down
10 changes: 10 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,19 @@ Die Zahlen in Klammern verweisen auf Pull Requests im
> `AI_VISION=1` ändert sich nichts. Voraussetzung sind ein bildfähiges Modell
> und die Pakete basicbar-ui ≥ 0.11.1 sowie basicbar-integrations 0.5.0
> (per Image-Rebuild).
> - **Neue optionale Umgebungsvariablen `AI_THROTTLE_RATE` (Standard
> `120/hour`) und `AI_VISION_THROTTLE_RATE` (Standard `30/hour`)**
> begrenzen KI-Aufrufe pro Person (`off` schaltet ab, Staff ausgenommen).
> Die Zähler liegen pro Backend-Prozess im Arbeitsspeicher, bei mehreren
> Workern ist die effektive Grenze entsprechend höher (siehe
> Installationsanleitung).

### Hinzugefügt

- Begrenzung der KI-Aufrufe pro Person (#343): Bei zu vielen Aufrufen in kurzer
Zeit erscheint die Meldung „Bitte versuchen Sie es in N Minuten erneut“
(HTTP 429 mit `Retry-After`) statt eines Fehlers; konfigurierbar über
`AI_THROTTLE_RATE` und `AI_VISION_THROTTLE_RATE`.
- Bildbeschreibung (Alternativtext) für Antwortbilder (#342): zweisprachig,
im Bild-Dialog (auch mit KI-Vorschlag, wenn freigeschaltet) und über den Stift
„Bild bearbeiten“ an der Antwort; reine Bildantworten ohne Beschreibung zeigen
Expand Down
225 changes: 225 additions & 0 deletions backend/common/tests_throttling.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,225 @@
# SPDX-License-Identifier: Apache-2.0
# Copyright 2026 Universität Osnabrück (virtUOS)

"""Per-user AI rate limits (#343)."""
import logging
from unittest import mock

from django.core.cache import cache
from django.core.files.base import ContentFile
from django.test import override_settings
from rest_framework.throttling import SimpleRateThrottle

from common import throttling
from common.throttling import AIThrottle, AIVisionThrottle
from live.models import Run
from rooms.models import Question, QuestionSet, UploadedImage
from rooms.tests import AI_ON, ApiTestCase
from rooms.tests_image_alt import CHAT, VISION_ON, _png

DISTRACTORS = "basicbar_integrations.ai.chat_json"


def _rates(**rates):
return override_settings(
REST_FRAMEWORK={
"DEFAULT_AUTHENTICATION_CLASSES": [
"rest_framework.authentication.SessionAuthentication"
],
"DEFAULT_THROTTLE_RATES": rates,
}
)


class AIThrottleTests(ApiTestCase):
def setUp(self):
super().setUp()
cache.clear()
self.addCleanup(cache.clear)
# keep the expected rejection warnings out of the test output
null = logging.NullHandler()
logging.getLogger("abstimmbar.ai").addHandler(null)
self.addCleanup(logging.getLogger("abstimmbar.ai").removeHandler, null)
self.qs = QuestionSet.objects.create(room=self.room, title="T")
self.url = f"/api/question-sets/{self.qs.pk}/ai-rephrase/"
self.img = UploadedImage(uploader=self.owner)
self.img.file.save("a.png", ContentFile(_png()), save=True)
self.alt_url = f"/api/images/{self.img.pk}/alt-suggestion/"

def _rephrase(self, **extra):
return self.client.post(
self.url, {"text": "Frage?"}, content_type="application/json", **extra
)

def _alt(self):
return self.client.post(self.alt_url, {"lang": "en"}, content_type="application/json")

@override_settings(**AI_ON)
def test_ai_scope_limits_after_n(self):
with _rates(ai="2/hour", ai_vision="2/hour"), mock.patch(
DISTRACTORS, return_value={"suggestions": ["Eine Frage?"]}
) as m:
self.assertEqual(self._rephrase().status_code, 200)
self.assertEqual(self._rephrase().status_code, 200)
r = self._rephrase(HTTP_ACCEPT_LANGUAGE="de")
self.assertEqual(r.status_code, 429)
self.assertEqual(m.call_count, 2)
self.assertIn("Sie haben die KI gerade sehr oft genutzt", r.json()["detail"])
self.assertIn("Minuten erneut", r.json()["detail"])
self.assertIn("Retry-After", r)

@override_settings(**VISION_ON)
def test_vision_scope_separate(self):
with _rates(ai="1/hour", ai_vision="1/hour"), mock.patch(
CHAT, return_value={"alt": "x", "suggestions": ["Q?"]}
):
self.assertEqual(self._rephrase().status_code, 200)
self.assertEqual(self._rephrase().status_code, 429)
# the text scope being exhausted does not affect the vision scope
self.assertEqual(self._alt().status_code, 200)
self.assertEqual(self._alt().status_code, 429)

@override_settings(**AI_ON)
def test_staff_exempt(self):
self.owner.is_staff = True
self.owner.save()
with _rates(ai="1/hour"), mock.patch(DISTRACTORS, return_value={"suggestions": ["Q?"]}) as m:
for _ in range(3):
self.assertEqual(self._rephrase().status_code, 200)
self.assertEqual(m.call_count, 3)

@override_settings(**VISION_ON)
def test_rate_off_disables(self):
with _rates(ai="off", ai_vision="OFF"), mock.patch(
CHAT, return_value={"alt": "x", "suggestions": ["Q?"]}
):
for _ in range(3):
self.assertEqual(self._rephrase().status_code, 200)
self.assertEqual(self._alt().status_code, 200)

@override_settings(**AI_ON)
def test_generation_status_not_throttled(self):
with _rates(ai="1/hour"), mock.patch("rooms.views.generation.start_job"):
r = self.client.post(
f"/api/question-sets/{self.qs.pk}/ai-generate/", {"text": "Material text."}
)
self.assertEqual(r.status_code, 201)
job_id = r.json()["job_id"]
self.assertEqual(
self.client.post(
f"/api/question-sets/{self.qs.pk}/ai-generate/", {"text": "Mehr."}
).status_code,
429,
)
for _ in range(3):
self.assertEqual(
self.client.get(
f"/api/question-sets/{self.qs.pk}/ai-generate/active/"
).status_code,
200,
)
self.assertEqual(
self.client.get(
f"/api/question-sets/{self.qs.pk}/ai-generate/jobs/{job_id}/"
).status_code,
200,
)

@override_settings(**AI_ON)
def test_singular_minute_message(self):
with _rates(ai="1/minute"), mock.patch(DISTRACTORS, return_value={"suggestions": ["Q?"]}):
self._rephrase()
de = self._rephrase(HTTP_ACCEPT_LANGUAGE="de")
en = self._rephrase(HTTP_ACCEPT_LANGUAGE="en")
self.assertEqual(de.status_code, 429)
self.assertTrue(de.json()["detail"].endswith("in 1 Minute erneut."), de.json())
self.assertTrue(en.json()["detail"].endswith("in 1 minute."), en.json())

@override_settings(**AI_ON)
def test_rejection_is_logged(self):
with _rates(ai="1/hour"), mock.patch(DISTRACTORS, return_value={"suggestions": ["Q?"]}):
self._rephrase()
with self.assertLogs("abstimmbar.ai", "WARNING") as logs:
self._rephrase()
self.assertIn(f"AI throttled scope=ai user={self.owner.pk}", logs.output[0])
self.assertTrue(logs.output[0].startswith("WARNING:"))

@override_settings(**VISION_ON)
def test_every_ai_endpoint_is_throttled_before_the_model(self):
qs, q = self.qs.pk, 1
text_endpoints = [
f"/api/question-sets/{qs}/ai-generate/",
f"/api/question-sets/{qs}/ai-generate/jobs/{q}/retry/",
f"/api/question-sets/{qs}/ai-distractors/",
f"/api/question-sets/{qs}/ai-rephrase/",
f"/api/question-sets/{qs}/ai-proofread/",
f"/api/questions/{q}/ai-distractors/",
f"/api/questions/{q}/ai-rephrase/",
f"/api/runs/{q}/matrix/{q}/ai-propose",
f"/api/runs/{q}/mindmap/{q}/ai-optimize",
f"/api/runs/{q}/questions/{q}/ai-wordcloud/",
f"/api/runs/{q}/questions/{q}/ai-freetext/",
f"/api/runs/{q}/questions/{q}/ai-summary/",
f"/api/runs/{q}/ai-summary/",
]
with _rates(ai="0/hour", ai_vision="0/hour"), mock.patch(DISTRACTORS) as m:
for url in text_endpoints:
r = self.client.post(url, {}, content_type="application/json")
self.assertEqual(r.status_code, 429, url)
r = self._alt()
self.assertEqual(r.status_code, 429)
m.assert_not_called()

@override_settings(**AI_ON)
def test_retry_after_is_rounded_up(self):
with _rates(ai="1/hour"), mock.patch(DISTRACTORS, return_value={"suggestions": ["Q?"]}), \
mock.patch.object(SimpleRateThrottle, "wait", return_value=59.2):
self._rephrase()
r = self._rephrase()
self.assertEqual(r.status_code, 429)
self.assertEqual(r["Retry-After"], "60")

@override_settings(**VISION_ON)
def test_staff_exempt_vision(self):
self.owner.is_staff = True
self.owner.save()
with _rates(ai_vision="1/hour"), mock.patch(
CHAT, return_value={"alt": "x", "suggestions": ["Q?"]}
) as m:
for _ in range(3):
self.assertEqual(self._alt().status_code, 200)
self.assertEqual(m.call_count, 3)

def test_invalid_rate_falls_back_to_default_and_warns_once(self):
throttling._warned.clear()
for bad in ("0", "120", "abc", "120/week"):
with _rates(ai=bad, ai_vision=bad):
self.assertEqual(AIThrottle().get_rate(), "120/hour", bad)
self.assertEqual(AIVisionThrottle().get_rate(), "30/hour", bad)

@override_settings(**AI_ON)
def test_invalid_rate_does_not_500(self):
throttling._warned.clear()
with _rates(ai="120/week"), mock.patch(
DISTRACTORS, return_value={"suggestions": ["Q?"]}
), self.assertLogs("abstimmbar.ai", "WARNING") as logs:
self.assertEqual(self._rephrase().status_code, 200)
self.assertEqual(self._rephrase().status_code, 200)
self.assertEqual(len([o for o in logs.output if "Invalid" in o]), 1)

@override_settings(**AI_ON)
def test_live_wordcloud_ai_not_counted(self):
run = Run.objects.create(question_set=self.qs)
q = Question.objects.create(
question_set=self.qs, kind="word_cloud", text="W", wordcloud_ai_enabled=True
)
url = f"/api/runs/{run.pk}/wordcloud-ai/"
with _rates(ai="1/hour"), mock.patch(DISTRACTORS, return_value={"suggestions": ["Q?"]}), \
mock.patch("live.views.ai_wordcloud_live.set_active"):
self.assertEqual(self._rephrase().status_code, 200)
self.assertEqual(self._rephrase().status_code, 429) # budget exhausted
for active in (True, False, True, False):
r = self.client.post(
url, {"question": q.pk, "active": active}, content_type="application/json"
)
self.assertEqual(r.status_code, 200, r.content)
82 changes: 82 additions & 0 deletions backend/common/throttling.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
# SPDX-License-Identifier: Apache-2.0
# Copyright 2026 Universität Osnabrück (virtUOS)

"""Per-user rate limits for the AI endpoints (#343).

Two scopes, rates in ``REST_FRAMEWORK["DEFAULT_THROTTLE_RATES"]`` (env
``AI_THROTTLE_RATE`` / ``AI_VISION_THROTTLE_RATE``): ``ai`` for every text
AI call, ``ai_vision`` for the alt-text suggestion. The value ``off``
disables a scope, staff are never throttled. DRF runs throttles in
``initial()``, i.e. before the handler (and so before the model) is reached.
"""
import logging
import math

from django.utils.translation import ngettext
from rest_framework.exceptions import Throttled
from rest_framework.settings import api_settings
from rest_framework.throttling import SimpleRateThrottle

logger = logging.getLogger("abstimmbar.ai")


_DEFAULTS = {"ai": "120/hour", "ai_vision": "30/hour"}
_warned: set[str] = set()


class _AIThrottle(SimpleRateThrottle):
scope = ""

def get_rate(self):
# Read lazily (not DRF's import-time class attribute) so the rates
# can be overridden in tests.
rate = api_settings.DEFAULT_THROTTLE_RATES.get(self.scope)
if not rate or str(rate).strip().lower() == "off":
return None
try:
self.parse_rate(rate) # DRF semantics: "N/second|minute|hour|day"
except (ValueError, KeyError, TypeError, AttributeError):
default = _DEFAULTS[self.scope]
if rate not in _warned:
_warned.add(rate)
logger.warning(
"Invalid rate %r for AI throttle scope %s, using %s",
rate, self.scope, default,
)
return default
return rate

def get_cache_key(self, request, view):
user = request.user
if not user or not user.is_authenticated:
return None # never reached: the endpoints require a login
return self.cache_format % {"scope": self.scope, "ident": user.pk}

def allow_request(self, request, view):
if getattr(request.user, "is_staff", False):
return True
if super().allow_request(request, view):
return True
logger.warning("AI throttled scope=%s user=%s", self.scope, request.user.pk)
wait = self.wait()
minutes = max(1, math.ceil(wait / 60)) if wait else 1
detail = ngettext(
"You have used the AI very often just now. "
"Please try again in %(minutes)s minute.",
"You have used the AI very often just now. "
"Please try again in %(minutes)s minutes.",
minutes,
) % {"minutes": minutes}
# wait=None: DRF would otherwise append its own "available in N seconds"
# sentence to the detail; Retry-After is taken from ``exc.wait``.
exc = Throttled(detail=detail)
exc.wait = math.ceil(wait) if wait else None
raise exc


class AIThrottle(_AIThrottle):
scope = "ai"


class AIVisionThrottle(_AIThrottle):
scope = "ai_vision"
4 changes: 4 additions & 0 deletions backend/config/settings.py
Original file line number Diff line number Diff line change
Expand Up @@ -247,6 +247,10 @@ def _float_or_default(name, default):
# Only scoped throttles, applied per action (no DEFAULT_THROTTLE_CLASSES).
"DEFAULT_THROTTLE_RATES": {
"committee-mail": "10/hour",
# Per-user caps for the AI endpoints (common/throttling.py, #343);
# "off" disables a scope, staff are never throttled.
"ai": os.environ.get("AI_THROTTLE_RATE") or "120/hour",
"ai_vision": os.environ.get("AI_VISION_THROTTLE_RATE") or "30/hour",
},
}

Expand Down
Loading