从文件到实际可用的模型
回顶部 ↑
部署现场档案 · 2026 / 10 / 13

把模型
真正运行起来。

下载得到权重,加载建立计算,服务连接应用。
从你这次 Qwen3.8-27B 部署开始,把每一步讲清楚。

云端自托管实战Windows / Linux / MacAndroid / iOSGGUF / PTH / Safetensors
你的这次结果RTX 3090 · Q8_0 · 52 GPU 层 · 8.12 tokens/s 短回答样本
先看懂,再动手

01阅读地图与结论

这是一份从一次真实部署出发的操作手册:记录你在 2026 年 10 月 13 日通过 AutoDL 部署 Qwen3.8-27B Q8_0 的完整过程,再扩展到 Windows、Linux、Mac、云服务器与手机。你发来的 15 张原始截图全部内嵌在这个 HTML 中,断网后仍可阅读和放大;外部官方资料链接需要联网。

优先读法: 想接着使用已部署的模型,直接看“日常启动、停止与连接”;想理解下载后怎么运行,先读“模型下载后怎么加载”;想换电脑或手机,按对应平台教程走;遇到问题,查“分层排错”。侧边目录可整体收起,也可逐组展开,搜索会筛选包含关键词的章节。

本次实测路线是 云端自托管模型 + Windows 本机远程访问。GPU 在 AutoDL 的 Linux 实例里,不在你的 Windows 笔记本里。浏览器地址是 127.0.0.1,是因为 SSH 把云端服务转发到了本机。

已验证项目最终结果
模型文件Qwen3.8-27B-Q8_0.gguf,来自 unsloth/Qwen3.8-27B-GGUF
执行设备AutoDL RTX 3090 24GB,14 核 CPU,90GB 内存
推理引擎自行编译的 CUDA 版 llama.cpp
执行方式52 层在 GPU,其余部分由 CPU 承担;后台 nohup 运行
上下文 / 并发4096 tokens / 1 个并行槽位
服务 / 本机网页云端 127.0.0.1:8080;Windows 127.0.0.1:18080
API / 模型别名http://127.0.0.1:18080/v1;qwen3.8-27b
显存40 层约 16.2GiB;52 层约 20.8GiB
短回答生成速度约 5.18 → 8.12 tokens/秒,提升约 57%

证据边界: AutoDL 路线已实际运行并核验。其他路线是按官方资料整理的教程,没有在你的 Windows 本机 GPU、Mac 或手机上实测。软件版本、模型支持与平台菜单会变化,文中的官方链接是复核入口;“示例模型”不代表推荐永远固定在某一代。

云端资产Q8_0 GGUF数据盘上的权重
→
云端执行llama.cpp3090 + CPU 混合
→
云端服务8080 / API模型与网页
→
网络转发SSH 隧道Windows 本机 18080
→
本机使用浏览器 / 客户端推理仍在云端
先看懂,再动手

02部署究竟部署了什么

一个聊天模型可拆成六层:模型权重 → 模型配置与分词器 → 推理运行时 → 服务接口 → 聊天应用 → 网络连接。下载只是得到第一层及配套文件;加载是让运行时建立计算结构、读取权重、分配内存并准备执行;提供 API 是把执行过程包装成可访问的服务;网页只是人机交互入口。

例如本次:GGUF 是模型文件;llama.cpp 负责计算;llama-server 提供 HTTP 接口并承载网页;Edge 显示界面;SSH 转发连接两台机器。没有任何一个单独的文件后缀能够替代全部这些环节。

方式模型在哪里计算你主要维护什么典型用途
完全本地部署自己的电脑 CPU/GPU/统一内存驱动、文件、运行软件离线个人聊天、隐私数据实验
云端自托管租来的 GPU 实例同上,再加网络、存储与计费大模型、临时实验、自己的 API
托管端点 / Serverless平台管理的计算实例模型配置、镜像或处理函数按需扩缩容、团队服务
调用厂商 API厂商或聚合平台API Key、调用代码、额度快速集成,不下载权重
手机端侧运行手机 CPU/GPU/NPUApp、支持的格式与资源预算离线便携、小模型应用
手机访问远程模型电脑或云服务器安全网络入口与手机客户端在手机使用大模型
浏览器内推理浏览器所在设备,例如 WebGPU浏览器兼容性、缓存、模型资产无安装演示、小模型体验

本地部署不自动意味着“永不联网”:首次下载、更新、插件、联网搜索或外部工具仍可能访问网络。云端自托管意味着推理由你控制,但数据仍在租用的云端机器上。

先看懂,再动手

03必须分清的基础概念

参数与 B: 27B 通常表示约 270 亿参数,是规模,不是 27GB,也不是显存需求。参数总量影响权重体积,实际运行还要看量化、结构、上下文和并发。MoE 模型的“总参数”和“每 token 激活参数”不同:激活少可以省计算,却不等于只需装入激活的那一小部分权重。

Token: 分词器处理的单位,不严格等于一个汉字或一个英文单词。文本、代码、标点乃至图像相关输入的计数方式取决于模型。上下文预算通常包含历史消息、系统提示、工具内容和输出;4096 tokens 不是“能无限聊天,只限制最新一句”。

训练 / 微调 / 推理: 训练与微调要计算梯度,并可能保存优化器状态,资源需求通常更高。推理用已有参数产生输出。本次没有训练模型、没有改变权重;把 GPU 层数从 40 改为 52 只是改变权重与计算的放置位置。

显存 / 内存 / 磁盘: 显存供 GPU 使用,内存供 CPU 使用,磁盘保存文件。50GB 数据盘不能替代 50GB 显存;90GB 系统内存可以帮助混合运行,但 CPU 内存带宽和计算速度与 GPU 不同。Apple Silicon 的统一内存由 CPU/GPU 共享,也不能把标称内存全部留给模型。

驱动 CUDA 版本 / Toolkit 版本: nvidia-smi 中的 CUDA Version 反映驱动支持的 CUDA 能力;nvcc --version 反映安装的编译工具。截图里前者是 13.0,后者是 12.8,它们不同并不自动说明安装错误。

模型能力 / 部署能力: 模型本身支持图像,不代表当前服务已经能接收并正确处理图像。本次完成的是文本聊天链路;多模态通常还需要视觉投影文件、处理器及对应运行时支持。

先看懂,再动手

04模型文件:GGUF、PTH、Safetensors 有什么区别

本章小节
GGUF:面向推理的文件容器PTH / PT:PyTorch 保存对象或权重的常见后缀Safetensors:安全性与高效读取导向的张量存储其他经常出现的格式

GGUF:面向推理的文件容器

GGUF 是 GGML/llama.cpp 生态使用的模型文件格式,容纳张量及元数据。它常与量化模型一起出现,也能保存非量化或较高精度张量。它不是“某一个 AI 模型”,不是“必然 4-bit”,也不是可以直接双击执行的程序。运行时仍须实现该模型的网络结构与算子。

常见 GGUF 会携带架构信息、张量、分词相关元数据及聊天模板,因此单文件使用比较方便。但大型模型可能分片,多模态可能另带 mmproj;具体以仓库说明为准。Q8_0 是量化类型,不是 GGUF 的同义词。GGUF 工具与格式入口 ↗

PTH / PT:PyTorch 保存对象或权重的常见后缀

.pth 与 .pt 常用来命名 torch.save 产生的文件,但后缀并不严格规定里面是什么。它可能是 state_dict、包含优化器等信息的 checkpoint、整个 Python 模型对象;某些 .pt 也可能是 TorchScript 导出物。看到一个 .pth,不能仅凭文件名判断它能否直接聊天。

state_dict 大体是“参数名 → 张量”的映射。要运行它,你往往还需要创建匹配的模型类,加载参数,并准备一致的输入预处理或分词器。原始对象反序列化可能依赖 Python 代码;只加载可信来源,优先采用当前 PyTorch 推荐的权重加载方式。PyTorch 保存与加载 ↗

Safetensors:安全性与高效读取导向的张量存储

.safetensors 保存张量数据,不通过 Pickle 保存任意 Python 对象,降低了权重文件反序列化执行代码的风险。不过它不自动包含完整推理应用:Transformers 模型通常是一个文件夹,包含 config.json、分词器文件和一个或多个权重分片;量化配置也可能在配置文件里。安全的权重格式不等于仓库里的所有代码、模型输出或外部工具都安全。Safetensors 官方说明 ↗

项目GGUFPTH / PTSafetensors
核心用途便捷分发与推理,尤其量化PyTorch 权重、checkpoint 或对象张量存储,HF 模型常用
是否自动是量化否;需要看张量类型否否;须看量化方案与配置
常见加载者llama.cpp、支持架构的 Ollama / LM StudioPyTorch / 匹配模型代码Transformers、支持的 vLLM / SGLang 等
是否常需附加配置元数据常内嵌;多模态或分片另看说明通常需要模型定义及预处理通常需要整个模型目录
适合训练恢复吗通常不是主流训练 checkpoint 选择常用,可含优化器状态常用于训练权重与发布
能通过改后缀转换吗不能不能不能

其他经常出现的格式

后缀 / 名称含义与适用范围
.bin泛用二进制后缀,可能是旧 HF PyTorch 权重,也可能完全是别的数据;先看仓库说明
.ckpt“检查点”的命名约定,内部格式由框架决定;不保证是单纯权重
.onnxONNX 计算图与参数,通常需 ONNX Runtime 或兼容后端及预处理
.engine / .plan常见 TensorRT 引擎文件;硬件与软件版本兼容性比普通权重更敏感
.tflite / .litertlmLiteRT 等端侧生态使用的模型或 LLM 资产格式,并非直接可导入任意 GGUF App
.mlmodel / .mlpackageApple Core ML 模型及其打包方式,通常经转换并由 App 调用
.pteExecuTorch 执行程序文件,需要对应 runtime 和支持的后端
adapter_model.safetensors常见 LoRA 适配器权重,通常还要配合正确的基础模型

ONNX、端侧编译格式和适配器都不能靠重命名变成 GGUF。ONNX Runtime ↗ · ExecuTorch ↗ · LiteRT-LM ↗

先看懂,再动手

05下载的是一个文件,还是完整模型目录

打开下载目录,先判断你拿到什么。不要把目录名、模型别名、远程仓库名与本地文件路径混成一个概念。

text
# GGUF 例子:本次文本模型
models/Qwen3.8-27B/
└── Qwen3.8-27B-Q8_0.gguf

# Transformers 目录示意,不同模型文件名可能不同
models/example-model/
├── config.json
├── tokenizer_config.json
├── tokenizer.json 或词表相关文件
├── generation_config.json(有时存在)
├── model.safetensors
└── 或 model-00001-of-0000N.safetensors 等分片
    以及 model.safetensors.index.json

# LoRA:这通常不是完整基础模型
adapter/
├── adapter_config.json
└── adapter_model.safetensors

完整目录通常告诉框架如何建立结构、如何切分输入、到哪里找分片。只下载分片中的一个,或只复制一个 safetensors 文件到空目录,通常无法正确加载。多模态目录还可能包含 processor、图像处理、音视频相关配置;具体以模型卡为准。

“模型下载完成”至少检查三件事:下载工具明确报告成功;文件尺寸与仓库一致;配套文件完整。严格完整性验证可以进一步比较官方 SHA-256 或工具支持的校验值。文件看起来很大也可能是预分配的未完成文件;仅看 ls 的大小不是强校验。

先看懂,再动手

06模型下载后怎么加载:从文件到回答

本章小节
第一步:选择与文件和架构匹配的加载软件第二步:指定准确的路径与运行设备第三步:运行时完成真正的“加载”第四步:准备输入并生成第五步:选择使用入口第六步:确认不是“只下载好了”

第一步:选择与文件和架构匹配的加载软件

GGUF → 先选 llama.cpp、Ollama 或 LM Studio;标准 HF 模型目录 → 选 Transformers,或者该模型被 vLLM / SGLang 支持的服务路线;PTH → 找原项目的模型类与加载代码;手机编译模型 → 使用对应 App / SDK。支持 GGUF 这个格式,不代表支持每一种 GGUF 内部架构。

第二步:指定准确的路径与运行设备

检查文件是在本机还是服务器。Windows 路径如 C:\Models\model.gguf 与 Linux 路径 /root/autodl-tmp/models/model.gguf 不可互换。路径含空格要加引号。服务端加载的路径是服务端磁盘路径,浏览器不能替服务器读取你电脑上的任意文件。

第三步:运行时完成真正的“加载”

运行时读取配置与权重,创建结构,把部分或全部张量放到 CPU/GPU,建立 KV cache 或其他模型状态,并可能做一次预热。这时会产生内存与显存占用。文件仍留在磁盘;加载没有“消耗掉”或训练它。

第四步:准备输入并生成

分词器把文本变成 token;聊天模板把 system/user/assistant 消息组织为模型训练时习惯的格式;推理引擎计算后按采样参数逐个生成 token;最后再解码成文字。直接把用户文字拼接给错误模板,即使能运行也可能回答异常。

第五步:选择使用入口

入口你怎么操作适合谁
桌面 App下载/导入 → Load/加载 → Chat/聊天想直接使用模型的人
命令行llama-cli 等命令加载并在终端问答验证、脚本、学习运行过程
Pythonfrom_pretrained 或 load_state_dict,再 generate / forward开发者、研究与定制预处理
API 服务启动服务器 → 客户端发 HTTP 请求多个程序、网页、聊天客户端
移动 App选择兼容模型 → 下载/导入 → 加载 → 对话手机离线使用

第六步:确认不是“只下载好了”

看加载日志、进程与资源使用;调用健康接口;发送一个小问题;检查实际答案和结束原因。健康接口返回 ok 只证明服务就绪,不证明答案质量;一次回答成功也不证明长上下文、图像、工具调用和多人并发都已验证。

先看懂,再动手

07模型的生命周期:下载、加载、卸载与删除

“模型在不在”至少有三种状态:磁盘里有资产、内存里有权重、网络上有服务。它们可以独立变化。下面按你最常做的动作区分:

动作改变什么通常还保留什么怎么确认
下载 / 复制磁盘出现权重与配套文件尚不一定有运行进程文件、大小、哈希、配套目录
导入工具建立自己的模型条目,可能复制或移动文件原文件是否保留看导入策略工具模型列表与实际磁盘位置
加载权重与状态进入内存/显存,可能预热磁盘文件一直存在加载日志、驻留列表、实际回答
换模型可能卸载旧模型并加载新模型,也可能并存旧权重通常仍在磁盘新 model ID、资源与回答
卸载释放模型驻留资源权重文件、应用进程可能仍在已加载列表、显存与内存
停止生成取消本次请求通常保留模型驻留和文件请求终止,服务能接下一次请求
停止服务结束服务进程及监听,通常释放其模型权重和配置仍在磁盘进程退出、监听消失
关闭网页 / 断开隧道关闭入口或连接远端后台推理服务可能仍在在服务器查进程与 health
删除权重删除明确的模型资产或工具条目聊天记录是否删除另看 App磁盘和模型列表;慎查共享缓存
关机 / 释放云实例停计算,释放可能同时删资产保留范围由云平台规则决定平台状态、持久存储与账单

Ollama 的 list / ps 分别对应磁盘条目和驻留状态;LM Studio 的模型列表与已加载列表也要分开读。llama-server 的本次单模型模式通常要停止并重新启动进程来换权重。模型管理产品可以按需加载、空闲卸载;API 能列出一个名字,并不一定意味着那个模型此刻已经占用 GPU。

首次请求慢可能是冷加载,后续快可能是模型已驻留或命中前缀缓存。换模型、增加上下文或 GPU 放置参数通常需要重新加载;temperature、输出上限常可随请求设置。不会因为把网页关掉,就把聊天内容训练进权重。

