토큰 사용량

LibreChat에서 토큰 사용량을 추적하고 제어하는 방법을 다룹니다. 컨텍스트와 비용을 확인하고, 트랜잭션을 구성하며, 사용자 잔액을 활성화하고, 계정에 크레딧을 추가하는 방법을 배울 수 있습니다.

소개

v0.6.0부터 LibreChat은 지원되는 endpoint에 대한 토큰 사용량을 정확하게 추적합니다. 모든 토큰 트랜잭션은 데이터베이스의 "Transactions" 컬렉션에 저장됩니다. 현재 릴리스에서는 활성화 시 대화 UI에서 실시간 컨텍스트 사용량과 비용을 확인할 수 있습니다.

현재 사용자 잔액 기능을 활성화하여 사용자 토큰 사용량을 제한할 수 있습니다. 환경 변수를 통해 토큰 크레딧 제한을 구성하는 대신, 이제 librechat.yaml 파일의 balance 섹션에서 이러한 옵션을 설정합니다. 비용 값은 기본적으로 숨겨져 있으며 interface.contextCost를 통해 활성화해야 합니다.

컨텍스트 사용량 및 비용 확인하기

LibreChat은 대화가 진행되는 동안 컨텍스트 게이지를 표시합니다. 이 게이지는 스트리밍 중 사용량 이벤트에 따라 업데이트되며 다음을 표시할 수 있습니다:

모델의 컨텍스트 윈도우 대비 현재 프롬프트/컨텍스트 사용량
빠른 토큰 및 비용 세부 정보를 위한 호버 요약
프롬프트, 완성, 캐시된 토큰 사용량, 브랜치 합계 및 대화 합계에 대한 클릭 가능한 상세 분석

사용량 분석은 메시지 및 대화와 함께 유지됩니다. 다시 열린 채팅은 활성 스트리밍 세션에만 의존하는 대신 브랜치 및 총 사용량/비용 세부 정보를 유지합니다.

요약 기능이 긴 대화를 압축할 때, LibreChat은 압축된 요약 기준점을 기록하며 컨텍스트 게이지를 위해 그 이후의 대화 턴만 계산합니다. 사용량 및 비용 합계에는 전체 브랜치 지출이 포함됩니다.

관리자는 librechat.yaml에서 이러한 표시를 제어할 수 있습니다:

interface:
  contextUsage: true
  contextCost: true
  currency:
    code: EUR
    rate: 0.92

contextUsage는 사용자가 컨텍스트 창과 토큰 사용량 측정기를 볼 수 있는지 여부를 제어합니다.
contextCost는 사용자가 사용량 세부 정보에서 비용 값을 볼 수 있는지 여부를 제어합니다. 기본값은 false입니다. 비용을 표시하려면 true로 설정하세요.
currency는 비용 표시가 활성화되었을 때 정적 승수를 사용하여 표시되는 USD 비용을 변환합니다. 거래는 여전히 LibreChat의 토큰 크레딧 회계를 사용하여 기록됩니다.

사용자 지정 endpoint 토큰 설정

사용자 지정 endpoint의 경우, endpoints.custom[].tokenConfig를 사용하여 모델별 컨텍스트 윈도우와 백만 토큰당 요금을 정의하십시오:

endpoints:
  custom:
    - name: 'Mistral'
      apiKey: '${MISTRAL_API_KEY}'
      baseURL: 'https://api.mistral.ai/v1'
      models:
        default: ['mistral-large-latest']
      tokenConfig:
        mistral-large-latest:
          prompt: 2
          completion: 6
          context: 128000

각 모델 항목에는 prompt, completion, context가 필수입니다. 캐시된 입력 사용량을 보고하는 공급자의 경우 cacheRead 및 cacheWrite를 추가할 수 있습니다. 여러 endpoint를 사용하는 에이전트의 경우, LibreChat은 사용량과 비용을 기록할 때 일치하는 endpoint/model 토큰 구성을 사용합니다.

엔드포인트 모델, 키, URL 또는 헤더가 요청 컨텍스트에 따라 달라질 수 있는 경우, 가져온 토큰 구성은 사용자 범위로 캐시되므로 격리된 사용자 지정 엔드포인트 가격 책정 및 컨텍스트 창이 분리된 상태로 유지됩니다.

트랜잭션 구성

트랜잭션 시스템은 토큰 사용 기록을 데이터베이스에 저장할지 여부를 제어합니다. 이는 잔액 시스템과는 별도로 구성할 수 있습니다.

트랜잭션 설정

version: 1.2.9

# Transaction settings
# Controls whether to save transaction records to the database
# Default is true (enabled)
transactions:
  enabled: false

중요: balance.enabled가 true로 설정되면 transactions.enabled 설정과 관계없이 트랜잭션 기록이 자동으로 활성화됩니다. 이는 모든 토큰 사용량에 대한 완전한 기록을 유지하여 잔액 추적 기능이 올바르게 작동하도록 보장합니다.

자세한 내용은 Transactions Configuration 페이지를 확인하세요.

잔액 설정

