10.7. CLI 참조¶
aigo CLI 도구는 Backend.AI GO 관리 API에 대한 커맨드라인 접근을 제공합니다. 이 도구를 사용하여 터미널에서 로컬 모델을 관리하고, 추론 서버를 제어하며, 시스템 리소스를 모니터링하고, 로드된 모델과 상호 작용할 수 있습니다.
설치¶
CLI는 Backend.AI GO 배포판에 포함되어 있습니다. 소스에서 빌드하는 경우 다음 명령을 사용합니다:
사용법¶
자동 발견 (Auto-Discovery)¶
--endpoint를 지정하지 않으면, CLI는 관리 API 서버가 시작 시 기록한 발견 파일을 읽어 실행 중인 Backend.AI GO 인스턴스를 자동으로 발견합니다. 로컬에서 실행 중인 인스턴스에 연결하는 일반적인 경우 별도의 설정이 필요하지 않습니다.
엔드포인트 결정 우선순위:
--endpoint플래그 또는BACKEND_AI_GO_ENDPOINT환경 변수 (명시적 재정의)- 구성 파일 엔드포인트 (
aigo config set endpoint ...로 기본값을 변경한 경우) - 자동 발견 파일 (로컬 인스턴스가 실행 중이고 정상인 경우)
- 기본 폴백:
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)¶
chat - 단발성 채팅 완성¶
로드된 모델에 메시지 하나를 보내고 응답을 출력합니다.
MESSAGE를 생략하면 stdin에서 입력을 읽습니다 (최대 1 MiB).
옵션:
| 옵션 | 단축 | 설명 |
|---|---|---|
--model <MODEL> | -m | 완성에 사용할 모델. |
--max-tokens <INT> | 생성할 최대 토큰 수 (기본값: 1024). | |
--temperature <FLOAT> | 샘플링 온도 0.0–2.0 (기본값: 0.7). --reasoning-effort 설정 시 무시됩니다. | |
--system <PROMPT> | -s | 앞에 추가할 시스템 프롬프트. |
--reasoning-effort <LEVEL> | 하이브리드 사고 모델의 추론 노력 수준. 허용 값: none, low, medium, high, xhigh. none으로 설정하면 chat_template_kwargs를 통해 사고 모드를 비활성화합니다. | |
--no-think | 사고 모드 비활성화 (chat_template_kwargs.enable_thinking=false 설정). --reasoning-effort보다 우선 적용됩니다. | |
--thinking-budget <N> | <think> 블록 안에서 모델이 출력할 수 있는 토큰 수의 요청별 상한값으로, 요청 본문에 thinking_budget_tokens 필드로 전송됩니다. -1이면 무제한(엔진 기본값), 0이면 즉시 종료(thinking 비활성화), N>0이면 N개 토큰의 하드 캡입니다. 엔진 비종속적이라 llama-server와 mlxcel-server 양쪽에서 동일하게 동작합니다. | |
--preserve-thinking | 이전 어시스턴트 턴들의 <think> 블록을 제거하지 않고 그대로 유지합니다(Qwen3.6+ 기능). chat_template_kwargs.preserve_thinking=true를 설정하는데, --no-think / --reasoning-effort와는 직교 관계라서 플래그를 함께 쓰면 양쪽 kwarg가 공존합니다. 그 이전 Qwen3/3.5 모델들은 플래그를 받기는 하지만 동작은 보장되지 않습니다. |
--reasoning-effort를 none 이외의 값으로 설정하면 요청에 reasoning_effort와 chat_template_kwargs: {"enable_thinking": true}가 함께 전송됩니다. none으로 설정하거나 --no-think를 사용하면 chat_template_kwargs: {"enable_thinking": false}만 전송되는데, 이것이 Qwen3/3.5 하이브리드 사고 모델에서 <think> 블록을 억제하는 올바른 방법입니다.
--thinking-budget와 --preserve-thinking는 --reasoning-effort와 독립적으로 동작하는데, 전자는 모델이 <think> 안에서 출력할 수 있는 토큰 수를 제한하고 후자는 이전 <think> 블록을 프롬프트에 남겨둘지를 결정합니다. 두 필드 모두 요청 본문에 그대로 실려가기 때문에 llama-server와 mlxcel-server로 변형 없이 전달되고, 중간에 continuum-router가 있어도 그대로 통과합니다.
예제:
# 기본 채팅
aigo chat "프랑스의 수도는 어디입니까?"
# Qwen3 모델에서 사고 모드 비활성화
aigo chat --no-think "이 문서를 요약해 주세요" < report.txt
# 중간 노력으로 사고 활성화
aigo chat --reasoning-effort medium "단계별로 풀어보세요: ..."
# thinking을 64토큰으로 제한 (간결한 추론 강제)
aigo chat --thinking-budget 64 --reasoning-effort high "빠르게: 2+2=?"
# 예산으로 thinking 비활성화 (이 기능을 구현한 엔진에서는 --no-think와 동등)
aigo chat --thinking-budget 0 "그냥 바로 답해주세요."
# Qwen3.6+에서 턴 간 <think> 블록 보존 (에이전트 KV 캐시 재사용 향상)
aigo chat --preserve-thinking --reasoning-effort high "방금 풀던 문제 이어서 풀어줘."
# 시스템 프롬프트와 함께 stdin 입력 파이프
echo "SELECT * FROM users" | aigo chat --system "당신은 SQL 전문가입니다."
complete - 단발성 텍스트 완성¶
텍스트 완성 형식(비채팅)으로 프롬프트를 전송합니다.
PROMPT를 생략하면 stdin에서 입력을 읽습니다.
옵션:
| 옵션 | 단축 | 설명 |
|---|---|---|
--model <MODEL> | -m | 사용할 모델. |
--max-tokens <INT> | 생성할 최대 토큰 수 (기본값: 256). | |
--temperature <FLOAT> | 샘플링 온도 0.0–2.0 (기본값: 0.7). |
config - 구성 관리¶
CLI 구성 설정을 관리합니다.
aigo config path: 구성 파일 경로를 표시합니다.aigo config get <KEY>: 구성 값을 가져옵니다.aigo config set <KEY> <VALUE>: 구성 값을 설정합니다.aigo config list: 모든 구성 값을 나열합니다.aigo config reset: 구성을 기본값으로 초기화합니다.
model - 로컬 모델 관리¶
로컬 디스크에 저장된 모델을 관리합니다.
aigo model list: 모든 로컬 모델을 나열합니다.aigo model info <MODEL_ID>: 특정 모델에 대한 자세한 정보를 가져옵니다.aigo model refresh: 모델 인덱스를 새로 고침합니다 (새 파일 검색).
loaded - 로드된 모델 작업¶
현재 추론을 위해 메모리에 로드된 모델을 제어합니다.
aigo loaded list: 현재 로드된 모델을 나열합니다.aigo loaded info <ID>: 로드된 모델 인스턴스의 세부 정보를 가져옵니다.aigo 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 파일 경로.
- 옵션:
aigo loaded unload <ID>: 리소스를 확보하기 위해 모델을 언로드합니다.aigo loaded health <ID>: 로드된 모델의 상태를 확인합니다.
router - 라우터 제어¶
Continuum Router 서비스를 관리합니다.
aigo router status: 라우터의 현재 상태를 가져옵니다.aigo router start: 라우터 서비스를 시작합니다.aigo router stop: 라우터 서비스를 중지합니다.aigo router restart: 라우터 서비스를 다시 시작합니다.
system - 시스템 모니터링¶
하드웨어 리소스 및 API 상태를 모니터링합니다.
aigo system info: 일반 시스템 정보(OS, 아키텍처)를 가져옵니다.aigo system metrics: 현재 시스템 지표(CPU, RAM 사용량)를 가져옵니다.aigo system gpu: 상세 GPU 정보를 가져옵니다.aigo system health: 전체 API 상태를 확인합니다.aigo system version: API 서버 버전을 가져옵니다.
예제¶
모든 사용 가능한 모델을 JSON 형식으로 나열:
특정 모델 로드 (GPU 레이어 지정):
시스템 GPU 상태 확인: