콘텐츠로 이동

9.7. CLI 참조

bgo CLI 도구는 Backend.AI GO 관리 API에 대한 커맨드라인 접근을 제공합니다. 이 도구를 사용하여 터미널에서 로컬 모델을 관리하고, 추론 서버를 제어하며, 시스템 리소스를 모니터링하고, 로드된 모델과 상호 작용할 수 있습니다.

설치

CLI는 Backend.AI GO 배포판에 포함되어 있습니다. 소스에서 빌드하는 경우 다음 명령을 사용합니다:

cd cli
cargo install --path .

사용법

bgo [OPTIONS] <COMMAND>

자동 발견 (Auto-Discovery)

--endpoint를 지정하지 않으면, CLI는 관리 API 서버가 시작 시 기록한 발견 파일을 읽어 실행 중인 Backend.AI GO 인스턴스를 자동으로 발견합니다. 로컬에서 실행 중인 인스턴스에 연결하는 일반적인 경우 별도의 설정이 필요하지 않습니다.

엔드포인트 결정 우선순위:

  1. --endpoint 플래그 또는 BACKEND_AI_GO_ENDPOINT 환경 변수 (명시적 재정의)
  2. 구성 파일 엔드포인트 (bgo config set endpoint ...로 기본값을 변경한 경우)
  3. 자동 발견 파일 (로컬 인스턴스가 실행 중이고 정상인 경우)
  4. 기본 폴백: http://127.0.0.1:8001

OS별 발견 파일 위치:

  • macOS: ~/Library/Application Support/ai.backend.go/mgmt-api.json
  • Linux: $XDG_RUNTIME_DIR/ai.backend.go/mgmt-api.json (폴백: ~/.config/ai.backend.go/mgmt-api.json)
  • Windows: %APPDATA%\ai.backend.go\mgmt-api.json

연결하기 전에 CLI는 서버 프로세스(PID로 식별)가 여전히 실행 중인지 확인하고 엔드포인트가 상태 확인에 응답하는지 검증하여 발견 파일을 유효성 검사합니다. 충돌한 인스턴스로부터 남겨진 오래된 파일은 자동으로 무시됩니다.

전역 옵션 (Global Options)

옵션 단축 환경 변수 설명
--endpoint -e BACKEND_AI_GO_ENDPOINT 관리 API 엔드포인트 (URL 또는 설정된 이름). 자동 발견을 재정의합니다.
--token -t BACKEND_AI_GO_TOKEN API 인증 토큰.
--output -o BACKEND_AI_GO_OUTPUT 출력 형식: console, json, yaml.
--quiet -q 필수적이지 않은 출력을 억제합니다.
--verbose -v 상세 출력을 활성화합니다.
--no-verify-ssl SSL 인증서 검증을 건너뜁니다.

명령어 (Commands)

config - 구성 관리

CLI 구성 설정을 관리합니다.

  • bgo config path: 구성 파일 경로를 표시합니다.
  • bgo config get <KEY>: 구성 값을 가져옵니다.
  • bgo config set <KEY> <VALUE>: 구성 값을 설정합니다.
  • bgo config list: 모든 구성 값을 나열합니다.
  • bgo config reset: 구성을 기본값으로 초기화합니다.

model - 로컬 모델 관리

로컬 디스크에 저장된 모델을 관리합니다.

  • bgo model list: 모든 로컬 모델을 나열합니다.
  • bgo model info <MODEL_ID>: 특정 모델에 대한 자세한 정보를 가져옵니다.
  • bgo model refresh: 모델 인덱스를 새로 고침합니다 (새 파일 검색).

loaded - 로드된 모델 작업

현재 추론을 위해 메모리에 로드된 모델을 제어합니다.

  • bgo loaded list: 현재 로드된 모델을 나열합니다.
  • bgo loaded info <ID>: 로드된 모델 인스턴스의 세부 정보를 가져옵니다.
  • bgo loaded load [OPTIONS] <MODEL_ID>: 모델을 메모리에 로드합니다.
    • 옵션:
      • -c, --context-length <INT>: 컨텍스트 길이 재설정.
      • -g, --gpu-layers <INT>: GPU로 오프로드할 레이어 수 (-1은 전체).
      • -t, --threads <INT>: 사용할 스레드 수.
      • -a, --alias <STRING>: 라우팅을 위한 모델 별칭.
      • --tool-calling: 도구 호출(Tool calling) 기능 활성화.
      • --mmproj <PATH>: 비전 모델을 위한 mmproj 파일 경로.
  • bgo loaded unload <ID>: 리소스를 확보하기 위해 모델을 언로드합니다.
  • bgo loaded health <ID>: 로드된 모델의 상태를 확인합니다.

router - 라우터 제어

Continuum Router 서비스를 관리합니다.

  • bgo router status: 라우터의 현재 상태를 가져옵니다.
  • bgo router start: 라우터 서비스를 시작합니다.
  • bgo router stop: 라우터 서비스를 중지합니다.
  • bgo router restart: 라우터 서비스를 다시 시작합니다.

system - 시스템 모니터링

하드웨어 리소스 및 API 상태를 모니터링합니다.

  • bgo system info: 일반 시스템 정보(OS, 아키텍처)를 가져옵니다.
  • bgo system metrics: 현재 시스템 지표(CPU, RAM 사용량)를 가져옵니다.
  • bgo system gpu: 상세 GPU 정보를 가져옵니다.
  • bgo system health: 전체 API 상태를 확인합니다.
  • bgo system version: API 서버 버전을 가져옵니다.

예제

모든 사용 가능한 모델을 JSON 형식으로 나열: 

bgo model list -o json

특정 모델 로드 (GPU 레이어 지정): 

bgo loaded load "gemma-3n-E4B-it-Q4_K_M" --gpu-layers 33

시스템 GPU 상태 확인: 

bgo system gpu