WebUI¶

mlxcel은 서버 바이너리 안에 관리용 브라우저 UI를 담아 제공합니다. 서버가 볼 수 있는 모델을 나열하고, 관리 캐시의 체크포인트를 다운로드하거나 삭제하고, 모델을 로드하거나 언로드하고, 런타임 활동을 보여 주고, 설정을 편집하며, 로컬 채팅 화면을 제공합니다. UI는 mlxcel과 mlxcel-server에 컴파일된 정적 번들이므로 실행 중에 Node 서비스, CDN, 네트워크 접근이 필요하지 않습니다.

목차¶

WebUI와 함께 서버 시작하기
접근과 보안
모델 없는 모드와 단일 모델 모드
화면
WebUI가 의존하는 엔드포인트
WebUI 없이 빌드하기

WebUI와 함께 서버 시작하기¶

mlxcel serve 또는 mlxcel-server에 --webui(별칭 --ui)를 전달합니다. 이 플래그는 기본적으로 꺼져 있고 --help의 "WebUI Options" 아래에 표시됩니다. 환경 변수로는 LLAMA_ARG_UI=on으로 켜고, --no-webui 또는 LLAMA_ARG_UI=0으로 명시적으로 끕니다.

# 모델 없이 시작: UI에서 모델을 둘러보고 로드합니다.
mlxcel-server --webui --models-dir ./models/mlx --metrics --props --settings

# 모델 하나를 제공하면서 UI를 함께 엽니다.
mlxcel serve -m ./models/Qwen3-4B-4bit --webui --metrics

UI는 API와 같은 리스너의 {api_prefix}/webui/에서 제공되며, 시작 로그가 전체 주소를 Bundled WebUI: <addr>/webui/ 형식으로 출력합니다. 기존 OpenAI, llama-server, 라우터 경로의 경로와 동작은 바뀌지 않습니다.

접근과 보안¶

WebUI 제어 평면(/ui-api/v1)은 관리용 API입니다. 서버의 다른 부분에 인증이 걸려 있는지와 관계없이 모든 요청에 bearer 키가 필요합니다. 셸과 정적 자산은 공개됩니다.

리스너	`--api-key` 없음	`--api-key` 있음
루프백 TCP, 대화형 터미널	서버가 재시작하면 사라지는 세션 키(`mlxcel_webui_...`)를 만들어 터미널에 한 번 출력합니다. 로그인 화면에 붙여 넣으십시오.	설정한 키를 사용합니다.
루프백 TCP, 터미널 없음(예: 서비스 관리자)	생성한 키를 보여 줄 수 없으므로 시작을 거부합니다.	설정한 키를 사용합니다.
루프백이 아닌 TCP	시작을 거부합니다.	TLS(`--ssl-cert-file`, `--ssl-key-file`)가 필요합니다. 또는 TLS 리버스 프록시 뒤의 루프백에 바인딩하십시오.
Unix 소켓(`--host *.sock`)	거부합니다.	거부합니다. 대신 리버스 프록시 뒤의 루프백 TCP 리스너를 사용하십시오.

WebUI 모드에서 서버는 브라우저 요청의 Host, Origin, Fetch Metadata 헤더도 검사합니다. 상태를 바꾸는 호환 경로(POST /models/load, POST /models/unload, POST /models, DELETE /models, 설정, GET /models?reload=...)도 여기에 포함됩니다. bearer 키로 인증하고 Origin 헤더를 보내지 않는 비브라우저 클라이언트는 그대로 동작합니다.

브라우저는 키를 메모리에만 보관합니다. 브라우저 저장소, URL, 로그에 기록하지 않으며, 새로 고침하면 다시 묻습니다.

llama-server 자체 브라우저 UI나 에이전트 도구를 설정하는 옵션은 무시하지 않고 시작 시 거부합니다: --ui-config, --ui-config-file, --path, --tools, --tools-runtime, --mcp-servers-config, --mcp-servers-json, --ui-mcp-proxy, --agent.

모델 없는 모드와 단일 모델 모드¶

모델 없는(라우터) 모드. 모델 인자 없이 --webui를 주면 서버는 모델을 로드하지 않고 autoload를 끈 라우터로 시작하므로, 카탈로그를 둘러봐도 모델이 로드되지 않습니다. 카탈로그는 관리 캐시, --models-dir 디렉터리, --models-preset 항목을 라우터의 기존 우선순위(캐시, 모델 디렉터리, 프리셋 순)로 나열합니다. 목록 작성은 config.json 같은 제한된 메타데이터만 읽으며 토크나이저를 열거나 가중치를 읽지 않습니다. 모델은 Models 또는 Chat 화면에서 명시적으로 로드하고 언로드하며, 로드는 한 번에 하나씩이고 --models-max의 제한을 받습니다.