先看懂,再动手

08量化、内存预算与选型计算器

粗略权重体积:参数数 × 每参数位数 ÷ 8。以 27B 为例,FP32 理论约 108GB,FP16/BF16 约 54GB,8-bit 约 27GB,4-bit 约 13.5GB。它们是纯权重的十进制估计,不是完整模型文件大小,更不是实际运行显存。

实际量化还会保存缩放因子、块信息、未量化张量等;多模态、词表和额外张量也影响体积。本次 Q8_0 下载约 29GB,终端显示约 28G,是量化开销和显示单位共同影响的实际结果。

动手算一算

权重预算计算器

只估算权重与手动预留量,不预测特定模型的 KV cache。

GB = 10⁹ 字节;GiB = 2³⁰ 字节。量化元数据、特殊张量及实际运行需求仍以文件与实测为准。若纯权重 + 预留超过显存,可考虑混合运行或改用更小模型/量化。

GPU 运行预算还包括模型状态、临时计算缓冲、上下文相关缓存、并发请求与系统占用。传统注意力模型的 KV cache 通常随上下文、层数、KV heads、head dimension、数据类型及并发增长;混合注意力、循环状态、滑动窗口等模型不能直接套一个统一系数。

精度 / 量化常见理解选型重点
FP32每参数通常 4 字节精度与研究用途;大模型推理资源要求高
FP16 / BF16每参数通常 2 字节,数值范围不同常见原始发布/服务精度,需要足够显存
FP8浮点 8-bit 方案依赖设备、算子与框架,不能与 GGUF Q8_0 混称
Q8_0GGUF 中一种块量化类型体积较大,保留较多数值精度;不保证任务结果必优于所有 Q4
Q4_K_M 等名称对应不同量化方案或混合策略常见资源折中;Q4 名字不代表所有张量精确 4-bit
AWQ / GPTQ / NVFP4不同的量化方法或表示与硬件路径看模型仓库配置、kernel 与 GPU 支持,不按后缀猜

不要把一个 Q4 文件重新量化成 Q8 当成恢复原始精度;丢掉的信息无法凭空补回来。8-bit 也不保证回答准确,它只是数值表达与压缩的一项选择。

对本次 3090 来说,Q8_0 不能全部装入 24GB 显存,因此混合运行可行但速度受 CPU 部分影响。优先把预算留给实际使用的上下文,再逐步增加 GPU 层数。若要更长上下文、更多并发或全 GPU Q8,通常应重新评估显存更大的设备,而不是只更换框架。

平台、框架与路线选择

09AI 模型平台有哪些:按职责分类

“模型平台”不是一个单一品类。下载权重的平台、出租 GPU 的平台、直接卖 API 的平台以及聊天产品,职责与账单不同。以下是代表性入口,不是穷尽清单;可用区域、模型目录与收费以官网为准。

类别代表平台 / 官方入口你拿到什么自己需要维护什么
模型与数据社区Hugging Face ↗、ModelScope 魔搭 ↗权重、模型卡、数据、示例或社区转换版下载、授权许可核查、运行环境
本地工具的模型目录Ollama Library ↗、LM Studio ↗面向对应工具的发现、下载或导入入口本机资源、模型加载与软件版本
GPU 实例租赁AutoDL ↗、Runpod Pods ↗、Vast.ai ↗计算实例、GPU 与磁盘环境、服务、数据保存、网络、计费
通用云 GPUAWS ↗、Azure ↗、Google Cloud ↗、阿里云 ↗云主机与相关网络/存储产品系统运维、成本、区域与配额
托管模型端点HF Inference Endpoints ↗、Runpod Serverless 等可调用端点与平台管理的 worker部署配置、版本、缩放与冷启动预算
国内模型 API阿里云百炼 / Model Studio ↗、DeepSeek ↗、硅基流动 ↗、火山方舟 ↗托管模型 APIKey、调用限制、模型名、数据与费用
其他 API / 聚合平台OpenAI ↗、Anthropic ↗、Gemini ↗、OpenRouter ↗、Together ↗、Fireworks ↗厂商或聚合 APIAPI 协议、模型目录、服务条款与预算
应用层 / 知识库工具Open WebUI ↗、Dify ↗、AnythingLLM ↗聊天、工作流、文档检索、管理界面连接模型后端与应用数据

在社区模型页面先读发布者身份、基础模型来源、许可证、文件格式、推荐 runtime 和量化方法。一个好听的仓库名不保证是官方模型;同一模型名下的量化版本也可能由不同作者制作。

托管 API 平台不必向你开放所有模型权重;一个模型有可下载版本,也不意味着每个平台都提供相同版本、上下文、工具或采样功能。网页聊天产品的订阅与 API 调用费用也可能属于不同产品。

平台、框架与路线选择

10推理框架、管理工具与前端的区别

工具属于哪一层主要场景与本次 Q8 GGUF 的关系
llama.cpp ↗C/C++ 推理运行时与服务程序跨平台、GGUF、CPU/GPU 混合已实测使用;有 CUDA 等后端
Ollama ↗模型管理、运行与 API 产品少命令、本地个人应用可导入被其 runtime 支持的 GGUF
LM Studio ↗桌面加载/聊天/API 产品GUI 使用、本地模型管理看内置 runtime 是否支持架构;Mac 可有 MLX 路线
Transformers ↗通用模型加载与推理库Python 开发、多模态、研究通常加载 HF 目录,不能把本次 GGUF 当同等目录
vLLM ↗服务型推理引擎连续批处理、并发与吞吐GGUF 路径当前仍有实验性限制,不是本次首选
SGLang ↗服务型推理与优化引擎API 服务、缓存、批量与推理优化需核对模型结构、量化与硬件支持
TensorRT-LLM ↗NVIDIA 优化推理栈特定 GPU 上高性能服务转换/构建与版本要求更强,非通用 GGUF 加载器
MLX / MLX-LM ↗Apple Silicon 推理与训练生态Mac 统一内存设备使用匹配的 MLX 模型配置与权重
MLC LLM ↗模型编译、跨平台运行生态手机、浏览器与不同 GPU 后端需匹配的转换模型及编译库
MNN ↗ / LiteRT-LM / ExecuTorch端侧 runtime 或编译部署生态手机、嵌入式、自定义 App通常要按生态转换和集成
ONNX Runtime ↗通用跨平台推理引擎ONNX 模型与部分生成模型方案不是把 GGUF 文件直接丢进去即可运行
WebLLM ↗浏览器内推理支持 WebGPU 的浏览器、小模型应用在浏览器设备计算;与本次远程网页服务不同

Qwen3.8 官方模型卡列出多种服务引擎支持,但这不意味着它们在你的硬件、量化文件和并发条件下效果一样。Qwen 部署入口 ↗

vLLM 官方目前把 GGUF 支持描述为实验性且优化有限,并提到插件路径;不能因为都是“推理加速框架”就认为直接换过去一定更快。vLLM GGUF 限制 ↗

Open WebUI、Dify、聊天客户端主要解决交互与应用编排;它们通常连接后端模型,并不是凭自己替代 GPU 执行模型。RAG 框架负责检索与组织上下文,也不等于底层推理引擎。

平台、框架与路线选择

11怎么选择部署路线与模型

先写清你需要的任务:普通中文聊天、代码、知识库、视觉、音视频、工具调用、离线、长文档还是多人同时请求。再依次筛选模型质量、许可证、设备资源、运行时兼容性与维护负担。

你的目标起步路线下一步
Windows 上尽快聊天LM Studio 或 Ollama,小模型 Q4 起步学会导入、上下文与 API
已下载一个 GGUF,想精确控资源llama.cpp检查 GPU 后端、层数与性能
Apple Silicon MacLM Studio/Ollama 或 MLX-LM留统一内存余量,匹配转换模型
24GB GPU 想用 27B Q8本次 CPU/GPU 混合路线接受速度折中,实测并调 GPU 层数
生产 API、多人并发足够 GPU 资源 + vLLM/SGLang压测、认证、TLS、监控与版本固定
手机离线聊天端侧 App + 小型兼容量化模型测内存、发热、续航和持续性能
手机使用 27B手机连接电脑/云端服务设置受控网络入口,而非手机强装 Q8
只想接入能力,不管理机器托管 API学会 model/base_url/key 与用量管理

新手顺序: 先让短输入、短回答、单请求成功,再扩大模型、上下文与并发。遇到“不支持架构”,先更新或更换支持的 runtime;遇到显存不足,优先减上下文/并发/批大小或调整权重放置,不要把所有问题都归为“模型下载坏了”。

本次实战:逐步复盘与截图证据

12起点与硬件:先验证能跑什么

起点是 AutoDL 容器实例列表:一个已经关机的单卡 RTX 3090 实例。没有直接租更大的卡,而是先正常 GPU 开机,进入 JupyterLab 的 Terminal 检查现有设备。

截图 01起点:AutoDL 单卡 RTX 3090 实例

实例尚未开机;这是云端 GPU,不是 Windows 本机显卡。

原图内嵌 · 点击放大 · 未裁剪或改写内容

检查命令都在 AutoDL 的 Linux 终端,不是 Windows PowerShell:

bash
nvidia-smi
df -h /root/autodl-tmp
python --version
nvcc --version

结果是 24GB 显存、14 核 CPU、90GB 内存、50GB 数据盘且约 44G 可用,Python 3.12.3、驱动 580.105.08、CUDA Toolkit 12.8。GPU 当时没有其他进程。

截图 02环境检查:GPU、磁盘、Python 与 Toolkit

24GB 显存,90GB 内存,44G 数据盘可用;驱动支持与 nvcc 版本分别检查。

原图内嵌 · 点击放大 · 未裁剪或改写内容

决策依据:CPU 内存足以支持 Q8 的部分 CPU 执行;GPU 不能完整容纳约 29GB 权重及运行时开销;数据盘能容纳一个 Q8 文件、工具和一定缓存。最初建议 Q4 是速度与资源折中,你明确选择 Q8 后,部署目标相应改为混合运行。

本次实战:逐步复盘与截图证据

13编译、文件下载与 Xet 故障

本章小节
编译 GPU 版运行时改为 Q8 前先看磁盘独立下载环境与首次进度失败的位置与修复

编译 GPU 版运行时

安装 CMake/C++ 等工具,把 llama.cpp 放在 /root/autodl-tmp,启用 CUDA,并为 RTX 3090 指定 86 架构。编译目标是 llama-server,最后用 --list-devices 检查程序真正识别 GPU。

截图 03编译完成:llama-server 识别 CUDA 设备

--list-devices 中出现 RTX 3090,证明当前程序具有可用的 GPU 后端。

原图内嵌 · 点击放大 · 未裁剪或改写内容

编译成功与驱动识别 GPU 是两件事:系统有 GPU 不代表你编译的程序有 CUDA 后端。这个检查能提前发现“模型看似跑了,实际全在 CPU”的问题。

改为 Q8 前先看磁盘

你选择 8-bit 后,我们检查目录和剩余空间。目录尚不存在,说明此前 Q4 未下载;44G 的剩余空间足够继续。这个顺序避免同时下载多个大文件把盘填满。

截图 04选择 Q8 后复查磁盘与模型目录

44G 可用,目录尚不存在;此前并未下载 Q4 文件。

原图内嵌 · 点击放大 · 未裁剪或改写内容

独立下载环境与首次进度

在数据盘创建 hf-tools 虚拟环境,把 HF_HOME 也放到数据盘,开启 AutoDL 的学术资源加速。下载指定 Q8 文件,而不是整个含很多量化版本的仓库。未登录的 HF_TOKEN 提示只是警告,当时进度确实开始增长。

截图 05安装独立下载工具并开始取得 Q8 文件

加速设置和 HF_HOME 生效;未登录警告没有阻止初次下载进度。

原图内嵌 · 点击放大 · 未裁剪或改写内容

失败的位置与修复

随后出现 File reconstruction error / CAS Client Error,调用栈落在 xet_get,访问存储域名请求失败。截图没有最终 GGUF 文件;这不是模型加载阶段的 OOM,也没有证据说明是 CUDA 编译错误。

截图 06下载中断:Xet 重建与 CAS 请求失败

堆栈落在 xet_get,最终 GGUF 尚未生成,故障发生在下载阶段。

原图内嵌 · 点击放大 · 未裁剪或改写内容

我们只改变下载路径:设置 HF_HUB_DISABLE_XET=1,改用支持的 HTTP 下载回退。第一次切换时加 --force-download,重新下载,避免沿用失败重建的临时状态。它没有证明网络为什么失败,只验证了关闭 Xet 这条替代路径在本次环境能完成。

截图 07关闭 Xet 后:HTTP 下载完成

29.0G/29.0G 与 Downloaded 提示;本地文件约 28G。

原图内嵌 · 点击放大 · 未裁剪或改写内容

经验:不要把所有网络下载失败都解释成“必须登录”。先识别元数据接口、下载重定向、存储 CDN、代理和本地磁盘分别在哪一步失败。--force-download 不是每次重试都要加;正常 HTTP 中断时,应先看下载工具是否支持复用进度。

本次实战:逐步复盘与截图证据

14从权重加载到健康接口与真实回答

首次加载使用 40 个 GPU 层、4096 上下文、1 个并行槽、12 个 CPU 线程,开启 Flash Attention 和 Jinja 聊天模板。服务只监听云端回环地址 127.0.0.1:8080。

截图 09首次前台加载:模型与 HTTP 监听就绪

model loaded 与 listening 证明服务启动;unused tensor 提示未阻止加载。

原图内嵌 · 点击放大 · 未裁剪或改写内容

日志里的 unused tensor 提示并没有阻止此次模型加载。不能仅凭一个警告推断具体 tensor 用途;本次没有启用或验证 MTP 加速。 判断是否可用,要看加载完成、健康检查和实际输出,而不是把所有 W 日志都当致命错误。

截图 0840 层加载后的健康检查与显存

health 返回 ok,显存约 16615MiB,只有目标服务进程。

原图内嵌 · 点击放大 · 未裁剪或改写内容

新开“终端 2”,健康接口返回 ok,显存约 16615MiB。通过 /v1/chat/completions 发中文问题,关闭该次请求的思考模式,得到了正常答案与 finish_reason=stop。

截图 10首个 API 回答与 timings

正常中文回答;47 个输出 tokens,解码速度约 5.18 tokens/秒。

原图内嵌 · 点击放大 · 未裁剪或改写内容

首次 API 记录:输入处理约 1354ms;生成 47 tokens 用时约 8874ms;predicted_per_second=5.1836。这个值是生成速度,不能与 GPU 空闲状态下的利用率或网页上的输入处理统计混为一谈。

本次实战:逐步复盘与截图证据

15SSH 转发、网页缺失与修复经过

本章小节
第一类现象:本机拒绝连接第二类现象:API 正常,网页返回 404浏览器端到端成功

第一类现象:本机拒绝连接

浏览器打开 127.0.0.1:18080 后一度显示 ERR_CONNECTION_REFUSED。这个地址对应 Windows 本机,首先应查本机端口是否在监听,以及 SSH 是否成功建立。截图本身不足以断言服务器模型坏了。

截图 11浏览器阶段:本机 18080 拒绝连接

先排查当前设备的端口监听与 SSH,而非直接认定模型错误。

原图内嵌 · 点击放大 · 未裁剪或改写内容

你执行的隧道命令使用 -N,因此没有远程交互 shell;连接后停在空白行是正常的。之后检查发现本机 18080 已由 ssh 进程监听,通过这个端口访问 /health 也拿到 ok。

截图 12Windows PowerShell 中的 SSH 隧道

-N 不提供交互 shell;隧道正常时停在空白行并不代表卡死。

