Chuyển đến nội dung chính
Hướng dẫn AI

Chạy Qwen3.8-Flash-Next trên Colab A100 với API tương thích OpenAI

Tìm hiểu cách dùng collabosm để cấp runtime Colab A100 High-RAM, tải Qwen3.8-Flash-Next bằng ExLlamaV3, công khai API bảo mật qua Cloudflare, kết nối các client, kiểm thử streaming cục bộ, tinh chỉnh bộ nhớ đệm và tắt VM tính phí an toàn.

Thời gian đọc khoảng 33 phút
Chạy Qwen3.8-Flash-Next trên Colab A100 với API tương thích OpenAI

collabosm thực hiện những gì

collabosm chạy Qwen3.8-Flash-Next trên một phiên bản Colab A100 80 GB High-RAM duy nhất. Mô hình này là mô hình mixture-of-experts 125B-A6B với kiến trúc kết hợp Gated-DeltaNet và full-attention, cùng độ dài ngữ cảnh gốc là 262.144 token.

Dự án cấp phát hoặc khôi phục máy ảo Colab, cài đặt runtime ExLlamaV3 đã cố định phiên bản, tải các trọng số mô hình đã cố định phiên bản, khởi chạy máy chủ HTTP tương thích OpenAI và công khai máy chủ qua một đường hầm Cloudflare. Client kết nối đến URL đường hầm dưới đường dẫn /v1 bằng bearer key được tạo tự động.

ExLlamaV3 là engine suy luận duy nhất được repository sử dụng. Máy chủ API do chính collabosm triển khai vì ExLlamaV3 không tích hợp máy chủ HTTP.

Tính năng chính

  • Triển khai trên một GPU: chạy khoảng 63,6 GiB trọng số nằm trong VRAM trên một runtime A100 80 GB High-RAM.
  • Giao diện tương thích OpenAI: hỗ trợ cả /v1/chat/completions và /v1/responses, bao gồm streaming tăng dần.
  • Khôi phục Colab an toàn: kết nối lại các assignment mồ côi thay vì tin vào các bản ghi phiên CLI cục bộ tạm thời hoặc tạo các máy ảo tính phí trùng lặp.
  • Xác thực phần cứng: từ chối và dừng A100 không tương thích 40 GB trước khi tải mô hình.
  • Bộ nhớ đệm prompt liên tục: duy trì một Generator ExLlamaV3 hoạt động lâu dài để page table và bộ nhớ đệm pinned-RAM được giữ lại giữa các request.
  • Thiết kế bộ nhớ đệm hai tầng: kết hợp dung lượng KV trên GPU với bộ nhớ đệm host-RAM pinned tùy chọn để nhanh chóng tiếp tục các cuộc hội thoại đang nhàn rỗi.
  • Kiểm thử giao thức cục bộ: cung cấp engine giả để kiểm tra HTTP handler thực mà không cần GPU hoặc trọng số mô hình.
  • Vision tùy chọn: có thể tải thành phần vision của mô hình và tiếp nhận các đầu vào hình ảnh được kiểm soát.
  • Client và giao diện cục bộ: bao gồm chat trên terminal, giao diện trình duyệt, các trang trạng thái, chỉ số hiệu năng suy ra từ stream và proxy giúp giữ upstream key ngoài trình duyệt.

Các phép đo được dự án báo cáo gồm tối đa 3.882 token prefill mỗi giây với prompt 30K và GCS=8192, 97,4 token decode mỗi giây với MTP depth 4 ở ngữ cảnh 30K và 90,1 token mỗi giây ở ngữ cảnh 114K. Hãy xem docs/MEASURED.md để biết nguồn gốc và các lưu ý, thay vì coi những con số này là mức đảm bảo.

Yêu cầu và lập kế hoạch dung lượng

Trước khi bắt đầu, hãy đảm bảo môi trường của bạn đáp ứng tất cả yêu cầu sau:

  • Một gói Colab có khả năng cấp phát A100.
  • Kiểu máy HIGH_RAM. A100 40 GB tiêu chuẩn không thể tải mô hình này.
  • Khoảng 110 GiB dung lượng ổ đĩa Colab cho các trọng số.
  • Công cụ dòng lệnh Google Colab, được cài đặt bằng uv tool install google-colab-cli.
  • Tùy chọn: GitHub CLI nếu bạn dự định fork hoặc push repository.
