메인 콘텐츠로 건너뛰기
이 대시보드 페이지에서는 GPU 머신에 vLLM을 새로 설치하는 단계부터 원격에서 접근 가능하고 인증이 필요한 API 엔드포인트를 생성하는 과정까지 전체 절차를 안내합니다. 소요 시간은 약 5분입니다. 사용하시는 업스트림 모델 ID는 귀하의 하드웨어에 그대로 보관되며, 입력하신 프롬프트 역시 어떠한 서드파티 추론 서버를 거치지 않습니다.
이미 vLLM이 실행 중이신가요? 그럴 경우 단계 3: Tokios 커넥터 설치하기로 바로 넘어가시면 됩니다. 간단한 요약이 필요하다면 vLLM 원격 접속 방법을 참고하세요.

사전 요구 사항

시작하기 전에 다음 조건들이 충족되었는지 확인해 주세요.
  • 1 CUDA를 지원하는 NVIDIA GPU (RTX 3090, 4090, A100 또는 DGX Spark).
  • CUDA 12.1 이상이 설치되어 있어야 합니다 (nvidia-smi 명령어로 확인 가능).
  • Python 3.9–3.12 버전이 설치되고 pip 패키지도 이용 가능해야 합니다.
  • A Tokios account (free to sign up).
다중 GPU 환경을 구성하려면 아래의 텐서 병렬 처리 항목을 참고하시기 바랍니다.

단계 1: vLLM을 설치하고 실행하기

pip를 사용해 vLLM을 설치하세요:
OpenAI 호환 서버를 실행합니다. 반드시 127.0.0.1에만 바인딩하되, 더 넓은 범위로 설정하지 마세요:
vLLM은 첫 실행 시 업스트림 모델 ID에 해당하는 모델 가중치를 다운로드한 뒤 GPU 메모리에 로드하고 http://127.0.0.1:8000에서 OpenAI 호환 HTTP 서버를 시작합니다.

서버가 정상적으로 실행 중인지 확인하세요

다른 터미널에서 다음 명령을 입력해보세요:
등록된 모델 목록이 화면에 표시될 것입니다.

일반적인 실행 설정 방법

사용 중인 하드웨어에 적합한 플래그를 선택하세요:
--max-model-len 값은 vLLM이 KV 캐시용으로 확보할 GPU 메모리 양을 결정합니다. 처음에는 보수적인 수치(4096 또는 8192)를 지정한 뒤 모델이 메모리 초과 없이 정상 로드되는지 확인한 후 값을 높여보세요. 메모리 산출 방식에 대해서는 KV 캐시 및 컨텍스트 문서를 참고하시기 바랍니다.

다중 GPU 환경: 텐서 병렬 처리

For models that don’t fit in 1 GPU, use tensor parallelism across multiple GPUs on the same machine:
단일 노드에서 여러 GPU를 사용할 때는 파이프라인 병렬화보다 텐서 병렬화가 권장됩니다. 디코드 단계에서 대역폭 활용도가 더 높기 때문입니다.

Windows (WSL2)

vLLM은 Windows에서 기본적으로 실행되지 않습니다. GPU 패스스루 기능을 활용해 WSL2 내에서 Docker를 사용하시기 바랍니다.

단계 2: 로컬 환경에서 테스트하기

원격 접속 환경을 설정하기 전에 vLLM이 올바르게 응답하는지 확인해야 합니다.
유효한 채팅 완성 응답이 반환되는지 확인하시기 바랍니다.

단계 3: Tokios 커넥터 설치하기

The connector dials out from your machine to https://api.tokios.com. No inbound port opens. No port forwarding. No DNS record. Sign in at tokios.com/console, open the Setup tab, and click Start pairing. Tokios shows a one-time claim code like TKS-XXXX-XXXX, valid for about 15 minutes. vLLM이 실행 중인 기기에서 설치 명령어를 실행하세요.
Windows
macOS
Linux
이미 tokios-connector이 설치되어 있다면 해당 코드를 직접 입력하시면 됩니다.
Back in the console, click Approve on the Setup or Connectors tab. The connector’s token (ct-tok-…) is delivered over the tunnel once approved — you never see it on screen or paste it into a file.

단계 4: 커넥터를 vLLM에 지정합니다

vLLM의 OpenAI 호환 서버는 Tokios가 기대하는 형식을 그대로 따릅니다. 단일 모델일 경우 콘솔의 설정 마법사가 자동으로 http://127.0.0.1:8000/v1을 기본값으로 지정합니다. 여러 모델이나 맞춤형 설정이 필요하다면 tokios-connector.json을 생성하시면 됩니다.
다중 모델용 파일 형식에 관해서는 커넥터 설정 문서를 참고하세요.

