Skip to main content
Skip to content

사용량 및 청구 메트릭

이 가이드에서는 Copilot SDK 애플리케이션에서 토큰 수, 컨텍스트 창 사용률, AI 크레딧 비용 및 계정 할당량을 읽는 방법을 보여 줍니다. TypeScript, Python, Go, .NET, Java 및 Rust에 대한 예제가 표시됩니다.

팁

각 예제는 여러 언어에서 기능적으로 동일합니다. TypeScript 코드 조각은 기본적으로 확장됩니다. 축소 가능한 블록에서 언어를 선택하여 해당 SDK에서 동일한 논리를 확인합니다.

Overview

SDK는 두 가지 보완 메커니즘을 통해 사용량 현황 데이터를 표시합니다.

  • 세션 이벤트: 런타임이 턴이 실행될 때 내보내는 임시 이벤트입니다. 실시간 API 호출별 데이터에 대해 이러한 데이터를 구독합니다.
  • RPC 메서드: 요청 시 수행된 요청/응답 호출입니다. 누적 합계를 스냅샷하거나 계정 수준 할당량을 조회하는 데 사용합니다.

아래 표는 각 신호를 노출하는 API에 매핑합니다.

신호APIScopeType
호출별 토큰 수
assistant.usage 이벤트세션Event
컨텍스트 창 사용률
session.usage_info 이벤트세션Event
컨텍스트 윈도우 세부 내역(요청 시)session.metadata.contextInfo세션RPC
누적 AI 크레딧 및 토큰 합계session.usage.getMetrics세션RPC
모델별 AI 크레딧 가격 책정models.list서버RPC
계정 할당량 및 프리미엄 상호 작용account.getQuota서버RPC
세션 소유 공급자 할당량 관찰값
session.quota.get 및 session.quota.refresh세션RPC
공급자 승인 상태 업데이트session.quota_observation세션Event

session.quota.get 는 로컬 런타임 상태를 읽습니다. session.quota.refresh 는 공급자 카탈로그 및 할당량 원본을 새로 고칩니다. 둘 다 공급자 ID, 할당량 ID 및 관찰 종류를 기준으로 키가 지정된 providerQuotas를 반환합니다. 런타임은 하나의 관찰 저장소를 유지합니다. 레거시 snapshots 필드는 두 번째 할당량 상태 원본이 아닌 신뢰할 수 있는 예산의 파생된 호환성 보기입니다.

공급자 카디널리티는 심에 제공되는 실제 사용 및 관찰의 창발적 속성입니다. 이 API는 사용자가 사용할 수 있는 공급자 수를 모르거나 강제하지 않습니다. 이 API는 0개, 1개 또는 많은 항목을 동일하게 기록하고 투영합니다. 생산자는 안정적인 공급자/계정 범위 참조를 제공합니다. 사용량은 모델 ID를 추가하고 할당량은 할당량 ID 및 관찰 종류를 추가합니다. get() 는 호출자가 공급자별 메서드 없이 정확한 키, 하위 집합 또는 모든 항목을 선택할 수 있도록 알려진 전체 컬렉션을 반환합니다. 취득은 업스트림 계정/모델 계층에서 제공하는 소스를 사용합니다. 합집합을 만들거나 선택한 공급자 필터를 읽기에 적용하지 않습니다.

측정값을 해석하기 전에 quantityKind, acquisitionStatus 및 observationKind를 확인합니다. authoritative_budget는 진행 상황과 재설정 메타데이터를 제공할 수 있습니다. advisory_balance 보고서는 백분율, 초기화 기간 또는 통화 후 잔액을 약속하지 않고 부호 있는 64비트 수량을 독립적으로 보고합니다. admission_state는 요청 허용 시 사용 권한/용량을 보고하고 수량을 전달하지 않습니다. 계정 잔액을 대체하지는 않습니다. 0으로 변환하지 않고 누락된 값과 명시적 null을 유지합니다. 실패했거나 사용할 수 없는 획득은 할당량 소진이 아닙니다.

Microsoft 365 Copilot의 경우 액세스 및 용량은 서비스 판정이며, 수량은 권고 사항입니다. 예를 들어 allowed/available 두 수량이 모두 명시적으로 0이면 0 / 0 AIC reported를 의미하며, 100% 사용됨 또는 일관되지 않은 상태가 아닙니다. 누락된 사용 권한은 값이 0인 사용 권한과 다릅니다. -1 자격 센티널은 보고된 용량 상태를 변경하지 않고 무제한 자격을 의미합니다. 추론 헤더는 캐시된 승인 상태를 반영할 수 있습니다. 이러한 헤더나 주문형 할당량 새로 고침은 이전 호출에 대한 과금 여부를 결정하지 않습니다.

