Wersjonowane katalogi cenowe dla bram API AI: zatrzymaj zmianę ceny w wyniku zerwania notowań i obciążenie zwrotne

Rozliczenia AI API nie powiodą się, gdy brama traktuje ceny dostawcy jako statyczną tabelę przeglądową. Najtrudniejszą częścią nie jest mnożenie żetonów przez stawkę. Najtrudniejszą częścią jest wiedza, która stawka była ważna w momencie żądania, który kod SKU odpowiadał faktycznemu zakresowi wykorzystania, czy cena została zatwierdzona i dlaczego oferta klienta różni się od faktury dostawcy.

Brama obsługująca wiele modeli, kont, regionów, trybów pamięci podręcznej, zadań wsadowych, hostowanych narzędzi i udostępnionych wdrożeń wymaga platformy kontroli cen. Ta płaszczyzna kontrolna powinna przyjmować arkusze cen dostawców, aktualizować każdą zatwierdzoną stawkę, mapować wykorzystanie dostawcy na podlegające rozliczeniu jednostki SKU, testować oferty przed wdrożeniem i uzgadniać rozliczone wiersze księgi z fakturami.

Problem czytelnika: dryf cenowy wykracza poza strony z cenami

Ceny dostawców mogą różnić się w zależności od wymiarów, które zespoły aplikacji rzadko widzą bezpośrednio: wersja modelu, tokeny wejściowe, tokeny wejściowe w pamięci podręcznej, tokeny wyjściowe, tokeny wnioskowania, zapisy w pamięci podręcznej, narzędzia hostowane, rabaty wsadowe, typ wdrożenia, region, waluta i plany dotyczące zatwierdzonej wydajności. Jeśli te wymiary zostaną spłaszczone w jednym polu „koszt na token”, brama w końcu błędnie poda kwotę, przekaże budżety, zaniży rachunki najemców lub przydzieli wydatki do niewłaściwego miejsca powstawania kosztów.

Awaria zwykle pojawia się w jednym z pięciu miejsc:

• Cytaty inspekcji wstępnej: żądanie zostało zaakceptowane, ponieważ brama dokonuje szacunków na podstawie starej lub niekompletnej stawki.
• Rezerwacje budżetowe: saldo najemcy jest rezerwowane w jednym katalogu, ale rozliczane w innym.
• Rejestry wykorzystania: tokeny przechowywane w pamięci podręcznej, tokeny wnioskowania, wywołania narzędzi lub jednostki wsadowe są przechowywane jako ogólne sumy i nie można ich poprawnie wycenić.
• Eksport obciążenia zwrotnego: dział finansów otrzymuje sumy najemców bez wymiarów faktury dostawcy potrzebnych do wyjaśnienia rozbieżności.
• Interfejsy API partnerów: produkty niższego szczebla ujawniają ceny, nie wiedząc, czy są to ceny aktualne, szacunkowe, przestarzałe czy zablokowane.

Fakty, które należy uwzględnić przy projektowaniu cen

Fakt: dokumentacja dostawcy publicznego zwykle oddziela ceny według modelu i kategorii tokena. Tokeny wejściowe, buforowane wejściowe i wyjściowe mogą mieć różne szybkości. Niektóre raporty użycia ujawniają liczbę danych wejściowych przechowywanych w pamięci podręcznej lub tokenów rozumowania, co oznacza, że brama powinna zachować podkategorie użycia, a nie przechowywać tylko całkowitą liczbę tokenów.

Fakt: ceny nie zawsze dotyczą wyłącznie tokenów typu płatność zgodnie z rzeczywistym użyciem. Niektórzy dostawcy sprzedają przydzieloną pojemność, zapewnioną przepustowość lub jednostki tokenów powiązane z wydajnością konkretnego modelu. W tych trybach koszt może opierać się na czasie, jednostkach wydajności lub specyficznych dla modelu współczynnikach wejścia/wyjścia, a nie na prostym rachunku za token na żądanie.

