AI教程

在 Colab A100 上运行 Qwen3.8-Flash-Next，并提供兼容 OpenAI 的 API

了解如何使用 collabosm 配置 Colab A100 高内存运行时，借助 ExLlamaV3 加载 Qwen3.8-Flash-Next，通过 Cloudflare 发布安全 API，连接客户端，在本地测试流式传输，调整缓存，并安全关闭按量计费的虚拟机。

AI我搜编辑部2026年9月26日阅读约 18 分钟

在 Colab A100 上运行 Qwen3.8-Flash-Next，并提供兼容 OpenAI 的 API

collabosm 的功能

collabosm 在单个 Colab A100 80 GB High-RAM 实例上运行 Qwen3.8-Flash-Next。该模型是一个 125B-A6B 混合专家模型，采用混合式 Gated-DeltaNet 与全注意力架构，原生上下文长度为 262,144 个 token。

该项目会配置或恢复 Colab 虚拟机，安装固定版本的 ExLlamaV3 运行时，下载固定版本的模型权重，启动兼容 OpenAI 的 HTTP 服务器，并通过 Cloudflare 隧道将其公开。客户端使用生成的 bearer 密钥，通过隧道 URL 下的 /v1 连接。

ExLlamaV3 是该仓库唯一使用的推理引擎。API 服务器本身由 collabosm 实现，因为 ExLlamaV3 不包含 HTTP 服务器。

主要功能

单 GPU 部署：在单个 A100 80 GB High-RAM 运行时上运行约 63.6 GiB 的显存驻留权重。
兼容 OpenAI 的接口：支持 /v1/chat/completions 和 /v1/responses，包括增量流式传输。
安全恢复 Colab：重新连接孤立的分配，而不是依赖一次性的本地 CLI 会话记录或创建重复的计费虚拟机。
硬件验证：在加载模型前拒绝并停止不兼容的 40 GB A100。
持久化提示缓存：保持一个长期运行的 ExLlamaV3 Generator，使页表和固定 RAM 缓存在请求之间保持有效。
双层缓存设计：结合 GPU KV 容量与可选的固定主机 RAM 缓存，以快速恢复空闲会话。
本地协议测试：提供一个无需 GPU 或模型权重即可调用真实 HTTP 处理程序的模拟引擎。
可选视觉功能：可以加载模型的视觉组件，并接受经过防护的图像输入。
本地客户端和界面：包含终端聊天、浏览器界面、状态页面、从流派生的性能指标，以及一个将上游密钥隐藏在浏览器之外的代理。

项目报告的测量结果包括：对于使用 GCS=8192 的 30K 提示词，预填充速度最高为每秒 3,882 个 token；在 30K 上下文、MTP 深度为 4 时，解码速度为每秒 97.4 个 token；在 114K 上下文时，速度为每秒 90.1 个 token。有关来源和注意事项，请参阅 docs/MEASURED.md，不要将这些数值视为保证。

需求与容量规划

开始前，请确保你的环境满足以下所有要求：

能够分配A100 的 Colab 套餐。
HIGH_RAM 机器类型。标准 40 GB A100 无法加载此模型。
约 110 GiB 的 Colab 磁盘空间，用于存放权重。
Google Colab 命令行工具，使用 uv tool install google-colab-cli 安装。
如果计划复刻或推送该仓库，也可以选择安装 GitHub CLI。

uv tool install google-colab-cli

High-RAM 要求是强制性的。不要通过在硬件输出中搜索“80”来判断适用的显卡，因为即使 A100 只有 40 GB 显存，也可能报告计算能力 sm_80。collabosm 会改为比较报告的 vram_GiB 值。

该项目是在 Colab Pro 套餐上开发的，该套餐每月约提供 200 个计算单元。测得的 A100 High-RAM 成本为每小时 7.52 CU，在所记录的环境中约为每小时 $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 密钥。该密钥也会存储在虚拟机的 /content/api-key.txt 中。

运行时来自一个固定版本的预构建 ExLlamaV3 wheel，与 Colab 的 Python、PyTorch 和 CUDA 环境匹配。权重从 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：固定内存中的第二层 KV 页面缓存；默认为 32 GiB，设为 0 可禁用。
RECURRENT_CACHE_GB：用于存储 Gated-DeltaNet 检查点的主机内存；默认为 24 GiB。
GCS：生成器块大小，也是影响预填充性能的主要控制项；默认为 8192。
NDT：多令牌预测草稿深度；默认为 4。
RUNTIME：使用预构建运行时的 wheel，或使用基于源码配置的 source。
TUNNEL_TOKEN：可选的命名隧道令牌。

主机内存缓存并不是免费的容量。默认 CPU 缓存会完整分配为固定内存，而循环缓存也会占用大量内存。它们会与仓库文档中所述的 36.4 GiB n-gram 表共存。