사용량 합계는 활성 계정이 아닌 세션에 속합니다. CLI에서 비어 있지 않은 Microsoft 365 Copilot 세션에서 벗어나려면 새 세션을 시작해야 합니다. 이전 세션은 재개를 위해 사용량 및 기록을 유지합니다. 새 세션은 자체 집계를 시작합니다.

참고

session.quota, session.usage.getMetrics, session.metadata.contextInfo, 및 session.metadata.recomputeContextTokens는 생성된 RPC 표면에서 실험적으로 표시됩니다. .NET에서는 GHCP001 실험적 진단을 발생시키며, 이는 #pragma warning disable GHCP001 또는 프로젝트 수준의 <NoWarn>GHCP001</NoWarn>로 억제합니다. 애플리케이션이 의존하는 경우 SDK와 Copilot CLI 런타임을 모두 고정합니다.

아래 필드 테이블은 이 페이지의 예제에 사용된 필드만 나열합니다. 항상 최신의 전체 필드 참조는 생성된 SDK 형식과 스트리밍 세션 이벤트이며 모든 종속성 범프에 대한 CLI 스키마에서 다시 생성됩니다. 이를 진리의 근원으로 취급하고 이 페이지를 작업 지향 가이드로 취급합니다.

호출별 토큰 수

assistant.usage 이벤트는 한 턴에서 각 모델 API 호출마다 한 번씩 발생합니다(하위 에이전트가 수행한 호출 포함). 해당 호출 1회분의 토큰 수와 요금 배수를 포함합니다.

아래 예제에서는 이러한 필드를 사용합니다. 캐시, 추론, 대기 시간 및 추적 필드를 비롯한 전체 목록은 스트리밍 세션 이벤트 을 참조하세요.

FieldTypeDescription
modelstring이 호출의 모델 식별자
inputTokensnumber사용된 입력 토큰
outputTokensnumber생성된 출력 토큰
costnumber이 호출에 적용되는 프리미엄 요청 배수

팁

assistant.usage 가 임시이므로 라이브로 배달되지만 세션을 다시 시작할 때 재생되지 않습니다. 사후에 누적 총계를 확인하려면 session.usage.getMetrics를 호출하세요(자세한 내용은 누적 AI 크레딧 및 토큰 총계 참조).

코드 언어 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}`,
    );
});

컨텍스트 창 사용률

토큰 개수는 각 호출이 사용된 내용을 알려줍니다. 컨텍스트 창 사용률은 자동 압축이 시작되기 전에 진행률 표시줄을 표시하거나 사용자에게 경고하는 데 유용한 모델의 프롬프트 창이 현재 얼마나 가득 찼는지를 알려줍니다.

실시간 업데이트 제공 session.usage_info

런타임은 컨텍스트 창 크기가 session.usage_info 변경 될 때마다 이벤트를 내보낸다. 예제에서는 currentTokens 및 tokenLimit을 사용합니다. 전체 페이로드는 스트리밍 세션 이벤트에서 확인하세요.

FieldTypeDescription
currentTokensnumber현재 컨텍스트 창에 있는 토큰
tokenLimitnumber모델의 컨텍스트 창에 대한 최대 토큰

코드 언어 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}%)`);
});

주문형 분석 session.metadata.contextInfo

이벤트는 컨텍스트가 변경되는 경우에만 발생합니다. 언제든지 현재 내역을 읽으려면(예: 세션을 재개한 직후) session.metadata.contextInfo를 호출하세요. 0 런타임 기본값을 사용하도록 전달 promptTokenLimit 합니다. 값을 알 수 없는 경우 전달 0``outputTokenLimit 합니다.

결과는 contextInfo``null 세션이 초기화될 때까지입니다(시스템 프롬프트 및 도구 메타데이터가 캐시됨). 합계를 , , 및 로 나눕니다.