Fakt: hostowane narzędzia i funkcje pobierania mogą powodować dodatkowe płatne zdarzenia poza normalnym wnioskowaniem o modelu. Podstawy wyszukiwania, wyszukiwanie plików, kontekst adresu URL, wykonywanie kodu, zapisy w pamięci podręcznej i pośrednie kroki agenta mogą wymagać oddzielnego mapowania jednostki SKU.

Zalecenie: traktuj te fakty jako wymagania schematu, a nie wyjątki. Jeśli zdarzenie użycia zawiera wymiar podlegający rozliczeniu, którego katalog nie może zmapować, brama powinna wstrzymać rozliczenie transakcji, zamiast po cichu wycenić ją na zero.

Utwórz wersjonowany katalog cen

Katalog cenowy powinien być najwyższej klasy tabelą lub usługą, a nie stałymi osadzonymi w adapterach dostawców. Katalog istnieje, aby odpowiedzieć na jedno pytanie: w przypadku tego zdarzenia użycia, w tym momencie, w kontekście konta najemcy i dostawcy, jaką zatwierdzoną stawkę należy zastosować?

Pola katalogu podstawowego

Praktyczny wiersz katalogu powinien zawierać przynajmniej te pola:

• catalog_version_id: niezmienna wersja używana do wyceny, rezerwowania, rozliczania i uzgadniania.
• provider: dostawca nadrzędny lub adapter dostawcy wewnętrznego.
• provider_account_scope: globalny, organizacja, projekt, obszar roboczy, dzierżawa BYOK, konto sprzedawcy lub umowa korporacyjna.
• model_id_or_alias: identyfikator modelu widoczny dla dostawcy lub alias modelu wewnętrznego, którego dotyczy wycena.
• pricing_sku: kanoniczna jednostka SKU używana przez bramę do rozliczeń.
• provider_meter_id: opcjonalny początkowy licznik faktur, jeśli jest dostępny.
• billing_unit: token wejściowy, token wejściowy w pamięci podręcznej, token wyjściowy, token wnioskowania, zapis w pamięci podręcznej, zapytanie wyszukiwania, token obrazu, sekunda audio, jednostka wsadowa, godzina PTU lub inna wyraźna jednostka.
• region_scope: globalny, region, strefa zamieszkania, rynek lub klasa przechowywania danych.
• deployment_type: bezserwerowe, wsadowe, udostępniane, dedykowane, dostrojone lub wewnętrzne piaskownice.
• service_tier: standardowy, priorytetowy, wsadowy, szybki, udostępniany lub inny poziom bramy.
• currency: waluta stawki przed narzutami, podatkami, ulgami lub konwersją.
• rate: dokładna liczba dziesiętna, nigdy binarna liczba zmiennoprzecinkowa.
• minimum_unit: najmniejsza jednostka płatna.
• rounding_rule: na żądanie, na wiersz faktury, na okres najmu lub definiowane przez dostawcę.
• source_url: dokumentacja, karta cenowa, numer kontraktu lub bilet wewnętrznego zatwierdzenia.
• observed_at: kiedy cena została wykryta lub zaimportowana.
• effective_from i effective_to: okno ważności.
• approval_state: wersja robocza, sprawdzona, zatwierdzona, przestarzała, zablokowana lub zastąpiona.

Ważny szczegół implementacji polega na tym, że wersja katalogu jest niezmienna po użyciu przez ruch. Korekty powinny tworzyć nową wersję lub wpis korygujący, a nie zmieniać wersję historyczną, do której odwołują się istniejące wiersze księgi.

Oddziel aliasy modeli od cenowych jednostek SKU

Aliasy wewnętrzne, takie jak chat-default, support-fast lub reasoning-premium to udogodnienia operacyjne. Nie powinny one zastępować identyfikatora modelu widocznego dla dostawcy ani kodu SKU cen w księdze.

Zdarzenie użycia powinno przechowywać wszystkie trzy tożsamości:

• requested_model_alias: o co prosiła aplikacja.
• upstream_model_id: jak właściwie nazywała się brama.
• pricing_sku: jakiego mechanizmu rozliczeniowego użył do rozliczenia.

