From f452deb69a95c95faa96e7ec3c65326e3058aadf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=BCdiger=20Rolf?= Date: Fri, 20 Nov 2026 00:27:52 +0100 Subject: [PATCH 1/4] feat(ai): per-user rate limits for AI endpoints (#343) Co-Authored-By: Claude Opus 5.5 --- backend/common/tests_throttling.py | 161 ++++++++++++++++++++++++ backend/common/throttling.py | 67 ++++++++++ backend/config/settings.py | 4 + backend/live/views.py | 9 +- backend/locale/de/LC_MESSAGES/django.mo | Bin 21530 -> 21902 bytes backend/locale/de/LC_MESSAGES/django.po | 15 +++ backend/rooms/views.py | 30 ++++- 7 files changed, 279 insertions(+), 7 deletions(-) create mode 100644 backend/common/tests_throttling.py create mode 100644 backend/common/throttling.py diff --git a/backend/common/tests_throttling.py b/backend/common/tests_throttling.py new file mode 100644 index 00000000..0d9622d2 --- /dev/null +++ b/backend/common/tests_throttling.py @@ -0,0 +1,161 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Universität Osnabrück (virtUOS) + +"""Per-user AI rate limits (#343).""" +from unittest import mock + +from django.core.cache import cache +from django.core.files.base import ContentFile +from django.test import override_settings + +from rooms.models import 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) + 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", "INFO") as logs: + self._rephrase() + self.assertIn(f"AI throttled scope=ai user={self.owner.pk}", logs.output[0]) + + @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() diff --git a/backend/common/throttling.py b/backend/common/throttling.py new file mode 100644 index 00000000..5869fdcc --- /dev/null +++ b/backend/common/throttling.py @@ -0,0 +1,67 @@ +# 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") + + +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 + 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.info("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 = wait + raise exc + + +class AIThrottle(_AIThrottle): + scope = "ai" + + +class AIVisionThrottle(_AIThrottle): + scope = "ai_vision" diff --git a/backend/config/settings.py b/backend/config/settings.py index 9e4e2dfa..f818875f 100644 --- a/backend/config/settings.py +++ b/backend/config/settings.py @@ -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", }, } diff --git a/backend/live/views.py b/backend/live/views.py index ee2a96b1..e04da87b 100644 --- a/backend/live/views.py +++ b/backend/live/views.py @@ -24,7 +24,7 @@ from django.views.decorators.clickjacking import xframe_options_exempt from django.views.decorators.csrf import ensure_csrf_cookie from rest_framework import status -from rest_framework.decorators import api_view, permission_classes +from rest_framework.decorators import api_view, permission_classes, throttle_classes from rest_framework.permissions import IsAuthenticated from rest_framework.response import Response @@ -32,6 +32,7 @@ from common.i18n_fields import resolve_translated_text, translated_map from common.markdown import render_markdown from common.models import SiteConfig +from common.throttling import AIThrottle from rooms.image_credits import credits_for_questions from rooms.models import AnswerOption, Question, QuestionSet, Room @@ -1192,6 +1193,7 @@ def matrix_teacher_delete(request, run_id, question_id): @api_view(["POST"]) @permission_classes([IsAuthenticated]) +@throttle_classes([AIThrottle]) def matrix_ai_propose(request, run_id, question_id): """Presenter (expert mode): ask the LLM which cards of a field belong together. Body ``{level: "spelling"|"same"|"similar"}`` → 200 ``{groups, @@ -2536,6 +2538,7 @@ def _mindmap_ai_overrides(data): @api_view(["POST"]) @permission_classes([IsAuthenticated]) +@throttle_classes([AIThrottle]) def mindmap_ai_optimize(request, run_id, question_id): """Presenter (expert mode): ask the LLM for an optimisation proposal of the live mind map. Body: optional settings overrides ``{merge?, @@ -2670,6 +2673,7 @@ def action(run, question, data): @api_view(["POST"]) @permission_classes([IsAuthenticated]) +@throttle_classes([AIThrottle]) def optimize_wordcloud(request, run_id, question_id): """Optional AI cleanup of a word-cloud result: merge spelling variants and synonyms, group into thematic clusters. Non-destructive — the raw @@ -2705,6 +2709,7 @@ def optimize_wordcloud(request, run_id, question_id): @api_view(["POST"]) @permission_classes([IsAuthenticated]) +@throttle_classes([AIThrottle]) def freetext_summary(request, run_id, question_id): """One-shot AI key statements (+ grouping) of a free-text question for the Quiz-Block walkthrough of a finished run. Same ``{merged, clusters}`` @@ -2876,6 +2881,7 @@ def wordcloud_ai(request, run_id): @api_view(["POST"]) @permission_classes([IsAuthenticated]) +@throttle_classes([AIThrottle]) def evaluate_freetext(request, run_id, question_id): """Optional AI evaluation of free-text answers: classify each distinct answer as korrekt / unklar / falsch. Non-destructive; counts are @@ -2924,6 +2930,7 @@ def evaluate_freetext(request, run_id, question_id): @api_view(["POST"]) @permission_classes([IsAuthenticated]) +@throttle_classes([AIThrottle]) def run_summary(request, run_id): """Optional AI short report of one run: a compact German Markdown summary of the (anonymous, already-aggregated) results. Display-only.""" diff --git a/backend/locale/de/LC_MESSAGES/django.mo b/backend/locale/de/LC_MESSAGES/django.mo index b15c201b7d8bbf35ab766034665527d79e50a4b0..992e861bfb51327b7f00cd578da01630f0fefde3 100644 GIT binary patch delta 5005 zcmb8zdvH|c8OQN=6Udc>Y?38x2;?LXVghWC7)cNe5JCx;G%08$2sFZy1R>C5iCC4@ zvB)qK#(ElsOlOJ;2xFNMv8~VwGE;}k03zVXr9uHmE(PTtkXygMoYQ|gopHLeC!hDc z=bZQQJnws!p>4fq#rvM{iR4bLhEKf5m<$ZX7*j`iZ<1<_sqbdY0BpeF_!joSBk0HL zn2CvL#uQ)xQ*j!0!DdXrmoXk!xaVzHX-wFxrx4ABc8tRZs2k(D8UYQS%xp8o*7_z5QB=NM1_<^%38d!sx$saKbx1c&Yj=S*&Dl*$yNVob<&;f06oEoi#L9aTfBH7nR4BA_ zP#rYmqxdow<6lq%y^Ojqy_YkfEY#x5L$YQnPy>Dj)xmsx1Ybl=XcKDYTTv0;-i!Ea zW?#A&zDDKdG{)i;)b%^4)I`#oOhh&0M|Ic>Bd|XvV*#q2k*Ek%V^>^+kKqc`F4+^N z(3`?ZREQ!ir@>V02pMW1g{TgPp>jGBRX-UY#u?ZbTTv1Ho9kDo$XrFGDxSRPdJZxt z6CO@s6ou(niEB_fx`ql_=WJ&{iKyIWpi(gq`(X`gAg`f1dL1?J4X9LYMWu2F>b_g3 z$V4z}u7{16f^yLvHNyZZq=l#)j&PlT8u4UQ3KpV5`YNg;+pTXyJ-^m*aI z=5oFZm5R$4pnnrb;ii;(ffh-&IB$i=|>sDl=nEN`Ny%+w_pZF6cbC?QVQsyoyH2wknu;6eUi7QbJ9><6A z9x4R|0r%I@^(|aO{bxv!%xr!VoUcYrbSoy{o-hT4?g;9J(-?<$Q7@9{fzHg+ zQ4jP(+BPMq?N*OkWUrt?ybh!BBzDEKsNA<>1jaLZT~9={7w$$Oi9#RLi=_xV;doRB z)u^1#Mm@M372;OZ%vPZWycX5r2dMTw#YFr9HNk(P*3bo1dr^ZrQW7?K6tX?6R3!ao zZlUvvT!{+#Vbp^+ksV`_Nt|{=F{WY*cEM$+j#r{O-r$~pj8i$^jT&ffk>eojqWwRN zf5i#QnGIb>0tt)PRan{gnff{iYDq_=7 zGo9)B60$+eo7fZgphA5Pb1*=79>Gbd0WC$PDEu}BExwOX+h-4IgvU`cJ%yUd9aIM~ z!=2qR6tz8r*bA4S2DA>-aXV(&w0rg^f50#1os0ejp1?S)}EWjC@Aoj+4?)9vn5Y1dF z$|&f8XR#8OqelD>tir3<7t4t6lQ>=&r5x5OoQ1=)8 z%vprfQIVK~Nw^dfu?^#J18RaFx!1!7DCk9V%B{GCT{({>QKZZGQTurY7UCl0?Q1?n zrQ{N(;C0k*Ma(4U-v>Q0mh&vsK>DE~I24tFN{rF|pG83T=44edka z`YY4`&tNKELp2=pgfqi*R0MKRt9>LYC9}|j+JgE#&rxLT{Yh~V#$z8#8td(>%kJki z#@R*QiQcs_CDtM!S*MYc`n#flLvcl*saM0 zJ#V_t23?P%cJ^|PtM;knQcsMXl~U-x&iP=DcR2KUpW_2j=elJEuj-NAX)e>xa-kLWn6l}C+FK7-~jq{!hSXFa^ zwaq~*#HHH0+J;7pZ_Yz=8yXjcg3Wo&mQxCt$@3Oi|5uBdKhosp4+H+}UNakl*0>6* zF4$B%GiWsj>zgz}&guVGA$xzdfAoJ1XhO%(tYA}Pa6u?wCelEC?K8~j$D7LdpG`G7 MZEfCG^>pOF0dnhlivR!s delta 4674 zcmXxo4^-9V9mnzK3Ig{6%Dr&CAaEfO3=|NA3G*+1!azfXBWhBairbl@u362qW7iE$ zbDN!=ADqpyW3AzmR%YgOYvx$%q?P4dGgr+tB%6o|R+^;k{o(i9JzieV^Zb6l=g;^1 zJU=*Yd*1cLbFR>7UwE70<8c|2f-9qp`5xuJ#HrPo1tW~f#f3N>H)Ap$!6ZC~X?P3s zF&Ho=0c$Y^mtrig!DxKMsc*$vV?yRP6e78B9zA#&b>j_;$B0B@!f+&}Vi0xTWMr;p z21ei<)PVCb9hae=--M%aJLNRs^b`zs}7P- z9jD_sEJ98Aesp6qYJv}=Cj2wh^G~A}U%+8_7^4~Ayh}j?eTaJSigUvNYUZAi_Db_n z6D>ilV7k*@i`CTUqbB|g@~GK`WX1dy_1p)JpP=qLkD+V|7b#4{5hOMbYf+(Hj~eJv zR0pl7mF&RVa5rk8xA7=;qaw41jil?ZqaxIe+D<;gp$KH4B37JA{2AMn(V);aq6S!s z-@!Flg1<*i^bG1gPtcx_7q$74kSv)})P(C$11!cOT!~uHGpLn!pd!8}Nc^?3H=GN{ zP`NpQZaj;+-h)cbRmWSXj@*o{0f*rbOhF%}q53IAMW76a<0_nlkDyM;pF_85Rxr8;kkJ%}8 z^HJ?9kS@$)7}CmKqA(Lr;2aEQ+bdp;dN2G6IojqZDsnp_}?mB&{ZrFsPn` zns5>77}ua8-GWuvmP7otSw5ygx$H$n;wCCYIb-dKRHE)%j??gAR7VF;IX#Ms+$jvh zYp8_{AlWpjbefK3sQ#DmL+^#h#}R*`Wd2Tre*0ZSg~pvrxNtm{;}%qhZ({-WqEe8S z=lphb+>8Xl?8j*Q1htSJ)B=a*+ndvmicm&~f^Nt~56(cnK;qz zsLk~bDztqVi8d(j6e_f5 zP%Ar!n(!4IjsqBn(S&Chrl3|h7PWVZQT@%ubX=>ti~P4yAl>F*q5W#?LWMeQg8g6_ zazM;Is8i5_dUbYU44y;{+=UwW3#T4Ng72Z8fSTw7j_Xm+ZNVg+|27I*(H`Ugm{&0# z&!HEuqaN@S+XDnJoq87XH;S2o+RgW&BDD(>@I_R=ucIRIo>Tuf>b`FDGrsAipb&=f zHqnjos18zbDi)$9^h4ANH=*utMIF!Ip(gq<>V0tu^}L&lnm`aW(HvC&<(P)EFvPuP zC4~rl7B#aDR0l6(6uyZI@i^+f9Cn;eO92M37WLe6)aG4mR+RPTb17E{34Cm-* zuT_;2f30XH4eH=-)b3n@jAhnfB0h&**ohjj{k!(DJ%rP!ccbphH_OG_Vg%&Sd+|)`*(W5=_S*U=scuwHMk^9lwm)l>b28Kb(rL z2T&6kjcT8adSh0iCRT&mlnX)>l#`{XoHpYKT#uS@D{971qC(bzTIn9gBglp~XE7E1 zY#4=l0_xPP!y?>?n$Y{G6kS9=hQ6hsqirV zu>TI2f?2u|8*o1^z!>7KR5YP-yAc)QlQ;(ZQ41JZZ9iX$_0(73eRvqNF|CID*HEbD z$0%$?ZKeY_6pv#BoczFwslS5S+*eVd51(a6E(O!5 z&znX3GbubsgI4e)-i-%Pq4M2j?}Z|~oq81x!PQuZ4`2?qqgH+#^~Sr7nou5LRsYSX z6-Ixz-&P!YI}ap)%>!!Qdy zSd3cObky}m)cd8`sfRXF7*0bQk`~jBI>(n$o6S>a3~yI66_tv0sN=N(73x+D!`q1)#sb$inI#iCnQ~^ zK9TQl`RemL-+sQ=to8BJT*f*SA8_5W{uMvLb>4C(q{V)&oA@;H{l+Rz$ah6qO$lRT z^&d3xv?&QUtfvwJv0=2VrRKuxR%gOb{1KFn(enS#(-eBFx&CC=WvkgA@P9^~xDS4w z;O7Ot7p?97eAgxGs6W|%llo}BJNQ1vckp9[0-9]+)/retry") + @action( + detail=True, + methods=["post"], + url_path=r"ai-generate/jobs/(?P[0-9]+)/retry", + throttle_classes=[AIThrottle], + ) def ai_generate_retry(self, request, pk=None, job_id=None): """Run a failed (or empty) generation again with the same material and settings, so the teacher need not re-upload the document (#302).""" @@ -945,7 +952,9 @@ def ai_generate_reviewed(self, request, pk=None, job_id=None): job.save(update_fields=["reviewed", "updated_at"]) return Response({"status": "ok"}) - @action(detail=True, methods=["post"], url_path="ai-distractors") + @action( + detail=True, methods=["post"], url_path="ai-distractors", throttle_classes=[AIThrottle] + ) def ai_distractors(self, request, pk=None): """Set-scoped distractor suggestions for a question that has not been saved yet (still being created in the editor) — same logic as @@ -954,14 +963,18 @@ def ai_distractors(self, request, pk=None): self.get_object() # ownership check return _ai_distractors_response(request, fallback_question=None) - @action(detail=True, methods=["post"], url_path="ai-rephrase") + @action( + detail=True, methods=["post"], url_path="ai-rephrase", throttle_classes=[AIThrottle] + ) def ai_rephrase(self, request, pk=None): """Set-scoped rephrase suggestions for a question that has not been saved yet — see ``ai_distractors`` above.""" self.get_object() # ownership check return _ai_rephrase_response(request, fallback_question=None) - @action(detail=True, methods=["post"], url_path="ai-proofread") + @action( + detail=True, methods=["post"], url_path="ai-proofread", throttle_classes=[AIThrottle] + ) def ai_proofread(self, request, pk=None): """Optional AI proofreading of a motion text (meeting sets only). @@ -1279,13 +1292,17 @@ def add_after(self, request, pk=None): self.get_serializer(after).data, status=status.HTTP_201_CREATED ) - @action(detail=True, methods=["post"], url_path="ai-distractors") + @action( + detail=True, methods=["post"], url_path="ai-distractors", throttle_classes=[AIThrottle] + ) def ai_distractors(self, request, pk=None): """Suggest plausible-but-wrong answer options (not saved). AI only.""" question = self.get_object() return _ai_distractors_response(request, fallback_question=question) - @action(detail=True, methods=["post"], url_path="ai-rephrase") + @action( + detail=True, methods=["post"], url_path="ai-rephrase", throttle_classes=[AIThrottle] + ) def ai_rephrase(self, request, pk=None): """Suggest clearer rephrasings of the question text (not saved).""" question = self.get_object() @@ -1518,6 +1535,7 @@ class ImageAltSuggestionView(APIView): the uploader or anyone allowed to edit the image may ask.""" permission_classes: ClassVar = [IsAuthenticated] + throttle_classes: ClassVar = [AIVisionThrottle] def post(self, request, pk): img = UploadedImage.objects.filter(pk=pk).first() From 0330a0a60142be77a75825f06582952bd7601efd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=BCdiger=20Rolf?= Date: Fri, 20 Nov 2026 00:29:22 +0100 Subject: [PATCH 2/4] fix(ai): throttle wordcloud_ai activation (#343) Co-Authored-By: Claude Opus 5.5 --- backend/common/tests_throttling.py | 1 + backend/live/views.py | 1 + 2 files changed, 2 insertions(+) diff --git a/backend/common/tests_throttling.py b/backend/common/tests_throttling.py index 0d9622d2..62a93cd6 100644 --- a/backend/common/tests_throttling.py +++ b/backend/common/tests_throttling.py @@ -151,6 +151,7 @@ def test_every_ai_endpoint_is_throttled_before_the_model(self): f"/api/runs/{q}/questions/{q}/ai-freetext/", f"/api/runs/{q}/questions/{q}/ai-summary/", f"/api/runs/{q}/ai-summary/", + f"/api/runs/{q}/wordcloud-ai/", ] with _rates(ai="0/hour", ai_vision="0/hour"), mock.patch(DISTRACTORS) as m: for url in text_endpoints: diff --git a/backend/live/views.py b/backend/live/views.py index e04da87b..e1a761c1 100644 --- a/backend/live/views.py +++ b/backend/live/views.py @@ -2849,6 +2849,7 @@ def wordcloud_ai_settings(request, run_id, question_id): @api_view(["POST"]) @permission_classes([IsAuthenticated]) +@throttle_classes([AIThrottle]) def wordcloud_ai(request, run_id): """Presenter toggles the live AI word-cloud view on/off for a question. From 87548d0d34ac4c2a1464bef06d850026b4839c5e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=BCdiger=20Rolf?= Date: Fri, 20 Nov 2026 00:33:46 +0100 Subject: [PATCH 3/4] feat(ai): show rate-limit message; AI_THROTTLE_RATE env + docs (#343) Walkthrough free-text summary shows the 429 message instead of the generic "unavailable" text; env vars in compose files and .env.prod.example; docs (DE/EN) and changelog; e2e for a throttled rephrase. Co-Authored-By: Claude Sonnet 5.5 --- .env.prod.example | 5 +++ CHANGELOG.md | 10 ++++++ docker-compose.prod.yml | 2 ++ docker-compose.yml | 2 ++ docs/deployment.md | 13 ++++++++ frontend/e2e/ai-throttle.spec.ts | 53 ++++++++++++++++++++++++++++++ frontend/src/pages/PresentPage.tsx | 24 +++++++++++--- website/en/installation.md | 11 +++++++ 8 files changed, 116 insertions(+), 4 deletions(-) create mode 100644 frontend/e2e/ai-throttle.spec.ts diff --git a/.env.prod.example b/.env.prod.example index e98f295d..bd543b03 100644 --- a/.env.prod.example +++ b/.env.prod.example @@ -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. diff --git a/CHANGELOG.md b/CHANGELOG.md index 9f4e41b9..585549d0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/docker-compose.prod.yml b/docker-compose.prod.yml index 39b2b446..2089fc41 100644 --- a/docker-compose.prod.yml +++ b/docker-compose.prod.yml @@ -129,6 +129,8 @@ services: AI_TIMEOUT: ${AI_TIMEOUT:-30} AI_MAX_TOKENS: ${AI_MAX_TOKENS:-2000} AI_GEN_PER_CALL: ${AI_GEN_PER_CALL:-5} + AI_THROTTLE_RATE: ${AI_THROTTLE_RATE:-120/hour} + AI_VISION_THROTTLE_RATE: ${AI_VISION_THROTTLE_RATE:-30/hour} AI_DISABLE_THINKING: ${AI_DISABLE_THINKING:-1} # Prometheus /metrics scrape token (unset = endpoint off / 404). METRICS_TOKEN: ${METRICS_TOKEN:-} diff --git a/docker-compose.yml b/docker-compose.yml index 29404074..f81e1b4f 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -80,6 +80,8 @@ services: AI_TIMEOUT: ${AI_TIMEOUT:-30} AI_MAX_TOKENS: ${AI_MAX_TOKENS:-2000} AI_GEN_PER_CALL: ${AI_GEN_PER_CALL:-5} + AI_THROTTLE_RATE: ${AI_THROTTLE_RATE:-120/hour} + AI_VISION_THROTTLE_RATE: ${AI_VISION_THROTTLE_RATE:-30/hour} AI_DISABLE_THINKING: ${AI_DISABLE_THINKING:-1} # Content translation (#33). Canonical language + optional LibreTranslate # pre-fill in the editor (off unless CONTENT_TRANSLATION_PROVIDER is set). diff --git a/docs/deployment.md b/docs/deployment.md index d61b5b7d..70e9b15b 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -613,6 +613,19 @@ berechtigte Person im Dialog ausdrücklich auf „Vorschlag erstellen“ klickt (verkleinert auf höchstens 1024 px). Es findet keine automatische Übertragung statt. Beide Variablen werden beim Start gelesen — Container neu erzeugen. +**`AI_THROTTLE_RATE`** (optional, Standard `120/hour`) begrenzt, wie oft eine +angemeldete Person die KI-Funktionen aufrufen darf (Format `N/minute`, +`N/hour` oder `N/day`; `off` schaltet die Begrenzung ab). Das Limit gilt pro +Person über alle KI-Funktionen zusammen; eine Dokument-Generierung zählt +einmal je gestartetem Auftrag. **`AI_VISION_THROTTLE_RATE`** (optional, +Standard `30/hour`) ist das eigene, niedrigere Limit für den +Bildbeschreibungs-Vorschlag. Mitarbeitende mit Django-Staff-Recht sind +ausgenommen. Bei Überschreitung zeigt die Oberfläche die Meldung „Bitte +versuchen Sie es in N Minuten erneut“ (HTTP 429). Hinweis: Die Zähler liegen +im Arbeitsspeicher des jeweiligen Backend-Prozesses und werden bei einem +Neustart zurückgesetzt; bei mehreren Workern gilt das Limit je Prozess, die +effektive Grenze ist entsprechend höher. + Gegenprüfen, was im laufenden Container ankommt: ```bash diff --git a/frontend/e2e/ai-throttle.spec.ts b/frontend/e2e/ai-throttle.spec.ts new file mode 100644 index 00000000..6c4dbc63 --- /dev/null +++ b/frontend/e2e/ai-throttle.spec.ts @@ -0,0 +1,53 @@ +/** AI rate limit (#343): a throttled AI call (429 with a translated `detail`) + * shows that message in the UI — not a generic "Request failed" — and no + * native dialog fires. The 429 is stubbed; only an "E2E AI" room is seeded + * and deleted. */ +import { test, expect, API_BASE_URL } from './fixtures'; +import { createRoomWithQuestions } from './helpers/seed'; + +test.use({ locale: 'de-DE', viewport: { width: 1280, height: 1000 } }); + +const THROTTLE_DETAIL = + 'Sie haben die KI gerade sehr oft genutzt. Bitte versuchen Sie es in 7 Minuten erneut.'; + +test.beforeEach(async ({ page }) => { + await page.route(/\/api\/whoami\/(\?.*)?$/, async (route) => { + if (route.request().method() !== 'GET') return route.continue(); + const response = await route.fetch(); + const json = await response.json(); + if (json.username) Object.assign(json, { onboarding_tour_seen: true, easy_mode: false, ai_enabled: true }); + await route.fulfill({ response, json }); + }); + await page.goto(`${API_BASE_URL}/oidc/authenticate/`); + await page.getByRole('textbox', { name: /Username or email|Benutzername/ }).fill('demo'); + await page.getByRole('textbox', { name: /Password|Passwort/ }).fill('demo'); + await page.getByRole('button', { name: /Sign In|Anmelden/ }).click(); + // Back on the frontend (not Keycloak, not the API origin). + await page.waitForURL((url) => url.origin !== API_BASE_URL && !url.pathname.startsWith('/realms')); +}); + +test('throttled rephrase shows the rate-limit message', async ({ page, trackRoom }) => { + const room = await createRoomWithQuestions(page.request, ['single_choice'], 'KI Limit', trackRoom, 'E2E AI'); + let dialogs = 0; + page.on('dialog', async (dialog) => { + dialogs += 1; + await dialog.dismiss(); + }); + await page.route(/\/api\/questions\/\d+\/ai-rephrase\/$/, (route) => + route.fulfill({ + status: 429, + headers: { 'Retry-After': '420' }, + json: { detail: THROTTLE_DETAIL }, + }), + ); + + await page.goto(`/sets/${room.setId}/questions/${room.questions[0].id}`); + const panel = page.getByText('Frage umformulieren').locator('xpath=..'); + const button = panel.getByRole('button', { name: 'Vorschläge erzeugen' }); + await button.scrollIntoViewIfNeeded(); + await button.click(); + + await expect(page.getByText(THROTTLE_DETAIL)).toBeVisible(); + await expect(page.getByText(/Request failed|429/)).toHaveCount(0); + expect(dialogs).toBe(0); +}); diff --git a/frontend/src/pages/PresentPage.tsx b/frontend/src/pages/PresentPage.tsx index 1561fbf0..5b255fd5 100644 --- a/frontend/src/pages/PresentPage.tsx +++ b/frontend/src/pages/PresentPage.tsx @@ -177,6 +177,8 @@ export default function PresentPage({ mode = "live" }: { mode?: "live" | "self_p const [walkViewState, setWalkView] = useState("raw"); const [walkAi, setWalkAi] = useState>({}); const walkAiLoading = useRef>(new Set()); + // Rate-limit message (429) of a failed summary, per "run:question" (#343). + const [walkAiLimit, setWalkAiLimit] = useState>({}); const [runId, setRunId] = useState(null); // Recording mode (#53): opted in on the set page (checkbox), carried here as // ?recording=1; live only (self-paced is already async). @@ -1358,15 +1360,24 @@ export default function PresentPage({ mode = "live" }: { mode?: "live" | "self_p void results .freeTextSummary(runId, walkItem.id) .then((res) => setWalkAi((m) => ({ ...m, [key]: { ...res, pending: false } }))) - .catch(() => setWalkAi((m) => ({ ...m, [key]: "error" }))) + .catch((err) => { + if (requestStatus(err) === 429) setWalkAiLimit((m) => ({ ...m, [key]: aiErrorText(err, t) })); + setWalkAi((m) => ({ ...m, [key]: "error" })); + }) .finally(() => walkAiLoading.current.delete(key)); - }, [walkWantsAi, walkAiKey, walkItem, runId, walkAi]); - const retryWalkAi = () => + }, [walkWantsAi, walkAiKey, walkItem, runId, walkAi, t]); + const retryWalkAi = () => { + setWalkAiLimit((m) => { + const next = { ...m }; + delete next[walkAiKey]; + return next; + }); setWalkAi((m) => { const next = { ...m }; delete next[walkAiKey]; return next; }); + }; const walkViewKey = walkViewOptions.map((o) => o.value).join(","); const cycleWalkView = useCallback(() => { const values = walkViewKey.split(",") as WcView[]; @@ -1852,6 +1863,7 @@ export default function PresentPage({ mode = "live" }: { mode?: "live" | "self_p item={item} view={walkView} ai={walkAi[walkAiKey]} + aiLimit={walkAiLimit[walkAiKey]} onRetryAi={retryWalkAi} /> void; }) { const { t } = useTranslation(); @@ -3252,7 +3268,7 @@ function WalkthroughResultBody({ if (ai === "error") { return (
-

{t("The AI summary is currently unavailable.")}

+

{aiLimit ?? t("The AI summary is currently unavailable.")}

{onRetryAi && (