Skip to main content

Métriques d’utilisation et de facturation

Ce guide montre comment lire le nombre de jetons, l’utilisation de la fenêtre de contexte, le coût en crédits IA et le quota du compte dans une application utilisant SDK Copilot. Des exemples sont présentés pour TypeScript, Python, Go, .NET, Java et Rust.

Conseil

Chaque exemple est fonctionnellement équivalent entre les langages. L’extrait TypeScript est déplié par défaut : sélectionnez votre langue dans les sections repliables pour voir la même logique dans le SDK correspondant.

Vue d’ensemble

Le SDK expose les données d’utilisation par le biais de deux mécanismes complémentaires :

  • Événements de session : événements éphémères émis par l’environnement d’exécution au cours de l’exécution d’un tour. Abonnez-vous à ceux-ci pour obtenir des données en temps réel pour chaque appel d’API.
  • Méthodes RPC : appels de requête/réponse que vous effectuez à la demande. Utilisez-les pour obtenir un instantané des totaux cumulés ou consulter le quota du compte.

Le tableau ci-dessous mappe chaque signal à l’API qui l’expose.

SignalAPIScopeType
Nombre de jetons par appel
événement assistant.usageSessionÉvénement
Utilisation de la fenêtre contextuelle
événement session.usage_infoSessionÉvénement
Répartition des fenêtres contextuelles (à la demande)session.metadata.contextInfoSessionRPC
Totaux cumulés des crédits d’IA et des jetonssession.usage.getMetricsSessionRPC
Tarification des crédits IA par modèlemodels.listServeurRPC
Interactions entre le quota du compte et la version premiumaccount.getQuotaServeurRPC

Remarque

session.usage.getMetrics, session.metadata.contextInfoet session.metadata.recomputeContextTokens sont marqués expérimentaux dans la surface RPC générée. Dans .NET, ils émettent le diagnostic expérimental GHCP001, que vous supprimez avec #pragma warning disable GHCP001 ou avec <NoWarn>GHCP001</NoWarn> au niveau du projet. Épinglez le Kit de développement logiciel (SDK) et le runtime cli Copilot si votre application en dépend.

Les tableaux de champs ci-dessous répertorient uniquement les champs utilisés dans les exemples de cette page. La référence des champs complète et toujours à jour se compose des types du SDK générés ainsi que de Événements de session de streaming, qui est régénéré à partir du schéma CLI à chaque mise à jour des dépendances. Considérez-les comme la référence et cette page comme un guide pratique.

Nombre de jetons par appel

L’événement assistant.usage est émis une fois pour chaque appel d’API de modèle à son tour (y compris les appels effectués par les sous-agents). Il indique le nombre de tokens et le multiplicateur de facturation pour cet appel uniquement.

L’exemple ci-dessous utilise ces champs. Consultez Événements de session de streaming pour obtenir la liste complète, notamment le cache, le raisonnement, la latence et les champs de suivi.

ChampTypeDescription
modelstringIdentificateur de modèle pour cet appel
inputTokensnumberJetons d’entrée consommés
outputTokensnumberJetons de sortie produits
costnumberMultiplicateur de demande Premium appliqué à cet appel

Conseil

assistant.usage est éphémère ; il est donc diffusé en direct, mais n’est pas rejoué lorsque vous reprenez une session. Pour lire les totaux cumulés a posteriori, appelez session.usage.getMetrics (voir Crédits IA et totaux de jetons cumulés).

Langages de code navigation

TypeScript
session.on("assistant.usage", (event) => {
    const { model, inputTokens, outputTokens, cost } = event.data;
    console.log(
        `${model}: in=${inputTokens ?? 0} out=${outputTokens ?? 0} cost=${cost ?? 0}`,
    );
});

Utilisation de la fenêtre contextuelle

Les nombres de jetons vous indiquent ce que chaque appel a consommé. L’utilisation de la fenêtre de contexte vous indique à quel point la fenêtre de contexte du modèle est remplie actuellement, ce qui est utile pour afficher une barre de progression ou avertir l’utilisateur avant que le compactage automatique ne se déclenche.

