FreeToken Docker環境構築 備忘録

概要

先週AirLLMの記事をまとめていたところFreeTokenの情報をYouTubeで得たので、早速使ってみた。Dockerイメージが公開されていないのでChatGPTと話しながら本機で構築したときのやり取りをまとめた。

• 実施期間: 2026年8月
• 環境：Ubuntu22.04LTS
• FreeToken: v0.1.2
• Docker Engine: v29.7.2
• LLM: nvidia/Qwen3.6-35B-A3B-NVFP4

1. FreeToken用ディレクトリ作成

Docker周りは外付けドライブにまとめているので、全て/media/ihmon/data_disk以下で作業する。

mkdir -p /media/ihmon/data_disk/freetoken-local/project
mkdir -p /media/ihmon/data_disk/freetoken-local/models
mkdir -p /media/ihmon/data_disk/freetoken-local/cache

cd /media/ihmon/data_disk/freetoken-local/project

最終的な構成は以下になる。

/media/ihmon/data_disk/freetoken-local/
├── project/
│   ├── Dockerfile
│   └── compose.yaml
├── models/
│   └── Qwen3.6-35B-A3B-NVFP4/
└── cache/

2. Dockerfile作成

/media/ihmon/data_disk/freetoken-local/project/Dockerfileを作成する。

FROM nvidia/cuda:13.0.0-devel-ubuntu22.04

ENV DEBIAN_FRONTEND=noninteractive
ENV PYTHONUNBUFFERED=1

RUN apt-get update && \
    apt-get install -y \
        python3 \
        python3-pip \
        python3-dev \
        build-essential \
        git \
        curl \
    && rm -rf /var/lib/apt/lists/*

RUN python3 -m pip install --upgrade pip setuptools wheel

RUN python3 -m pip install --no-cache-dir "freetoken[accel]"

WORKDIR /workspace

CMD ["ft", "--help"]

3. FreeToken Docker imageをbuild

cd /media/ihmon/data_disk/freetoken-local/project

docker build -t freetoken-local .

4. NVFP4モデルをダウンロード

かなり時間がかかる。

docker run --rm \
  -v /media/ihmon/data_disk/freetoken-local/models:/models \
  freetoken-local \
  hf download nvidia/Qwen3.6-35B-A3B-NVFP4 \
    --local-dir /models/Qwen3.6-35B-A3B-NVFP4

5. compose.yaml作成

/media/ihmon/data_disk/freetoken-local/project/compose.yamlを作成する。Llama.cppのように量子化bitの指定は現在実装されていない。

services:
  freetoken:
    image: freetoken-local:latest
    container_name: freetoken-qwen36

    ports:
      - "1919:1919"

    volumes:
      - /media/ihmon/data_disk/freetoken-local/models:/models:ro
      - /media/ihmon/data_disk/freetoken-local/cache:/root/.cache

    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

    command:
      - ft
      - serve
      - --model
      - /models/Qwen3.6-35B-A3B-NVFP4
      - --served-model-name
      - Qwen3.6-35B-A3B-NVFP4
      - --host
      - 0.0.0.0
      - --port
      - "1919"
      - --max-running-requests
      - "1"
      - --max-seq-len-override
      - "32768"

6. FreeTokenを起動

cd /media/ihmon/data_disk/freetoken-local/project

docker compose up -d

7. クライアントから接続

VSCode 機能拡張 Continue

Continueから接続する場合、config.yamlへ下記モデルの定義を追加する。

models:
  - name: Qwen3.6-35B-A3B-NVFP4
    provider: openai
    model: Qwen3.6-35B-A3B-NVFP4
    apiBase: http://192.168.10.113:1919/v1
    # apiBase: http://127.0.0.1:1919/v1    # 同じUbuntuマシン上のVSCodeから接続する場合
    apiKey: no-key

    capabilities:
      - tool_use

    roles:
      - chat
      - edit
      - apply

    defaultCompletionOptions:
      contextLength: 32768
      maxTokens: 4096
      temperature: 0.1
      topP: 0.9

Hermes

Hermesから接続する場合、/media/ihmon/data_disk/hermes-local/home/config.yamlへ下記モデルの定義を追加する。Hermesはcontext_lengthが64k以上でなければ起動しないので、ここでは100,000としている。その場合、FreeTokenのmax-seq-len-overrideも合わせて変更すること。

providers:
  local:
    name: Local FreeToken
    api: http://host.docker.internal:1919/v1
    api_key: no-key
    transport: chat_completions
    default_model: Qwen3.6-35B-A3B-NVFP4
    context_length: 100000
    discover_models: true
    models:
      local-model:
        context_length: 100000

KVキャッシュの確保
FreeTokenはmoeにメモリ割当を優先するので、KVキャッシュが枯渇してしまう。するとHermesは長い処理ができずにコンテキストの圧縮が頻繁に発生する。まず、メモリの確保状態をdocker exec -it freetoken-qwen36 ft ctl cacheで確認する。FreeToken起動中に実行してもOK。

state=serving, 17.8 GiB allocated (rebuild budget 17.9 GiB)
  pool size vram resizable to
  moe 10240 slots (lru, 100%) 16.9 GiB 256..10240
  kv 19861 tok (19861 x 1) 387.9 MiB 1..935965 
  mamba 8 slots 491.2 MiB 4..297

Qwen3.6-35B-A3B-NVFP4の場合、40layer x 256routed Expert = 10240 slotsで100%メモリをVRAMに置けていることを示している。17.9GiB中、17.8GiB使用していて余裕がないのでmoeを減らしてKVキャッシュに回す調整を行う。10240slots -> 9000slotsへ減らし、様子を見る。

docker exec -it freetoken-qwen36 ft ctl cache --moe 9000

status=ok
state=serving, 15.7 GiB allocated (rebuild budget 17.9 GiB)
  pool   size                     vram       resizable to
  moe    9000 slots (lru, 87.9%)  14.9 GiB   256..10240
  kv     19861 tok (19861 x 1)    387.9 MiB  1..935965
  mamba  8 slots                  491.2 MiB  4..297

容量が減ったので、その分をKVキャッシュに割当て、context長と同じ量を確保する。
docker exec -it freetoken-qwen36 ft ctl cache --kv 100000

status=ok
state=serving, 17.3 GiB allocated (rebuild budget 17.9 GiB)
  pool   size                     vram       resizable to
  moe    9000 slots (lru, 87.9%)  14.9 GiB   256..10240
  kv     100000 tok (100000 x 1)  1.9 GiB    1..935965
  mamba  8 slots                  491.2 MiB  4..297

Hermesとつなげて問題なければDockerの'compose.yaml'へ反映させること。

command:
  - ft
  - serve
  - --model
  - /models/Qwen3.6-35B-A3B-NVFP4
  - --served-model-name
  - Qwen3.6-35B-A3B-NVFP4
  - --host
  - 0.0.0.0
  - --port
  - "1919"
  - --max-running-requests
  - "1"
  - --max-seq-len-override
  - "100000"
  - --moe-cache-size
  - "9000"
  - --num-tokens
  - "100000"

8. 日常運用

起動

cd /media/ihmon/data_disk/freetoken-local/project
docker compose up -d

停止・コンテナ削除

docker compose down

状態確認

docker compose ps

ログ確認

docker compose logs -f freetoken

9. LAN上のクライアントから接続

OpenAI base URL:
http://192.168.10.113:1919/v1

Model:
Qwen3.6-35B-A3B-NVFP4

API key:
no-key