Zapobiega to ponownemu zapisywaniu historii przez promocje aliasów. Jeśli chat-default wskazuje na jeden model w sierpniu i nowszy model we wrześniu, wykorzystanie w sierpniu powinno pozostać powiązane z sierpniowym modelem wyższego szczebla i sierpniową wersją katalogu.

Cytuj niezmienną wersję katalogu

Cytaty są przydatne tylko wtedy, gdy można je później wyjaśnić. Bramka powinna wybrać wersję katalogu przed wysyłką, użyć jej do wyceny wstępnej, zachować ją w rezerwacji budżetowej i przeprowadzić ostateczne rozliczenie.

Minimalny cykl życia żądania wygląda następująco:

1. Normalizuj żądanie według oczekiwanych wymiarów podlegających rozliczeniu: model, poziom usług, region, szacunkowy token, kwalifikowalność pamięci podręcznej, narzędzia, tryb wsadowy i typ wdrożenia.
2. Wybierz aktywną zatwierdzoną wersję katalogu dla zakresu konta dzierżawcy i dostawcy.
3. Rozwiąż oczekiwane kody SKU dla każdego możliwego wymiaru podlegającego rozliczeniu.
4. Oblicz wstępny kosztorys i zarezerwuj budżet najemcy.
5. Wyślij żądanie nadrzędne tylko wtedy, gdy istnieją wszystkie wymagane mapowania jednostek SKU.
6. Przechwytuj metadane końcowego użycia z odpowiedzi dostawcy, łącznie z podkategoriami.
7. Rozliczaj rzeczywiste wykorzystanie, korzystając z tej samej wersji katalogu, chyba że wymagany jest wyraźny przepływ pracy związany z korektą.
8. Zapisuj wszelkie rozbieżności między kwotami zarezerwowanymi i rozliczonymi.

Zalecenie: zacytuj i zastrzeż przy ostrożnych założeniach, a następnie rozlicz się z wykorzystania po udzieleniu odpowiedzi. Dokładne ceny przed wysyłką są trudne w przypadku przesyłania strumieniowego, ponownych prób, hostowanych narzędzi, długotrwałych agentów i zachowań związanych z trafieniami w pamięci podręcznej. Celem nie jest doskonałe przewidywanie. Celem jest kontrolowana ekspozycja i możliwe do wytłumaczenia rozliczenie.

Awaria zamknięta dla nieznanych wymiarów podlegających rozliczeniu

Najniebezpieczniejszy błąd cenowy to brakujący kod SKU, który powoduje, że można go używać bezpłatnie. Brama powinna zakończyć się niepowodzeniem, gdy odpowiedź dostawcy zawiera segment użycia, który nie ma zatwierdzonego mapowania.

Przykłady, które powinny spowodować wstrzymanie płatności:

• Odpowiedź modelu zawiera cached_input_tokens, ale katalog zawiera tylko ogólne stawki tokenów wejściowych i wyjściowych.
• Model wnioskowania zwraca reasoning_tokens, ale nie skonfigurowano żadnej jednostki SKU wnioskowania.
• Hostowane narzędzie wyszukiwania rozlicza się za zapytanie, ale brama rejestruje tylko tokeny modelu.
• Zadanie wsadowe otrzymuje zniżkę, ale katalog mapuje je na standardową jednostkę SKU bezserwerową.
• Wdrożenie z obsługą administracyjną generuje cogodzinne opłaty za pojemność, ale księga dzierżawy oczekuje rozliczenia na podstawie tokenu.
• Wdrożenie regionalne wykorzystuje modyfikator miejsca zamieszkania, którego nie ma w aktywnym katalogu.

Wstrzymanie płatności nie powinno spowodować utraty wydarzenia. Powinien zachować surowe użycie dostawcy, znormalizowane użycie, identyfikatory żądań, identyfikatory dzierżawy, zakres konta dostawcy, próbę wersji katalogu, brakujące pola SKU i przyczynę zablokowania rozliczenia. Po zaktualizowaniu i zatwierdzeniu katalogu kolejkę wstrzymań można odtworzyć w sposób deterministyczny.