原图内嵌 · 点击放大 · 未裁剪或改写内容

第二类现象:API 正常,网页返回 404

继续请求网页根路径,返回 File Not Found / 404。远程检查 CMake 配置与源码发现,没有可用的内嵌 UI 资产:本地 UI 源码构建没有开启,预构建资源也未在首次构建时成功取得。--webui 开关不能代替缺失的网页文件。

这次教学流程的遗漏在于:初次编译只检查了运行时与 GPU,没有同时确认网页资源与首页。改进后的教程把 API 健康和网页检查分开,并检查 UI: embedded N assets 的构建输出。

通过开启网络加速重新运行 llama-ui-assets 目标,官方预构建网页资源下载并校验完成,嵌入了 70 项资产。随后停止旧服务,重新链接 llama-server,再启动模型。

截图 13网页资源补齐后重新编译服务

UI 资源已进入构建,随后重新链接并加载模型。

原图内嵌 · 点击放大 · 未裁剪或改写内容

本机 curl 检查网页时需支持压缩:本次嵌入的是 gzip 资产,不带压缩支持的请求曾返回 415;使用 curl --compressed 后返回 200 HTML。浏览器通常自带支持,所以这与最初的本机拒绝连接不是同一种故障。

浏览器端到端成功

刷新后出现 llama-ui,发送“你好”得到中文回复。网页模型回复处约为 5.14 t/s,93 tokens 用时约 18 秒;上方 79.20 tokens/s 的输入处理统计不代表模型回答每秒生成 79 tokens。

截图 14浏览器聊天成功:你好

回复下方约 5.14 t/s;输入处理统计与解码速度分别解读。

原图内嵌 · 点击放大 · 未裁剪或改写内容
本次实战:逐步复盘与截图证据

16后台运行、52 层优化与结果边界

本章小节
这次做对的事情下次应更早做的检查

把已核验的启动参数保存成 run-qwen-q8.sh,默认使用 52 个 GPU 层,可传 40 回退。使用 nohup 运行并保存 PID 与日志,健康检查继续返回 ok,显存变为 21321MiB 左右。

截图 15最终后台运行:52 层与资源占用

nohup 启动,health 为 ok,显存约 21321MiB;速度提升另有 API 实测。

原图内嵌 · 点击放大 · 未裁剪或改写内容

之后用同一个“100 字以内介绍能力”的短问题再次发起 API 请求,关闭思考模式,结果正常结束:生成 48 tokens,生成时间 5785.515ms,速度 8.1237 tokens/秒,输入处理约 849.345ms。

条件40 个 GPU 层52 个 GPU 层
短问题相同文字与 max_tokens 上限相同文字与 max_tokens 上限
思考模式该次 API 请求关闭该次 API 请求关闭
输出量47 tokens48 tokens
解码用时8.874 秒5.786 秒
解码速度5.1836 tokens/s8.1237 tokens/s
观察到的改善基线约 56.7%

这是一次短回答对比,采样后的文字不同,不是严格多轮平均基准,更不是所有任务都提升 57% 的承诺。本次没有压测长文、多人并发、视觉输入、MTP、生产可用性或手机执行。当前 4096 上下文也不等于模型宣传的最大上下文能力。

这次做对的事情

  • 先检查资源,再选文件与量化;没有直接用 BF16 权重硬塞 24GB 显存。
  • 将模型、下载工具和缓存放到数据盘,指定下载单个量化文件。
  • 下载完成、程序识别 GPU、模型加载、健康接口、API 答案、网页分别验证。
  • 根据错误所在层改变一个关键条件;未把网页错误当模型精度问题。
  • 使用 SSH 本地转发访问回环服务,随后再设置后台运行。

下次应更早做的检查

  • 在编译结束时检查 UI 资源和首页,不只执行 --list-devices。
  • 明确“你的电脑”与“AutoDL 实例”的终端边界,减少路径和端口误用。
  • 初次下载时说明 Xet 网络可能需要替代路径,并谨慎检查临时文件完整性。
  • 把验证条件、上下文和并发一起记录,避免只看一个速度数字。
  • 预先保存可重复的启动配置,并区分后台运行与开机自动启动。
云端自托管:本次路线的完整教程

17AutoDL 从零到 Qwen3.8 Q8:准备与下载

本章小节
1. 选择实例、镜像与存储2. 安装编译依赖与取得源码3. 配置与编译,确认 GPU 与网页资源4. 独立安装下载工具,并指定缓存位置5. 下载一个 Q8_0 文件

这部分是可复现的操作顺序,适用于与本次相近的 Ubuntu/CUDA 实例。以下 Bash 在 AutoDL 的 JupyterLab Terminal 执行;Windows SSH 命令会单独标注。 硬件不同时,不照搬 CUDA 架构 86 或 GPU 层数。

1. 选择实例、镜像与存储

需要可用的 NVIDIA GPU、可运行的 Linux 环境,以及与驱动兼容的 CUDA Toolkit。若采用预构建二进制,未必需要 nvcc;本路线自行编译,所以要有 Toolkit 与 C++ 编译器。50GB 盘能放本次单个 Q8 文件,但不适合同时保留多个大精度版本、原始 BF16 与转换中间文件。

正常 GPU 开机后进入 JupyterLab。做 nvidia-smi、df、Python 与 nvcc 检查;如果显卡被其他程序占用,先查清进程用途,不要盲目 kill 全部进程。AutoDL 开始教程 ↗

2. 安装编译依赖与取得源码

bash
apt-get update
apt-get install -y git cmake build-essential libssl-dev libcurl4-openssl-dev
cd /root/autodl-tmp
git clone --depth 1 https://github.com/ggml-org/llama.cpp.git
cd /root/autodl-tmp/llama.cpp

如果 git 下载困难,可按 AutoDL 文档先启用下面的加速设置。它只对当前终端环境生效,可能影响其他域名的网络速度。AutoDL 学术资源加速 ↗

bash
source /etc/network_turbo

3. 配置与编译,确认 GPU 与网页资源

bash
cmake -B build \
  -DGGML_CUDA=ON \
  -DCMAKE_CUDA_ARCHITECTURES=86 \
  -DCMAKE_BUILD_TYPE=Release \
  -DLLAMA_USE_PREBUILT_UI=ON
cmake --build build -j 8 --target llama-server
./build/bin/llama-server --list-devices

86 对应本次 RTX 3090 的计算能力,不是所有 GPU 的通用值。构建应识别 CUDA 设备;网页资产构建还要出现非零 embedded assets。预构建资源取不到时,可以在正确网络下再次运行下面命令,或按官方 UI 构建说明安装适配的 Node/npm 并启用本地源码构建。官方 CUDA 构建说明 ↗

bash
cmake --build build --target llama-ui-assets
cmake --build build -j 8 --target llama-server

LLAMA_BUILD_UI=ON 表示尝试从源码构建 UI,不是免依赖的开关;构建系统和命名后续可能变化。不要因为服务二进制生成了,就忽略“building without an embedded UI”一类构建提示。

4. 独立安装下载工具,并指定缓存位置

bash
python -m venv /root/autodl-tmp/hf-tools
/root/autodl-tmp/hf-tools/bin/python -m pip install -U huggingface_hub
export HF_HOME=/root/autodl-tmp/hf-cache

模型和下载工具环境与训练环境分开,有助于避免随意升级训练目录中的 Transformers/PyTorch 依赖。

5. 下载一个 Q8_0 文件

bash
source /etc/network_turbo
export HF_HUB_DISABLE_XET=1
/root/autodl-tmp/hf-tools/bin/hf download \
  unsloth/Qwen3.8-27B-GGUF \
  Qwen3.8-27B-Q8_0.gguf \
  --local-dir /root/autodl-tmp/models/Qwen3.8-27B

这里采用本次验证成功的 HTTP 路径;在网络良好的其他环境,可保留默认 Xet。不要去掉文件名下载整个含许多量化文件的仓库。若刚从失败的 Xet 重建切换过来,第一次可加 --force-download 从头取得文件;日常重试则先确认是否可续传。

bash
ls -lh /root/autodl-tmp/models/Qwen3.8-27B/Qwen3.8-27B-Q8_0.gguf
df -h /root/autodl-tmp

最后以工具的完成提示和仓库大小为基础检查,必要时校验哈希。HF 下载工具 ↗ · Xet 配置 ↗

云端自托管:本次路线的完整教程

18AutoDL 真正加载模型与 API 验证

本章小节
6. 首次先前台启动,方便看错误7. 发一个实际聊天请求8. 理解主要加载参数

6. 首次先前台启动,方便看错误

bash
/root/autodl-tmp/llama.cpp/build/bin/llama-server \
  --model /root/autodl-tmp/models/Qwen3.8-27B/Qwen3.8-27B-Q8_0.gguf \
  --alias qwen3.8-27b \
  --n-gpu-layers 40 \
  --ctx-size 4096 \
  --parallel 1 \
  --threads 12 \
  --batch-size 256 \
  --ubatch-size 128 \
  --flash-attn on \
  --jinja \
  --host 127.0.0.1 \
  --port 8080

这个终端不返回命令提示符是正常的:服务在运行。等模型加载完成和 listening 日志出现。在另一个 Terminal 执行下列检查;如果返回加载中,稍后再测。

bash
curl --noproxy '*' http://127.0.0.1:8080/health
nvidia-smi
curl --compressed --noproxy '*' -I http://127.0.0.1:8080/

7. 发一个实际聊天请求

bash
curl --noproxy '*' -sS http://127.0.0.1:8080/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "qwen3.8-27b",
    "messages": [{"role":"user","content":"请用中文简要介绍你能帮我做什么,控制在100字以内。"}],
    "max_tokens": 256,
    "temperature": 0.7,
    "chat_template_kwargs": {"enable_thinking": false}
  }' | python -m json.tool --no-ensure-ascii

看 choices 中的 message.content;看 finish_reason 是否正常;看 timings 中的 predicted_per_second。max_tokens 是此次输出上限,不是整个服务上下文长度。temperature 控制采样随机性,不是 GPU 加速开关。该模型的 enable_thinking 属于模板相关参数,不应不加检查地发给任何其他 API。llama-server 参数与接口 ↗

8. 理解主要加载参数

参数本次值作用与误区
--model本地 GGUF 文件路径找真实权重,不是 API model 名
--aliasqwen3.8-27b给客户端用的名称,不会改变权重
--n-gpu-layers40 起步,52 最终控制卸载到 GPU 的层数;不要凭参数值猜所有 tensor 的位置
--ctx-size4096资源预算与输入/历史/输出长度相关;不等于训练时最大上下文
--parallel1并行槽位;提高会增加状态与缓存资源需求
--threads12CPU 执行线程;大于 CPU 数不一定更快
--batch-size / --ubatch-size256 / 128影响提示词处理与临时内存;不是一句话输出长度
--flash-attn on开启注意力计算优化;看设备与 kernel 支持
--jinja开启使用模板引擎组织聊天消息
--host / --port127.0.0.1 / 8080服务监听地址;与本机 SSH 转发端口分开

GPU 层数增加后要重新检查服务就绪、显存、短输出和持续请求。系统空闲显存够,不代表任何 batch/上下文都不会 OOM;保留余量比把卡填到最后一个 MiB 更适合长期使用。

云端自托管:本次路线的完整教程

19Windows 如何连接云端网页与 API

本章小节
9. 在 Windows PowerShell 运行 SSH 隧道10. 本机连接失败时的最小诊断

9. 在 Windows PowerShell 运行 SSH 隧道

这条命令在你的 Windows 电脑执行,不在 AutoDL Terminal 执行。

powershell
ssh -p 33976 -N -L 127.0.0.1:18080:127.0.0.1:8080 -o ExitOnForwardFailure=yes -o ServerAliveInterval=30 root@connect.nmb2.seetacloud.com

端口和主机是本次实例的信息,别人的实例或实例迁移后必须使用控制台的新登录指令。首次连接检查目标主机并确认主机密钥;按提示输入 SSH 密码,输入时通常不显示字符。若免密已配置,则可能不需要输入密码。

连接后窗口不输出内容且不退出,是 -N 正常工作状态。保持它打开。AutoDL SSH 隧道说明 ↗

text
浏览器:http://127.0.0.1:18080
API base_url:http://127.0.0.1:18080/v1
model:qwen3.8-27b

127.0.0.1 是“当前设备自身”。同一个地址在 Windows 指向 Windows,在云实例指向云实例,在手机指向手机。手机访问 http://127.0.0.1:18080 不会自动访问你的电脑。

10. 本机连接失败时的最小诊断

在另一个 Windows PowerShell 窗口执行,不要关闭正在工作的 SSH 窗口:

powershell
Get-NetTCPConnection -LocalPort 18080 -State Listen -ErrorAction SilentlyContinue
curl.exe --noproxy '*' http://127.0.0.1:18080/health
curl.exe --compressed --noproxy '*' -I http://127.0.0.1:18080/

没有监听 → 查 SSH;健康正常、首页 404 → 查 UI 资产;健康连接失败但 SSH 在监听 → 查云端进程与云端 8080;浏览器失败但 curl 正常 → 查浏览器代理、地址协议、缓存与扩展。SSH 本地转发只解决网络,不会修复模型内存不足或缺失网页文件。

云端自托管:本次路线的完整教程

20日常启动、停止、后台与重启

本章小节
保存运行脚本后台启动与确认谨慎停止指定的后台进程每次重新使用的顺序

保存运行脚本

本次服务器已存在 /root/autodl-tmp/run-qwen-q8.sh。换实例时可在 Linux Terminal 创建下面文件;它只是保存命令,并不会立即启动模型。

bash
cat > /root/autodl-tmp/run-qwen-q8.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
qwen_gpu_layers="${1:-52}"
case "$qwen_gpu_layers" in
  40|52) ;;
  *) printf 'Usage: bash run-qwen-q8.sh [40|52]\n' >&2; exit 2 ;;
esac
exec /root/autodl-tmp/llama.cpp/build/bin/llama-server \
  --model /root/autodl-tmp/models/Qwen3.8-27B/Qwen3.8-27B-Q8_0.gguf \
  --alias qwen3.8-27b \
  --n-gpu-layers "$qwen_gpu_layers" \
  --ctx-size 4096 --parallel 1 --threads 12 \
  --batch-size 256 --ubatch-size 128 \
  --flash-attn on --jinja --host 127.0.0.1 --port 8080
EOF
bash -n /root/autodl-tmp/run-qwen-q8.sh

后台启动与确认

确保旧服务已经停止,再启动一个新服务,不要重复起多个模型进程。前台运行时在原终端按 Ctrl+C 即可停止。

bash
nohup bash /root/autodl-tmp/run-qwen-q8.sh 52 > /root/autodl-tmp/qwen-q8.log 2>&1 &
echo $! > /root/autodl-tmp/qwen-q8.pid
bash
curl --noproxy '*' http://127.0.0.1:8080/health
tail -n 40 /root/autodl-tmp/qwen-q8.log
nvidia-smi

若 52 层出现资源问题,确认旧进程已退出后,把启动参数 52 改为 40;没有必要重新下载权重。现有 nohup 命令会覆盖同名日志,重要排错日志先另存。

谨慎停止指定的后台进程

只停止保存的、仍对应本次模型的进程。PID 可能在重启后失效或被复用,不应盲目根据一个旧数字 kill。