LibreChat의 잔액 시스템을 통해 관리자는 사용자의 토큰 크레딧 잔액이 관리되는 방식을 구성할 수 있습니다. 이제 모든 잔액 설정은 YAML 구성의 balance 객체 아래에서 관리됩니다.

참고: 이는 이전 환경 변수(CHECK_BALANCE 및 START_BALANCE)를 대체하며, 사용자 잔액을 관리하는 보다 구조화된 방법을 제공합니다.

전체 잔액 설정

version: 1.3.5

# Balance settings
balance:
  enabled: true # Enable token credit balances for users
  startBalance: 20000 # Initial tokens credited upon registration
  autoRefillEnabled: false # Enable automatic token refills
  refillIntervalValue: 30 # Numerical value for refill interval
  refillIntervalUnit: 'days' # Time unit for refill interval (days, hours, etc.)
  refillAmount: 10000 # Tokens added during each refill

Balance Settings 설명

enabled: 사용자별 토큰 크레딧 추적 및 잔액 관리를 활성화합니다. true로 설정하면 시스템이 토큰 사용량을 추적하고 잔액 제한을 적용합니다.
startBalance: 사용자가 등록할 때 지급되는 초기 토큰 수를 지정합니다. 이는 모든 신규 사용자의 시작 잔액입니다.
autoRefillEnabled: 토큰 크레딧의 자동 충전 활성화 여부를 결정합니다. true로 설정하면, 시스템이 충전 주기에 따라 사용자 잔액에 크레딧을 자동으로 추가합니다.
refillIntervalValue: 토큰 크레딧이 자동으로 충전되는 간격의 수치 값을 지정합니다. refillIntervalUnit과 함께 작동합니다.
refillIntervalUnit: 리필 간격에 대한 시간 단위를 지정합니다. 지원되는 값은 "seconds", "minutes", "hours", "days", "weeks", "months"입니다.
refillAmount: 자동 충전이 발생할 때마다 사용자의 잔액에 추가될 토큰 수를 지정합니다.

자세한 내용은 Balance Configuration 페이지를 확인하세요.

Auto-Refill 작동 방식

사용자의 잔액이 추적되고 autoRefill이 활성화된 경우, 시스템은 마지막 충전 이후 지정된 시간 간격이 경과했을 때만 자동으로 잔액을 충전합니다. 이는 현재 날짜와 lastRefill 날짜에 지정된 간격을 더한 값을 비교하여 수행됩니다.

자동 충전 프로세스

사용자가 토큰을 사용하려고 시도하면, 시스템은 현재 잔액이 충분한지 확인합니다.
트랜잭션 후 잔액이 0 이하로 떨어질 경우, 시스템은 자동 충전이 활성화되어 있는지 확인합니다.
auto-refill이 활성화된 경우, 시스템은 마지막 refill 이후 설정된 시간 간격이 지났는지 확인합니다:
- 시스템은 현재 날짜를 lastRefill + refillInterval과 비교합니다.
- 간격이 지나면 토큰이 사용자 잔액에 추가됩니다.
- lastRefill 날짜가 현재 날짜로 업데이트됩니다.
잔액이 충분하면(원래 잔액이거나 충전 후 잔액) 거래가 진행됩니다.

지원되는 시간 단위

refillIntervalUnit은 다음 값 중 하나로 설정할 수 있습니다:

초
분
시간
일
주
개월

예를 들어, refillIntervalValue가 30으로 설정되고 refillIntervalUnit이 days인 경우, 시스템은 마지막 충전 이후 30일이 경과했을 때만 사용자의 잔액에 refillAmount만큼의 토큰을 추가합니다.

잔액 동기화

사용자가 로그인하면 시스템은 해당 사용자의 잔액 설정을 현재의 전역 잔액 구성과 자동으로 동기화합니다. 이를 통해 잔액 구성에 대한 모든 변경 사항이 모든 사용자에게 적용되도록 보장합니다.

동기화 프로세스:

사용자에게 잔액 기록이 있는지 확인합니다
레코드가 존재하지 않으면, 현재 startBalance로 레코드를 생성합니다.
사용자의 자동 충전 설정을 전역 구성과 일치하도록 업데이트합니다
사용자의 리필 간격 및 수량이 전역 설정과 일치하도록 보장합니다.

토큰 잔액 관리

사용자 잔액을 수동으로 추가하거나 설정할 수 있습니다. 이는 개발 중이거나 향후 (예: 관리자 대시보드를 통해) 전체 잔액 누적 시스템을 구축하려는 경우 특히 유용합니다.

잔액 추가하기

# Local Development
npm run add-balance

# Docker (default setup)
docker compose exec api npm run add-balance

# Docker (deployment setup)
docker exec -it LibreChat-API /bin/sh -c "cd .. && npm run add-balance"

# Local Development
npm run add-balance [email protected] 1000

# Docker (default setup)
docker compose exec api npm run add-balance [email protected] 1000

# Docker (deployment setup)
docker exec -it LibreChat-API /bin/sh -c "cd .. && npm run add-balance [email protected] 1000"

잔액 설정