uv tool install google-colab-cli

Yêu cầu High-RAM là bắt buộc. Không xác định card phù hợp bằng cách tìm “80” trong thông tin phần cứng, vì A100 có thể báo compute capability sm_80 ngay cả khi chỉ có 40 GB VRAM. Thay vào đó, collabosm so sánh giá trị vram_GiB được báo cáo.

Dự án được phát triển trên gói Colab Pro với khoảng 200 compute unit mỗi tháng. Chi phí A100 High-RAM đo được là 7,52 CU mỗi giờ, tương đương khoảng 0,75 USD mỗi giờ trong môi trường được ghi nhận. Giá và khả năng cấp phát có thể thay đổi độc lập với repository.

Khởi động máy chủ

1. Mở thư mục repository

Tải xuống hoặc clone repository collabosm, sau đó chạy các lệnh sau từ thư mục gốc. Các script sử dụng những đường dẫn tương đối với repository như scripts/up.sh, scripts/bootstrap.sh và scripts/serve.sh.

2. Cấp phát, bootstrap và phục vụ

bash scripts/up.sh

Lệnh duy nhất này sẽ khôi phục assignment hiện có nếu có thể hoặc tạo một assignment High-RAM mới, tải project lên, cài đặt runtime đã cố định phiên bản, tải các trọng số đã cố định phiên bản, khởi chạy API, mở đường hầm Cloudflare và chờ kiểm tra health thành công.

Lệnh gọi thành công chỉ thoát với trạng thái 0 sau khi cả API và URL đường hầm công khai đều sẵn sàng. Lệnh sẽ in URL đường hầm và API key. Key cũng được lưu trên máy ảo tại /content/api-key.txt.

Runtime được chọn từ một wheel ExLlamaV3 dựng sẵn đã cố định phiên bản, tương thích với môi trường Python, PyTorch và CUDA của Colab. Các trọng số được tải từ Hugging Face tại một revision đã cố định. Nếu đường tải xuống Xet bị treo, README xác định HF_HUB_DISABLE_XET=1 là phương án dự phòng.

3. Ghi lại các thông tin kết nối

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

Tên máy chủ quick tunnel có thể thay đổi giữa các lần khởi chạy. Để có tên máy chủ ổn định, hãy cấu hình đường hầm Cloudflare được đặt tên với TUNNEL_TOKEN và kết hợp với PUBLIC_URL cho địa chỉ hiển thị trong thông tin trạng thái.

4. Kiểm tra cấu hình đang chạy

Gửi request GET /v1/status để xem các tham số mà tiến trình đang chạy thực sự nhận được, bao gồm cài đặt bộ nhớ đệm, tham số khởi chạy, thời gian hoạt động, khả năng vision và chính sách đầu vào hình ảnh.

Repository lưu ý rằng chưa phải tất cả các giá trị mặc định hiện tại đã được xác minh khi kết hợp với nhau. Hãy kiểm tra endpoint trạng thái trực tiếp và xem docs/MEASURED.md trước khi cho rằng một tổ hợp cụ thể đã được xác thực.

Cấu hình bộ nhớ đệm và quá trình tạo

Tất cả các tùy chọn khởi chạy chính đều là biến môi trường được truyền vào scripts/up.sh. Ví dụ:

SESSION=mybox CACHE_SIZE=524288 CPU_CACHE_GB=8 bash scripts/up.sh
  • SESSION: tên phiên cục bộ; mặc định là collabosm.
  • CACHE_SIZE: tổng số token KV trên tất cả các tác vụ; mặc định là 500224 và phải là bội số của 256.
  • CACHE_QUANT: độ rộng bit của bộ nhớ đệm KV; mặc định là 4, cho phép các giá trị từ 2 đến 8.
  • CPU_CACHE_GB: bộ nhớ đệm trang KV tầng hai trong RAM được ghim; mặc định là 32 GiB, đặt 0 để tắt.
  • RECURRENT_CACHE_GB: dung lượng RAM máy chủ dành cho các điểm kiểm tra Gated-DeltaNet; mặc định là 24 GiB.
  • GCS: kích thước khối của trình tạo và là tùy chọn kiểm soát quan trọng đối với hiệu năng prefill; mặc định là 8192.
  • NDT: độ sâu dự đoán bản nháp đa token; mặc định là 4.
  • RUNTIME: wheel để dùng runtime dựng sẵn hoặc source để thiết lập dựa trên mã nguồn.
  • TUNNEL_TOKEN: token đường hầm có tên, tùy chọn.