bash
qwen_pid_file=/root/autodl-tmp/qwen-q8.pid
if [ -f "$qwen_pid_file" ]; then
  qwen_pid=$(cat "$qwen_pid_file")
  case "$qwen_pid" in
    ''|*[!0-9]*) printf 'PID 文件无效\n' ;;
    *)
      if [ -r "/proc/$qwen_pid/cmdline" ]; then
        qwen_cmd=$(tr '\0' ' ' < "/proc/$qwen_pid/cmdline")
        case "$qwen_cmd" in
          *llama-server*Qwen3.8-27B-Q8_0.gguf*) kill -- "$qwen_pid" ;;
          *) printf 'PID 对应其他程序,未停止\n' ;;
        esac
      else
        printf '该进程已经不在运行\n'
      fi
      ;;
  esac
fi

每次重新使用的顺序

  1. AutoDL 正常 GPU 开机,确认模型和环境仍存在。
  2. JupyterLab Terminal 后台启动模型,健康检查返回 ok。
  3. Windows PowerShell 重新运行 SSH 转发,保持窗口打开。
  4. 浏览器打开 18080,或者应用连接 /v1 API。
  5. 不用时在 AutoDL 控制台关机,停止 GPU 使用计费;存储等其他费用看平台规则。

nohup 不等于开机自动启动,不等于崩溃自动重启。 它主要避免会话挂断信号影响程序。tmux/screen 更方便重新进入交互终端;systemd/supervisor/Docker restart 等适合具备对应管理环境的长期服务。AutoDL 容器不一定运行 systemd,不能把普通云主机的 systemctl 命令无条件照搬。

本机部署:Windows、Linux 与 Mac

21Windows 路线一:Ollama 下载、导入与使用

本章小节
A. 从工具目录下载一个小模型B. 已经下载 GGUF,怎么导入C. 给其他程序使用

这是适合新手的完整流程。本机能跑多大,取决于你的 Windows 电脑实际硬件;本次 AutoDL 3090 的资源不自动属于这台电脑。

A. 从工具目录下载一个小模型

  1. 从 Ollama 官方下载页 ↗ 安装适合 Windows 的版本,启动应用。
  2. 打开 Windows PowerShell,执行 ollama --version 确认安装成功。
  3. 先用目录中可用的小模型,例如 qwen3:4b,验证本机链路。
powershell
ollama --version
ollama pull qwen3:4b
ollama run qwen3:4b

pull 下载工具管理的模型;run 加载并进入对话,未下载时也可能触发下载。看到输入提示后问一句简单中文问题。模型支持的特殊命令以当前交互帮助为准。4B 是规模示例,不是当前 Qwen3.8-27B 的同一个模型。示例模型目录页 ↗

powershell
ollama list
ollama ps
ollama stop qwen3:4b

list 看磁盘中已有模型,ps 看当前驻留的模型,stop 请求卸载指定模型。这些都与删除权重不是同一个动作。安装过多个 runtime 时,更新应用后重新确认正在使用的引擎版本。

B. 已经下载 GGUF,怎么导入

把兼容的 GGUF 放到本机,例如 C:\Models\model.gguf。确认这不是云端路径,而且本机能承担其资源需求。创建 Modelfile:

powershell
$modelFileText = @'
FROM C:/Models/model.gguf
PARAMETER num_ctx 4096
'@
[System.IO.File]::WriteAllText((Join-Path (Get-Location) 'Modelfile'), $modelFileText, [System.Text.UTF8Encoding]::new($false))
ollama create my-local-model -f .\Modelfile
ollama run my-local-model

model.gguf 是需要你替换的真实本地文件名。my-local-model 是工具里的新名称。create 不是重新训练模型;导入 GGUF 也不会自动把 Q8 变成 Q4。支持架构、聊天模板与参数行为以当前版本为准。官方导入说明 ↗

C. 给其他程序使用

Ollama 有原生 /api 路线,也提供兼容接口路线;不要把两者的请求字段混用。确认服务实际端口和当前版本文档后,客户端通常填写 localhost:11434 对应地址及工具中的 model 名。原生 API 的最小 Python 示例:

python
import json
import urllib.request
payload = {
    "model": "qwen3:4b",
    "messages": [{"role": "user", "content": "你好,请用中文回答。"}],
    "stream": False,
}
request = urllib.request.Request(
    "http://127.0.0.1:11434/api/chat",
    data=json.dumps(payload).encode("utf-8"),
    headers={"Content-Type": "application/json"},
)
opener = urllib.request.build_opener(urllib.request.ProxyHandler({}))
with opener.open(request, timeout=180) as response:
    result = json.load(response)
print(result["message"]["content"])

这里关闭代理继承只针对这个 Python 客户端,避免本机回环请求绕到外部代理。若软件显示加载失败,先检查日志和内存,不要重复导入很多份权重。

本机部署:Windows、Linux 与 Mac

22Windows 路线二:LM Studio 图形界面

本章小节
从模型文件到聊天已下载 GGUF 的 CLI 完整路径启动本地 API

从模型文件到聊天

  1. 从 LM Studio 官方入口 ↗ 安装,查看系统要求和可用 runtime。
  2. 在模型发现/下载界面找到合适的模型与量化,先读发布者和资源估计。
  3. 下载完成后进入已下载模型列表;若已有 GGUF,使用导入功能或 lms import,而不是把文件后缀改成软件认识的名字。
  4. 选择模型并点击加载。先用较短上下文、单请求;内存预算不够就换小模型或降低量化位宽。
  5. 等界面显示加载完成,发送短问题,查看回答、速度与资源占用。
  6. 想节省显存时卸载模型,文件仍保留在磁盘。

“下载列表里有模型”只代表资产存在;“模型已加载”才代表运行时准备好了。软件 UI 和菜单名字会随版本改变,顺序是下载/导入 → 选择 → 加载 → 问答。

已下载 GGUF 的 CLI 完整路径

若 lms 不在 PATH,先按软件的 CLI 安装/引导说明配置,再新开 PowerShell。以下用你已经放在本机的兼容 GGUF;这里选择复制保留源文件,目标目录会额外占用磁盘:

powershell
lms --help
lms import 'C:\Models\model.gguf' --dry-run
lms import 'C:\Models\model.gguf' --copy
lms ls
lms load --context-length 4096
lms ps
lms chat

lms load 未给模型 key 时交互选择;选刚导入的条目,等加载完成,再聊天。需要脚本自动加载时,用 lms ls 列出的真实 key,按 lms load --help 指定;API ID 可用 --identifier 设置。运行 lms unload 按提示选择已加载模型,可以释放驻留资源。

特别留意:当前 lms import 默认移动文件;--copy 才保留原位置,--dry-run 只预览。不要导入后发现旧路径消失,就再次下载一份同样的大文件。LM Studio 导入规则 ↗ · 加载与卸载参数 ↗

启动本地 API

进入开发/本地服务器界面,选择已加载模型并启动服务;也可使用当前版本的 CLI:

powershell
lms server start
lms server status

默认与具体端口以当前界面为准,常见开发配置是 1234。给支持兼容接口的客户端填 http://127.0.0.1:1234/v1 和服务器公布的 model id;先查 /v1/models,不要猜名称一定与文件名相同。本地服务器说明 ↗ · CLI 启动 ↗

LM Studio 是模型运行与使用产品,不保证任意 GGUF 都能加载。新架构通常需要新 runtime;Mac 上 MLX 权重与 GGUF 也应按对应后端分别导入。

本机部署:Windows、Linux 与 Mac

23Windows / Linux 路线三:直接使用 llama.cpp

本章小节
Windows 预构建程序Linux 原生与 WSL 的区别

Windows 预构建程序

  1. 在 官方 releases ↗ 找与你的系统架构、GPU 后端和运行库要求相符的构建;不要混拿 CPU 版当 CUDA 版。
  2. 解压到例如 C:\Tools\llama,保留程序需要的同包动态库,不只复制一个 exe。
  3. 模型放到 C:\Models;检查真实路径,确认模型架构被该版本支持。
  4. 在 PowerShell 查询设备,然后先验证加载与短输出。
powershell
& 'C:\Tools\llama\llama-server.exe' --list-devices
& 'C:\Tools\llama\llama-server.exe' --model 'C:\Models\model.gguf' --ctx-size 4096 --parallel 1 --n-gpu-layers 0 --host 127.0.0.1 --port 8080

这是明确的 CPU 基线示例:0 表示不把模型层放到 GPU。若有正确 GPU 后端与足够资源,再逐步增加层数。不能把本次 52 层照搬到一台 GPU 型号未知的电脑。

  1. 在另一个 PowerShell 检查 /health,打开本机 8080 网页。这次不需要 SSH:程序就在本机。 若 release 没包含可用 UI,则 API 与网页要分开检查。
  2. 要终端聊天,用同包 llama-cli 的 --model 参数加载,而非 llama-server;具体交互行为以 --help 为准。
powershell
& 'C:\Tools\llama\llama-cli.exe' --model 'C:\Models\model.gguf' --ctx-size 2048 --n-gpu-layers 0 --conversation

同一个模型不要同时用 CLI 和 server 各加载一份,再误判为模型本身需要双倍资源。CLI 的 --conversation 依赖正确聊天模板;若当前版本或模型不支持,先检查 --help 和仓库说明。

本机 server 启动后,在另一个 PowerShell 验证:

powershell
curl.exe --noproxy '*' http://127.0.0.1:8080/health
curl.exe --noproxy '*' http://127.0.0.1:8080/v1/models

返回的模型 ID 才是当前 API 的调用依据。浏览器访问网页用 http://127.0.0.1:8080;客户端 base_url 用 http://127.0.0.1:8080/v1,两个入口不要混填。

Linux 原生与 WSL 的区别

Linux NVIDIA 路线可复用本次 apt/CMake/CUDA 操作,只改存储路径与 GPU 架构。CPU 路线不启用 GGML_CUDA;AMD、Intel、Apple 等设备使用各自支持的后端,不能通过安装 CUDA 让任何 GPU 都变成 NVIDIA GPU。

Windows 的 WSL2 是 Linux 环境,适合使用主要面向 Linux 的工具。先验证 WSL 中能看到 GPU,再安装适配框架;驱动路径、Docker GPU 透传和本机网络行为遵循当前官方说明,不要在 WSL 中盲目安装会覆盖宿主驱动路径的普通 Linux 驱动方案。文件最好放在适合当前运行环境的磁盘位置,留意跨 Windows/Linux 文件系统的 I/O。微软 WSL GPU 指南 ↗

本机部署:Windows、Linux 与 Mac

24没有 NVIDIA 显卡:CPU、AMD、Intel 与端侧芯片

先识别硬件和运行后端,再装软件。GPU 厂商不同,驱动、运行时和模型算子支持就可能不同;“能打开 App”不是“已经 GPU 加速”的证据。

设备可评估的执行路线必须核对
普通 x86 / ARM CPUllama.cpp CPU、支持的桌面工具、PyTorch CPU内存、指令集、线程、实际速度
NVIDIA GPUCUDA 版 llama.cpp / 支持的服务引擎驱动、二进制依赖、计算能力与显存
AMD GPU项目支持的 HIP/ROCm 或 Vulkan 路线具体 GPU/OS 支持,不只看显存容量
Intel GPU项目支持的 SYCL、Vulkan、OpenVINO 等路线驱动、后端版本、模型兼容与实际 offload
Apple SiliconMetal 或 MLX 对应 runtime系统/芯片支持与统一内存余量
手机 GPU / NPUApp/SDK 的 GPU、NPU delegate 或专用 backend算子、量化、编译资产与真机资源

这些是后端类别,不是“每个软件都支持表中全部设备”的承诺。以 llama.cpp 构建指南和工具自己的硬件支持页核对具体组合。llama.cpp 各后端构建 ↗ · Ollama 硬件支持 ↗

实际操作顺序:系统识别设备 → 安装与该设备匹配的 runtime → 查询 runtime 的设备列表 → 加载小模型 → 查看实际权重放置和生成日志 → 与 CPU 基线比较。不要只在空闲时看 GPU 利用率;有些阶段很短,有些层仍在 CPU,监控采样可能错过计算。

集成显卡可能共享系统内存,显示“共享 GPU 内存”不代表每种引擎都能高效利用全部容量。没有独显也可以运行小模型,但能否达到你接受的速度必须测。更大位宽、更长上下文和多用户同时运行都会增加压力。

本机部署:Windows、Linux 与 Mac

25Mac:统一内存、Metal 与 MLX

本章小节
图形工具路线MLX-LM Python 路线

图形工具路线

Apple Silicon Mac 可先使用支持其硬件的 LM Studio 或 Ollama。查实际内存容量并留出系统余量,选兼容的 GGUF 或 MLX 权重。Intel Mac 与 Apple Silicon 不应混用同一套硬件假设;不存在“Mac 装个 CUDA 就按 3090 教程运行”的通用路线。

MLX-LM Python 路线

MLX-LM 面向 Apple Silicon 的 MLX 生态。使用它支持的模型目录;量化方式由配套配置说明,不能因为权重也叫 safetensors 就认定与任何 HF 目录可互换。MLX-LM 官方项目 ↗

bash
# 在 Apple Silicon Mac 的 Terminal 中
python3 -m venv ~/mlx-llm-env
source ~/mlx-llm-env/bin/activate
python -m pip install -U mlx-lm
mlx_lm.generate \
  --model mlx-community/Qwen2.5-3B-Instruct-4bit \
  --prompt '请用中文介绍你能做什么。' \
  --max-tokens 128

这个示例会在需要时取得模型文件;它是较小模型的使用演示,不是本次 27B Q8 配置。先确认这个转换仓库仍可访问、当前 runtime 支持,以及原模型许可证。示例 MLX 仓库 ↗

使用步骤是创建环境 → 取得适配模型 → 执行 generate → 看答案 → 再考虑服务接口。大型模型、长上下文与其他 App 会竞争统一内存;发生系统换页时,速度和体验可能明显下降。

下载好之后:按格式加载的代码教程

26HF / Safetensors:如何用 Python 加载完整目录

本章小节
1. 准备独立环境与目录2. 加载模型、应用模板、生成和解码3. 为什么本次 Qwen3.8 的原始目录不能无条件照抄

1. 准备独立环境与目录

下面以一个小型文本模型演示,Linux/macOS 使用 Bash;Windows 用虚拟环境的 Scripts\python.exe,或按对应激活方式调整。PyTorch GPU 安装要与设备和官方安装选项匹配,不把某个 CUDA wheel 当作全平台安装包。

bash
python3 -m venv ./hf-runtime
source ./hf-runtime/bin/activate
python -m pip install -U torch transformers accelerate huggingface_hub
hf download Qwen/Qwen2.5-3B-Instruct --local-dir ./models/qwen2.5-3b

确认目录里有 config、tokenizer 和全部权重分片。示例的目的只是教学;许可证和版本要求仍需查模型卡。Qwen2.5-3B 示例模型卡 ↗

Windows 的环境创建可以这样做,直接调用虚拟环境的 Python,避免脚本激活权限成为第一道障碍:

powershell
python -m venv .\hf-runtime
.\hf-runtime\Scripts\python.exe -m pip install -U torch transformers accelerate huggingface_hub
.\hf-runtime\Scripts\hf.exe download Qwen/Qwen2.5-3B-Instruct --local-dir .\models\qwen2.5-3b
.\hf-runtime\Scripts\python.exe -c "import torch; print(torch.__version__); print('CUDA available:', torch.cuda.is_available())"

这是通用环境示例,PyTorch 的默认安装结果仍取决于当前发布与包源。需要 GPU 时先用 PyTorch 官方安装选择器 ↗ 取得匹配系统和设备的安装命令;不要把 CUDA available=False 直接解释为模型文件损坏。把下一段代码保存为 run_local_model.py,再用虚拟环境的 Python 执行,而不是双击 .safetensors 文件。

2. 加载模型、应用模板、生成和解码

保存下面代码为一个 Python 文件,从上面的工作目录执行。离线加载时指向本地目录,并设 local_files_only=True;这样缺文件会报错,不会偷偷改成从远程下载。