Skorzystaj z kontroli różnic cenowych przed zatwierdzeniem

Strony z cenami dostawców i interfejsy API nie zawsze działają stabilnie na komputerze, a umowy mogą mieć pierwszeństwo przed stawkami publicznymi. Mimo to automatyczne kontrole różnic są przydatne jako alerty. Powinni wykryć zmiany, zanim wpłyną one na wyceny widoczne dla klienta.

Plan importu cen powinien porównywać nowo zaobserwowane arkusze cen z ostatnim zatwierdzonym katalogiem i flagą:

• nowe modele lub wycofane modele;
• zmienione dane wejściowe, buforowane dane wejściowe, dane wyjściowe lub współczynniki wnioskowania;
• nowe kategorie tokenów lub liczniki narzędzi;
• zmieniono mnożniki zapisu w pamięci podręcznej lub trafień w pamięci podręcznej;
• nowe modyfikatory regionalne, rezydencjalne lub rynkowe;
• zmieniono zasady rabatów zbiorczych;
• zmieniono reguły dotyczące udostępnionej lub zatwierdzonej pojemności;
• zmiany walut;
• zaokrąglanie lub zmiany jednostek minimalnych;
• konflikty pomiędzy publicznymi kartami cenowymi a stawkami umownymi specyficznymi dla konta.

Zalecenie: traktuj fragmenty i importy jako dane robocze. Wymagaj zatwierdzenia przez człowieka w przypadku wszelkich zmian wpływających na ruch płatny, ceny widoczne dla partnerów lub eksport finansowy. Wewnętrzne eksperymenty mogą wykorzystywać katalog piaskownicy, ale powinien on mieć wyraźnie określone pułapy wydatków i nigdy nie należy go mylić z zatwierdzonymi rozliczeniami klienta.

Dodaj testy wyceny jako CI

Zmiany cen wymagają testów z tego samego powodu, co zmiany w kodzie: niewielka zmiana może mieć wpływ na wiele kształtów żądań. Testy ofert powinny być uruchamiane za każdym razem, gdy ulegną zmianie wiersze katalogu, mapowania jednostek SKU, adaptery dostawców lub zasady dotyczące znaczników.

Użyj syntetycznych kształtów żądań obejmujących powierzchnię cenową:

• standardowe żądanie tekstowe z tokenami wejściowymi i wyjściowymi;
• żądanie z buforowanymi tokenami wejściowymi;
• żądanie wymagające dużej ilości rozumowania z oddzielnym użyciem rozumowania;
• żądanie użycia narzędzia z opłatami za wyszukiwanie, plik lub wykonanie kodu;
• żądanie multimodalne zawierające jednostki obrazu, audio, wideo lub wygenerowanych multimediów;
• zadanie wsadowe ze stawkami obniżonymi i opóźnionym rozliczeniem;
• wdrożenie udostępnione z wydajnością godzinową i zachowaniem dodatkowym;
• prośba dotycząca regionu lub miejsca zamieszkania;
• najemca ze stawkami umownymi dostosowanymi do dostawcy;
• najemca partnerski z polityką dopłat lub zniżek.

Każdy test powinien wykazać więcej niż sumę końcową. Powinien zawierać wybraną wersję katalogu, listę SKU, jednostki rozliczeniowe, stawki, sposób zaokrąglania, walutę, szacowaną sumę, kwotę rezerwacji i oczekiwane wiersze rozliczenia.

Przykładowy test wyceny

{
  "name": "cached_input_plus_reasoning_output_standard_tier",
  "request": {
    "tenant_id": "tenant_test",
    "model_alias": "reasoning-default",
    "service_tier": "standard",
    "region": "global",
    "estimated_usage": {
      "input_tokens": 12000,
      "cached_input_tokens": 8000,
      "output_tokens": 1500,
      "reasoning_tokens": 3000
    }
  },
  "expect": {
    "catalog_version_id": "2026-09-01-approved",
    "required_skus": [
      "text_input",
      "text_cached_input",
      "text_output",
      "reasoning_output"
    ],
    "approval_state": "approved",
    "unknown_dimensions": []
  }
}

