AI 튜토리얼

OpenAI 호환 API로 Colab A100에서 Qwen3.8-Flash-Next 실행하기

collabosm을 사용해 Colab A100 High-RAM 런타임을 프로비저닝하고, ExLlamaV3로 Qwen3.8-Flash-Next를 로드한 뒤 Cloudflare를 통해 보안 API를 공개하고, 클라이언트를 연결하며, 로컬에서 스트리밍을 테스트하고, 캐시를 조정하고, 과금되는 VM을 안전하게 종료하는 방법을 알아보세요.

2026년 9월 26일약 20분 소요

OpenAI 호환 API로 Colab A100에서 Qwen3.8-Flash-Next 실행하기

collabosm의 기능

collabosm은 단일 Colab A100 80GB High-RAM 인스턴스에서 Qwen3.8-Flash-Next를 실행합니다. 이 모델은 125B-A6B 혼합 전문가 모델로, 하이브리드 Gated-DeltaNet 및 전체 어텐션 아키텍처와 262,144토큰의 네이티브 컨텍스트 길이를 사용합니다.

이 프로젝트는 Colab VM을 프로비저닝하거나 복원하고, 버전이 고정된 ExLlamaV3 런타임을 설치하며, 버전이 고정된 모델 가중치를 다운로드하고, OpenAI 호환 HTTP 서버를 시작한 다음 Cloudflare 터널을 통해 공개합니다. 클라이언트는 생성된 bearer 키를 사용해 /v1 경로의 터널 URL에 연결합니다.

이 저장소에서 사용하는 추론 엔진은 ExLlamaV3뿐입니다. ExLlamaV3에는 HTTP 서버가 포함되어 있지 않으므로 API 서버 자체는 collabosm이 구현합니다.

주요 기능

단일 GPU 배포: 하나의 A100 80GB High-RAM 런타임에서 약 63.6GiB의 VRAM 상주 가중치를 실행합니다.
OpenAI 호환 인터페이스: 증분 스트리밍을 포함해 /v1/chat/completions와 /v1/responses를 모두 지원합니다.
안전한 Colab 복원: 일회성 로컬 CLI 세션 기록을 신뢰하거나 비용이 청구되는 중복 VM을 생성하는 대신, 고아 할당을 다시 연결합니다.
하드웨어 검증: 호환되지 않는 40GB A100을 거부하고 모델을 로드하기 전에 중지합니다.
영구 프롬프트 캐싱: 장기간 유지되는 하나의 ExLlamaV3 Generator를 사용해 페이지 테이블과 고정 RAM 캐시를 요청 간에 유지합니다.
2단계 캐시 설계: GPU KV 용량과 선택적 고정 호스트 RAM 캐시를 결합해 유휴 대화를 빠르게 재개합니다.
로컬 프로토콜 테스트: GPU나 모델 가중치 없이 실제 HTTP 핸들러를 실행하는 가짜 엔진을 제공합니다.
선택적 비전: 모델의 비전 구성 요소를 로드하고 검증된 이미지 입력을 받을 수 있습니다.
로컬 클라이언트 및 UI: 터미널 채팅, 브라우저 UI, 상태 페이지, 스트림에서 파생된 성능 지표, 브라우저에 업스트림 키가 노출되지 않도록 하는 프록시를 포함합니다.

프로젝트가 보고한 측정값에는 GCS=8192인 30K 프롬프트에서 최대 초당 3,882개의 프리필 토큰, 30K 컨텍스트에서 MTP 깊이 4를 사용한 초당 97.4개의 디코드 토큰, 114K 컨텍스트에서 초당 90.1개의 토큰이 포함됩니다. 이 수치를 보장된 성능으로 간주하지 말고, 측정의 출처와 주의사항은 docs/MEASURED.md를 참조하세요.

요구 사항 및 용량 계획

시작하기 전에 환경이 다음 요구 사항을 모두 충족하는지 확인하세요:

A100을 할당할 수 있는 Colab 요금제.
HIGH_RAM 머신 형태. 일반 40GB A100에서는 이 모델을 로드할 수 없습니다.
가중치를 저장하기 위한 약 110GiB의 Colab 디스크 공간.
uv tool install google-colab-cli로 설치한 Google Colab 명령줄 도구.
저장소를 포크하거나 푸시할 계획이라면 선택적으로 GitHub CLI.

uv tool install google-colab-cli