python
import torch
from transformers import AutoTokenizer, AutoModelForCausalLM

model_dir = "./models/qwen2.5-3b"
tokenizer = AutoTokenizer.from_pretrained(model_dir, local_files_only=True)
model = AutoModelForCausalLM.from_pretrained(
    model_dir,
    dtype="auto",
    device_map="auto",
    local_files_only=True,
)
model.eval()
messages = [{"role": "user", "content": "用中文解释什么是模型推理。"}]
text = tokenizer.apply_chat_template(
    messages, tokenize=False, add_generation_prompt=True
)
inputs = tokenizer(text, add_special_tokens=False, return_tensors="pt").to(model.device)
with torch.inference_mode():
    generated = model.generate(**inputs, max_new_tokens=128)
answer_tokens = generated[0, inputs["input_ids"].shape[-1]:]
print(tokenizer.decode(answer_tokens, skip_special_tokens=True))

tokenizer 负责切分与模板,from_pretrained 负责按目录配置加载结构和权重,device_map 决定设备放置,generate 执行自回归输出。模板已经添加模型需要的特殊 token,所以再次分词设 add_special_tokens=False,避免重复 BOS/EOS;也可按该版本文档让 apply_chat_template 直接分词并返回输入字典。聊天模板与特殊 token ↗

auto 并不承诺“所有层都在 GPU”;资源不够时需要明确评估 offload 和框架支持。可以查看 model.hf_device_map 了解实际分配;模型跨设备时,输入应匹配输入嵌入所在的执行设备,不能把任意 model.device 当作所有层所在位置。不同 Transformers 版本可能使用不同 dtype 参数命名,要按版本报错与官方文档调整。

3. 为什么本次 Qwen3.8 的原始目录不能无条件照抄

本次部署的是 GGUF;原始 Qwen3.8 是多模态发布目录,可能需要 AutoProcessor 与支持该架构的模型类/版本。不能拿 Q8 GGUF 文件当成上述 HF 文件夹,也不能因一个旧 Transformers 版本识别 qwen2 就认为它必然识别新架构。多模态加载还要正确的图像/视频预处理。

仓库 ID 与本地路径: from_pretrained("发布者/仓库名") 可能联网下载并缓存;from_pretrained("./完整目录") 使用本地资产。设备和依赖是否满足决定能否加载,与字符串看起来像模型名字无关。

下载好之后:按格式加载的代码教程

27PTH:拿到权重后为什么还需要原项目代码

本章小节
判断保存方式一个可理解的 state_dict 加载示例整对象与 TorchScript 的区别

判断保存方式

先查发布说明:文件是 state_dict、checkpoint、整个模型对象还是 TorchScript?找架构、输入尺寸、预处理、标签映射与软件版本。一个视觉分类器的 pth 不是大语言模型;一份优化器 checkpoint 也不是直接可聊天的文件。

一个可理解的 state_dict 加载示例

下面演示“结构 → 权重 → 推理”关系。TinyClassifier 是示例结构,不是你下载的任意模型的通用结构;只有文件与结构匹配时才可加载。输入 16 维、输出 4 维也只是教学设定。

python
from pathlib import Path
import torch
from torch import nn

class TinyClassifier(nn.Module):
    def __init__(self):
        super().__init__()
        self.net = nn.Sequential(nn.Linear(16, 32), nn.ReLU(), nn.Linear(32, 4))
    def forward(self, x):
        return self.net(x)

weight_path = Path("classifier.pth")
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
model = TinyClassifier()
state = torch.load(weight_path, map_location="cpu", weights_only=True)
# 若原项目保存的是 {"model_state_dict": ...},按原项目取对应字段
model.load_state_dict(state)
model.to(device).eval()
sample = torch.zeros(1, 16, device=device)
with torch.inference_mode():
    logits = model(sample)
print(logits)

如果只想验证这个示例的数据流,可先用相同类执行 torch.save(TinyClassifier().state_dict(), "classifier.pth"),但那是随机初始化权重,没有任务能力。真实模型应加载实际训练得到的参数。

load_state_dict 的 key/shape 不匹配说明结构或保存方式不符;随意 strict=False 可能掩盖重要权重未加载,不能作为万能修复。模型和输入必须在适当设备上;eval 与 inference_mode 与“切换 GPU”不是同一件事。PyTorch 序列化说明 ↗

整对象与 TorchScript 的区别

整模型对象可能需要原 Python 类可导入;TorchScript 文件通常通过 torch.jit.load 使用,但不是任意 .pt 都是 TorchScript。TorchScript 属于仍会遇到的旧导出路线,当前 PyTorch 文档将其标为 deprecated,新项目应查 torch.export 等当前路线;导出程序与 state_dict 也不是一类资产。TorchScript 当前状态 ↗

不要为了绕过报错就对未知权重无条件打开不受限制的对象加载。weights_only=True 降低部分反序列化风险,也不是对任意恶意文件的完整隔离。正确做法是回到可信原项目说明判断文件类型,匹配结构和依赖。

下载好之后:按格式加载的代码教程

28模型转换、量化、分片与 LoRA

本章小节
格式转换不是重命名分片不要乱合并LoRA 不是完整模型Transformers 的加载时量化与 GGUF 量化不同

格式转换不是重命名

HF → GGUF 通常经过受支持架构的转换程序。转换读取结构、权重、分词元数据,可能改变张量布局;量化是随后或结合进行的数值压缩步骤。GGUF → 原始高精度目录不一定有完整可逆转换路径,量化信息丢失更不可逆。

bash
# 仅用于当前转换器支持的模型目录,示例路径需要替换
cd /path/to/llama.cpp
python -m pip install -r requirements.txt
python convert_hf_to_gguf.py /path/to/original-model \
  --outfile /path/to/model-f16.gguf --outtype f16
cmake --build build --target llama-quantize
./build/bin/llama-quantize \
  /path/to/model-f16.gguf /path/to/model-q8.gguf Q8_0

转换原始大模型可能同时占用输入权重、输出高精度文件、输出量化文件和临时空间;本次 50GB 数据盘并不适合就地保留这整套 27B 文件。多模态投影转换也不一定由同一条命令完成。新手优先下载可信、兼容、说明完整的发布版本。

分片不要乱合并

Safetensors 分片靠 index 和加载框架组织;GGUF 分片按原始编号与 runtime 规则加载。不要用文本拼接或 cat 随意把文件凑成一个“大模型”。不同仓库作者的同名分片不能混搭。

LoRA 不是完整模型

适配器记录对基础参数的调整,一般需正确的基座模型、版本和适配配置。它既可能被运行时动态加载,也可能先合并再转换。模型名相近不等于参数布局和训练基座一致;兼容性以适配器发布说明为准。

Transformers 的加载时量化与 GGUF 量化不同

Transformers 可在兼容设备与模型上通过 bitsandbytes 等方案执行加载时 8-bit/4-bit 量化:传入 BitsAndBytesConfig 和适当 quantization_config,而不是给 from_pretrained 传一个 GGUF Q8 文件。它涉及不同的算子、权重表示及设备放置,数字都叫“8-bit”也不能互换。HF bitsandbytes 量化说明 ↗

加载时量化可能降低驻留预算,但原始下载仍可能是高精度大目录,还需考虑转换/加载峰值与 CPU offload。已发布的 AWQ/GPTQ/FP8 等仓库应按量化配置和引擎支持加载;不要同时堆叠不兼容方案,或把“磁盘文件变小”与“加载时内存变小”当作同一流程。

服务型部署:云主机、Docker 与托管 API

29vLLM / SGLang:足够 GPU 资源上的服务路线

本章小节
vLLM:从原始模型到 APISGLang:相同的资源核验原则多 GPU 怎么理解

当目标变成多人并发、API 吞吐、较长上下文或生产服务,服务型引擎更值得评估。这条路线与本次单卡 3090 的 Q8 GGUF 路线不同:示例使用原始 HF 模型,不加载本次 GGUF 文件。

vLLM:从原始模型到 API

示例资源前提是足够承载原始 BF16 权重、8192 上下文和运行缓冲的 Linux NVIDIA GPU 环境;27B 原始权重本身约五十多 GB,可先评估单卡 80GB 级资源。这里是预算起点,不保证任意并发与上下文都能装下。磁盘应为下载及缓存留足空间。

  1. 在云平台选实例、磁盘和适配驱动;确认 nvidia-smi 正常。
  2. 创建独立 Python 环境,按当前 vLLM 安装要求处理 PyTorch/CUDA 组合。
  3. HF_HOME 放到持久数据盘,确认原始仓库可下载;也可提前下载完整目录并使用本地路径。
  4. 固定输出长度与模型上下文,先单请求测试,然后按需求逐步压测。
bash
python3 -m venv /data/vllm-env
source /data/vllm-env/bin/activate
python -m pip install -U vllm
export HF_HOME=/data/hf-cache
export MODEL_API_KEY='替换为自己生成的访问密钥'
vllm serve Qwen/Qwen3.8-27B \
  --dtype bfloat16 \
  --max-model-len 8192 \
  --gpu-memory-utilization 0.90 \
  --host 127.0.0.1 --port 8000 \
  --api-key "$MODEL_API_KEY"

这条命令不适用于直接在本次 24GB 3090 上加载原始 BF16 模型。不同新版本和模型可能需要特定 recipe、额外依赖或 attention backend;先复核官方模型支持页与安装说明,再固定验证过的版本。vLLM 快速开始 ↗ · Qwen 服务说明 ↗

SGLang:相同的资源核验原则

在另一个独立环境安装当前模型 recipe 要求的 SGLang 与依赖,然后指定 HF 仓库或完整目录。以下是服务启动形态,未在本次实例执行:

bash
python -m sglang.launch_server \
  --model-path Qwen/Qwen3.8-27B \
  --context-length 8192 \
  --max-running-requests 1 \
  --host 127.0.0.1 --port 30000

示例明确设置 8192 上下文与最多 1 个执行中的请求,避免继承模型很大的默认窗口;它仍需要足够的 GPU 资源,也不是已经在本次实例验证过的完整版本配方。按硬件与官方 recipe 配置量化、缓存、并行及验证参数。要改多人服务,对队列延迟、吞吐、内存、超时和错误率都做测量。SGLang 服务参数 ↗ · SGLang 官方项目 ↗ · Qwen3.8 专项 cookbook ↗

多 GPU 怎么理解

Tensor Parallel 把同一模型的计算/参数在 GPU 间分担;Data Parallel 用不同副本处理不同请求;Pipeline Parallel 分担不同阶段。多 GPU 显存不应只机械相加:分片约束、互联、通信、模型结构、量化 kernels 都会影响可行性。两张 24GB 卡也不能凭相加就保证任意约 48GB 权重顺利执行。

服务型部署:云主机、Docker 与托管 API

30Docker 与长期服务部署

本章小节
通用 vLLM 容器形态VM 上 systemd,容器中 supervisor / 平台管理

Docker 解决依赖与环境打包,不会凭空增加 GPU 显存。NVIDIA 设备还要具备宿主驱动及正确容器 GPU 支持;Linux、Docker Desktop/WSL 与 AutoDL 容器内再次套 Docker 的能力不同,先确认平台允许。

通用 vLLM 容器形态

以下是在满足 GPU 容器前提的 Linux 云主机上的示例,原始模型资源前提同上一章。部署可复现时把镜像版本或 digest 固定为经过你验证的值。

bash
docker run --gpus all \
  --name qwen-api \
  -p 127.0.0.1:8000:8000 \
  -v /data/hf-cache:/root/.cache/huggingface \
  --shm-size 8g \
  vllm/vllm-openai:latest \
  --model Qwen/Qwen3.8-27B \
  --dtype bfloat16 --max-model-len 8192 \
  --host 0.0.0.0 --port 8000

容器内监听 0.0.0.0,宿主端口映射仍限定在回环,这两个地址作用于不同网络边界。示例未配置生产认证;对外服务前增加认证、受控网络、TLS 和调用限制。停止与查日志使用 docker stop qwen-api、docker logs qwen-api;持久模型放在挂载路径,别只留在易失容器层。

VM 上 systemd,容器中 supervisor / 平台管理

普通 Linux VM 可创建专用服务用户,使用 systemd 管理明确的 ExecStart、WorkingDirectory、环境配置、Restart 和日志;验证 systemd 与权限存在后再配置。AutoDL 等容器环境优先使用其支持的管理方法,不要因 systemctl 不可用就重装整套系统。

生产化还包括:存活与就绪检查、异常重启、日志轮转、磁盘容量、版本锁定、备份、配额、观测和回滚。开发用 nohup 可以很实用,但与高可用服务不是同一个交付标准。

服务型部署:云主机、Docker 与托管 API

31托管端点、Serverless 与调用现成 API

本章小节
托管端点:保留模型选择,交给平台管理运行现成 API:不下载、不加载,只调用服务租卡与 API 如何比较费用

托管端点:保留模型选择,交给平台管理运行

以 HF Inference Endpoints 或同类平台为例:选择仓库与兼容引擎 → 选择资源、区域与访问方式 → 配置环境与扩缩容 → 部署并等待就绪 → 用返回的地址与凭证测试 → 观察成本与延迟。自定义量化或新架构先看容器/handler 是否支持,不是所有社区仓库都能“一键跑”。HF 托管端点文档 ↗

Serverless 可能在空闲时缩到零,节省活跃计算,但请求要承担冷启动、权重下载或初始化时间;缓存、镜像体积、worker 最小数量与 GPU 配额都影响体验。常驻 Pod/实例更适合低延迟连续使用,但闲置也可能计费。Runpod 平台路线 ↗

现成 API:不下载、不加载,只调用服务

从平台创建账户和 API Key,查当前支持的模型 ID、区域 base_url、输入限制和计费方式。以兼容 Chat Completions 的平台为例,客户端通常配置三项:base_url、api_key、model。它们是调用信息,不是你电脑上的权重文件路径。

python
import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["MODEL_BASE_URL"],
    api_key=os.environ["MODEL_API_KEY"],
)
response = client.chat.completions.create(
    model=os.environ["MODEL_ID"],
    messages=[{"role": "user", "content": "用中文说明什么是模型部署。"}],
    max_tokens=128,
)
print(response.choices[0].message.content)

变量必须由你按平台设置;不是把本次 qwen3.8-27b 别名填到所有平台都能用。兼容接口不保证所有平台支持相同的工具调用、多模态、流式 usage、思考控制和采样参数。把 Key 放在服务端或环境配置中,不硬编码到可公开分享的 HTML 前端。百炼兼容 API 入口 ↗ · DeepSeek API 入口 ↗

租卡与 API 如何比较费用

租卡按活跃时长、存储、网络及平台规则计算;API 可能分别对输入、输出、缓存或其他功能计费。比较你的实际负载与闲置时间,不是只比较每小时 GPU 单价和一个不含输入长度的“每次提问”价格。

简单估算:云实例月计算费≈单价×开机小时数,再加存储等;API 月费≈各类 token 用量×相应单价,再加其他服务项。低频调用与持续满载,最经济的路线可能不同。本文不固定任何平台价格,避免把会变化的报价写成永久结论。

手机与浏览器端侧部署

32手机部署先分清:端侧计算还是远程聊天

手机本地运行:模型权重进入手机存储,CPU/GPU/NPU 在手机上计算;运行兼容的小模型后可断网聊天。手机远程聊天:权重留在电脑或云实例,手机只是界面;它可以使用很大的模型,但不能在离开网络后继续远程计算。

