enterprise_ai.finops
Source : sdks/python/src/enterprise_ai/finops/__init__.py. Retour à l'index de la référence du SDK Python.
Cette page est générée par tools/docs/gen_sdk_reference.py depuis les sources du SDK et les dossiers de textes OpenAPI. Ne la modifiez pas à la main : changez la source et régénérez.
Classe FinopsClient
FinOps. Gestion des coûts de l'usage de l'IA : grilles tarifaires, événements d'usage, estimations, quotas et réservations, répartition du coût des GPU, rapprochement de la facturation et alertes.
Resource
FinopsClient.alerts
alerts() -> Any
Lister les alertes FinOps. Alertes de budget, de quota et d'écart de facturation du tenant, de la plus récente à la plus ancienne, avec leur message dans la langue de la requête. Une seule page. Demande un rôle de lecteur et un principal de tenant.
Route : /v1/finops/alerts (GET).
Cet élément ne prend aucun paramètre.
Retour : Any. Réponse JSON décodée de l'opération « Lister les alertes FinOps ».
Erreurs levées : les erreurs typées du transport (Erreurs).
FinopsClient.check_budget
check_budget(agent: str | None = None, project: str | None = None, run: str | None = None) -> Any
Lire la consommation des quotas. Chaque quota du tenant avec sa fenêtre courante et le coût et les jetons consommés et réservés dans celle-ci. Les quotas par exécution demandent run pour trouver leur fenêtre. Demande un rôle de lecteur et un principal de tenant.
Route : /v1/quotas/usage (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
agent | str | None | None | non | Agent utilisé pour résoudre les fenêtres. |
project | str | None | None | non | Projet utilisé pour résoudre les fenêtres. |
run | str | None | None | non | Exécution d'agent dont les fenêtres des quotas run sont lues. |
Retour : Any. Réponse JSON décodée de l'opération « Lire la consommation des quotas ».
Erreurs levées : les erreurs typées du transport (Erreurs).
FinopsClient.create_allocation_policy
create_allocation_policy(policy: dict[str, Any]) -> Any
Créer une politique de répartition GPU. Crée une politique qui valorise les échantillons GPU des déploiements correspondants et répond 201. Le motif de déploiement le plus précis l'emporte. Coût d'un échantillon de s secondes à P watts : GPU s / 3600 * gpu_hourly_cost, énergie P * s / 3600 / 1000 * energy_kwh_price * pue, stockage storage_gb * storage_gb_month_price * (s / 3600) / 730, total multiplié par 1 + overhead_pct / 100. Audité. Demande platform_admin.
Route : /v1/finops/allocation-policies (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
policy | dict[str, Any] | oui | Politique d'imputation des coûts à créer, envoyée comme corps de la requête. |
Retour : Any. Réponse JSON décodée de l'opération « Créer une politique de répartition GPU ».
Erreurs levées : les erreurs typées du transport (Erreurs).
FinopsClient.create_media_price
create_media_price(price: dict[str, Any]) -> Any
Ajouter une révision de prix de média. Ajoute une révision de prix datée pour une unité de média et répond 201. Une révision ne réécrit jamais une révision plus ancienne. Les mêmes unité, fournisseur, ressource et date de début répondent 409 media_price_exists ; un champ invalide 422 media_price_invalid. Audité. Demande finops ou tenant_admin, et un principal de tenant.
Route : /v1/finops/media-prices (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
price | dict[str, Any] | oui | Carte de prix média à créer (prix par image, seconde d'audio ou de vidéo, caractère...). |
Retour : Any. Réponse JSON décodée de l'opération « Ajouter une révision de prix de média ».
Erreurs levées : les erreurs typées du transport (Erreurs).
FinopsClient.create_price_card
create_price_card(card: dict[str, Any]) -> Any
Créer une grille tarifaire. Crée une grille tarifaire pour le tenant (ou une grille globale pour un administrateur de la plateforme sans tenant) et répond 201. La grille en vigueur pour le même fournisseur, le même motif de modèle, la même région et le même type d'usage est close à la nouvelle date de début ; une grille commençant plus tard dans la nouvelle validité répond 409 conflict. Des clés de prix inconnues, des prix négatifs ou une grille sans aucun prix répondent 422 price_card_invalid. Audité. Demande finops ou tenant_admin (platform_admin pour une grille globale).
Route : /v1/finops/price-cards (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
card | dict[str, Any] | oui | Carte de prix à créer, envoyée comme corps de la requête. |
Retour : Any. Réponse JSON décodée de l'opération « Créer une grille tarifaire ».
Erreurs levées : les erreurs typées du transport (Erreurs).
FinopsClient.estimate
estimate(provider: str, model_id: str | None = None, input_tokens: int = 0, output_tokens: int = 0, reasoning_effort: str | None = None, usage_type: str = 'llm', **extra: Any) -> Any
Estimer le coût d'un appel. Valorise un appel prévu avec la grille tarifaire en vigueur (motif de modèle et région les plus précis d'abord), le convertit dans la devise du tenant et le compare aux quotas correspondants, sans rien réserver. Les jetons de raisonnement sont ajoutés selon le mode de facturation de la grille. Sans grille : 404 price_card_not_found ; sans taux de change : 422 fx_rate_missing. Demande un rôle d'usage ou de lecteur et un principal de tenant.
Route : /v1/finops/estimate (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
provider | str | oui | Fournisseur de l'appel (obligatoire). | |
model_id | str | None | None | non | Modèle de l'appel, comparé aux motifs de modèle des grilles tarifaires. |
input_tokens | int | 0 | non | Nombre de jetons d'entrée à valoriser (0 par défaut). |
output_tokens | int | 0 | non | Nombre de jetons de sortie à valoriser (0 par défaut). |
reasoning_effort | str | None | None | non | Effort de raisonnement (none, minimal, low, medium, high, max) qui donne une réserve par défaut de jetons de raisonnement. |
usage_type | str | 'llm' | non | Type d'usage, llm par défaut. |
**extra | Any | non | Champs supplémentaires fusionnés dans le corps de la requête. |
Retour : Any. Réponse JSON décodée de l'opération « Estimer le coût d'un appel ».
Erreurs levées : les erreurs typées du transport (Erreurs).
FinopsClient.estimate_media_cost
estimate_media_cost(request: dict[str, Any]) -> Any
Estimer des coûts de médias. Valorise jusqu'à 100 éléments de médias avec la révision en vigueur à leur date (ressource exacte d'abord, puis la révision * du fournisseur). Un élément sans prix revient avec amount: null, status: unavailable et reason: price_unknown ; total n'est donné que si tous les éléments sont valorisés dans une seule devise (complete: true). Des éléments invalides répondent 422 media_price_invalid avec le champ. Demande un rôle de lecteur ou agent, et un principal de tenant.
Route : /v1/finops/media-costs/estimate (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
request | dict[str, Any] | oui | items : de 1 à 100 objets avec unit (audio_second, image, video_second, gpu_second, storage_gb_month), provider, quantity (nombre positif), et facultativement resource (* par défaut) et at (ISO 8601, maintenant par défaut). |
Retour : Any. Réponse JSON décodée de l'opération « Estimer des coûts de médias ».
Erreurs levées : les erreurs typées du transport (Erreurs).
FinopsClient.fx_rates
fx_rates() -> Any
Lister les taux de change. Taux de change (globaux et propres au tenant) par devise de base, devise de cotation et date la plus récente d'abord, avec leur source. Demande un rôle de lecteur.
Route : /v1/finops/fx-rates (GET).
Cet élément ne prend aucun paramètre.
Retour : Any. Réponse JSON décodée de l'opération « Lister les taux de change ».
Erreurs levées : les erreurs typées du transport (Erreurs).
FinopsClient.get_price_card
get_price_card(card_id: str) -> Any
Lire une grille tarifaire. Une grille tarifaire avec ses prix, ses paliers, sa validité et son statut. Identifiant inconnu : 404 not_found. Demande un rôle de lecteur.
Route : /v1/finops/price-cards/{card_id} (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
card_id | str | oui | Identifiant (UUID) de la grille tarifaire. |
Retour : Any. Réponse JSON décodée de l'opération « Lire une grille tarifaire ».
Erreurs levées : les erreurs typées du transport (Erreurs).
FinopsClient.gpu_allocation
gpu_allocation(start: str | None = None, end: str | None = None, **filters: Any) -> Any
Lire la répartition du coût GPU. Coût des déploiements GPU locaux sur la fenêtre, calculé à partir des échantillons GPU et des politiques de répartition, et partagé entre les tenants au prorata des secondes GPU de leurs événements d'usage sur chaque déploiement. Un tenant voit sa propre part ; un administrateur de la plateforme sans tenant voit tous les tenants. Demande un rôle de lecteur.
Route : /v1/finops/gpu/allocation (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
start | str | None | None | non | Début de la période (ISO 8601), envoyé comme from ; par défaut un jour avant end. |
end | str | None | None | non | Fin de la période (ISO 8601), envoyée comme to ; maintenant par défaut. |
**filters | Any | non | Paramètres de requête supplémentaires, envoyés tels quels. |
Retour : Any. Réponse JSON décodée de l'opération « Lire la répartition du coût GPU ».
Erreurs levées : les erreurs typées du transport (Erreurs).
FinopsClient.gpu_samples
gpu_samples(samples: list[dict[str, Any]]) -> Any
Ingérer des échantillons GPU. Enregistre des échantillons d'utilisation GPU (en général issus de DCGM), de 1 à 10000 par appel, utilisés pour la répartition du coût GPU. Un événement d'audit par lot. Demande platform_admin.
Route : /v1/finops/gpu/samples (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
samples | list[dict[str, Any]] | oui | Échantillons à enregistrer, de 1 à 10000. |
Retour : Any. Réponse JSON décodée de l'opération « Ingérer des échantillons GPU ».
Erreurs levées : les erreurs typées du transport (Erreurs).
FinopsClient.import_invoice
import_invoice(source: str, content: str, filename: str | None = None, **extra: Any) -> Any
Importer un export de facturation. Analyse un export de facturation d'un fournisseur, convertit chaque ligne dans la devise du tenant et l'enregistre, puis répond 201 avec l'import (nombre de lignes, total, période). Un export illisible répond 422 import_invalid avec la raison. Lancez ensuite le rapprochement. Audité. Demande finops ou tenant_admin, et un principal de tenant.
Route : /v1/finops/reconciliation/imports (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
source | str | oui | Format de l'export : openai, anthropic, aws_cur, azure, gcp ou generic_csv. | |
content | str | oui | Contenu de l'export tel que le fournisseur le donne (document JSON ou texte CSV). | |
filename | str | None | None | non | Nom du fichier importé, conservé pour l'historique. |
**extra | Any | non | Champs supplémentaires fusionnés dans le corps de la requête. |
Retour : Any. Réponse JSON décodée de l'opération « Importer un export de facturation ».
Erreurs levées : ValueError, les erreurs typées du transport (Erreurs).
FinopsClient.ingest_usage
ingest_usage(event: dict[str, Any]) -> Any
Ingérer un événement d'usage. Valide un Usage Event v1, le valorise (coût mesuré dans la devise du tenant) et l'enregistre ; répond 201, ou 200 avec duplicate: true si le même event_id était déjà enregistré. Un événement invalide répond 422 usage_event_invalid avec les erreurs ; un événement d'un autre tenant 403 usage_tenant_mismatch. Un événement d'audit par appel, jamais le contenu. Demande finops, tenant_admin, agent ou developer, et un principal de tenant.
Route : /v1/finops/usage (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
event | dict[str, Any] | oui | Document Usage Event (voir usage_event) ; son event_id sert de clé d'idempotence. |
Retour : Any. Réponse JSON décodée de l'opération « Ingérer un événement d'usage ».
Erreurs levées : les erreurs typées du transport (Erreurs).
FinopsClient.ingest_usage_batch
ingest_usage_batch(events: list[dict[str, Any]]) -> Any
Ingérer des événements d'usage par lot. Ingère jusqu'à 1000 événements d'usage, chacun dans son propre point de sauvegarde : la réponse liste chaque événement comme created, duplicate ou error (avec code, message et détails) ainsi que les totaux. Plus de 1000 événements répondent 413 batch_too_large ; un corps sans liste events 422 validation_error. Un événement d'audit par lot. Demande finops, tenant_admin, agent ou developer, et un principal de tenant.
Route : /v1/finops/usage/batch (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
events | list[dict[str, Any]] | oui | Documents Usage Event, envoyés comme {events}. |
Retour : Any. Réponse JSON décodée de l'opération « Ingérer des événements d'usage par lot ».
Erreurs levées : les erreurs typées du transport (Erreurs).
FinopsClient.list_allocation_policies
list_allocation_policies() -> Any
Lister les politiques de répartition GPU. Politiques qui transforment les échantillons GPU en coût (coût horaire du GPU, énergie, PUE, stockage et frais généraux) par motif de déploiement et modèle de GPU. Demande un rôle de lecteur.
Route : /v1/finops/allocation-policies (GET).
Cet élément ne prend aucun paramètre.
Retour : Any. Réponse JSON décodée de l'opération « Lister les politiques de répartition GPU ».
Erreurs levées : les erreurs typées du transport (Erreurs).
FinopsClient.list_imports
list_imports() -> Any
Lister les imports de facturation. Exports de facturation importés par le tenant, avec source, fournisseur, nom de fichier, nombre de lignes, montant total, devise et période. Demande un rôle de lecteur et un principal de tenant.
Route : /v1/finops/reconciliation/imports (GET).
Cet élément ne prend aucun paramètre.
Retour : Any. Réponse JSON décodée de l'opération « Lister les imports de facturation ».
Erreurs levées : les erreurs typées du transport (Erreurs).
FinopsClient.list_media_prices
list_media_prices(unit: str | None = None) -> Any
Lister les prix des médias. Révisions datées des prix des médias du tenant par unité, fournisseur, ressource et date, avec la liste des unités prises en charge. Une unité inconnue répond 422 media_price_invalid. Demande un rôle de lecteur et un principal de tenant.
Route : /v1/finops/media-prices (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
unit | str | None | None | non | Seulement les prix de cette unité : audio_second, image, video_second, gpu_second ou storage_gb_month. |
Retour : Any. Réponse JSON décodée de l'opération « Lister les prix des médias ».
Erreurs levées : les erreurs typées du transport (Erreurs).
FinopsClient.list_price_cards
list_price_cards(provider: str | None = None, model: str | None = None, at: str | None = None, include_retired: bool | None = None, **page: Any) -> Any
Lister les grilles tarifaires. Grilles tarifaires visibles par l'appelant (globales et propres au tenant), par fournisseur, motif de modèle et date de début. Seulement les grilles actives sauf si include_retired ou at est fourni. Une seule page. Demande un rôle de lecteur.
Route : /v1/finops/price-cards (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
provider | str | None | None | non | Seulement les grilles de ce fournisseur. |
model | str | None | None | non | Seulement les grilles dont le motif de modèle correspond à cet identifiant de modèle (motif glob insensible à la casse). |
at | str | None | None | non | Seulement les grilles en vigueur à cette date et heure (ISO 8601), y compris les grilles retirées. |
include_retired | bool | None | None | non | Inclure les grilles retirées (faux par défaut). |
**page | Any | non | Options de pagination transmises à la liste : limit (nombre maximal d'éléments par page) et cursor (le next_cursor de la page précédente). Itérer sur la page renvoyée suit tous les curseurs. |
Retour : Any. Réponse JSON décodée de l'opération « Lister les grilles tarifaires ».
Erreurs levées : les erreurs typées du transport (Erreurs).
FinopsClient.reconcile
reconcile(start: str | None = None, end: str | None = None) -> Any
Lancer le rapprochement de facturation. Répartit les lignes facturées importées de la période sur les événements d'usage : une ligne portant un provider_request_id va à cet événement, les autres sont réparties au prorata du coût mesuré des événements du même fournisseur, du même modèle et du même jour (à parts égales si rien n'a été mesuré) ; les lignes sans événement candidat sont signalées comme non rapprochées. Des alertes d'écart sont levées au-delà du seuil du tenant. Audité. Demande finops ou tenant_admin, et un principal de tenant.
Route : /v1/finops/reconciliation/run (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
start | str | None | None | non | Début de la période rapprochée (ISO 8601), envoyé comme from. |
end | str | None | None | non | Fin de la période rapprochée (ISO 8601), envoyée comme to. |
Retour : Any. Réponse JSON décodée de l'opération « Lancer le rapprochement de facturation ».
Erreurs levées : les erreurs typées du transport (Erreurs).
FinopsClient.reconciliation_report
reconciliation_report(start: str | None = None, end: str | None = None) -> Any
Lire le rapport de rapprochement. Coût mesuré comparé au coût facturé sur la période, avec l'écart, les lignes de facturation non rapprochées et les 100 dernières alertes d'écart. Un from postérieur à to répond 422 validation_error. Demande un rôle de lecteur et un principal de tenant.
Route : /v1/finops/reconciliation/report (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
start | str | None | None | non | Début de la période du rapport (ISO 8601), envoyé comme from. |
end | str | None | None | non | Fin de la période du rapport (ISO 8601), envoyée comme to. |
Retour : Any. Réponse JSON décodée de l'opération « Lire le rapport de rapprochement ».
Erreurs levées : les erreurs typées du transport (Erreurs).
FinopsClient.record_usage
record_usage(event: dict[str, Any]) -> Any
Ingérer un événement d'usage. Valide un Usage Event v1, le valorise (coût mesuré dans la devise du tenant) et l'enregistre ; répond 201, ou 200 avec duplicate: true si le même event_id était déjà enregistré. Un événement invalide répond 422 usage_event_invalid avec les erreurs ; un événement d'un autre tenant 403 usage_tenant_mismatch. Un événement d'audit par appel, jamais le contenu. Demande finops, tenant_admin, agent ou developer, et un principal de tenant.
Route : /v1/finops/usage (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
event | dict[str, Any] | oui | Document Usage Event (voir usage_event) ; son event_id sert de clé d'idempotence. |
Retour : Any. Réponse JSON décodée de l'opération « Ingérer un événement d'usage ».
Erreurs levées : les erreurs typées du transport (Erreurs).
FinopsClient.reserve
reserve(cost: number | string = '0', tokens: int = 0, scope: dict[str, Any] | None = None, ttl_seconds: int | None = None) -> Any
Réserver un coût et des jetons. Réserve un montant sur chaque quota actif correspondant à la portée (les quotas du tenant correspondent toujours ; un principal utilisateur ajoute sa propre portée utilisateur) et répond 201 avec la réservation, ses éléments par quota et fenêtre, les quotas souples dépassés et son échéance. Un quota strict qui serait dépassé répond 429 quota_exceeded avec Retry-After: 60, et rien n'est réservé. Les réservations expirées sont d'abord libérées. Audité. Demande finops, tenant_admin, agent ou developer, et un principal de tenant.
Route : /v1/quotas/reserve (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
cost | number | string | '0' | non | Coût à réserver dans la devise du tenant, de 0 à 10^15, 0 par défaut ; converti dans la devise de chaque quota. |
tokens | int | 0 | non | Jetons à réserver, de 0 à 2^62, 0 par défaut. |
scope | dict[str, Any] | None | None | non | Pour qui est l'appel : clés project, agent, user, model, provider, run (ou les mêmes avec _id), comparées aux portées des quotas. |
ttl_seconds | int | None | None | non | Durée de vie de la réservation en secondes, de 1 à 86400 ; par défaut le reservation_ttl_seconds du tenant (900). Une réservation expirée est libérée. |
Retour : Any. Réponse JSON décodée de l'opération « Réserver un coût et des jetons ».
Erreurs levées : les erreurs typées du transport (Erreurs).
FinopsClient.retire_price_card
retire_price_card(card_id: str) -> Any
Retirer une grille tarifaire. Marque la grille retired et termine sa validité à at (maintenant par défaut) si elle restait ouverte après cette date. Les usages passés gardent le prix avec lequel ils ont été valorisés. Identifiant inconnu : 404 not_found. Audité. Demande finops ou tenant_admin.
Route : /v1/finops/price-cards/{card_id}/retire (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
card_id | str | oui | Identifiant (UUID) de la grille tarifaire. |
Retour : Any. Réponse JSON décodée de l'opération « Retirer une grille tarifaire ».
Erreurs levées : les erreurs typées du transport (Erreurs).
FinopsClient.set_fx_rates
set_fx_rates(rates: dict[str, str]) -> Any
Définir des taux de change. Ajoute ou remplace de 1 à 1000 taux de change (mêmes devises et même date : remplacé) pour le tenant, ou des taux globaux pour un administrateur de la plateforme sans tenant, et répond le nombre mis à jour avec la liste complète. Les conversions passent par USD comme pivot quand aucun taux direct n'existe. Audité. Demande finops ou tenant_admin (platform_admin pour les taux globaux).
Route : /v1/finops/fx-rates (PUT).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
rates | dict[str, str] | oui | Taux à ajouter ou remplacer, de 1 à 1000. |
Retour : Any. Réponse JSON décodée de l'opération « Définir des taux de change ».
Erreurs levées : les erreurs typées du transport (Erreurs).
FinopsClient.settings
settings() -> Any
Lire les paramètres FinOps. Devise, budget mensuel, seuil d'écart et durée de vie des réservations du tenant (valeurs par défaut : USD, pas de budget, 10 pour cent, 900 secondes). Demande un rôle de lecteur et un principal de tenant.
Route : /v1/finops/settings (GET).
Cet élément ne prend aucun paramètre.
Retour : Any. Réponse JSON décodée de l'opération « Lire les paramètres FinOps ».
Erreurs levées : les erreurs typées du transport (Erreurs).
FinopsClient.summary
summary(group_by: str = 'model', **filters: Any) -> Any
Synthétiser la dépense. Événements d'usage du tenant regroupés selon une dimension, par devise : nombre d'événements, jetons, secondes GPU, montants estimés, mesurés et facturés (le facturé vaut null si rien n'a été rapproché). Un regroupement inconnu répond 400 finops_group_by_invalid. Demande un rôle de lecteur et un principal de tenant.
Route : /v1/finops/summary (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
group_by | str | 'model' | non | Regroupement : model (par défaut), tenant, project, agent, provider, usage_type ou day. |
**filters | Any | non | Paramètres de requête supplémentaires, comme la période from et to (ISO 8601). |
Retour : Any. Réponse JSON décodée de l'opération « Synthétiser la dépense ».
Erreurs levées : ValueError, les erreurs typées du transport (Erreurs).
FinopsClient.update_settings
update_settings(currency: str | None = None, monthly_budget: number | string | null = None, variance_threshold_pct: number | string | null = None, reservation_ttl_seconds: int | None = None) -> Any
Modifier les paramètres FinOps. Modifie les paramètres fournis du tenant ; les champs omis ou null gardent leur valeur. Audité (finops.settings.update). Demande finops ou tenant_admin, et un principal de tenant.
Route : /v1/finops/settings (PUT).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
currency | str | None | None | non | Devise ISO 4217 dans laquelle les coûts du tenant sont tenus. |
monthly_budget | number | string | null | None | non | Budget mensuel du tenant, au moins 0 : la dépense mesurée du mois lui est comparée et des alertes de budget se déclenchent aux seuils (50, 80 et 100 pour cent par défaut). Il ne refuse pas d'appel par lui-même ; utilisez pour cela des quotas stricts. |
variance_threshold_pct | number | string | null | None | non | Écart entre coût mesuré et coût facturé, en pour cent, au-delà duquel une alerte d'écart est levée (10 par défaut). |
reservation_ttl_seconds | int | None | None | non | Durée de vie par défaut d'une réservation de quota en secondes, supérieure à 0 (900 par défaut). |
Retour : Any. Réponse JSON décodée de l'opération « Modifier les paramètres FinOps ».
Erreurs levées : les erreurs typées du transport (Erreurs).
FinopsClient.usage
usage(**filters: Any) -> Any
Lister les événements d'usage. Événements d'usage du tenant avec leurs unités et leurs coûts estimés, mesurés et facturés, filtrés et paginés. Demande un rôle de lecteur et un principal de tenant.
Route : /v1/finops/usage (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
**filters | Any | non | Filtres de requête (project_id, agent_id, run_id, model_id, provider, usage_type, from, to...) et pagination (limit, cursor). |
Retour : Any. Réponse JSON décodée de l'opération « Lister les événements d'usage ».
Erreurs levées : les erreurs typées du transport (Erreurs).
Fonctions
money
money(amount: Decimal | str | int, currency: str = 'EUR') -> dict[str, str]
{amount, currency} avec un montant en chaîne décimale.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
amount | Decimal | str | int | oui | Montant sous forme de Decimal, de chaîne décimale ou d'entier ; converti sans arrondi flottant. | |
currency | str | 'EUR' | non | Code de devise ISO 4217 (EUR par défaut). |
Retour : dict[str, str]. Dict {amount, currency}, amount en chaîne décimale.
token_units
token_units(input_tokens: int, output_tokens: int, cached_input_tokens: int = 0, reasoning_tokens: int = 0) -> dict[str, int]
Unités de jetons selon la règle FinOps.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
input_tokens | int | oui | Total des jetons d'entrée indiqué par le fournisseur, jetons en cache compris. | |
output_tokens | int | oui | Total des jetons de sortie indiqué par le fournisseur, jetons de raisonnement compris. | |
cached_input_tokens | int | 0 | non | Jetons d'entrée en cache, déjà comptés dans input_tokens (0 par défaut) ; une valeur supérieure à input_tokens lève ValueError. |
reasoning_tokens | int | 0 | non | Jetons de raisonnement, déjà comptés dans output_tokens (0 par défaut) ; une valeur supérieure à output_tokens lève ValueError. |
Retour : dict[str, int]. Dict {input_tokens, output_tokens}, plus cached_input_tokens et reasoning_tokens s'ils ne sont pas nuls.
Erreurs levées : ValueError.
usage_event
usage_event(usage_type: str, provider: str, units: dict[str, Any], tenant_id: str, region: str = 'global', agent_id: str | None = None, session_id: str | None = None, task_id: str | None = None, run_id: str | None = None, model_id: str | None = None, source: str = 'runtime', pricing: dict[str, Any] | None = None, cost: dict[str, Any] | None = None, **extra: Any) -> dict[str, Any]
Construit un document Usage Event (le coût est calculé par le serveur s'il n'est pas fourni).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
usage_type | str | oui | Type de consommation, par exemple llm. | |
provider | str | oui | Fournisseur qui a servi la consommation, par exemple openai. | |
units | dict[str, Any] | oui | Unités consommées, pour les jetons le dict de token_units. | |
tenant_id | str | oui | Tenant auquel la consommation est imputée. | |
region | str | 'global' | non | Région de la consommation (global par défaut). |
agent_id | str | None | None | non | Agent consommateur, facultatif. |
session_id | str | None | None | non | Session à laquelle appartient la consommation, facultative. |
task_id | str | None | None | non | Tâche à laquelle appartient la consommation, facultative. |
run_id | str | None | None | non | Exécution à laquelle appartient la consommation ; la clé run_id n'est ajoutée que si elle est fournie. |
model_id | str | None | None | non | Modèle utilisé, facultatif. |
source | str | 'runtime' | non | Producteur de l'événement (runtime par défaut). |
pricing | dict[str, Any] | None | None | non | Référence de tarification ; par défaut {currency: EUR, pricing_version: server, effective_at: maintenant}. |
cost | dict[str, Any] | None | None | non | Coût {estimated, measured, billed} ; par défaut tout à None, le serveur le calcule. |
**extra | Any | non | Champs supplémentaires fusionnés dans le corps de la requête. |
Retour : dict[str, Any]. Dict Usage Event avec schema_version 1.0, un nouvel event_id (préfixe ue-) et occurred_at à l'heure UTC courante ; les arguments nommés supplémentaires y sont fusionnés.