f8499c4e40
Produktentscheidung 07/2026: ungenutzte Credits verfallen zum Periodenende, es gilt der harte Monatsdeckel wie verkauft. Der Uebertrag (credits_rollover/credits_carried) fliegt komplett raus: roll_credit_period setzt nur noch Verbrauch + Warnflag zurueck, check_license rechnet verfuegbar = credits_total, die Migration legt die beiden Spalten gar nicht erst an (Live hat sie nie bekommen, die Promote-Warteschlange enthielt sie noch). ABRECHNUNG.md angepasst. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
148 Zeilen
7.3 KiB
Markdown
148 Zeilen
7.3 KiB
Markdown
# Credits und Abrechnung
|
|
|
|
Wie das Kontingent eines Kunden funktioniert, welche Stellschrauben es gibt und
|
|
was die Verwaltung setzen muss. Stand 2026-07-25 (Portierung aus dem Lokal-Fork,
|
|
Sätze auf die am 23.07.2026 beschlossenen Verkaufswerte gesetzt).
|
|
|
|
## Begriffe
|
|
|
|
Der Kunde sieht **Credits**, nicht Token und nicht Dollar. Das ist Absicht.
|
|
"Token" ist ein KI-Fachbegriff mit einer festen Bedeutung, und 10.000 echte
|
|
Token wären etwa 7.500 Wörter, also ein einziger längerer Artikel. Wer den
|
|
Begriff kennt, hält so eine Angabe für einen Fehler. Intern heißen die Felder
|
|
`credits_*`, nach außen steht überall "Credits" (Entscheidung vom 25.07.2026,
|
|
einheitlich in Monitor und Verwaltungsportal).
|
|
|
|
## Was eine Aktion kostet
|
|
|
|
Im Modus `flat` (Voreinstellung) kostet jede Aktion einen festen Satz,
|
|
unabhängig davon, was sie uns tatsächlich verursacht hat. 1 Credit entspricht
|
|
0,20 USD. Die wirksamen Sätze stehen seit 25.07.2026 in der geteilten Tabelle
|
|
`billing_tariff` und sind über den Verbrauchsrechner des Verwaltungsportals
|
|
pflegbar. `CREDIT_TARIFF` in `src/config.py` befüllt die Tabelle beim ersten
|
|
Start und bleibt Rückfallebene für fehlende Schlüssel.
|
|
|
|
| Aktion | Credits | Herkunft des Werts |
|
|
|---|---|---|
|
|
| Live-Refresh (adhoc) | 45 | beschlossen 23.07.2026 (gemessener Median 24 Credits = 4,76 USD) |
|
|
| Recherche je Durchlauf | 40 | beschlossen 23.07.2026 (gemessener Median 33 Credits = 6,54 USD) |
|
|
| Analyse-Baustein (Studio) | 12 | geschätzt, rund ein Viertel eines Live-Laufs |
|
|
| Faktencheck-Baustein (Studio) | 12 | geschätzt |
|
|
| Chat, Beschreibungs-Assistent, Globe | 1 | real 0,02 bis 0,03 USD je Aufruf |
|
|
|
|
Die erste Aktualisierung einer Recherche-Lage fährt drei Durchläufe, kostet also
|
|
120 Credits. Die Verkaufssätze liegen bewusst über den gemessenen Medianen.
|
|
Messgrundlage sind 1.341 abgeschlossene Refreshes des Live-Systems aus dem
|
|
Zeitraum 28.02.2026 bis 21.06.2026 (`refresh_log`). Der Verbrauchsrechner im
|
|
Verwaltungsportal rechnet mit denselben Sätzen.
|
|
|
|
### Warum feste Sätze und nicht die echten Kosten
|
|
|
|
Vorher wurde `echte_kosten / cost_per_credit` abgebucht. Das hatte zwei Nachteile.
|
|
Der Kunde konnte nicht planen, weil ein Refresh einer großen Lage ein Vielfaches
|
|
eines Refreshs einer frischen kostet, ohne dass er den Unterschied sieht. Und
|
|
sobald das Modell-Backend billiger wird, etwa beim Wechsel von Anthropic auf eine
|
|
EU-Cloud, hätte derselbe Kunde plötzlich ein Vielfaches an Aktionen bekommen,
|
|
oder wir hätten `cost_per_credit` nachziehen müssen, was nach einer heimlichen
|
|
Preiserhöhung aussieht.
|
|
|
|
Der alte Modus lebt weiter unter `BILLING_MODE=actual` als Rückfallebene. Die
|
|
echten Kosten wandern in beiden Modi unverändert nach `token_usage_monthly`, die
|
|
interne Kostenkontrolle bleibt also vollständig erhalten.
|
|
|
|
## Abrechnungsperiode
|
|
|
|
`licenses.credits_period` steuert den Bezugszeitraum.
|
|
|
|
- `monthly` (Voreinstellung) füllt die Credits zum Monatswechsel neu auf.
|
|
- `total` lässt das Kontingent für die gesamte Lizenzlaufzeit gelten.
|
|
|
|
Der Wechsel passiert träge bei der nächsten Lizenzprüfung, nicht über einen
|
|
Zeitplan. Ein verpasster Monatswechsel wird dadurch beim nächsten Zugriff
|
|
nachgeholt, und ohne Nutzung wird ohnehin nichts verbraucht.
|
|
|
|
Ungenutzte Credits verfallen zum Periodenende. Ein Übertrag in den Folgemonat
|
|
war kurz vorgesehen und wurde als Produktentscheidung 07/2026 wieder entfernt,
|
|
es gilt der harte Monatsdeckel wie verkauft.
|
|
|
|
Eine Bestandslizenz ohne Periodenmarke bekommt beim ersten Zugriff die aktuelle
|
|
Periode eingetragen, **ohne** den Verbrauch zurückzusetzen. Sonst würden ihr
|
|
Credits geschenkt, die im laufenden Monat bereits verbraucht wurden.
|
|
|
|
## Warnung und Sperre
|
|
|
|
Bei Erreichen von `budget_warning_percent` (Voreinstellung 80) bekommen alle
|
|
aktiven Nutzer der Organisation eine Meldung im Benachrichtigungsbereich. Das
|
|
Flag `budget_warning_sent` verhindert, dass sich die Warnung bei jeder weiteren
|
|
Buchung wiederholt, und wird beim Periodenwechsel zurückgesetzt.
|
|
|
|
Sind die Credits aufgebraucht, wechselt die Organisation in den Nur-Lese-Modus.
|
|
Bestehende Lagen bleiben vollständig lesbar, es lassen sich nur keine neuen
|
|
Aktualisierungen mehr starten. Abgeschaltet wird nichts.
|
|
|
|
**Offen.** Die Warnung geht bisher nur in die Oberfläche, nicht per E-Mail. Wer
|
|
sich nicht anmeldet, sieht sie nicht. Ein Versand über `email_utils` wäre der
|
|
nächste Schritt.
|
|
|
|
## Was die Verwaltung je Lizenz setzen muss
|
|
|
|
| Spalte | Bedeutung | Beispiel |
|
|
|---|---|---|
|
|
| `credits_total` | Kontingent je Periode | 10000 |
|
|
| `cost_per_credit` | nur für `BILLING_MODE=actual` und die interne Rechnung | 0.20 |
|
|
| `credits_period` | `monthly` oder `total` | monthly |
|
|
| `budget_warning_percent` | Warnschwelle in Prozent | 80 |
|
|
| `unlimited_budget` | Kontingent aushebeln | 0 |
|
|
|
|
Ohne `credits_total` läuft die Organisation ohne Kontingent, dann wird nichts
|
|
belastet. So stehen aktuell alle vier Live-Lizenzen (`unlimited_budget=1`), die
|
|
Umstellung ändert für sie nichts, bis ihnen ein Kontingent gesetzt wird.
|
|
Das Verwaltungsportal hat für diese Stellwerte noch keine Eingabefelder, das ist
|
|
ein eigenes, offenes Arbeitspaket auf der Portal-Seite.
|
|
|
|
## Einordnung der Größenordnung
|
|
|
|
Bei einem Satz von 45 Credits je Live-Lauf entspricht ein Monatskontingent von
|
|
10.000 Credits rund 222 Live-Refreshes oder rund 83 neu angelegten Recherchen.
|
|
Zum Vergleich, das gesamte Live-System mit 46 aktiven Lagen verbrauchte im Mai
|
|
2026 nach den gemessenen Medianen rund 11.700 Credits, mit den Verkaufssätzen
|
|
bewertet wären es grob 20.000 bis 22.000.
|
|
|
|
Ein Hinweis zur Fortschreibung. Die Ist-Kosten je Refresh sind zwischen März und
|
|
Mai 2026 von 3,54 auf 7,80 Dollar gestiegen, vermutlich weil ein Lagebild mit
|
|
wachsendem Materialbestand auf mehr Kontext aufsetzt. Falls sich das bestätigt,
|
|
verbraucht derselbe Kunde im zweiten Jahr mehr als im ersten. Die Sätze in
|
|
`CREDIT_TARIFF` sollten deshalb regelmäßig gegen `token_usage_monthly` geprüft
|
|
werden.
|
|
|
|
## Auto-Refresh-Takt
|
|
|
|
Der Takt ist die wichtigste Stellschraube am Verbrauch. Achtung, im Online-Monitor
|
|
liegt die Untergrenze derzeit noch bei 10 Minuten und die Voreinstellung bei
|
|
15 Minuten. Ein Live-Refresh dauert gemessen im Median aber 12,7 Minuten, jeder
|
|
zehnte länger als 22,9 Minuten, und im 15-Minuten-Takt verbraucht eine einzige
|
|
Lage bei 45 Credits je Lauf rund 130.000 Credits im Monat. Der Lokal-Fork hat
|
|
dafür bereits eine Lösung (Untergrenze 30 Minuten, Voreinstellung 12 Stunden,
|
|
Kostenvorschau im Anlege-Dialog, Commit 5b0b578), deren Portierung noch offen ist.
|
|
|
|
Zur Orientierung bei einem Kontingent von 10.000 Credits und 45 Credits je Lauf.
|
|
|
|
| Takt | Refreshes je Monat | Credits | Anteil |
|
|
|---|---|---|---|
|
|
| 30 Min | 1.440 | 64.800 | 648 Prozent |
|
|
| 1 Stunde | 720 | 32.400 | 324 Prozent |
|
|
| 6 Stunden | 120 | 5.400 | 54 Prozent |
|
|
| 12 Stunden | 60 | 2.700 | 27 Prozent |
|
|
| 24 Stunden | 30 | 1.350 | 14 Prozent |
|
|
|
|
## Offene Punkte
|
|
|
|
- E-Mail-Versand der Budget-Warnung.
|
|
- Takt-Untergrenze und Kostenvorschau aus dem Lokal-Fork portieren (siehe oben).
|
|
- Nachkaufpakete. Ohne sie ist der Deckel eine Sackgasse, mit ihnen eine
|
|
Umsatzquelle. Der Verkauf gehört ins Verwaltungsportal, im Monitor müsste nur
|
|
der Hinweistext bei aufgebrauchten Credits darauf zeigen.
|
|
- Sätze für die Studio-Bausteine sind geschätzt und sollten nachgemessen werden,
|
|
sobald `token_usage_monthly` Zeilen mit `source='analysis'` und `'factcheck'`
|
|
enthält.
|