本次约 29GB 的 27B Q8 文件不是合理的普通手机起步选择。手机可供 App 使用的内存通常低于整机标称值,还要考虑预处理、上下文、系统限制与散热。以 0.5B~3B、Q4 左右、较短上下文 作为初次实验范围,是资源预算建议,不是对任意手机的运行保证。

项目手机端侧手机远程访问
权重保存手机电脑 / 云实例
计算位置手机芯片远端 CPU/GPU
网络下载后部分功能可离线使用时需要连接
规模瓶颈App 内存、算力、后端与散热服务器资源与网络
格式要求App 或 SDK 支持的专用资产客户端 API 协议
本次 27B Q8不建议作为手机端侧起步适合把手机作为远程客户端

你不能仅凭手机芯片宣传“有 NPU”就认定任何 GGUF 自动用 NPU。runtime 必须有对应 delegate/后端,模型算子和量化也须兼容。很多现成端侧 App 实际使用 CPU 或 GPU。

手机与浏览器端侧部署

33Android / iPhone:现成 App 的完整使用步骤

本章小节
1. 先确认 App 支持什么2. 选择小模型与量化3. 下载或导入4. 点击加载5. 问一个短问题并验证离线6. 测持续表现iOS 的特殊点

可从 PocketPal AI 官方项目 ↗ 提供的商店或发布入口取得应用;MNN 的官方项目也提供端侧 App 路线。具体可用平台、商店区域和模型目录以发布页面为准,不用来路不明的“加速包”。

1. 先确认 App 支持什么

查看其当前 runtime 支持的模型架构、GGUF 或专用格式、上下文配置、后台行为和最低系统要求。App 能导入文件,不等于能运行最新模型结构;新模型可能比应用内嵌引擎的更新更快。

2. 选择小模型与量化

优先从应用的兼容目录选小型聊天模型,再考虑手动导入。留够“权重 + 缓存/状态 + 临时缓冲”的空间与内存。文件下载完成后也要确认它不是 HTML 错误页、部分下载或其他格式。

3. 下载或导入

使用 App 内的下载按钮,或把正确格式的完整文件保存到手机可访问目录,再用“导入/添加本地模型”入口选择。如果模型分片或需要额外文件,按应用文档放置,不能只导入第一片就期待完整模型。

4. 点击加载

从模型列表选择刚取得的模型,点击加载。上下文先用 1024~2048 这类较小测试预算;后端、线程或 GPU 开关只用应用支持的选项。若 App 被系统杀掉、返回桌面或报内存不足,先降低资源需求。

5. 问一个短问题并验证离线

问“你好,请用中文回答”或一个有明确答案的问题。观察加载时间、首 token 等待、回答速度与内容。需要离线功能时,在模型已经下载完成后断开网络,确认本地聊天仍能运行;联网检索/云 API 等额外功能不会随本地模型一起自动离线。

6. 测持续表现

初次短回答快,不保证连续十几分钟的性能。手机升温后可能降频,后台也可能被系统回收。先短上下文、小输出、单会话,逐步增加;别把 App 退出与模型文件损坏混为一谈。

iOS 的特殊点

iPhone/iPad 的 App 内存预算、后台生命周期和可用运行时与桌面 Mac 不同。能在 Mac 上运行一个 MLX 模型,不意味着能把同一目录丢给任意 iOS App。通过文件 App 的导入、权重下载以及可选后端均按应用的官方流程来操作。

手机与浏览器端侧部署

34Android Termux:命令行 CPU 实验路线

这条路线适合学习运行过程,不是保证每台手机都高效的推荐配置。使用来自官方可信渠道的 Termux;手机端库、编译器与权限行为和普通 Ubuntu 不同。下面是通用 CPU 起步,未在你的手机上实测。llama.cpp Android 文档 ↗

bash
# 在 Android 的 Termux 内,不是在 Windows 或 AutoDL 中
pkg update
pkg install git cmake clang make
git clone --depth 1 https://github.com/ggml-org/llama.cpp.git
cd llama.cpp
cmake -B build \
  -DCMAKE_BUILD_TYPE=Release \
  -DGGML_OPENMP=OFF \
  -DGGML_LLAMAFILE=OFF
cmake --build build -j 2 --target llama-cli

编译选项随版本和设备变化,遇到报错按官方 Android 文档调整。-j 2 是降低编译峰值资源的示例,不是推理线程固定必须为 2。没有启用 CUDA,也没有假定 Android GPU/NPU 已工作。

模型用一个兼容的小 GGUF,放在 Termux 私有目录或明确授予访问权限的目录。若通过 Android 共享存储选文件,要先按 Termux 官方方式取得权限,注意系统版本的限制。下面路径是待替换示例。

bash
./build/bin/llama-cli \
  --model /path/to/small-model.gguf \
  --ctx-size 1024 --threads 4 --n-gpu-layers 0 \
  --predict 128 \
  --prompt '用中文简要解释什么是模型量化。'

先看 --help 与真实输出。要使用 GPU 后端,需要另查 Vulkan/OpenCL/设备专用 backend 的编译与驱动支持;不能把 --n-gpu-layers 改成很多就认为 GPU 已加速。在手机用运行时已有的兼容 App,一般比自行维护编译链更省事。

手机与浏览器端侧部署

35自己开发手机 App:MLC、MNN、LiteRT-LM、ExecuTorch

本章小节
MLC Android 开发顺序MLC iOS 开发顺序

这是开发者部署路线,复杂度高于下载聊天 App。核心链路是 选择支持的模型 → 转换与量化 → 为设备编译或打包 → 集成 runtime → 实机验证。

路线需要准备加载的不是“任意原始文件”
MLC Android ↗Android Studio、NDK、JDK、Python/MLC 与模型库兼容的转换权重 + 针对目标构建的 model library
MLC iOS ↗Mac、Xcode、签名、runtime 与模型库对应转换权重及打包配置
MNN ↗MNN 工具、目标 backend、App 工程按 MNN 流程转换的模型与配置
LiteRT-LM ↗支持的模型资产、Android/iOS SDK 与后端要求对应 LLM 资产格式与运行配置
ExecuTorch ↗导出、量化、后端编译与移动库运行时可执行的导出程序及数据

MLC Android 开发顺序

  1. 用官方文档要求的工具版本准备 Android Studio/NDK、JDK 和必要语言工具,设置各自环境变量。
  2. 获取 MLC 源码与其依赖,安装匹配的 MLC Python 工具;源代码与 Python 二进制包要注意版本一致。
  3. 在 Android 工程的 mlc-package-config.json 中选择模型、模型 ID 与目标设备信息。
  4. 取得预转换权重或按官方流程转换,并为目标设备构建/打包模型库;权重与库必须匹配。
  5. 打开 Android 工程,构建并安装到真实设备,不只在桌面编译成功就宣布手机成功。
  6. 使用短输入验证加载、回答、内存、GPU/backend 和持续运行。调整上下文及预填充分块后再次实测。

MLC iOS 开发顺序

  1. 在 Mac 准备 Xcode、目标 iPhone/iPad 及签名配置。
  2. 按文档取得 runtime、模型库和转换权重,修改 iOS 打包配置。
  3. 决定权重随 App 打包还是首次运行下载,考虑包体、持久存储与更新。
  4. 集成生成/取消、状态管理与资源释放,避免每个 token 都重新加载模型。
  5. 用 Xcode 真机安装,验证 App 内存限制、后台/前台切换及持续输出。
  6. 针对设备设置上下文和预填充预算;它们不同于模型训练时的最大上下文。

本手册提供操作链与检查点,不伪造一套适用于所有手机 SDK 版本的 NDK/Xcode 命令。精确工具链、模型库命名和打包命令,应从上述当前官方指南逐项匹配。手机模型的可运行性既看权重,也看算子、后端与 App 实现。

手机与浏览器端侧部署

36手机访问电脑或云端模型,浏览器内推理

本章小节
手机连接你的电脑或云端沿用本次云实例:手机自己做 SSH 转发浏览器内推理:另一条独立路线

手机连接你的电脑或云端

当前 Windows 隧道只绑定 127.0.0.1,因此手机直接输入同样 URL 不会连上。你有三类路线:手机自己建立支持的 SSH/受控隧道;使用安全的 VPN/组网连接到服务;或者部署带认证与 HTTPS 的受控入口,手机客户端填真实 API 地址。

若只是家庭局域网电脑服务,要先确认 runtime 是否允许监听 LAN 地址、对应防火墙规则、认证及信任边界。不要把无鉴权的开发服务随意暴露到公网。 云端的认证、HTTPS 与访问控制由服务器/网关配置,不靠手机浏览器“替你加安全”。

步骤:先确认远端 /health 和真实对话正常 → 配置受控网络入口 → 在手机确认能访问该入口 → 在客户端设置 base_url/key/model → 发短问题 → 再验证断线、超时和长请求。它是“手机远程使用”,不是“手机本地部署”。

沿用本次云实例:手机自己做 SSH 转发

这是无需让 Windows 电脑一直开机的一条路线,但前提是手机上的 SSH 客户端支持本地端口转发,并能在你使用浏览器时保持连接:

  1. AutoDL 开机,确认后台模型在云端 127.0.0.1:8080 正常工作。
  2. 手机 SSH 客户端新建连接:主机 connect.nmb2.seetacloud.com,SSH 端口 33976,用户 root,用你自己的密码或私钥认证;不要复制到可分享的教程里。
  3. 新建“本地端口转发”:手机监听 127.0.0.1:18080,远端目标 127.0.0.1:8080。这里目标回环是从云端 SSH 主机理解的。
  4. 连接并保持隧道;手机浏览器打开 http://127.0.0.1:18080,API 客户端填写 http://127.0.0.1:18080/v1。
  5. 发短问题验证。若切换 App 后断线,查手机客户端的后台生命周期;特别是 iOS,不能假定任何 SSH App 都能长期在后台保持隧道。

此时手机的 127.0.0.1 能用,是因为你在手机上实际建立了隧道。Windows 那个隧道不能自动替手机建立同样的监听。上面仍是教程,本次没有替你在手机安装或测试 SSH 客户端。

使用位置服务地址示例成立条件
AutoDL 自己调用自己http://127.0.0.1:8080/v1云端模型正在运行
Windows 调用 AutoDLhttp://127.0.0.1:18080/v1Windows 上 SSH 转发在线
手机调用 AutoDLhttp://127.0.0.1:18080/v1手机上独立 SSH 转发在线
受控 VPN / HTTPS 网关客户端网关实际可达地址 + /v1网络、认证及证书配置完成

网页能打开但客户端失败时,还要确认客户端要求的是 base_url 还是完整 /chat/completions URL;填法以客户端定义为准。没有手机隧道时,不要机械复制表里的手机回环地址。

浏览器内推理:另一条独立路线

WebLLM ↗ 可在支持的浏览器设备通过 WebGPU 等能力执行模型,需要匹配的模型资产与后端支持。下载可能缓存到浏览器存储,设备内存、浏览器配额与缓存清理都会影响使用。

本次 llama-ui 只是调用云端 API;关掉服务器后,网页不会自己接管 27B 的计算。浏览器页面长得像聊天框,并不能证明模型在浏览器本地运行。

连接应用、优化、排错与扩展

37下载并加载之后,怎样给程序和聊天客户端使用

本章小节
本次 API 的三个配置项直接 Python 使用本次模型流式与多轮会话可直接运行的流式输出示例可直接运行的两轮对话示例生成参数怎么设置才不会混淆不同后端的地址与模型名对照接入 Open WebUI / Dify / 其他客户端

本次 API 的三个配置项

字段本次配置说明
base_urlhttp://127.0.0.1:18080/v1Windows SSH 隧道连通后使用
modelqwen3.8-27b--alias 配置的名称
api_key当前服务未设置;SDK 可用占位值若以后启用认证,必须替换成真实 Key

客户端的 API Key 占位值不是安全设置,不能保护无鉴权服务。OpenAI-compatible 是协议兼容概念,不代表服务在调用 OpenAI 云端,或任何模型都支持同样功能。

直接 Python 使用本次模型

本例在 Windows 电脑执行,PowerShell 隧道需在运行。安装 SDK 是客户端依赖,不会再次下载 Qwen 权重。

powershell
python -m pip install -U openai httpx
python
import httpx
from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:18080/v1",
    api_key="local-not-used",
    http_client=httpx.Client(trust_env=False, timeout=180.0),
)
answer = client.chat.completions.create(
    model="qwen3.8-27b",
    messages=[{"role": "user", "content": "请用中文简要解释 GGUF。"}],
    max_tokens=256,
    extra_body={"chat_template_kwargs": {"enable_thinking": False}},
)
print(answer.choices[0].message.content)

trust_env=False 让这个客户端不继承环境代理。若在云端调用自己的服务,URL 通常应改成云端回环 8080,而不是 Windows 的 18080。

流式与多轮会话

stream=True 时服务按块返回;客户端要逐块处理,而不是把完整响应解析逻辑原封不动照搬。多轮通常需要客户端把历史消息加入 messages;服务加载了模型不代表它默认记得所有历史用户。

上下文到上限时需要缩短、总结或截断历史;不要只增加 max_tokens。思考输出可能占生成预算,调试时先关闭,复杂任务再开启与测量;“减少思考”也不保证整个复杂任务必然更快。

可直接运行的流式输出示例

下面仍在 Windows 执行,使用本次隧道和已安装的 openai/httpx。代码保存为 stream_chat.py,再运行 python .\stream_chat.py。它只请求文本并关闭该次思考,便于观察回答块;不用再次加载/下载模型。

python
import httpx
from openai import OpenAI

with OpenAI(
    base_url="http://127.0.0.1:18080/v1",
    api_key="local-not-used",
    http_client=httpx.Client(trust_env=False, timeout=180.0),
) as client:
    stream = client.chat.completions.create(
        model="qwen3.8-27b",
        messages=[{"role": "user", "content": "用三句话说明 GGUF 是什么。"}],
        max_tokens=192,
        stream=True,
        extra_body={"chat_template_kwargs": {"enable_thinking": False}},
    )
    with stream:
        for chunk in stream:
            if not chunk.choices:
                continue
            delta = chunk.choices[0].delta
            if delta.content:
                print(delta.content, end="", flush=True)
            if chunk.choices[0].finish_reason:
                print("\n结束原因:", chunk.choices[0].finish_reason)
    print()

流式 API 传输的是响应事件/块,块与单个 token 不一定一一对应。若开启思考,接口可能把 reasoning_content 或其他字段单独返回,需要按该后端协议处理;不能只读 content 就认定模型没输出。

可直接运行的两轮对话示例

历史由客户端保存在 messages 中并在下一次请求送回。下面用两次请求示范,不额外训练模型;脚本结束后列表不自动保存到磁盘。

python
import httpx
from openai import OpenAI

history = [{"role": "system", "content": "你是一个用中文简洁回答的助手。"}]
with OpenAI(
    base_url="http://127.0.0.1:18080/v1",
    api_key="local-not-used",
    http_client=httpx.Client(trust_env=False, timeout=180.0),
) as client:
    for question in ["这个演示中的项目代号是蓝鲸,请记住。", "刚才的项目代号是什么?"]:
        history.append({"role": "user", "content": question})
        reply = client.chat.completions.create(
            model="qwen3.8-27b",
            messages=history,
            max_tokens=128,
            extra_body={"chat_template_kwargs": {"enable_thinking": False}},
        )
        choice = reply.choices[0]
        answer = choice.message.content or ""
        print("用户:", question)
        print("助手:", answer, "| 结束原因:", choice.finish_reason)
        history.append({"role": "assistant", "content": answer})

若第二次只发送最新问题,服务通常拿不到第一轮的事实。历史增加会占用当前 4096 上下文;实际聊天应用需要做预算、摘要或清理。这个例子关闭思考,避免把保留 reasoning 的复杂协议混入初次教学;开启保留思考时,还要按模型模板传回相应字段。