Bộ nhớ đệm trong RAM máy chủ không phải là dung lượng miễn phí. Bộ nhớ đệm CPU mặc định được cấp phát toàn bộ dưới dạng bộ nhớ ghim, đồng thời bộ nhớ đệm recurrent cũng tiêu tốn lượng RAM đáng kể. Chúng tồn tại cùng với bảng n-gram 36.4 GiB được tài liệu của kho mã mô tả.

Tầng RAM được ghim giúp cải thiện thời gian tiếp tục của các cuộc trò chuyện không hoạt động mà các trang không được tham chiếu đã bị loại bỏ. Tầng này không làm tăng số ngữ cảnh có thể hoạt động đồng thời, vì các trang đang hoạt động không thể bị loại bỏ như thể RAM máy chủ là vùng hoán đổi thông thường.

Gọi API tương thích với OpenAI

Liệt kê mô hình

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

Endpoint trả về một mã định danh mô hình duy nhất là qwen3.8-flash-next-exl3. Tuyến API này yêu cầu xác thực, trong khi /health không yêu cầu xác thực và trả về ok dạng văn bản thuần.

Tạo bản hoàn tất cuộc trò chuyện

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
  }'

Giao diện chat trả về nội dung trong choices[].message.content, lý do kết thúc là stop hoặc length, cùng thông tin sử dụng có thể bao gồm số token prompt được lưu trong bộ nhớ đệm.

Phát trực tuyến bản hoàn tất

Đặt stream thành true để nhận Server-Sent Events trong khi mô hình giải mã. Đối với bản hoàn tất cuộc trò chuyện, luồng kết thúc bằng [DONE]. Đặt stream_options.include_usage để yêu cầu dữ liệu sử dụng trong phản hồi phát trực tuyến.

{
  "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
}

Endpoint /v1/responses cũng hỗ trợ phát trực tuyến. Chuỗi sự kiện của endpoint này bao gồm các sự kiện tạo, tiến trình, mục đầu ra, phần nội dung, delta văn bản, hoàn tất và phản hồi kết thúc. Mỗi sự kiện được phát trực tuyến đều mang sequence_number tăng đơn điệu, trong khi các delta mang chỉ mục mục và nội dung mà client cần để liên kết chúng chính xác.

Sử dụng chế độ suy luận

Chế độ suy luận mặc định bị tắt để tương thích với các client chat thông thường. Bật chế độ này bằng enable_thinking: true hoặc bằng giá trị reasoning_effort được hỗ trợ là xhigh, medium hoặc low. Trên giao diện chat, chuỗi suy luận được trả về riêng trong message.reasoning_content và không bị đưa vào trường nội dung thông thường.

temperature và top_p được chấp nhận nhưng hiện bị bỏ qua vì máy chủ tạo các tác vụ với sampler=None. Các tùy chọn suy luận, max_tokens và chuỗi dừng vẫn hoạt động.

Sử dụng client đi kèm

Client collabosm.py cục bộ chỉ sử dụng thư viện chuẩn Python và không cần cài đặt riêng. Khởi tạo cấu hình bằng endpoint đường hầm và khóa được tạo:

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

Sau đó, bạn có thể trò chuyện từ terminal hoặc khởi chạy giao diện trình duyệt cục bộ:

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

ui cung cấp trang và proxy tại http://127.0.0.1:8790. start mở các cửa sổ chat và trạng thái. Client cố ý không khởi động hoặc dừng máy ảo Colab, vì vậy việc mở client không tự tiêu tốn đơn vị tính toán.