단일 모델 모드. -m을 주면 UI는 로드된 모델 하나와 실제 추론 ID를 보여 줍니다. 이 모드에서 로드, 언로드, 다운로드, 삭제는 읽기 전용이며, 다른 시작 설정이 필요한 항목은 적용 버튼 대신 재시작 방법을 보여 줍니다.

화면¶

앱 셸의 도구 모음은 서버가 현재 가진 모델과 그 수명 주기 상태를 보여 줍니다. 명령 팔레트는 로드된 모델과 카탈로그 모델을 검색하고, 단축키 도움말 대화 상자는 전역 단축키를 나열합니다(Cmd+N 또는 Ctrl+N은 새 대화로 Chat을 엽니다). 테마는 glass 테마를 포함해 Settings에서 고릅니다.

Models¶

모델 라이브러리는 카탈로그를 페이지 단위로 보여 주는 표로, 필터를 제공하며 모델마다 한 줄로 이름, 크기, 양자화(양자화하지 않은 체크포인트라면 config.json의 torch_dtype 또는 dtype에 적힌 가중치 dtype, 예: bf16), 태스크 배지, 수명 주기 상태, 행 동작을 보여 줍니다. 열 머리글을 누르면 이름, 크기, 양자화, 상태 순으로 정렬하는데, 어떤 정렬이든 Ready 모델이 먼저 오고 전환 중인 모델, 나머지 순으로 이어집니다. 검색어, 필터, 정렬은 같은 탭 세션 안에서 경로를 옮겨도 유지되고, 새로고침이나 로그아웃, 다른 서버 인스턴스에서는 기본값으로 돌아가며 어디에도 저장하지 않습니다.

검사 패널은 선택한 모델을 보여 주며, 하나의 "동작함" 배지로 뭉뚱그리지 않고 여러 사실을 따로 보여 줍니다. 체크포인트 파일이 완전한지, 아키텍처를 지원하는지, 런타임에 결정된 GPU 백엔드(Metal, CUDA, ROCm)에서 실행할 수 있는지, 현재 수명 주기 상태가 무엇인지입니다. 창 너비가 1100 px 이상이면 목록 옆 패널로 선택을 따라가고, 1100 px 미만이면 Inspect를 눌렀을 때만 열리는 서랍이 됩니다. 불투명 식별자, 서버가 보낸 원래 사유, 내부 카운터는 열었을 때만 렌더링되는 닫힌 Details 영역에 들어 있습니다.

각 행에는 그 행에만 작용하는 동작이 있습니다.

Use in Chat(Ready 상태의 채팅 모델)은 해당 모델을 선택한 상태로 Chat 화면을 엽니다.
Load와 Unload는 명시적 동작입니다. Ready 모델에는 Unload가, 나머지 상태에는 로드할 수 있을 때까지 비활성화된 Load가 보입니다. 서버가 용량 한도에 있으면 로드할 때 어느 로드된 모델을 내보낼지 묻고, 내보내기는 확인한 모델 리비전에만 적용됩니다. 저장한 다음 로드 프로필이 있으면 로드에 적용합니다.
Inspect는 그 행의 검사 패널을 엽니다.
Delete(관리 캐시 행만 해당)는 캐시 파일을 지웁니다. --models-dir나 프리셋의 항목, 사용 중이거나 로드·다운로드·드레인 중인 모델은 삭제할 수 없습니다.

Download는 공개 owner/name 저장소 ID(선택적으로 리비전 포함)를 받아 관리 캐시에 쓰며 진행 상황과 취소를 제공합니다. 경로, URL, 비공개 저장소는 받지 않습니다.

Chat¶

Chat은 서버 자체의 /v1/chat/completions 경로로 autoload=false를 붙여 스트리밍합니다. 대화 헤더에서 모델을 고르면 선택만 할 뿐이며, 모델이 Ready가 아니면 헤더가 확인을 먼저 묻는 Load 버튼을 보여 줍니다. 추론 내용은 접힌 영역으로 보이고, 도구 호출은 구조화된 카드로 표시할 뿐 실행하지 않으며, 모델 출력은 원시 HTML이나 원격 이미지 없이 제한된 Markdown 부분 집합으로 렌더링합니다. 로드된 모델이 비전 입력을 보고하면 로컬 PNG, JPEG, 애니메이션이 아닌 WebP 이미지를 첨부할 수 있습니다.