High-RAM 요구 사항은 필수입니다. 하드웨어 출력에서 “80”을 검색해 적합한 카드를 식별하지 마세요. A100은 VRAM이 40GB뿐인 경우에도 컴퓨팅 성능을 sm_80으로 보고할 수 있습니다. collabosm은 대신 보고된 vram_GiB 값을 비교합니다.

이 프로젝트는 월 약 200 컴퓨트 유닛을 제공하는 Colab Pro 등급에서 개발되었습니다. 측정된 A100 High-RAM 비용은 시간당 7.52CU였으며, 문서화된 환경에서는 시간당 약 $0.75였습니다. 가격과 할당 가능 여부는 저장소와 무관하게 변경될 수 있습니다.

서버 시작

1. 저장소 디렉터리 열기

collabosm 저장소를 다운로드하거나 복제한 다음 루트 디렉터리에서 다음 명령을 실행하세요. 스크립트는 scripts/up.sh, scripts/bootstrap.sh, scripts/serve.sh와 같은 저장소 기준 경로를 사용합니다.

2. 프로비저닝, 부트스트랩 및 서비스 시작

bash scripts/up.sh

이 단일 명령은 가능한 경우 기존 할당을 복원하고, 그렇지 않으면 새로운 High-RAM 할당을 생성합니다. 이후 프로젝트를 업로드하고, 버전이 고정된 런타임을 설치하며, 버전이 고정된 가중치를 다운로드하고, API를 시작하고, Cloudflare 터널을 실행한 다음 정상적인 상태 확인이 완료될 때까지 기다립니다.

성공적으로 실행되면 API와 공개 터널 URL이 모두 준비된 후에만 상태 코드 0으로 종료됩니다. 명령은 터널 URL과 API 키를 출력합니다. 키는 VM의 /content/api-key.txt에도 저장됩니다.

런타임은 Colab의 Python, PyTorch 및 CUDA 환경에 맞는 버전이 고정된 사전 빌드 ExLlamaV3 휠에서 선택됩니다. 가중치는 버전이 고정된 리비전으로 Hugging Face에서 가져옵니다. Xet 다운로드 경로가 멈추면 README에서 HF_HUB_DISABLE_XET=1을 대안으로 안내합니다.

3. 연결 설정 기록

base_url = https://<host>.trycloudflare.com/v1
api_key  = <printed API key>
model    = qwen3.8-flash-next-exl3

퀵 터널 호스트 이름은 실행할 때마다 변경될 수 있습니다. 안정적인 호스트 이름을 사용하려면 TUNNEL_TOKEN으로 이름이 지정된 Cloudflare 터널을 구성하고, 상태 출력에 표시되는 주소에 PUBLIC_URL을 연결하세요.

4. 실행 중인 구성 확인

GET /v1/status를 요청하면 캐시 설정, 실행 매개변수, 가동 시간, 비전 사용 가능 여부, 이미지 입력 정책 등 실행 중인 프로세스가 실제로 받은 매개변수를 확인할 수 있습니다.

저장소의 설명에 따르면 현재 기본값이 모두 함께 검증된 것은 아닙니다. 특정 조합이 검증되었다고 가정하기 전에 실시간 상태 엔드포인트를 확인하고 docs/MEASURED.md를 참조하세요.

캐시 및 생성 구성

모든 기본 실행 제어 항목은 scripts/up.sh에 전달되는 환경 변수입니다. 예:

SESSION=mybox CACHE_SIZE=524288 CPU_CACHE_GB=8 bash scripts/up.sh

SESSION: 로컬 세션 이름. 기본값은 collabosm입니다.
CACHE_SIZE: 작업 전체의 KV 토큰 수. 기본값은 500224이며 256의 배수여야 합니다.
CACHE_QUANT: KV 캐시 비트 폭. 기본값은 4이며 2부터 8까지 사용할 수 있습니다.
CPU_CACHE_GB: 고정 RAM을 사용하는 2단계 KV 페이지 캐시. 기본값은 32GiB이며 0으로 비활성화할 수 있습니다.
RECURRENT_CACHE_GB: Gated-DeltaNet 체크포인트를 저장하는 호스트 RAM 공간. 기본값은 24GiB입니다.
GCS: 생성기 청크 크기이자 프리필 성능을 크게 좌우하는 제어 항목. 기본값은 8192입니다.
NDT: 다중 토큰 예측 초안 깊이. 기본값은 4입니다.
RUNTIME: 사전 빌드된 런타임에는 wheel, 소스 기반 설정에는 source를 사용합니다.
TUNNEL_TOKEN: 선택 사항인 명명된 터널 토큰입니다.