生成参数怎么设置才不会混淆

参数用途不能当作什么
max_tokens / max_new_tokensAPI / Python 路线中的输出预算,具体字段看接口不是给模型新增上下文容量
temperature采样随机性不是 GPU 提频或“正确率按钮”
top_p / top_k / min_p候选采样范围,支持随后端变化不保证全部接口都接受
stop匹配停止条件不应随意加入可能出现在正文的中文词
seed后端支持时固定部分随机因素不保证跨后端/硬件完全重现
enable_thinking当前模型模板的思考控制不是所有模型/API 的通用字段

新手先保留模型卡建议的采样方案,只改输出预算与已确认支持的思考开关;需要严谨 JSON 时使用后端支持的结构化输出并验证结果,而不是仅把 temperature 降低。

不同后端的地址与模型名对照

后端 / 运行位置常见兼容接口 base_urlmodel 应从哪里取得
本次 Windows → AutoDL 隧道http://127.0.0.1:18080/v1本次 --alias:qwen3.8-27b
Windows 本地 llama-server 示例http://127.0.0.1:8080/v1--alias 或该服务 /v1/models
Ollama 兼容接口http://127.0.0.1:11434/v1ollama list 中的名字,例如 qwen3:4b
LM Studio 本地服务http://127.0.0.1:1234/v1,以实际端口为准服务的 /v1/models 或指定 identifier
本文 vLLM 示例http://127.0.0.1:8000/v1默认示例仓库 ID:Qwen/Qwen3.8-27B
本文 SGLang 示例http://127.0.0.1:30000/v1默认示例模型名,查 /v1/models 确认
厂商 / 聚合平台该平台文档给出的兼容地址该平台的准确模型 ID

表中的回环 URL 均从客户端运行所在设备理解;服务在别处时还需隧道、受控网络或网关。Ollama 原生 /api/chat 与兼容 /v1/chat/completions 是不同接口;不要给要求兼容接口的客户端填原生 /api 地址。Ollama 兼容接口 ↗

接入 Open WebUI / Dify / 其他客户端

在其连接配置里选择兼容后端,填 API 地址和模型 ID,按需设置 Key。若前端在 Docker、另一台机器或手机里,它的 127.0.0.1 指向它自己。 应使用能够从该进程/容器到达的服务地址与受控网络,而不是机械粘贴你的 Windows 回环地址。

先在运行前端的同一网络环境做一次 API 请求验证,再调 UI。角色模板、系统提示、输出长度、超时、多模态以及工具调用功能需要分别验证。Open WebUI 快速开始 ↗

连接应用、优化、排错与扩展

38推理加速到底加速什么

本章小节
Prefill、Decode、首 token 与吞吐MTP 是什么:多 token 预测与投机解码正确测速度

Prefill、Decode、首 token 与吞吐

Prefill 处理输入上下文,Decode 逐步生成输出;两者的每秒 token 指标不能直接互换。首 token 延迟包括队列、网络、输入处理及其他开销;完整响应时间还与输出长短相关。吞吐衡量整个系统处理多少请求/token,不等于一个用户的每次回复更快。

优化手段想改善什么代价或前提
增加 GPU 放置减少 CPU 执行带来的瓶颈GPU 内存余量,重新验证
更低位宽量化降低权重带宽/存储/显存任务质量需复核,不是无损
Flash Attention降低部分注意力计算/访存开销模型、设备与 kernel 兼容
Prefix / prompt cache复用相同前缀的工作命中率与服务策略
连续批处理多请求资源利用与吞吐队列、延迟与显存预算
KV cache 量化降低缓存预算支持的缓存类型及质量影响
投机解码 / MTP草稿与验证减少部分解码成本模型/草稿支持、接受率、额外内存
多 GPU 并行容量与计算分担互联、通信、分片支持

本次已验证的是 GPU 放置与当前 Flash Attention 配置,没有实测 MTP 加速。是否能加 MTP,要确认具体模型资产、runtime 版本和显存,不照搬其他 Qwen 变体的参数或倍率。

MTP 是什么:多 token 预测与投机解码

MTP 是 Multi-Token Prediction,即“多 token 预测”。模型在训练中增加预测后续多个位置的目标或模块;在兼容推理实现中,相关预测模块可以用来提出后续 token 草稿。模型带有 MTP 能力,与服务实际启用 MTP 加速,是两件事。 Qwen3.8-27B 官方模型卡明确记载了多步 MTP 训练。Qwen3.8 模型结构说明 ↗

普通自回归生成是:产生一个 token → 用更新后的上下文算下一个 → 继续。MTP 用于投机解码时,可以理解为:

  1. 提出草稿: 使用支持的 MTP 模块,较快地提出一串后续 token 候选。
  2. 批量验证: 主模型计算并检查这些候选,避免完全按照普通逐 token 路径验证每一项。
  3. 接受或修正: 接受符合验证规则的候选前缀,拒绝的部分按实现的正确流程修正,再继续下一轮。

例如草稿提出 3 个候选,验证可能接受其中前 2 个;也可能全部接受或几乎都不接受。这是概念示意,不是本次模型的实测接受率或固定草稿长度。批量验证能够利用不同于单 token 生成的计算效率,但草稿生成、验证和状态管理也有成本。

MTP 不等于全部投机解码。 独立小模型、EAGLE、n-gram 等也能提供草稿;MTP 路线通常利用与主模型匹配的预测模块。具体需要完整文件还是额外转换资产,由运行时与仓库决定。当前 llama.cpp 文档列出 draft-mtp 路线,不能据此假定旧二进制或任意 GGUF 都可以启用。llama.cpp 投机解码与 MTP ↗

容易混淆的选项与 MTP 的区别
stream=True分块把已生成内容发送给客户端,不会自行启用预测模块
max_tokens=256限制本次输出总量,不表示一次预测 256 个 token
batch-size执行批量组织与资源预算,单独增加不等于开启 MTP
Flash Attention注意力计算优化,可与兼容的投机路线共存
关闭思考改变生成内容与长度,不能当作 MTP 开关

本次启动命令没有启用 MTP,5.18 → 8.12 tokens/s 的改善来自 GPU 放置调整,而不是 MTP 测试。 加载日志中的 unused tensor 提示也不能证明相关预测模块已经参与计算。

要尝试 MTP,应先核对模型预测权重是否保留、当前引擎是否支持该架构和量化,再固定基线,设置兼容参数,确认日志确实启用,并记录接受率、平均接受长度、实际输出速度、内存峰值与质量。原始 HF 模型的 SGLang 配方不能直接照搬到本次 llama.cpp Q8 GGUF。

你这套 3090 已有 CPU offload;增加草稿和验证计算可能受到同样的 CPU、传输和资源瓶颈影响。因此 MTP 是可评估的优化路线,没有证据保证把当前 8 tokens/s 自动提高到某个倍率,接受率低或开销大时也可能不提速。

正确测速度

固定模型文件、runtime 版本、上下文、量化、层数、并发、输出上限与思考模式;区分第一次冷加载与已预热请求;记录输入/输出 tokens、输入处理时间、生成时间、首 token 与错误率。质量评估也要跟上:更快地生成错误答案没有达到部署目标。

本次提升约 57% 只对应那一组短回答结果。长文、代码、思考、多模态与并发的瓶颈不同,不能从这个数字直接外推。

连接应用、优化、排错与扩展

39分层排错表:先找故障在哪一层

现象优先检查下一步操作
下载超时 / 无进度网络、代理、元数据与存储域名看最后报错 URL,验证连接,换受支持下载路径
Xet reconstruction / CAS errorXet 请求与存储连接本次用 HF_HUB_DISABLE_XET=1 回退;首次切换注意未完成数据
No space left on device系统盘、数据盘、缓存盘分别的容量df -h;不要只看模型目录;查明确的工具临时文件
文件不存在机器与路径、下载是否完成Linux 与 Windows 路径分开;核对完整文件名
GGUF bad magic / 无法解析下载成错误页、部分文件或格式不符查文件头与仓库大小/哈希;不通过改后缀修复
Unsupported architectureruntime 与模型结构查支持列表、版本与正确转换仓库
CUDA 编译失败Toolkit、编译器、GPU 架构、CMake 日志找首个编译错误;不先重下载模型
--list-devices 没 GPU程序是否有正确 GPU 后端与系统 nvidia-smi 分开核验
CUDA out of memory权重、上下文、并发、batch 与其他进程调预算、层数或量化;先确认旧服务已退出
被系统 killed / 手机闪退CPU/App 内存、系统资源限制系统日志与内存;换小模型、缩短上下文
health 加载中模型仍在初始化查日志并等待,而非反复启动副本
浏览器 connection refused当前设备端口有没有监听先查 SSH/服务,而不是清模型缓存
health ok、首页 404UI 文件/构建/路由检查嵌入资源或静态路径;API 与 UI 分开
curl 首页 415压缩与资源支持本次使用 --compressed;再看响应正文
API 401/403Key、服务鉴权、平台授权检查对应服务配置,不把占位 Key 当真实 Key
API 模型名找不到alias / /v1/models / 平台模型 ID不用文件名或别的平台名称猜
回答乱码/角色乱跳tokenizer、模板、错误转换或分片验证完整目录与模板,不只调 temperature
推理慢且 GPU 空闲CPU offload、请求状态、内存/线程idle 时空闲正常;结合执行中日志与 timings 判断
生成很久但没有最终答案思考输出、输出上限、模板检查 reasoning_content、finish_reason、生成预算
SSH 转发 bind 失败本机端口被占用查占用程序用途,换自己的本地转发端口
Docker 前端连不上 localhost容器网络的回环边界从容器内测试可达地址,正确配置网络

排错时保留“执行命令、最后错误、机器、路径、版本、资源占用”。先修最早的相关失败,不要只截长堆栈中间。一次只改变一个关键条件,再用相同检查验证,避免把偶然恢复当成确定根因。

连接应用、优化、排错与扩展

40多模态、RAG、工具调用与模型质量

本章小节
视觉和音视频RAG:让模型利用你的文档工具调用与联网质量不是靠位宽单独决定

视觉和音视频

下载的语言权重与额外投影器、processor、音视频组件须匹配。图像分辨率、图片数量与视频采样会扩大资源和上下文需求。本次 GGUF 仓库有额外视觉资产,但本次启动命令没有指定视觉投影文件,所以本文不把“文本聊天已成功”写成“看图已验证”。

RAG:让模型利用你的文档

RAG 通常是文档解析 → 切片 → embedding → 检索 → 把相关片段加入提示词 → 模型回答并给出处。它通常不改变大语言模型权重。需要额外选择 embedding 模型、存储和检索策略;文件放在模型目录旁边,不会自动让模型读懂它。

工具调用与联网

模型产生工具请求只是第一步,应用还要定义工具、执行动作、传回结果并控制权限。模型本身会写“我搜索到了”,不代表你的部署真的连了搜索工具。把无权限确认的系统命令执行器接给模型,也不是安全的默认教程步骤。

质量不是靠位宽单独决定

用你的真实任务评估中文、代码、数学、事实、上下文利用和提示遵循。模型版本、微调、模板、采样、检索和工具质量都可能影响结果。Q8 比 Q4 保存更多数值信息,不能当作“Q8 保证不幻觉”的结论。

连接应用、优化、排错与扩展

41安全、版本、数据与持续维护

本次回环监听 + SSH 只把服务给本机使用,适合个人实验。对公网或多人提供服务,增加明确身份认证、HTTPS/受控网络、配额与日志管理;按真正的部署边界保护数据,不能只靠“地址很难猜”。

下载权重查许可证与来源。GGUF/Safetensors 减少部分格式层面的风险,但仓库脚本、插件、工具权限与未经核验的 PTH 对象加载仍应单独评估。只读权重也不意味着模型输出可信到可以不检查地执行。

固定已经验证过的模型 revision、文件哈希、引擎 commit、依赖版本和启动参数;升级先测试,不在唯一可用环境里随意混装。保留:模型来源、量化类型、完整路径、运行命令、设备与性能样本。

备份原始数据、启动脚本和有价值的应用状态。AutoDL 数据盘的文件保留和实例释放不是无限期保证:本次控制台提示连续关机 15 天可能释放,规则以后以控制台/官方文档为准。关机前保存重要资料,释放实例前明确备份需求。

本 HTML 保留了你提供的原始截图,里面含实例标识、账户显示和连接地址;没有加入 SSH 密码。它适合个人复盘,公开分享前请评估是否要另做去标识版本。

连接应用、优化、排错与扩展

42文件迁移、离线准备、版本记录与恢复

本章小节
从云端把模型下载到 Windows真正离线运行要提前准备哪些东西下载授权、哈希与固定版本数据要备份哪几类

从云端把模型下载到 Windows

你已有云端 GGUF,迁移到本机通常不需要重新训练或转换。先确认本机磁盘与内存足够、运行时支持该架构,再复制文件。复制约 29GB 权重只带来资产,不会把云端 RTX 3090 算力一起搬过来。

以下在 Windows PowerShell 执行;主机和端口只适用于本次实例,目标盘要有足够空间。传输时实例需在线且 SSH 可用,可能产生时间、计算或流量成本。

powershell
New-Item -ItemType Directory -Path 'C:\Models\Qwen3.8-27B' -Force | Out-Null
scp -P 33976 'root@connect.nmb2.seetacloud.com:/root/autodl-tmp/models/Qwen3.8-27B/Qwen3.8-27B-Q8_0.gguf' 'C:\Models\Qwen3.8-27B\'
Get-FileHash -LiteralPath 'C:\Models\Qwen3.8-27B\Qwen3.8-27B-Q8_0.gguf' -Algorithm SHA256

scp 的端口选项是大写 -P,ssh 是小写 -p。不要把 SSH 隧道端口 18080 当作文件传输端口。传输中断时,先确认工具是否支持续传;上述普通 scp 命令不能当作完整的断点续传方案。

在 AutoDL 的 Linux Terminal 计算源文件哈希:

bash
sha256sum /root/autodl-tmp/models/Qwen3.8-27B/Qwen3.8-27B-Q8_0.gguf

比较两边的 64 位十六进制值,忽略大小写,应该一致。这证明复制前后内容相同;如果源文件本来就是错误版本,二者相同也不会替你证明它来自官方。读取整个 29GB 文件计算哈希会耗时,这是正常磁盘工作。

真正离线运行要提前准备哪些东西

  1. 完整模型资产:GGUF 或 HF 目录、分片、分词器、必要 processor/mmproj;LoRA 还需正确基座。
  2. 可执行环境:兼容的引擎、DLL/共享库、驱动、Python 依赖及实际需要的编译工具。
  3. 使用入口:聊天 App 或本地网页资源;本次 API 正常而 UI 缺失就是漏掉网页资产的例子。
  4. 配置:路径、模板、设备、上下文、模型别名与加载参数。
  5. 断网验收:断开外部网络后重新加载,发送短问题,验证全部必要资源都已就位。

HF 的 HF_HOME 是缓存根目录,不代表随意复制这个目录里的一个符号链接就能完整迁移。可以提前下载到明确的 --local-dir,迁移整个模型目录。用仓库 ID 加载可能查网络;离线时使用本地路径与 local_files_only=True,需要时设置 HF_HUB_OFFLINE=1。HF 离线与缓存环境变量 ↗

powershell
$env:HF_HUB_OFFLINE = '1'
.\hf-runtime\Scripts\python.exe .\run_local_model.py

上面假设你已按 Python 加载章节保存了脚本;环境变量仅作用于当前 PowerShell 及其启动的子进程。它不是下载命令,也不能修复缺失文件。llama-server 直接加载本地 GGUF 时不会因为这个变量获得新能力。