Khi muốn proxy chèn khóa bearer thực, hãy cung cấp cho client tương thích với OpenAI endpoint proxy cục bộ thay vì endpoint máy ảo:

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

Thiết kế này giữ khóa thực bên trong tiến trình proxy cục bộ, tránh chính sách CORS quá rộng và cho phép cập nhật giao diện trình duyệt độc lập với máy ảo.

Kiểm thử giao thức không cần GPU

Sử dụng stub phát triển để xác thực hành vi yêu cầu và phát trực tuyến mà không phải trả phí cho A100 hoặc tải trọng số:

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

Stub nhập trình xử lý vận chuyển thực và chỉ thay thế hàm xử lý mảnh engine của nó. Bộ kiểm tra giao diện thực hiện 13 lần kiểm tra, bao gồm các delta ban đầu, sự kiện kết thúc, đầu ra chat và Responses tương ứng, các chỉ mục item bắt buộc và số thứ tự tăng đơn điệu. Bộ kiểm tra thoát với trạng thái 1 khi một lần kiểm tra thất bại.

Thêm --think vào lệnh stub để kiểm tra vòng đời của reasoning-item. Điều này đặc biệt hữu ích trước khi thay đổi dạng sự kiện stream hoặc kết nối các client nghiêm ngặt như Codex CLI.

Bật và kiểm tra vision cẩn thận

Gói model hỗ trợ đa phương thức, nhưng vision bị tắt theo mặc định vì chưa đo được chi phí VRAM bổ sung của vision tower trên card vốn đã được sử dụng gần hết. Hãy bật riêng thành phần vision một cách rõ ràng:

VISION=1 bash scripts/up.sh

Các tùy chọn hình ảnh bổ sung gồm:

IMAGE_URLS=1
MAX_IMAGE_BYTES=12582912
MAX_IMAGES=8

Cả hai dialect API được hỗ trợ đều chấp nhận các image part tiêu chuẩn của OpenAI. Data URL được chấp nhận khi vision được bật. URL hình ảnh HTTP hoặc HTTPS từ xa vẫn bị tắt trừ khi có IMAGE_URLS=1.

{
  "role": "user",
  "content": [
    {"type": "text", "text": "What colour is this image?"},
    {
      "type": "image_url",
      "image_url": {"url": "data:image/png;base64,..."}
    }
  ]
}

Khi URL từ xa được bật, server phân giải hostname và yêu cầu mọi địa chỉ phải có thể định tuyến toàn cục. Server từ chối các địa chỉ loopback, private, link-local và metadata, đồng thời không theo chuyển hướng. Đường dẫn hệ thống tệp không bao giờ được chấp nhận. Nếu không thể nhúng hình ảnh, server trả về lỗi JSON 400 với type vision_unavailable thay vì âm thầm bỏ qua hình ảnh.

Kiểm tra GET /v1/status để biết vision có đang hoạt động hay không, sau đó xác minh hành vi được bật hoặc bị từ chối có chủ đích bằng:

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

Mẹo về đồng thời và hiệu năng

API sử dụng một generator chạy lâu dài được bảo vệ bằng lock. Do đó, các request được tuần tự hóa: nhiều stream được xếp hàng thay vì giải mã song song. Batch size lớn hơn một chưa được kiểm thử, và các phép đo đã công bố sử dụng một slot.

Dung lượng phiên trực tiếp đo được phụ thuộc nhiều vào độ dài context:

  • 500K token mỗi stream: 1 phiên trực tiếp.
  • 262K token mỗi stream: 2 phiên trực tiếp.
  • 131K token mỗi stream: 5 phiên trực tiếp.
  • 32K token mỗi stream: 11 phiên trực tiếp.
  • 16K token mỗi stream: 14 phiên trực tiếp.

Mỗi slot trực tiếp tiêu thụ khoảng 546 MiB trạng thái Gated-DeltaNet trước phần lưu trữ KV. Với context ngắn, trạng thái hồi quy trở thành yếu tố giới hạn; phạm vi thực tế được ghi nhận là khoảng 8 đến 14 slot trực tiếp, mặc dù các request vẫn được tuần tự hóa bởi lock API hiện tại.