호스트 RAM 캐시는 여유 용량이 아닙니다. 기본 CPU 캐시는 전체가 고정 메모리로 할당되며, 순환 캐시도 상당한 RAM을 사용합니다. 두 캐시는 저장소에 문서화된 36.4GiB n-gram 테이블과 함께 사용됩니다.

고정 RAM 계층은 참조되지 않는 페이지가 제거된 유휴 대화의 재개 시간을 단축합니다. 호스트 RAM이 일반 스왑처럼 작동하는 것이 아니므로, 활성 페이지를 제거할 수 없으며 동시에 유지할 수 있는 컨텍스트 수를 늘리지도 않습니다.

OpenAI 호환 API 호출

모델 목록 확인

curl https://<host>.trycloudflare.com/v1/models \
  -H "Authorization: Bearer <api-key>"

엔드포인트는 단일 모델 식별자 qwen3.8-flash-next-exl3를 반환합니다. 이 API 경로에는 인증이 필요하지만 /health는 인증 없이 사용할 수 있으며 일반 텍스트 ok를 반환합니다.

채팅 완성 생성

curl https://<host>.trycloudflare.com/v1/chat/completions \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.8-flash-next-exl3",
    "messages": [
      {"role": "user", "content": "Reply with exactly: pong"}
    ],
    "max_tokens": 16
  }'

채팅 인터페이스는 choices[].message.content 아래에 콘텐츠를 반환하며, stop 또는 length 종료 사유와 캐시된 프롬프트 토큰을 포함할 수 있는 사용량 정보를 함께 반환합니다.

완성 결과 스트리밍

stream을 true로 설정하면 모델이 디코딩하는 동안 Server-Sent Events를 받을 수 있습니다. 채팅 완성의 스트림은 [DONE]으로 끝납니다. stream_options.include_usage를 설정하면 스트리밍 응답에 사용량 데이터를 요청할 수 있습니다.

{
  "model": "qwen3.8-flash-next-exl3",
  "messages": [{"role": "user", "content": "Explain prompt caching briefly."}],
  "stream": true,
  "stream_options": {"include_usage": true},
  "max_completion_tokens": 200
}

/v1/responses 엔드포인트도 스트리밍을 지원합니다. 이벤트 순서에는 생성, 진행, 출력 항목, 콘텐츠 부분, 텍스트 델타, 완성, 종료 응답 이벤트가 포함됩니다. 스트리밍되는 모든 이벤트에는 단조 증가하는 sequence_number가 포함되며, 델타에는 클라이언트가 올바르게 연결하는 데 필요한 항목 및 콘텐츠 인덱스가 포함됩니다.

사고 모드 사용

일반 채팅 클라이언트와의 호환성을 위해 사고 기능은 기본적으로 비활성화되어 있습니다. enable_thinking: true를 사용하거나 지원되는 reasoning_effort 값인 xhigh, medium, low 중 하나를 지정해 활성화할 수 있습니다. 채팅 인터페이스에서는 추론 과정이 message.reasoning_content에 별도로 반환되며 일반 콘텐츠 필드에 포함되지 않습니다.

temperature와 top_p는 허용되지만, 서버가 sampler=None으로 작업을 생성하므로 현재 무시됩니다. 사고 제어 항목, max_tokens, 중지 시퀀스는 작동합니다.

포함된 클라이언트 사용

로컬 collabosm.py 클라이언트는 Python 표준 라이브러리만 사용하므로 별도의 설치가 필요하지 않습니다. 터널 엔드포인트와 생성된 키를 사용해 구성을 초기화합니다:

python collabosm.py config --init \
  --endpoint https://<host>.trycloudflare.com/v1 \
  --api-key <key>

이후 터미널에서 채팅하거나 로컬 브라우저 인터페이스를 실행할 수 있습니다:

python collabosm.py chat "hello"
python collabosm.py ui
python collabosm.py start

ui는 http://127.0.0.1:8790에서 페이지와 프록시를 제공합니다. start는 채팅 창과 상태 창을 엽니다. 클라이언트는 의도적으로 Colab VM을 시작하거나 중지하지 않으므로, 클라이언트를 여는 것만으로는 컴퓨팅 단위를 사용할 수 없습니다.

