# modelctl 인터페이스: CLI, TUI, MCP > modelctl 모델 툴체인을 구동하는 세 가지 방법 — 스크립트용 CLI, 대화형 터미널 UI, 코딩 에이전트를 위한 MCP 서버 — 그리고 각각을 언제 쓸지. `modelctl`은 세 가지 방법으로 구동할 수 있습니다. 세 방법 모두 **동일한 하위 CLI 명령**(`convert` / `validate` / `quantize` / `package`)을 실행하므로 결과는 같습니다 — 작업 방식에 맞는 인터페이스를 고르세요: | 인터페이스 | 적합한 용도 | 추가 설치 | | --- | --- | --- | | **CLI** (`modelctl`) | 스크립팅, CI 파이프라인, 단발성 명령 | 코어(없음) | | **TUI** (`modelctl-tui`) | 대화형 사용 — 폼, 실시간 출력, 플래그 암기 불필요 | `[tui]` | | **MCP 서버** (`modelctl-mcp`) | 타입이 정의된 도구를 호출하는 코딩 AI 에이전트(Claude Code, Cursor 등) | `[mcp]` | TUI와 MCP 서버는 CLI를 감싼 얇은 서브프로세스 래퍼이며 동일한 [자동 라우팅](#자동-라우팅-올바른-환경-선택)을 공유합니다: `venv-torch` / `venv-tf` 환경을 감지해 각 명령을 필요한 프레임워크가 있는 환경으로 보내므로, 잘못된 환경에서 단계를 실행할 일이 없습니다. 둘 다 `torch`/`tensorflow`를 직접 import하지 않으므로 의존성 충돌이 없습니다. 이 페이지는 **인터페이스**를 다룹니다. 전체 모델 준비 작업 흐름 (convert → validate → quantize → package)과 플래그 상세는 [modelctl로 모델 준비하기](/ko/configure/prepare-models/)를 참고하세요. ## CLI (`modelctl`) 표준 인터페이스입니다. 네 개의 서브커맨드, 명확한 exit 코드, ✓/✗ 검사 출력 — 셸과 CI를 위해 만들어졌습니다. ```bash # TorchScript 모델을 ONNX로 변환 modelctl convert --source model.pt --format pytorch --output model.onnx \ --input-shape 1,3,224,224 --opset 18 # 검증 (스키마 · 엣지 런타임 대비 opset · 런타임 로드 · 테스트 추론) modelctl validate --model model.onnx --target-ort 1.18 # Dynamic INT8 양자화 modelctl quantize --model model.onnx --output model.int8.onnx # 체크섬이 포함된 오프라인 번들로 패키징 modelctl package --model model.onnx --name pump-anomaly-v1 ```
플레이스홀더 — convert, validate, quantize, package를 ✓ 검사 라인과 함께 실행하는 modelctl CLI 세션의 터미널 스크린샷
일반적인 CLI 세션: 각 명령이 ✓/✗ 검사를 출력하고 실패 시 0이 아닌 코드로 종료합니다.
CLI 고유 사항: - **설정 파일**: `modelctl convert --config model.yaml`은 YAML 설정을 읽습니다. 우선순위는 **CLI 플래그 > YAML > 기본값**입니다. - **Exit 코드**는 실패 단계에 대응합니다(3 = 의존성 누락, 4 = convert, 5 = validate, 6 = package, 7 = quantize) — CI를 여기에 걸어 게이팅하세요. - **재현 가능한 번들**: `--timestamp`를 넘기거나 `SOURCE_DATE_EPOCH`를 설정해 `metadata.json` / `checksums.sha256`이 실행마다 byte-identical이 되게 하세요. ## TUI (`modelctl-tui`) 선택 사항인 [Textual](https://textual.textualize.io/) 프런트엔드입니다: 명령을 고르고, 폼을 채우고, ✓/✗ 출력이 실시간으로 흐르는 것을 성공/오류 배지와 함께 지켜보세요. ```bash pip install 'modelctl[tui]' modelctl-tui # venv-torch / venv-tf가 있는 디렉터리에서 실행 ``` ### 화면 구성 ```text ┌ modelctl-tui ──────────── envs: venv-torch[core, pytorch, quantize] venv-tf[core, quantize, tensorflow] ┐ │ Command │ Output │ │ ( ) convert │ $ venv-torch/bin/modelctl validate --model model.onnx │ │ (•) validate │ ✓ ONNX schema valid │ │ ( ) quantize │ ✓ Opset supported │ │ ( ) package │ ✓ ONNX Runtime load successful │ │ Options │ ✓ Test inference successful │ │ --model * [model.onnx ] │ │ │ --target-ort [1.18 ] │ │ │ [ Run ] │ │ │ → will run in: venv-torch [...] │ ● SUCCESS exit 0 │ └──────────────────────────── q quit ctrl+r run ctrl+e re-detect envs ────────────────────┘ ``` - **헤더** — 감지된 환경과 그 기능(`core` / `pytorch` / `tensorflow` / `quantize`). - **Command + Options (왼쪽)** — 폼은 명령마다 바뀌며, `*`는 필수 항목을 표시합니다. - **실행 힌트** — **Run** 아래 줄이 명령이 실행될 환경, 또는 아직 실행할 수 없는 이유를 알려줍니다. - **Output (오른쪽)** — 실시간 ✓/✗ 스트림과 `● SUCCESS exit 0` / `● FAILED exit N` 배지.
플레이스홀더 — 명령 목록, 옵션 폼, 실시간 출력 창, 상태 배지가 있는 modelctl-tui 화면 스크린샷
실제 TUI 화면. venv-torch로 라우팅된 validate 실행을 보여줍니다.
### 키 바인딩 | 키 | 동작 | | --- | --- | | `ctrl+r` | 선택한 명령 실행(**Run**과 동일) | | `ctrl+e` | 환경 재감지(venv 생성/수정 후) | | `q` | 종료 | 헤더에 `envs: none detected`가 표시되면, `venv-torch/` / `venv-tf/`가 있는 디렉터리에서 `modelctl-tui`를 실행하거나, venv를 만든 뒤 `ctrl+e`를 누르세요. ## MCP 서버 (`modelctl-mcp`) 선택 사항인 [Model Context Protocol](https://modelcontextprotocol.io/) stdio 서버로, 동일한 명령을 코딩 에이전트에게 **타입이 정의된 도구**로 노출합니다. 에이전트가 셸 접근 없이 엣지 박스용 모델을 준비할 수 있습니다. ```bash pip install 'modelctl[mcp]' ``` 에이전트에 등록하세요 — Claude Code라면 `claude.json`에(Cursor도 유사): ```json { "mcpServers": { "modelctl": { "command": "modelctl-mcp", "cwd": "/path/with/venv-torch-and-venv-tf" } } } ``` `cwd`에는 `venv-torch/` / `venv-tf/` 디렉터리(라우터의 기본 탐색 루트)가 있어야 합니다 — 또는 에이전트가 먼저 `list_environments`를 호출해 라우팅 가능한 대상을 확인하게 하세요. ### 도구 | 도구 | 용도 | 주요 파라미터 | | --- | --- | --- | | `list_environments` | 환경과 기능 탐색 | — | | `convert` | PyTorch / TensorFlow → ONNX | `source`, `format`, `output`, `input_shape` | | `validate` | 스키마, opset, 런타임 로드, 테스트 추론 | `model`; 선택 `target_ort`, `no_runtime` | | `quantize` | Dynamic INT8 양자화 | `model`; 선택 `output`, `input_shape` | | `package` | 검증 후 체크섬 포함 오프라인 릴리스로 번들링 | `model`, `name`; 선택 `version`, `quantize`, `out_root` | 모든 도구는 동일한 결과 형태를 반환합니다: `command`, `env_label`, `exit_code`, `ok`, `stdout`, `stderr`, 그리고 `artifact_path`(성공 시 생성된 파일/번들) — 에이전트는 `ok`를 확인한 뒤 `artifact_path`를 사용해야 합니다.
플레이스홀더 — list_environments, convert, validate MCP 도구를 호출하고 JSON 결과를 받는 코딩 에이전트 세션 스크린샷
코딩 에이전트 세션: list_environments → convert → validate, 각각 타입이 정의된 결과를 반환합니다.
## 자동 라우팅: 올바른 환경 선택 `quantize`와 `tensorflow` extra는 하나의 Python 환경을 공유할 수 없습니다 (`ml_dtypes` 버전 충돌). 그래서 툴링이 venv 두 개를 유지합니다. TUI와 MCP 서버는 각 환경의 기능을 조사해 명령별로 라우팅합니다: | 명령 | 필요한 기능 | 일반적인 라우팅 대상 | | --- | --- | --- | | `validate`, `package`(quantize 없이) | core | 아무 환경 | | `convert --format pytorch` | pytorch | `venv-torch` | | `convert --format tensorflow` | tensorflow | `venv-tf` | | `quantize`, 또는 모든 `--quantize` 플래그 | quantize | `venv-torch` | 설계상 만족시킬 수 없는 조합이 하나 있습니다: **TensorFlow convert와 quantize를 함께** 쓰는 경우입니다. 두 인터페이스 모두 실행 중간에 실패하는 대신 이를 먼저 알려줍니다 — TUI는 힌트와 함께 **Run**을 비활성화하고, MCP는 오류를 반환합니다 — 두 단계로 나누세요: 먼저 `convert`(tensorflow)로 `.onnx`를 만들고, 그 `.onnx`를 `quantize`하세요. ## 다음 단계 - [modelctl로 모델 준비하기](/ko/configure/prepare-models/) — convert → validate → quantize → package 전체 작업 흐름과 플래그 레퍼런스. - [modelctl 모범 사례](/ko/configure/modelctl-best-practices/) — 해야 할 것/하지 말 것: 프로필, 검증 게이트, 재현 가능한 번들, CI. - [모델 배포](/ko/configure/models/) — ONNX 번들을 업로드하고 플로우에서 모델을 사용합니다.