Ten rodzaj testu wychwytuje błędy katalogu ukrywane przez pulpity nawigacyjne: brakujący kod SKU tokenu w pamięci podręcznej, nieaktualny współczynnik wnioskowania lub niezgodność poziomów, która pojawia się tylko w przypadku zakresu jednego konta dostawcy.

Uzgodnij według wymiarów faktury dostawcy

Suma obciążeń zwrotnych nie jest wystarczająca do uzgodnienia. Brama powinna agregować wiersze księgi według tych samych wymiarów, których używa faktura dostawcy, a następnie mapować te sumy z powrotem na dzierżawców, zespoły, klucze, użytkowników, produkty i przepływy pracy.

Zadanie uzgadniania powinno być grupowane według pól, takich jak dostawca, konto, okres fakturowania, licznik, model, jednostka SKU, region, typ wdrożenia, poziom usług, waluta i wersja katalogu. Różnice należy uwzględnić w znanych przyczynach:

• termin kursu wymiany lub konwersja waluty;
• zaokrąglanie na poziomie żądania w porównaniu z poziomem wiersza faktury;
• opóźnione raporty użycia dostawcy;
• brakujące zdarzenia narzędzia hostowanego;
• niezgodność wersji katalogu;
• kredyty, zobowiązania lub rabaty dla przedsiębiorstw po stronie dostawcy;
• podatki, opłaty rynkowe i opłaty za brak użytkowania;
• ręczne korekty lub zwroty pieniędzy.

Zalecenie: stawki kosztów dostawcy modelu oddzielnie od stawek obciążeń zwrotnych klienta. Faktury dostawcy mogą zawierać kredyty, zobowiązania, rabaty lub podatki, które nie powinny automatycznie zmieniać cen oferowanych klientom. Czysty system może wyjaśnić obie liczby: kwotę pobieraną przez dostawcę i kwotę pobieraną przez najemcę zgodnie z zatwierdzonymi zasadami dotyczącymi bramy.

Udostępnij pochodzenie cen finansom i partnerom

Katalog cenowy to nie tylko wewnętrzna zależność rozliczeniowa. Zespoły finansowe, administratorzy platform i partnerzy muszą wiedzieć, czy cena jest aktualna i godna zaufania.

Udostępnij pola pochodzenia w widokach administratora i interfejsach API partnerów:

• bieżący kurs i waluta;
• data wejścia w życie i planowana data zakończenia;
• źródłowy adres URL lub odniesienie do umowy;
• stan zatwierdzenia;
• zakres konta dostawcy;
• Zasady dotyczące narzutów i rabatów;
• czy cena jest szacunkowa, zatwierdzona, przestarzała, zablokowana czy zastąpiona;
• status ostatniego uzgodnienia.

Dzięki temu produkty niższego szczebla unikają przedstawiania nieaktualnych twierdzeń o „najtańszym modelu” lub stałych cen dla klientów po zmianach cen na rynku wyższego szczebla. Daje także finansom możliwą do obrony ścieżkę, gdy budżety i faktury się nie zgadzają.

Lista kontrolna wdrożenia

• Utwórz niezmienny katalog cen z datami obowiązywania i stanami zatwierdzenia.
• Wyraźnie przedstawiaj jednostki podlegające rozliczeniu, zamiast przechowywać tylko ogólne sumy tokenów.
• Przechowuj żądany alias, identyfikator modelu nadrzędnego i kod SKU cenowy przy każdym zdarzeniu użycia.
• Utrzymaj catalog_version_id w ofertach, rezerwacjach, wierszach księgi i zapisach uzgodnień.
• Awaria zamknięta, gdy użycie zawiera niezamapowany wymiar płatny.
• Korzystaj z importu wersji roboczej i sprawdzania różnic, aby wykryć zmiany cen dostawców.
• Wymagaj zatwierdzenia, zanim zmiany w katalogu wpłyną na rozliczany ruch klientów.
• Dodaj testy ofert dla tokenów buforowanych, tokenów wnioskowania, narzędzi, zadań wsadowych, udostępnionych wdrożeń i modyfikatorów regionalnych.
• Oddziel stawki kosztów dostawcy od stawek obciążeń zwrotnych klienta.
• Uzgodnij wymiary faktury dostawcy przed przypisaniem rozbieżności najemcom.