下载授权、哈希与固定版本

公开模型未登录的警告与私有/受限仓库的拒绝访问是两种情况。受限仓库可能需要先在页面接受条件,再用有权限的账号登录;“登录成功”不能替代许可证或准入授权。不把 Token 写到可以分享的脚本或截图里。

bash
hf auth login
hf auth whoami

对于本次只下载一个量化文件的目录,当前 HF 工具支持按仓库校验本地已取得的文件;目录里没下载其他量化版本出现缺失提示是预期的,不应为了消掉提示下载整个仓库:

bash
/root/autodl-tmp/hf-tools/bin/hf cache verify \
  unsloth/Qwen3.8-27B-GGUF \
  --local-dir /root/autodl-tmp/models/Qwen3.8-27B

先查 hf cache verify --help 确认工具版本有该子命令;校验需要访问仓库,不等于离线操作。如果没有这项功能,使用发布者提供的正确文件校验值或源/目标哈希比较。原部署的证据是下载完成和成功加载,不把本次新增校验教程写成已经对服务器权重做过该校验。 HF 登录、下载与校验 ↗

为可复现性记录:仓库 ID + revision/commit、文件名 + SHA-256、引擎版本或源码 commit、驱动/系统、启动参数、实测问题与结果。更新时保留旧可执行环境和配置,先验证新版本再切换。仅 pip freeze 不足以完整记录 GPU 驱动、系统库和编译选项;离线装依赖也要准备与目标 OS/Python/硬件一致的软件包。

数据要备份哪几类

模型权重、启动脚本、聊天记录、RAG 文档/向量库、应用配置是不同资产。备份模型不会自动备份聊天记录;备份聊天记录不会自动保留模型。密钥单独保护,迁移后核对配置指向的是目标机器。

本次截图的“关机一段时间后释放实例”提示意味着需要关注控制台倒计时。关机、保存镜像、备份数据盘、释放实例不是同一个操作;以该平台实际规则为准,别把 /root/autodl-tmp 的名字理解成一定立即丢失,也别理解成永久保留。

连接应用、优化、排错与扩展

43一套能照着做的验收与性能记录

本章小节
按顺序验证,避免拿“健康”替代“可用”怎样记录一次可比较的测量如何选择下一步优化

按顺序验证,避免拿“健康”替代“可用”

检查操作通过标准
资产核对路径、配套文件、来源和哈希完整且与选定版本一致
运行时设备列表、版本、加载日志架构支持,后端符合预期
服务health 和模型列表就绪,能找到正确模型 ID
文本简单中文、有明确答案的问题返回有意义答案,结束原因合理
多轮告诉它一个测试事实,再追问客户端发送历史后能接续
上下文从短输入逐步增加到真实需求没有超预算、异常截断或 OOM
入口浏览器、Python、实际聊天客户端从各自运行位置都可达
稳定性连续请求、停止、重新启动无残留副本,日志与恢复流程明确
费用与数据查实例状态、持久盘及备份明确不用时的操作与保留范围

需要图像、工具、知识库或并发时,给每一项单独增加测试。通过文本验收不能替这些功能验收。

怎样记录一次可比较的测量

至少记录模型与哈希、精度、运行时版本、GPU/CPU、GPU 层数、上下文、并发、输入/输出 tokens、思考模式、预热/缓存情况与错误。相同提示词可以因采样产生不同输出长度,比较总耗时前先看生成量。

可为每个配置先预热一次,再做多次固定条件请求,分别记录生成速度、首 token 等待与总耗时;报告中位数和范围,保留失败次数。缓存命中可能影响输入处理,把“冷请求”和“命中缓存”分开。temperature=0 也不保证所有硬件/后端产生逐字一致的结果。

本次 5.18 与 8.12 tokens/s 是历史短样本,不作为本次文档复查时重新跑出的数字。下面是后续你可填写的空白记录,不虚构更多测量:

配置输出 tokensPrefill 时间Decode 时间 / 速度首 token完整耗时是否成功
冷加载后首请求待测待测待测待测待测待测
预热后重复请求待测待测待测待测待测待测
真实长输入待测待测待测待测待测待测
连续使用 / 手机升温后待测待测待测待测待测待测

如何选择下一步优化

如果目标是减少等待,先判断时间花在网络、排队、prefill、思考还是 decode。当前 Q8 有 CPU 部分时,提高 GPU 放置是可评估的方向;显存预算不足时,也可比较较低位宽且尽量全 GPU 的配置,但必须重新测试真实任务质量。不能从“Q8 精度更高”直接推断它在这张卡上最适合你的需求。

对于 API 返回 finish_reason=length,先看输出是否撞到 max_tokens,再检查输入加输出预算;对于 finish_reason=stop,仍需看答案内容,它只是生成终止条件。流式输出减少用户看见第一段文字的等待感,通常不等于底层计算每秒多产生了 token。

连接应用、优化、排错与扩展

44常见问题:一问一答

本章小节
下载好了为什么还没有答案?下载模型后还要训练吗?本地模型能联网吗?模型会记住我的聊天吗?Q8 不能全装显存,为什么还能运行?GGUF 与 PTH 谁更高级?可以把 safetensors 直接拖到任意 App 吗?为什么手机打开本机地址失败?换 vLLM 一定能变快吗?只关闭网页会停止计费吗?手机跑不动 27B,是不是不能使用它?

下载好了为什么还没有答案?

因为文件还没被匹配的运行时加载。先确认格式/架构,选择 App 或引擎,指定路径,配置资源,加载后才发送请求。下载工具的任务是取文件,不是执行模型。

下载模型后还要训练吗?

通常不需要,现成聊天模型已经训练过。本次做的是推理部署。若拿到 Base 模型,其行为与 Instruct/Chat 模型可能不同,但也不等于必须重新训练才能运行。

本地模型能联网吗?

能否联网取决于应用和工具,不取决于“本地”两个字。运行时离线生成与应用额外搜索是不同功能。

模型会记住我的聊天吗?

客户端保存聊天、请求携带历史、服务复用缓存、参数被训练修改是不同机制。本次没有在线训练,回答不会自动写回 GGUF。网页历史的保存位置以客户端实现为准。

Q8 不能全装显存,为什么还能运行?

llama.cpp 支持 CPU/GPU 混合放置,系统内存承担一部分。本次资源允许这样做,速度比全 GPU 路线可能更低,且层数需要实测。

GGUF 与 PTH 谁更高级?

它们服务不同工作流。GGUF 便于推理分发,PTH 常用于 PyTorch 保存/恢复,Safetensors 是张量存储选择。应按加载器与任务选择,不按后缀排名。

可以把 safetensors 直接拖到任意 App 吗?

不一定。App 需支持相关 runtime、架构与完整目录;模型还可能需要配置、tokenizer、投影器或专用转换。文件类型只是兼容性的一个条件。

为什么手机打开本机地址失败?

手机上的 127.0.0.1 是手机自己。Windows 隧道绑定本机回环,不自动给手机提供服务。需要手机可到达且受控的入口。

换 vLLM 一定能变快吗?

不一定。框架的吞吐优势、模型/量化支持、CPU offload、设备与负载共同决定。本次选 llama.cpp 是因为 GGUF 与混合运行路径合适。

只关闭网页会停止计费吗?

不会。浏览器不是 GPU 实例电源;后台模型仍可运行。停止计算资源计费要按平台规则关机/停实例,存储等其他费用另看平台规则。

手机跑不动 27B,是不是不能使用它?

仍可作为远程客户端使用电脑/云端服务。端侧与远程使用是两条不同路线。

连接应用、优化、排错与扩展

45术语速查与最终验收清单

术语一句话解释
weights训练得到的参数张量
checkpoint某时刻保存的状态,可能不只有权重
architecture模型计算结构,运行时必须实现
tokenizer文本与 token 的转换规则
chat template对话消息组织为模型输入的规则
quantization用较低位宽/表示压缩数值,需质量验证
offload把部分权重或计算放到另一设备/内存层
prefill处理输入上下文阶段
decode逐步生成新 token 阶段
KV cache部分注意力模型复用历史计算的缓存
context单次推理可处理的输入/历史/生成预算
batch同批处理的执行组织,不是聊天历史条数
concurrency同时处理的请求数量
MTP / speculative decoding多 token 预测或草稿验证等加速路线
endpoint提供 API 的网络入口
localhost当前设备或网络命名空间自身
model alias对外公布的模型名,可不同于文件名
cold start尚未准备好的实例/模型初始化阶段

部署验收应该包括:文件完整且许可证明确;设备和架构支持;模型实际加载;健康接口;短问题正确返回;网页/客户端连通;适当资源余量;后台与重启流程;停止计费操作清楚;需要的长上下文、多模态或并发分别验证。

本次已完成: Q8 文件下载、CUDA runtime、40/52 层混合加载、API、SSH、网页聊天、后台启动与短回答对比。后续需求才需要进一步测试: 长文、看图、RAG、MTP、多人服务和手机本地执行。

参考资料与使用说明

46官方资料入口与文档更新时间

本章小节
2026-10-13 复查与修订记录

本手册整理于 2026-10-13(Asia/Shanghai)。实测数字来自这次会话和截图;其他技术路线按官方项目与文档核实。文中每一类框架、格式和平台附近都有对应链接。平台价格、区域、模型供应和软件参数会更新,不把本地 HTML 当作永远不变的兼容清单。

GGUF 工具与格式入口https://github.com/ggml-org/llama.cpp/blob/master/gguf-py/README.mdPyTorch 保存与加载https://docs.pytorch.org/tutorials/beginner/saving_loading_models.htmlSafetensors 官方说明https://huggingface.co/docs/safetensors/indexONNX Runtimehttps://onnxruntime.ai/docs/ExecuTorchhttps://docs.pytorch.org/executorch/stable/index.htmlLiteRT-LMhttps://developers.google.com/edge/litert-lm/overviewHugging Facehttps://huggingface.co/modelsModelScope 魔搭https://github.com/modelscope/modelscopeOllama Libraryhttps://ollama.com/libraryLM Studiohttps://lmstudio.ai/docs/appAutoDLhttps://www.autodl.com/docs/quick_start/Runpod Podshttps://docs.runpod.io/overviewVast.aihttps://docs.vast.ai/AWShttps://aws.amazon.com/ec2/instance-types/Azurehttps://azure.microsoft.com/products/virtual-machinesGoogle Cloudhttps://cloud.google.com/gpu阿里云https://www.alibabacloud.com/product/ecsHF Inference Endpointshttps://huggingface.co/docs/inference-endpoints/index阿里云百炼 / Model Studiohttps://www.alibabacloud.com/help/en/model-studio/what-is-model-studioDeepSeekhttps://api-docs.deepseek.com/硅基流动https://docs.siliconflow.cn/火山方舟https://www.volcengine.com/product/arkOpenAIhttps://platform.openai.com/Anthropichttps://docs.anthropic.com/Geminihttps://ai.google.dev/OpenRouterhttps://openrouter.ai/docs/Togetherhttps://docs.together.ai/Fireworkshttps://docs.fireworks.ai/Open WebUIhttps://docs.openwebui.com/getting-started/quick-start/Difyhttps://docs.dify.ai/AnythingLLMhttps://docs.anythingllm.com/llama.cpphttps://github.com/ggml-org/llama.cppOllamahttps://docs.ollama.com/Transformershttps://huggingface.co/docs/transformers/indexvLLMhttps://docs.vllm.ai/en/latest/getting_started/quickstart/SGLanghttps://github.com/sgl-project/sglangTensorRT-LLMhttps://github.com/NVIDIA/TensorRT-LLMMLX / MLX-LMhttps://github.com/ml-explore/mlx-lmMLC LLMhttps://llm.mlc.ai/docs/MNNhttps://github.com/alibaba/MNNWebLLMhttps://github.com/mlc-ai/web-llmQwen 部署入口https://huggingface.co/Qwen/Qwen3.8-27B#serving-qwen38vLLM GGUF 限制https://docs.vllm.ai/en/latest/features/quantization/gguf/AutoDL 学术资源加速https://www.autodl.com/docs/network_turbo/官方 CUDA 构建说明https://github.com/ggml-org/llama.cpp/blob/master/docs/build.mdHF 下载工具https://huggingface.co/docs/huggingface_hub/guides/cliXet 配置https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhubdisablexetllama-server 参数与接口https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.mdAutoDL SSH 隧道说明https://www.autodl.com/docs/ssh_proxy/Ollama 官方下载页https://ollama.com/download示例模型目录页https://ollama.com/library/qwen3:4b官方导入说明https://docs.ollama.com/importLM Studio 导入规则https://lmstudio.ai/docs/cli/local-models/import加载与卸载参数https://lmstudio.ai/docs/cli/local-models/load本地服务器说明https://lmstudio.ai/docs/developer/core/serverCLI 启动https://lmstudio.ai/docs/cli/serve/server-start官方 releaseshttps://github.com/ggml-org/llama.cpp/releases微软 WSL GPU 指南https://learn.microsoft.com/en-us/windows/ai/directml/gpu-cuda-in-wslOllama 硬件支持https://docs.ollama.com/gpu示例 MLX 仓库https://huggingface.co/mlx-community/Qwen2.5-3B-Instruct-4bitQwen2.5-3B 示例模型卡https://huggingface.co/Qwen/Qwen2.5-3B-InstructPyTorch 官方安装选择器https://pytorch.org/get-started/locally/聊天模板与特殊 tokenhttps://huggingface.co/docs/transformers/chat_templatingPyTorch 序列化说明https://docs.pytorch.org/docs/stable/notes/serialization.htmlTorchScript 当前状态https://docs.pytorch.org/docs/stable/jit.htmlHF bitsandbytes 量化说明https://huggingface.co/docs/transformers/quantization/bitsandbytesSGLang 服务参数https://docs.sglang.io/docs/advanced_features/server_argumentsQwen3.8 专项 cookbookhttps://github.com/sgl-project/sglang/blob/main/docs/cookbook/autoregressive/Qwen/Qwen3.8-27B.mdxPocketPal AI 官方项目https://github.com/a-ghorbani/pocketpal-aillama.cpp Android 文档https://github.com/ggml-org/llama.cpp/blob/master/docs/android.mdMLC Androidhttps://llm.mlc.ai/docs/deploy/android.htmlMLC iOShttps://llm.mlc.ai/docs/deploy/ios.htmlOllama 兼容接口https://docs.ollama.com/api/openai-compatibilityQwen3.8 模型结构说明https://huggingface.co/Qwen/Qwen3.8-27B#model-overviewllama.cpp 投机解码与 MTPhttps://github.com/ggml-org/llama.cpp/blob/master/docs/speculative.mdHF 离线与缓存环境变量https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables

所有截图均为你在本次会话提供的原始 PNG,内嵌后不依赖临时文件路径。点击图片可放大,Esc 关闭;目录搜索不会联网;代码复制仅复制文本,不自动执行。命令中的 /path/to、model.gguf、密钥占位值等必须替换;标注“本次实例”的主机与端口仅用于你这一次连接环境。

2026-10-13 复查与修订记录

此次复查补齐了模型生命周期、非 NVIDIA 后端、CLI 实际导入/加载、Windows Python 环境、流式和多轮调用、手机独立 SSH 转发、文件迁移、离线准备以及验收记录。修正聊天模板二次分词的特殊 token 处理,并给 SGLang 示例明确上下文和单请求预算。

检查范围是技术文字、参考入口、代码语法、原图完整性与离线网页交互。原图保留未修改;新增路线和代码例子未全部在对应 GPU、Mac 或手机上执行,不把文档检查表述为新增硬件实测。历史性能值及本次服务器配置保留原来的证据边界。