Mises à jour en direct avec session.usage_info

Le runtime émet un session.usage_info événement chaque fois que la taille de la fenêtre de contexte change. L’exemple utilise currentTokens et tokenLimit; consultez Événements de session de streaming pour la charge utile complète.

ChampTypeDescription
currentTokensnumberTokens actuellement dans la fenêtre de contexte
tokenLimitnumberNombre maximal de jetons pour la fenêtre de contexte du modèle

Langages de code navigation

TypeScript
session.on("session.usage_info", (event) => {
    const { currentTokens, tokenLimit } = event.data;
    const pct = Math.round((currentTokens / tokenLimit) * 100);
    console.log(`Context: ${currentTokens}/${tokenLimit} (${pct}%)`);
});

Décomposition à la demande avec session.metadata.contextInfo

Les événements se déclenchent uniquement lorsque le contexte change. Pour lire la répartition actuelle à tout moment, par exemple, juste après avoir repris une session, appelez session.metadata.contextInfo. Passez 0 pour promptTokenLimit afin d’utiliser la valeur par défaut de l’environnement d’exécution ; passez 0 pour outputTokenLimit si la valeur est inconnue.

Le null du résultat est contextInfo jusqu’à ce que la session ait été initialisée (l’invite système et les métadonnées de l’outil ont été mises en cache). Il décompose le total en systemTokens, conversationTokenset toolDefinitionsTokens, en même temps que le promptTokenLimit.

Langages de code navigation

TypeScript
const { contextInfo } = await session.rpc.metadata.contextInfo({
    promptTokenLimit: 0,
    outputTokenLimit: 0,
});

if (contextInfo) {
    console.log(
        `Total ${contextInfo.totalTokens}/${contextInfo.promptTokenLimit} ` +
            `(system=${contextInfo.systemTokens}, conversation=${contextInfo.conversationTokens})`,
    );
}

Totaux cumulés des crédits d’IA et des jetons

session.usage.getMetrics retourne les totaux cumulés de toute la session en un seul appel. C’est la façon la plus claire de consulter le coût en crédits IA, car elle agrège tous les appels à l’API (agent principal et sous-agents) pour vous.

L’exemple utilise les champs ci-dessous. Le type généré UsageGetMetricsResult est la référence complète.

ChampTypeDescription
totalNanoAiunumberCoût en crédits IA sur l’ensemble de la session, en nano-unités d’IA
totalPremiumRequestCostnumberCoût de la demande Premium sur tous les modèles, après les multiplicateurs
modelMetricsRecord<string, ModelMetric>Répartition par modèle ; chaque entrée a usage.inputTokens, usage.outputTokenset totalNanoAiu

Remarque

Le coût est signalé dans les unités nano-IA (le champ est nommé totalNanoAiu). La conversion exacte en crédits d’IA et la signification exacte du décompte des requêtes premium sont définies par la facturation de GitHub Copilot, et non par le SDK ; considérez la documentation de facturation de GitHub Copilot comme la référence faisant foi et vérifiez-la avant d’afficher aux utilisateurs des valeurs assimilables à des montants. Les exemples divisent les valeurs par 1e9 par souci de simplicité, conformément au préfixe SI nano ; vérifiez que cela correspond à la facturation actuelle avant de vous y fier. Les mappages modelMetrics et tokenDetails ont pour clés des chaînes définies à l’exécution (identifiants de modèle et noms de types de jeton) que le système de types SDK ne valide pas.

Langages de code navigation

TypeScript
const metrics = await session.rpc.usage.getMetrics();

const aiCredits = (metrics.totalNanoAiu ?? 0) / 1e9;
console.log(`AI credits used: ${aiCredits.toFixed(6)}`);
console.log(`Premium requests: ${metrics.totalPremiumRequestCost}`);