Đối với hiệu năng prefill, GCS là đòn bẩy lớn nhất mà dự án tìm thấy. Tuy nhiên, cần kiểm tra các thiết lập cache lớn hơn hoặc đã thay đổi dựa trên mức sử dụng VRAM và RAM máy chủ, thay vì sao chép một cách máy móc.

Tránh tạo một Generator mới cho mỗi request. Page table và CPU page cache được tạo bên trong Generator.__init__; việc dựng lại chúng sẽ âm thầm loại bỏ khả năng tái sử dụng prompt-cache và buộc phải prefill lặp lại. Server đi kèm đã duy trì đúng instance chạy lâu dài.

Khắc phục sự cố

CLI báo không có phiên hoạt động

Bản ghi phiên cục bộ có thể biến mất khi token proxy runtime hết hạn, dù VM vẫn hoạt động và vẫn tính phí. Hãy dùng quy trình khôi phục của repository thay vì tự tạo một VM khác. scripts/restore.py truy vấn các assignment phía server và gắn lại instance bị mồ côi.

Model không vừa

Hãy xác nhận runtime có khoảng 80 GB VRAM và thuộc loại High-RAM. Script khôi phục được thiết kế để từ chối và dừng assignment 40 GB trước khi tải model.

API hoạt động bình thường nhưng không xuất hiện URL công khai

up.sh phân biệt VM hoạt động bình thường nhưng chưa có URL tunnel được công bố với trạng thái sẵn sàng hoàn toàn. Trạng thái thoát 9 cho biết trường hợp này. Hãy kiểm tra log serving và tunnel thay vì cho rằng endpoint đã có thể truy cập công khai.

Request dường như bỏ qua các điều khiển sampling

Đây là hành vi dự kiến đối với temperature và top_p trong server hiện tại. Chúng được phân tích nhưng không được chuyển tiếp đến sampler.

Khả năng tương thích streaming bị lỗi

Tái hiện vấn đề bằng scripts/dev_stub.py, sau đó chạy scripts/check_surface.py. Trình xử lý thực được đưa vào kiểm thử, nhờ đó có thể phát hiện hồi quy giao thức mà không cần cấp phát model.

Dừng VM và kiểm soát chi phí

Khi hoàn tất, hãy dừng ngay runtime tính phí:

bash scripts/down.sh

Đây là lệnh kiểm soát chi phí quan trọng nhất của dự án. Đóng trình duyệt, mất bản ghi CLI cục bộ hoặc ngắt kết nối khỏi Colab không chứng minh rằng việc tính phí đã dừng.

Control plane frontend tùy chọn bổ sung bước xác nhận trước khi cấp phát, sổ cái CU cục bộ, tự động dừng khi không hoạt động, thời lượng phiên tối đa, tính năng hủy và dọn dẹp khi cấp phát thất bại sau khi đã assignment. Bạn có thể diễn tập quy trình đó mà không cần thẻ hoặc compute unit:

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

Kết luận

collabosm đóng gói các phần khó khi chạy Qwen3.8-Flash-Next trên Colab: yêu cầu đúng cấu hình A100, khôi phục các phân bổ bị bỏ lại, cài đặt runtime ExLlamaV3 tương thích, tải các trọng số đã được ghim phiên bản, duy trì bộ nhớ đệm, mở một đường hầm được bảo mật và cung cấp hai giao thức API tương thích với OpenAI.

Bắt đầu bằng bash scripts/up.sh, xác minh cấu hình đang hoạt động qua /v1/status, kết nối thông qua endpoint /v1 được in ra và luôn kết thúc bằng bash scripts/down.sh. Để thử nghiệm gần với môi trường production, hãy đặc biệt chú ý đến các yêu cầu được xử lý tuần tự, những điều khiển lấy mẫu chưa được triển khai, chi phí bộ nhớ của bộ nhớ đệm, mức tiêu thụ VRAM tùy chọn của khả năng xử lý hình ảnh và sự khác biệt giữa việc tiếp tục từ bộ nhớ đệm khi không hoạt động với năng lực phiên trực tiếp thực sự.