실제 bearer 키를 프록시가 주입하도록 하려면 기존 OpenAI 호환 클라이언트에 VM 엔드포인트 대신 로컬 프록시를 지정합니다:

base URL : http://127.0.0.1:8790/v1
API key  : anything
model    : qwen3.8-flash-next-exl3

이 설계는 실제 키를 로컬 프록시 프로세스 내부에 유지하고, 광범위한 CORS 정책을 피하며, 브라우저 UI를 VM과 독립적으로 업데이트할 수 있게 합니다.

GPU 없이 프로토콜 테스트

A100을 사용하거나 가중치를 다운로드하지 않고도 개발 스텁을 사용해 요청 및 스트리밍 동작을 검증할 수 있습니다:

python scripts/dev_stub.py --port 8099 --chunk 24 --delay 0.01
python scripts/check_surface.py --base http://127.0.0.1:8099/v1

스텁은 실제 배송 핸들러를 가져오고 엔진 조각 함수만 대체합니다. 표면 검사는 초기 델타, 종료 이벤트, 일치하는 Chat 및 Responses 출력, 필수 item 인덱스, 단조 증가하는 시퀀스 번호를 포함해 13가지 검사를 수행합니다. 검사가 실패하면 상태 코드 1로 종료됩니다.

스텁 명령에 --think를 추가하면 추론 item 수명 주기를 테스트할 수 있습니다. 스트림 이벤트 형식을 변경하거나 Codex CLI 같은 엄격한 클라이언트를 연결하기 전에 특히 유용합니다.

비전 기능을 신중하게 활성화하고 테스트하기

모델 팩은 멀티모달이지만, 이미 사용량이 높은 카드에서 비전 타워의 추가 VRAM 비용을 측정하지 않았기 때문에 비전 기능은 기본적으로 비활성화되어 있습니다. 별도의 비전 컴포넌트를 명시적으로 활성화하세요.

VISION=1 bash scripts/up.sh

이미지 관련 선택적 제어 항목은 다음과 같습니다.

IMAGE_URLS=1
MAX_IMAGE_BYTES=12582912
MAX_IMAGES=8

지원되는 두 API 방언 모두 표준 OpenAI 이미지 파트를 허용합니다. 비전 기능이 활성화되면 데이터 URL을 사용할 수 있습니다. 원격 HTTP 또는 HTTPS 이미지 URL은 IMAGE_URLS=1인 경우에만 허용됩니다.

{
  "role": "user",
  "content": [
    {"type": "text", "text": "이 이미지의 색상은 무엇인가요?"},
    {
      "type": "image_url",
      "image_url": {"url": "data:image/png;base64,..."}
    }
  ]
}

원격 URL이 활성화되면 서버는 호스트 이름을 확인하고 모든 주소가 전역 라우팅 가능해야 한다고 요구합니다. 루프백, 사설, 링크 로컬 및 메타데이터 주소는 거부하며 리디렉션을 따르지 않습니다. 파일 시스템 경로는 절대 허용되지 않습니다. 이미지를 삽입할 수 없으면 서버는 이미지를 조용히 무시하는 대신 vision_unavailable 유형의 JSON 400 오류를 반환합니다.

GET /v1/status를 확인해 비전 기능이 활성 상태인지 확인한 다음, 다음 명령으로 활성화되었거나 의도적으로 거부되는 동작을 검증하세요.

python scripts/check_vision.py \
  --base https://<host>.trycloudflare.com/v1 \
  --key <key>

동시성 및 성능 팁

API는 잠금으로 보호되는 하나의 장기 실행 제너레이터를 사용합니다. 따라서 요청은 직렬화됩니다. 여러 스트림은 병렬로 디코딩되지 않고 대기열에 들어갑니다. 1보다 큰 배치 크기는 테스트되지 않았으며, 공개된 측정값은 하나의 슬롯을 사용했습니다.

측정된 실시간 세션 용량은 컨텍스트 길이에 크게 좌우됩니다.

스트림당 500K 토큰: 실시간 세션 1개.
스트림당 262K 토큰: 실시간 세션 2개.
스트림당 131K 토큰: 실시간 세션 5개.
스트림당 32K 토큰: 실시간 세션 11개.
스트림당 16K 토큰: 실시간 세션 14개.