Kompromis

Więcej wersji oznacza więcej pracy operacyjnej. Każda zmiana ceny wymaga importu, przeglądu, zatwierdzenia, testów i wdrożenia. Zaletą jest to, że stare zużycie nigdy nie jest przypadkowo przeliczane na nową stawkę.

Niepowodzenie zamknięcia może opóźnić dostęp do nowego modelu. Jest to właściwa wartość domyślna dla rozliczanego ruchu klientów. Do wewnętrznych eksperymentów użyj katalogu piaskownicy z wyraźnymi limitami wydatków i przejrzystymi etykietami.

Automatyczne porównywanie cen jest przydatne, ale nie jest wiarygodne. Strony publiczne mogą zmieniać układ, pomijać rabaty kontraktowe lub prościej opisywać ceny. Użyj automatyzacji, aby wykryć dryf, a następnie zatwierdź sprawdzone wiersze katalogu, zanim wpłyną one na rozliczenia.

Doskonałe szacunki dotyczące inspekcji wstępnej są nierealistyczne. Przesyłanie strumieniowe, ponowne próby, pętle agentów, trafienia w pamięć podręczną i hostowane narzędzia mogą zmienić ostateczne wykorzystanie. Bramka powinna łączyć konserwatywne rezerwacje z rozliczeniem po odpowiedzi i wyraźnym raportowaniem rozbieżności.

Przewidywanie: katalogi cenowe staną się infrastrukturą bramową

Przewidywanie: w miarę rozprzestrzeniania się wykorzystania sztucznej inteligencji w zespołach katalog cen stanie się równie ważny jak katalog modeli. Model routingu odpowiada na pytanie „dokąd powinno trafić to żądanie?” Odpowiedzi dotyczące kontroli cen „Czy możemy wycenić, zarezerwować, rozliczyć i wyjaśnić tę prośbę?”

Przewidywanie: zespoły utrzymujące ceny w statycznych plikach konfiguracyjnych będą miały trudności, ponieważ dostawcy będą dodawać więcej kategorii tokenów, liczników narzędzi, reguł pamięci podręcznej i planów wydajności. Presja będzie pochodzić przede wszystkim ze strony finansów i partnerów, a nie twórców aplikacji.

Wniosek

Brama obsługująca wiele modeli nie może traktować cen jako tabeli bocznej. Potrzebuje wersjonowanego katalogu z datami obowiązywania, mapowaniem SKU, testami ofert, przepływem pracy zatwierdzania i uzgadnianiem faktur. Praktyczna zasada jest prosta: każdy naliczony segment wykorzystania musi odpowiadać zatwierdzonej stawce, każda wycena musi odnosić się do niezmiennej wersji katalogu, a każdy rozliczony wiersz księgi musi być możliwy do wyjaśnienia po zmianie cen dostawcy.

Zacznij od wymiarów, które już wpływają na ruch produkcyjny: model, kategoria tokenu, warstwa usług, region, typ wdrożenia, zachowanie pamięci podręcznej i hostowane narzędzia. Następnie dodaj stany zatwierdzenia, zachowanie w przypadku zamknięcia awaryjnego i grupy uzgadniania. Ta podstawa zapobiega sytuacji, w której zmiana cen staje się incydentem rozliczeniowym.

Powiązana lektura

• wycena, rezerwacja, rozliczanie i uzgadnianie wywołań modeli
• narzędzia AI hostowane przez mierniki poza normalnym rozliczaniem tokenów
• eksportuj księgi bram dla Obciążenie zwrotne FinOps