코드 언어 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})`,
    );
}

누적 AI 크레딧 및 토큰 합계

session.usage.getMetrics 는 단일 호출에서 전체 세션의 실행 합계를 반환합니다. 이는 모든 API 호출(주 에이전트 및 하위 에이전트)을 집계하기 때문에 AI 크레딧 비용을 읽는 가장 깨끗한 방법입니다.

이 예제에서는 아래 필드를 사용합니다. 생성된 UsageGetMetricsResult 형식이 전체 참조입니다.

FieldTypeDescription
totalNanoAiunumber세션 차원의 AI 크레딧 비용(nano-AI 단위)
totalPremiumRequestCostnumber승수 적용 후 전체 모델에 걸친 프리미엄 요청 비용
modelMetricsRecord<string, ModelMetric>모델별 분석; 각 항목에는 usage.inputTokens, usage.outputTokens및 totalNanoAiu

참고

비용은 nano-AI 단위 로 보고됩니다(필드 이름은 totalNanoAiu지정됨). AI 크레딧으로의 정확한 변환과 프리미엄 요청 계정의 정확한 의미는 SDK가 아닌 GitHub Copilot 청구에 의해 정의됩니다. GitHub Copilot 청구 설명서를 진실의 근원으로 취급하고 사용자에게 통화와 유사한 값을 표시하기 전에 확인합니다. 예제는 SI 1e9 접두사에 따라 편의를 위해 나눕니다nano. 이 예제가 현재 청구와 일치하는지 확인한 후 이를 사용합니다. modelMetrics 및 tokenDetails 맵의 키는 SDK 형식 시스템이 유효성을 검사하지 않는 런타임 문자열(모델 ID 및 토큰 유형 이름)입니다.

코드 언어 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}`,
    );
}

모델별 AI 크레딧 가격 책정

턴을 실행하기 전에 비용을 예측하려면 각 모델의 토큰 가격을 읽어보 models.list십시오. 클라이언트에서 서버 범위 호출이므로 세션이 필요하지 않습니다. 가격은 토큰의 청구 일괄 처리당 AI 크레딧으로 표현됩니다. 생성된 ModelBillingTokenPrices 형식은 cachePrice를 포함한 모든 필드를 나열합니다.

FieldTypeDescription
billing.multipliernumber기본 요금 대비 프리미엄 요청 비용 배수
billing.tokenPrices.inputPricenumber입력 토큰 일괄 처리당 AI 크레딧 비용
billing.tokenPrices.outputPricenumber출력 토큰 일괄 처리당 AI 크레딧 비용
billing.tokenPrices.batchSizenumber청구 일괄 처리당 토큰 수

참고

요금제와 모델이 발전함에 따라 가격 값이 변경됩니다. 아래와 같이 런타임에 값을 읽어 오고, 해당 숫자를 애플리케이션에 절대 하드코딩하지 마십시오.

코드 언어 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})`,
    );
}

계정 할당량 및 프리미엄 상호 작용

account.getQuota인증된 사용자의 남은 Copilot 권한을 보고합니다. 결과의 quotaSnapshots 맵은 할당량 유형을 키로 사용하며, 일반적으로 premium_interactions, chat, completions입니다. 이를 사용하여 사용자에게 월별 수당이 얼마나 남아 있는지 표시하거나 제한에 도달하기 전에 작업을 게이트하는 데 사용합니다.

이 예제에서는 아래 필드를 사용합니다. 생성된 AccountQuotaSnapshot 형식이 전체 참조입니다. quotaSnapshots 키는 SDK 타입 시스템에서 유효성을 검사하지 않는 런타임 문자열이므로 조회 시 검사를 수행하세요.

FieldTypeDescription
entitlementRequestsnumber자격에 포함된 요청 또는 -1 무제한 요청
usedRequestsnumber이 기간 동안 사용된 요청
remainingPercentagenumber남은 자격의 백분율
resetDatestring할당량이 다시 설정되는 ISO 8601 날짜

팁

연결의 전역 인증 컨텍스트(예: 다중 테넌트 백 엔드)가 아닌 특정 사용자에 대한 할당량을 읽으려면 해당 사용자의 GitHub 토큰을 전달합니다getQuota. 다중 테넌트 및 서버 배포을(를) 참조하세요.

코드 언어 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"})`,
    );
}

올바른 API 선택

이 요약을 사용하여 사용 사례에 맞는 API를 결정합니다.

  • 턴이 진행되는 동안 실시간 비용 또는 토큰 미터를 표시하려면: assistant.usage 및 session.usage_info를 구독하세요.
  • 턴 또는 세션 후 최종 비용 요약 표시: 호출 session.usage.getMetrics.
  • 재개 시, 새 턴이 시작되기 전에 컨텍스트 윈도우 사용량을 표시: session.metadata.contextInfo 호출.
  • 작업을 실행하기 전에 비용을 추정하세요: models.list 토큰 가격을 확인하세요.
  • 사용자의 요금제가 소진되기 전에 경고: account.getQuota 호출.

추가 읽기