각 실시간 슬롯은 KV 저장 공간을 제외하고 약 546 MiB의 Gated-DeltaNet 상태를 사용합니다. 짧은 컨텍스트에서는 순환 상태가 제한 요소가 되며, 현재 API 잠금으로 요청이 여전히 직렬화되기는 하지만 문서화된 실용적 범위는 대략 8~14개의 실시간 슬롯입니다.

프리필 성능에서는 프로젝트가 확인한 가장 큰 조정 요소가 GCS였습니다. 그러나 더 크거나 변경된 캐시 설정은 그대로 복사하지 말고 VRAM 및 호스트 RAM 사용량을 기준으로 검증해야 합니다.

요청마다 새 Generator를 생성하지 마세요. 페이지 테이블과 CPU 페이지 캐시는 Generator.__init__ 내부에서 생성되므로, 이를 다시 만들면 프롬프트 캐시 재사용이 조용히 폐기되고 프리필이 반복됩니다. 포함된 서버는 이미 올바른 장기 실행 인스턴스를 유지합니다.

문제 해결

CLI에 활성 세션이 없다고 표시됩니다

VM이 여전히 활성 상태이고 요금이 부과되고 있더라도 런타임 프록시 토큰이 만료되면 로컬 세션 기록이 사라질 수 있습니다. VM을 수동으로 다시 만들지 말고 저장소의 복원 절차를 사용하세요. scripts/restore.py는 서버 측 할당을 조회하고 고아가 된 인스턴스에 다시 연결합니다.

모델이 맞지 않습니다

런타임에 약 80 GB의 VRAM이 있고 High-RAM 사양인지 확인하세요. 복원 스크립트는 모델을 로드하기 전에 40 GB 할당을 거부하고 중지하도록 설계되었습니다.

API는 정상인데 공개 URL이 표시되지 않습니다

up.sh는 공개 터널 URL이 없는 정상 VM 상태와 완전한 준비 상태를 구분합니다. 종료 상태 9는 이 경우를 나타냅니다. 엔드포인트에 공개적으로 연결할 수 있다고 가정하지 말고 서비스 및 터널 로그를 확인하세요.

요청이 샘플링 제어를 무시하는 것처럼 보입니다

현재 서버에서 temperature와 top_p에 대해 이는 예상된 동작입니다. 두 값은 파싱되지만 샘플러로 전달되지 않습니다.

스트리밍 호환성이 깨집니다

scripts/dev_stub.py로 문제를 재현한 다음 scripts/check_surface.py를 실행하세요. 실제 핸들러를 테스트하므로 모델을 프로비저닝하지 않고도 프로토콜 회귀를 확인할 수 있습니다.

VM 중지 및 비용 관리

작업을 마치면 요금이 부과되는 런타임을 즉시 중지하세요.

bash scripts/down.sh

이는 프로젝트에서 가장 중요한 비용 관리 명령입니다. 브라우저를 닫거나, 로컬 CLI 기록을 잃거나, Colab 연결을 끊었다고 해서 요금 청구가 중지되었다는 의미는 아닙니다.

선택적 프런트엔드 제어 플레인은 프로비저닝 전 확인, 로컬 CU 원장, 유휴 자동 중지, 최대 세션 지속 시간, 취소 기능, 할당 후 프로비저닝 실패 시 정리 기능을 추가합니다. 카드나 컴퓨팅 유닛 없이 해당 워크플로를 미리 실행해 볼 수 있습니다.

python frontend/server.py --fake-provision
python frontend/server.py --mock
python scripts/dev_stub.py --port 8099 &
python frontend/server.py --mock --backend http://127.0.0.1:8099

결론

collabosm은 올바른 A100 사양 요청, 고아 할당 복구, 호환되는 ExLlamaV3 런타임 설치, 고정된 가중치 로드, 캐시 유지, 보안 터널 노출, 두 가지 OpenAI 호환 API 방언 제공 등 Colab에서 Qwen3.8-Flash-Next를 실행할 때 까다로운 부분을 처리합니다.

bash scripts/up.sh로 시작하고, /v1/status를 통해 실행 중인 구성을 확인한 다음, 출력된 /v1 엔드포인트로 연결하세요. 항상 bash scripts/down.sh로 종료해야 합니다. 프로덕션과 유사한 실험에서는 직렬화된 요청, 구현되지 않은 샘플링 제어, 캐시 메모리 비용, 비전 기능의 선택적 VRAM 사용량, 그리고 유휴 캐시 재개와 실제 라이브 세션 용량의 차이에 특히 주의하세요.