for (const [model, m] of Object.entries(metrics.modelMetrics)) {
    if (!m) continue;
    console.log(
        `${model}: in=${m.usage.inputTokens} out=${m.usage.outputTokens} ` +
            `nanoAiu=${m.totalNanoAiu ?? 0}`,
    );
}

Tarification des crédits IA par modèle

Pour estimer le coût avant d’effectuer un tour, consultez le prix des jetons de chaque modèle dans models.list. Il s’agit d’un appel de portée serveur côté client, il ne nécessite donc pas de session. Les prix sont exprimés en crédits IA par lot de jetons facturé. Le type généré ModelBillingTokenPrices répertorie chaque champ, y compris cachePrice.

ChampTypeDescription
billing.multipliernumberMultiplicateur de coût de la demande Premium par rapport au taux de base
billing.tokenPrices.inputPricenumberCoût de crédit IA par lot de jetons d’entrée
billing.tokenPrices.outputPricenumberCoût en crédits d’IA par lot de jetons de sortie
billing.tokenPrices.batchSizenumberNombre de jetons par lot de facturation

Remarque

Les valeurs de prix changent à mesure que les plans et les modèles évoluent. Lisez-les au moment de l’exécution, comme indiqué ci-dessous ; ne codez jamais en dur les nombres dans votre application.

Langages de code navigation

TypeScript
const { models } = await client.rpc.models.list({});

for (const model of models) {
    const prices = model.billing?.tokenPrices;
    if (!prices) continue;
    console.log(
        `${model.id}: input=${prices.inputPrice} output=${prices.outputPrice} ` +
            `per ${prices.batchSize} tokens (x${model.billing?.multiplier ?? 1})`,
    );
}

Interactions entre le quota du compte et la version premium

account.getQuota indique le quota Copilot restant de l’utilisateur authentifié. La table quotaSnapshots du résultat est indexée par type de quota, généralement premium_interactions, chat et completions. Utilisez-le pour montrer aux utilisateurs la quantité de leur allocation mensuelle restante ou pour effectuer un travail avant d’atteindre une limite.

L’exemple utilise les champs ci-dessous ; le type généré AccountQuotaSnapshot est la référence complète. Les quotaSnapshots clés sont des chaînes d’exécution que le système de type du Kit de développement logiciel (SDK) ne valide pas. Par conséquent, protégez vos recherches.

ChampTypeDescription
entitlementRequestsnumberDemandes incluses dans le forfait, ou -1 pour un nombre illimité
usedRequestsnumberRequêtes utilisées jusqu’à présent pendant cette période
remainingPercentagenumberPourcentage du droit restant
resetDatestringDate de réinitialisation du quota ISO 8601

Conseil

Pour lire le quota pour un utilisateur spécifique plutôt que le contexte d'authentification global de la connexion (par exemple, dans un serveur principal multilocataire), transmettez le jeton GitHub de cet utilisateur à getQuota. Consultez « Multilocataire et déploiements de serveurs ».

Langages de code navigation

TypeScript
const { quotaSnapshots } = await client.rpc.account.getQuota({});
const premium = quotaSnapshots["premium_interactions"];

if (premium) {
    console.log(
        `Premium interactions: ${premium.usedRequests}/${premium.entitlementRequests} ` +
            `(${premium.remainingPercentage.toFixed(1)}% left, resets ${premium.resetDate ?? "n/a"})`,
    );
}

Choix de l’API appropriée

Utilisez ce résumé pour déterminer l’API qui correspond à votre cas d’usage :

  •           **Afficher un coût en temps réel ou un compteur de jetons pendant l’exécution d’un tour** : abonnez-vous à `assistant.usage` et `session.usage_info`.
    
  • Afficher un résumé des coûts finals après un tour ou une session : appel session.usage.getMetrics.
  • Afficher l’utilisation de la fenêtre contextuelle lors de la reprise, avant tout nouveau tour : appel session.metadata.contextInfo.
  • Estimer le coût avant l’exécution du travail : lire models.list les prix des jetons.
  • Avertir les utilisateurs avant qu’ils n’épuisent leur plan : appel account.getQuota.

Lectures complémentaires