固定内存层可以缩短空闲会话的恢复时间，这些会话中未被引用的页面曾被驱逐。它不会增加可同时存活的上下文数量，因为存活页面不能像普通交换空间中的页面那样被驱逐。

调用 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，即可在模型解码时接收服务器发送事件。对于聊天补全，流会以 [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 虚拟机，因此仅打开它本身不会消耗计算单元。

如果希望代理注入真实的 bearer 密钥，请将现有的 OpenAI 兼容客户端指向本地代理，而不是虚拟机端点：

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

这种设计将实际密钥保留在本地代理进程中，避免采用宽泛的 CORS 策略，并允许独立于虚拟机更新浏览器界面。

在没有 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

该存根会导入真实的流式处理器，仅替换其引擎片段函数。表层检查器会执行 13 项检查，包括早期增量、终止事件、匹配的 Chat 和 Responses 输出、必需的项目索引以及单调递增的序列号。检查失败时，它会以状态码 1 退出。

向存根命令添加 --think，即可测试推理项目的生命周期。在修改流事件结构或连接 Codex CLI 等严格客户端之前，这尤其有用。

谨慎启用和测试视觉功能

该模型包支持多模态，但视觉功能默认处于禁用状态，因为视觉塔的额外显存开销尚未在这张已高度占用的显卡上完成测量。请显式启用独立的视觉组件：

VISION=1 bash scripts/up.sh

可选的图像控制项包括：

IMAGE_URLS=1
MAX_IMAGE_BYTES=12582912
MAX_IMAGES=8

两种受支持的 API 方言都接受标准的 OpenAI 图像部分。启用视觉功能后，可以使用数据 URL。除非设置 IMAGE_URLS=1，否则远程 HTTP 或 HTTPS 图像 URL 仍处于禁用状态。

{
  "role": "user",
  "content": [
    {"type": "text", "text": "What colour is this image?"},
    {
      "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 个 token：1 个活动会话。
每个流 262K 个 token：2 个活动会话。
每个流 131K 个 token：5 个活动会话。
每个流 32K 个 token：11 个活动会话。
每个流 16K 个 token：14 个活动会话。

每个活动槽位在 KV 存储之前约消耗 546 MiB 的 Gated-DeltaNet 状态。对于较短的上下文，循环状态会成为限制因素；实际文档记录的范围大约为 8 到 14 个活动槽位，不过当前 API 锁仍会将请求串行处理。

就预填充性能而言，项目发现 GCS 是影响最大的参数。不过，应根据显存和主机内存的使用情况验证更大或经过修改的缓存设置，而不是盲目照搬。

避免为每个请求构造新的 Generator。页表和 CPU 页缓存都在 Generator.__init__ 中创建；重新构造会悄悄丢弃提示缓存复用，并迫使系统重复预填充。随附的服务器已经维护了正确的长生命周期实例。

故障排除

CLI 提示没有活动会话

即使虚拟机仍处于活动状态并持续计费，本地会话记录也可能在运行时代理令牌过期时消失。请使用仓库提供的恢复流程，而不要手动创建另一台虚拟机。scripts/restore.py 会查询服务器端分配信息，并重新连接已孤立的实例。

模型无法装入

确认运行时拥有大约 80 GB 显存，并且使用的是 High-RAM 规格。恢复脚本会在加载模型前拒绝并停止 40 GB 的分配。

API 状态正常，但没有出现公共 URL

up.sh 会区分“虚拟机状态正常但没有已发布隧道 URL”和完全就绪这两种情况。退出状态 9 表示前一种情况。请检查服务和隧道日志，不要假定端点已可从公网访问。

请求似乎忽略了采样控制项

在当前服务器中，temperature 和 top_p 出现这种情况是预期行为。它们会被解析，但不会转发给采样器。

流式兼容性出现问题

使用 scripts/dev_stub.py 重现问题，然后运行 scripts/check_surface.py。测试针对的是真实处理器，因此无需配置模型即可捕获协议回归。

停止虚拟机并控制成本

完成后，请立即停止按量计费的运行时：

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 将在 Colab 上运行 Qwen3.8-Flash-Next 的复杂部分打包处理：请求正确的 A100 规格、恢复孤立的分配、安装匹配的 ExLlamaV3 运行时、加载固定版本的权重、保留缓存、公开受保护的隧道，并提供两种兼容 OpenAI 的 API 方言。

使用 bash scripts/up.sh 启动，通过 /v1/status 验证实时配置，使用打印出的 /v1 端点连接，并始终以 bash scripts/down.sh 结束。对于接近生产环境的实验，请特别注意请求串行化、尚未实现的采样控制、缓存的内存成本、视觉功能可选的显存占用，以及空闲缓存恢复与真正的实时会话容量之间的区别。