단계 5: 배포 항목을 등록합니다

In the Models tab, register your vLLM model and choose a public name — for example, mistral-tunnel. 이 공개 이름이 클라이언트 측에서 model 필드에 입력하는 값입니다. 이 값은 vLLM의 로컬 업스트림 모델 ID와는 별개이므로 클라이언트 설정을 손상시키지 않고 업스트림 모델을 변경할 수 있습니다.
LoRA 어댑터를 사용 중이라면 --enable-lora --lora-modules adapter1=/path/to/adapter 매개변수를 지정해 vLLM을 실행한 뒤 각 어댑터를 별도의 Tokios 배포 항목으로 등록하세요. 자세한 내용은 모델 라우팅 문서를 참고하세요.

단계 6: API 키를 생성합니다

In the Keys tab, click Create key.
  • 원한다면 모델 이름 패턴을 지정해 특정 배포 항목에만 API 키 사용 범위를 제한할 수 있습니다. 모든 배포 항목에 적용하려면 *을 입력하시면 됩니다.
  • 지금 sk-tok-… 키 값을 복사해두세요. 이 값은 한 번만 표시되기 때문입니다.
여러 개의 API 키를 생성할 수 있습니다. 팀원, 에이전트, 또는 환경마다 하나씩 만들고 개별적으로 취소도 가능합니다.

단계 7: 어떤 클라이언트에서든 커넥터를 연결하세요

이제 귀하의 vLLM 모델은 https://api.tokios.com 주소에서 접근 가능합니다. 호출 방법은 다음과 같습니다:
The model field is always your registered deployment name (mistral-tunnel), never vLLM’s local model id.

보안 모델: 아웃바운드 전용 터널

이 방식이 SSH 터널, 포트 포워딩, 혹은 Tailscale과 다른 점은 다음과 같습니다:
사용자의 vLLM 프로세스는 전혀 변경되지 않으며 127.0.0.1:8000 상태로 유지됩니다. 외부에서는 접근할 수 없으며, 오직 커넥터만이 해당 프로세스에 접속할 수 있고 아웃바운드 연결만 허용됩니다.
커넥터와 vLLM 사이의 루프백 연결에 대해서는 vLLM의 --api-key 플래그를 추가적인 보안 수단으로 활용할 수 있습니다. Tokios를 통한 클라이언트 요청은 sk-tok-… API 키로 인증되며, 실제로 127.0.0.1:8000에 접근할 수 있는 주체는 오직 커넥터뿐입니다.

자주 묻는 질문

네. "stream": true을 설정하면 Tokios가 호출한 API에 따라 OpenAI 또는 Anthropic 형식의 표준 서버 전송 이벤트(SSE)를 반환합니다.
가능합니다. Models 탭에서 추가적인 배포 항목을 등록하거나 tokios-connector.json 설정 파일을 활용해 여러 업스트림 모델 ID와 라우팅 규칙을 지정할 수 있습니다. 자세한 내용은 커넥터 설정을 참고하세요.
Yes. Create a separate sk-tok-… key per teammate in the Keys tab. Scope each key to only the deployments they need. Revoking a key cuts access immediately.
커넥터가 vLLM이 다시 가동될 때 자동으로 재연결됩니다. 별도의 조작이 필요하지 않으며, vLLM만 재시작하면 엔드포인트가 정상화됩니다.
네. WSL2 환경에서 Docker를 통해 vLLM을 실행한 뒤(위에 제시된 WSL2 설정 참조), Windows 호스트나 WSL2 내부에 Tokios 커넥터를 설치하면 됩니다. 두 방법 모두 사용 가능합니다.

어디서든 접근 가능한 여러분만의 vLLM

vLLM은 기존과 동일하게 로컬호스트와 GPU 환경에서 작동하며 외부로 열린 포트도 없습니다. 커넥터는 오직 외부로만 연결됩니다. 인증, 라우팅, 스트리밍, 키 관리 등 모든 기능은 단일 엔드포인트를 통해 처리되며, API 키를 부여받은 누구나 이를 활용할 수 있습니다.

빠른 시작 가이드

커넥터를 연결하고 첫 번째 모델을 전체 과정에 걸쳐 배포해 보세요.

API 키 관리

팀원들과 에이전트들을 위해 sk-tok-… API 키를 생성하고 권한을 설정하며 주기적으로 교체할 수 있습니다.

호환 가능한 클라이언트

39 클라이언트들이 정상 작동함이 확인되었습니다 — 코딩 에이전트, 채팅 애플리케이션, SDK들도 모두 문제없이 작동합니다.

원격 접속 솔루션 비교

Tokios가 Tailscale, Cloudflare Tunnel, SSH 터널과 비교했을 때 어떤 차이점이 있는지 알아보세요.