또한, 사용자의 잔액을 설정할 수 있습니다. 기존 잔액은 새로운 잔액으로 덮어쓰기 됩니다.

# Local Development
npm run set-balance

# Docker (default setup)
docker compose exec api npm run set-balance

# Docker (deployment setup)
docker exec -it LibreChat-API /bin/sh -c "cd .. && npm run set-balance"

# Local Development
npm run set-balance [email protected] 1000

# Docker (default setup)
docker compose exec api npm run set-balance [email protected] 1000

# Docker (deployment setup)
docker exec -it LibreChat-API /bin/sh -c "cd .. && npm run set-balance [email protected] 1000"

잔액 목록

# Local Development
npm run list-balances

# Docker (default setup)
docker compose exec api npm run list-balances

# Docker (deployment setup)
docker exec -it LibreChat-API /bin/sh -c "cd .. && npm run list-balances"

이는 개인적인 용도로 자신의 사용량을 추적하는 데 효과적입니다. 1000 크레딧 = $0.001 (0.001 달러)

토큰 사용량 및 잔액 관련 참고 사항

요약 기능이 활성화된 경우, 요약해야 할 콘텐츠와 메시지 페이로드를 합친 비용이 현재 잔액을 초과하면 API 요청이 차단됩니다.
Subagent child-run model usage is recorded against the parent transaction so parent agent runs include delegated usage in their totals.

Subagent child-run 모델 사용량은 부모 트랜잭션에 기록되므로, 부모 에이전트 실행 시 위임된 사용량이 총계에 포함됩니다.

프롬프트 토큰 계산은 OpenAI 호출에 대해서는 매우 정확하지만, 플러그인의 경우(함수 호출로 인해) 100% 정확하지는 않습니다. 매우 근사하고 보수적인 수치이므로, 실제 계산값이 2-5 토큰 정도 더 높을 수 있습니다.
이 시스템은 완료 토큰으로 인해 발생하는 부족분을 허용합니다. 프롬프트 토큰에 대해서만 충분한 잔액이 있는지 확인하며, 완료 토큰에 대해서는 상당히 관대하게 처리합니다. 아래 그래프는 해당 로직을 자세히 설명합니다.
위에서 언급했듯이, 플러그인은 여러 API 호출을 통해 프로세스가 작동하므로 각 생성 단계에서 확인됩니다. 초기 사용자 프롬프트 이후 LLM이 생성한 모든 내용은 아래와 같이 오류 메시지를 통해 사용자에게 공유됩니다.
제목 생성은 2단계 과정이므로 150 토큰의 버퍼가 있으며, 이는 평균적으로 총 200 토큰 정도를 차지합니다. 잔액이 부족한 경우, 비용이 발생하기 전에 제목 생성이 취소되며 오류는 발생하지 않습니다.

추가 세부 정보

출처: LibreChat/discussions/1640

"rawAmount": -000, // 이건 무엇인가요?

토크나이저 알고리즘에 따라 계산된 토큰의 원시 수량입니다.

"tokenValue": -00000, // 이게 무엇인가요?

토큰 크레딧 값. 1000 크레딧 = $0.001 (0.001 USD)

"rate": 00, // 이게 무엇인가요?

토큰이 크레딧으로 차감되는 비율입니다.

예를 들어, gpt-3.5-turbo-1106은 사용자 프롬프트(입력)에 대해 1, 완료(출력)에 대해 2의 비율을 가집니다.

모델	입력	출력
gpt-3.5-turbo-1106	$0.0010 / 1K 토큰	$0.0020 / 1K 토큰

제공된 예시를 바탕으로:

    "rawAmount": -137
    "tokenValue": -205.5
    "rate": 1.5

\text{Token Value} = (\text{Raw Amount of Tokens}) \times (\text{Rate})

137 \times 1.5 = 205.5

그리고 Token Value를 기반으로 실제 USD 지출 금액을 확인하려면 다음과 같습니다:

\frac{\text{Token Value}}{1,000,000} = \left(\frac{\text{Raw Amount of Tokens} \times \text{Rate}}{1,000,000}\right)

\frac{205.5}{1,000,000} = \$0.0002055 \text{ USD}

사용자 지정 endpoint의 경우, 모델별 요금 및 컨텍스트 윈도우 설정을 위해 librechat.yaml 내의 endpoints.custom[].tokenConfig를 사용하는 것을 권장합니다.

미리보기

추가 참고 사항

요약 기능이 활성화된 경우, 콘텐츠와 메시지 페이로드를 합친 비용이 현재 잔액을 초과하면 API 요청이 차단됩니다.
이 시스템은 완료 토큰에 대해 관대하며, 잔액 확인을 위해 주로 프롬프트 토큰에 중점을 둡니다.
2단계 프로세스를 고려하여 제목 지정(titling)을 위한 버퍼(약 150 토큰)가 추가됩니다.
토큰 크레딧은 금전적 가치로 환산됩니다 (예: 1000 크레딧 = $0.001 USD).

더 자세한 내용과 사용자 정의 설정은 LibreChat Documentation을 참조하세요.