턴별 파라미터 재정의(max_tokens, temperature, top_p, top_k, min_p, repetition_penalty, seed)는 채팅 설정 서랍에 있으며 다음 턴에만 적용됩니다. 대화 기록은 저장을 켜지 않는 한 메모리에만 있습니다. 저장한 기록은 이 브라우저의 IndexedDB에 남고 대화 50개로 제한되며, 내보내기, 가져오기, 지우기를 할 수 있습니다.

Activity¶

Activity는 선택한 모델의 상태 페이지입니다. 헤더에는 모델 선택기(Ready 모델이 먼저), Refresh, Export, 마지막 스냅샷 시각이 있습니다. 그 아래 요약 타일 네 개가 고정 순서로 놓이는데, Active requests(최근 기록 스파크라인 포함), Total completed requests, Total completion tokens, Queued requests입니다. 이어서 슬롯별 문맥 점유량을 보여 주는 슬롯 표가 있고, 서버 세션 기록의 작업(다운로드, 로드, 삭제)이 한 줄씩 나옵니다.

탭이 보일 때 2초마다 폴링하고 숨겨지면 멈춥니다. 값은 기존 서버 카운터에서 오므로 요청 카운터에는 --metrics가 필요하고 슬롯은 --no-slots로 꺼져 있지 않아야 합니다. 서버가 값을 보고하지 않는 타일은 0이 아니라 unknown으로 표시하고 그 사유를 알려 주는 힌트를 붙이며, 저렴한 출처가 없는 메모리 수치는 추정하지 않습니다. 문맥 크기를 아는 유휴 슬롯은 0 / D tokens로 표시합니다. "All measurements and sources" 영역은 모든 측정값을 범위, 관측 시각, 서버가 보낸 원래 사유와 함께 나열합니다. 진단 내보내기에는 개수, 상태, 숫자 측정값만 담기며 경로, 프롬프트, 키는 담기지 않습니다.

Settings¶

Settings에는 범위별로 네 개의 탭이 있습니다.

탭	범위	바꾸는 것
Appearance	이 브라우저	테마와 표시 설정.
Requests	이 브라우저 세션	메모리에만 두는 기본 요청 파라미터. 빈 필드는 서버 기본값을 따릅니다.
Model	선택한 모델	다음 로드 프로필(`ctx_size` 1에서 262144, `n_parallel` 1에서 32, KV 캐시 모드)과, Ready 모델의 경우 `/v1/settings`가 노출하는 실시간 값. 실시간 변경은 새로 수락한 요청에 적용됩니다.
Server	선택한 모델의 서버	읽기 전용 시작 값, `/props`가 보고하는 슬롯별 유효 문맥, 선택적 원시 토큰 수 확인.

명시한 CLI 플래그가 다음 로드 프로필보다 우선하고, 프로필은 프리셋보다 우선합니다. 프로필을 저장해도 아무것도 로드하지 않으며, 다음 명시적 로드에 적용됩니다. WebUI는 --settings, --props, --metrics, 슬롯을 스스로 켜지 않으므로, 탭에서 쓰려는 엔드포인트를 켜고 서버를 시작하십시오.

WebUI가 의존하는 엔드포인트¶

화면	서버 옵션	없을 때
Activity 요청 카운터	`--metrics`	카운터를 사용할 수 없음으로 표시합니다.
Activity 슬롯	슬롯 활성화(기본값)	슬롯 데이터를 사용할 수 없음으로 표시합니다.
Settings Model 탭의 실시간 값	`--settings`	다음 로드 프로필만 편집할 수 있습니다.
Settings Server 탭의 문맥	`--props`	`/props`가 응답하지 않는다고 알려 줍니다.

/ui-api/v1 경로는 저장소의 docs/webui/ 디렉터리에 기여자용으로 OpenAPI 스키마와 함께 문서화되어 있습니다.

WebUI 없이 빌드하기¶

webui Cargo feature는 기본으로 켜져 있으며 컴파일된 자산을 두 바이너리에 내장합니다. 빼려면 기본 feature를 끄고 필요한 feature만 다시 지정하십시오.

cargo build --release --no-default-features --features metal,accelerate,surgery

이 feature 없이 빌드한 바이너리는 시작 시 --webui를 거부하며 webui feature가 필요하다고 알려 줍니다.