企业官网建设流程全解析

上周有朋友抱着一台带 24G 显存的机器来问我，说手里有一堆内部文档，想用 Gemma 的指令微调版本搭一个问答工具，又不想自己写几百行推理胶水代码。我给他演示了一圈 Xinference，从装环境到把 gemma-instruct 拉起来、调通 OpenAI 兼容接口，前后不到半小时。Xinference 是一个统一的模型推理与部署框架，它把各家开源模型的加载、量化、API 封装、并发管理这些脏活累活收进一个命令行和一套 Web UI 里，你只需要告诉它模型名、参数量和格式，剩下的它自己编排。Gemma 是开源社区发布的一系列轻量级开放权重模型，it 指的就是 instruction-tuned 指令微调版，专门用来做对话、问答这类任务。

这篇东西写给三类人：一是手上有卡、想快速把大模型跑成服务的人；二是被 transformers 手写推理脚本折磨过、想换个省心工具的人；三是需要给团队内部搭一个统一模型入口、后面还要接多个模型的人。下面我按自己的实操顺序讲，先说选型逻辑，再说环境盘点、安装启动、部署 Gemma 的完整流程，最后把踩过的坑整理成排查表。每一步我都给出命令和参数背后的原因，方便你按自己的硬件条件改。

1. 为什么在 Xinference 上部署 Gemma，而不是直接跑原始权重

1.1 手写 transformers 推理脚本的四个隐形坑

很多人第一次跑 Gemma 的路线是：装 transformers、写个AutoModelForCausalLM.from_pretrained、把权重加载到显存、再拼一个对话模板。跑通一次 demo 没问题，但要变成"服务"，立刻会撞上四堵墙。

第一堵是显存管理。裸跑的时候你很难控制 KV Cache 的预分配，模型加载完之后剩多少显存全靠猜，长上下文一来就 OOM，你得自己去调max_new_tokens、past_key_values的裁剪逻辑。第二堵是并发。transformers 的 generate 是同步阻塞的，两个请求同时进来，第二个就得排队干等，想上批处理又得自己写 batching 和调度。第三堵是量化。Gemma 7B 的 FP16 权重差不多 14 到 15GB，你想用 4bit 量化省显存，得自己接 bitsandbytes 或者换 GPTQ 权重重打包，每个模型的适配细节都不一样。第四堵是接口封装。跑通之后你还得用 FastAPI 包一层，处理流式输出、错误码、鉴权、多模型路由。

这四堵墙每一堵都不难，但叠起来就是几百行代码加一堆版本依赖，而且换一个模型你还得重来一遍。Xinference 干的事就是把这套东西标准化：模型以"模型名 + 参数量 + 格式"的元组描述，引擎负责加载，框架负责调度和暴露接口。你换模型的时候只改命令行参数，不碰代码。

1.2 Xinference 到底解决的是什么问题

用一句话概括：它把"模型推理"这件事从"写代码"降级成"下指令"。你在命令行敲xinference launch，它去模型仓库拉权重、选引擎、按显存预算加载、注册到服务里、分配一个 model_uid，然后你在 Web UI 或者 REST 接口里就能直接对话。

它内部有几层设计值得说清楚。第一层是模型抽象层，所有模型被归一成 chat、generate、embedding 这几类能力，调用方式统一，Gemma、Qwen、Llama 这些名字对你来说只是参数差异。第二层是引擎适配层，同一个模型可以选择用 transformers 引擎跑、用 vLLM 引擎跑、用 llama.cpp 引擎跑（对应 gguf 格式），你不需要改任何业务代码就能切。第三层是服务层，它默认起一个本地服务，监听 9997 端口，同时提供原生 API 和 OpenAI 兼容的/v1/chat/completions，你现有的、按 OpenAI 接口写的客户端代码基本可以原样搬过来，只改 base_url 和 model 字段。

还有一层容易被忽略但很实用：Web UI。模型列表、加载状态、显存占用、对话测试都可视化，对不熟悉命令行的人来说，排查"模型到底加载成功没有"这件事省了很多事。

1.3 和 Ollama、vLLM、FastChat 的横向对比

选型这件事没有绝对答案，我把几个常见方案按实际使用感受列一下，你可以对照自己的场景挑。

我的实际体会是：Xinference 的优势在"编排"，它可以把 vLLM 当作后端引擎来用，也就是说你既要吞吐又要统一管理的时候，不需要二选一。而 Ollama 的优势在"开箱即用"，本机跑个量化模型确实快，但你要挂三个模型、要按模型分组做权限、要接内部网关，就得上更重的方案。所以我给那位朋友的建议是：先用 Xinference 把流程跑通，等真出现吞吐瓶颈了，再把 Gemma 那个实例的引擎从 transformers 切成 vLLM，其余不动。

2. 动手前的环境盘点与依赖清单

2.1 显存怎么算，Gemma 各尺寸跑得动吗

先算账，别装完了才发现卡不够。模型占显存的大头是三块：权重、KV Cache、框架和 CUDA 上下文的固定开销。

权重这块按参数量和精度估：FP16 每 10 亿参数约 2GB，所以 Gemma 2B 约 4 到 5GB，Gemma 7B 约 14 到 15GB。量化之后按位宽折算，4bit 大约是 FP16 的四分之一多一点，7B 的 Q4 量化权重落在 4.5 到 5GB 区间。KV Cache 跟上下文长度、批大小、层数、隐藏维度都相关，粗略按"每个并发请求预留 1 到 2GB"来估不会太离谱。固定开销方面，CUDA 上下文加框架本身一般吃掉 1 到 2GB。

我整理了一张对照表，你可以直接对号入座：

注意：表里的"建议最低显存"是按单并发、上下文 2K 到 4K 估的。如果你要开多并发或者长上下文，往上加 30% 到 50% 比较稳妥。

2.2 软件环境：Python、CUDA 和驱动的版本对齐

这一步是新手最容易翻车的地方，我见过太多"装完了启动报 CUDA error"的案例，根子都在版本没对齐。

驱动层，先跑nvidia-smi看右上角的 CUDA Version，那是驱动支持的最高 CUDA 版本，不是你实际装的版本。框架层，PyTorch 的 wheel 包是绑定 CUDA 版本编译的，比如cu121对应 CUDA 12.1。这两者要满足"驱动支持的版本 ≥ PyTorch 编译的版本"。举个具体例子：驱动显示 CUDA 12.2，那你装 cu121 的 torch 没问题，装 cu124 的就会报错。

Python 版本我建议 3.10 或 3.11。3.9 也能跑，但部分较新的依赖会挑版本；3.12 有些包的预编译轮子还没跟上，容易触发源码编译，耗时不说还容易失败。虚拟环境一定用起来，conda 或者 venv 都行，别往系统 Python 里灌。

# 先确认驱动和显卡状态 nvidia-smi # 创建一个干净的虚拟环境 conda create -n xinf python=3.11 -y conda activate xinf # 确认 python 版本 python -V

2.3 磁盘空间和模型缓存目录的规划

模型权重很占地方。Gemma 7B 的 FP16 权重下载下来 15GB 左右，如果你同时试 pytorch 和 gguf 两个格式，再加上量化版本，很容易吃掉五六十 GB。安装前先df -h看一眼，给模型目录留足空间，建议至少 100GB 余量，后面换模型不用反复删。

Xinference 默认把模型缓存在用户目录下的一个隐藏文件夹里。这个位置在系统盘上，很多人系统盘就 50G，跑两个模型就满了。我的做法是一开始就把缓存目录指到大盘上，用环境变量设一次，后面所有的模型都落在那里，不用每次启动手动传参。

# 建议提前规划好，避免系统盘被撑爆 export XINFERENCE_HOME=/data/xinference mkdir -p $XINFERENCE_HOME

这个变量同时管理虚拟环境和模型缓存，换机器或者备份的时候整个目录拷走就行，省事。

3. 从零安装 Xinference 并启动服务

3.1 pip 安装：all 和按引擎分装怎么选

Xinference 的 pip 包有几种装法，差别在于带的引擎多不多。xinference[all]是全家桶，包含 transformers、vLLM、llama.cpp 等所有后端，体积大但省心；xinference[transformers]只带 transformers 引擎；xinference[vllm]只带 vLLM。如果你是第一次用、想少折腾，直接上全家桶。

pip install "xinference[all]"

装的过程中会拉一堆依赖，其中 torch 的体积最大。如果公司内网下载慢，可以临时指定软件源：

pip install "xinference[all]" -i https://pypi.tuna.tsinghua.edu.cn/simple

提示：装完之后先跑python -c "import torch; print(torch.__version__, torch.cuda.is_available())"，输出里带True才说明 torch 认得到卡。这一步不通过，后面全白搭。

3.2 启动本地服务的几个关键参数

安装完成后有两个常用命令要分清楚：xinference-local是启动本地服务的，xinference launch是向已启动的服务申请加载模型的。很多人第一次用会直接敲 launch，然后报连接失败，原因是服务没起来。

# 前台启动，方便看日志 xinference-local --host 0.0.0.0 --port 9997

参数解释一下：--host 0.0.0.0表示监听所有网卡，别的机器能访问；如果你只想本机用，写127.0.0.1更安全。--port默认就是 9997，冲突了再改。还有一个--log-level，调试阶段设成debug，能看到模型加载时每一步在干什么，排查问题时很有用。

# 后台运行，日志重定向到文件 nohup xinference-local --host 0.0.0.0 --port 9997 --log-level info > xinf.log 2>&1 &

服务起来之后打开浏览器访问http://127.0.0.1:9997，能看到 Web UI。左边是模型列表，按能力分类，语言模型、嵌入模型、多模态都在里面。右上角能看到当前已加载的模型和占用的显存。

3.3 用 Web UI 摸清模型清单

我建议第一次部署之前先在 UI 里把模型清单翻一遍。点进语言模型分类，能找到 gemma-instruct，点开之后会列出可选的参数量（2B、7B）、格式（pytorch、gguf）、量化方式。这个列表其实就是命令行参数的来源，UI 上显示什么，命令行就能传什么，两者是一一对应的。

UI 里还有一个"Launch"按钮，点一下等价于执行一条 launch 命令。对不熟悉命令行的人来说，这是最快的验证方式。但我还是建议你把它当成"可视化说明书"用，实际部署走命令行，因为命令行能写进脚本、能复制给别人、能进版本管理。

提示：如果你在 UI 里看不到某个模型，多半是版本问题。Xinference 的模型清单随版本更新，新模型要升级版本才有。升级命令是pip install -U "xinference[all]"，升完重启服务。

4. 部署 Gemma-it 的完整实操流程

4.1 模型命名规则：gemma-instruct 和 gemma-it 的关系

先澄清一个名词问题。开源社区发布的 Gemma 有两个版本，一个是基座版（base），适合继续预训练或者微调；另一个是指令微调版（instruction-tuned），也就是常说的 it 版。在 Xinference 的模型注册表里，指令微调版的名字是gemma-instruct，所以标题里说的"gemma-it"落到命令里就是--model-name gemma-instruct。这个对应关系搞错了会报"模型不存在"。

参数上还有几个必填项要理解：--size-in-billions是参数量，单位是十亿，Gemma 就填 2 或 7；--model-format是权重格式，pytorch 是原始权重，gguf 是 llama.cpp 用的量化格式；--quantization只在 gguf 格式下有意义，常见值有 q4_0、q4_k_m、q5_k_m、q8_0。这几个参数拼起来，就唯一确定了一份权重。

4.2 最小可用命令：先把 2B 跑通

我建议都从 2B 开始，因为它加载快、显存压力小，能在几分钟内验证整条链路是否通。别一上来就 7B，万一下载卡住或者显存不够，你分不清是环境问题还是模型问题。

xinference launch \ --model-name gemma-instruct \ --size-in-billions 2 \ --model-format pytorch

执行之后终端会有一段等待，日志里能看到下载进度和解码器加载过程。成功之后会返回一个 model_uid，形如gemma-instruct-2b-xxxx，这串 ID 后面调接口要用到。

如果显存紧张，直接上 gguf 的量化版：

xinference launch \ --model-name gemma-instruct \ --size-in-billions 2 \ --model-format gguf \ --quantization q4_k_m

量化版的好处不只是显存，加载速度也明显更快，因为文件小、读取少。实测 2B 的 q4_k_m 在普通 SSD 上十几秒就能加载完，而 FP16 版本要等将近一分钟。

4.3 7B 的两种跑法：transformers 引擎和 vLLM 引擎

2B 跑通之后，7B 只是把参数量改掉。如果你的卡是 24G，FP16 能跑，但要注意控制上下文长度，因为 KV Cache 会吃掉剩余显存。

xinference launch \ --model-name gemma-instruct \ --size-in-billions 7 \ --model-format pytorch

如果追求并发吞吐，可以显式指定 vLLM 引擎：

xinference launch \ --model-name gemma-instruct \ --size-in-billions 7 \ --model-format pytorch \ --model-engine vllm

这里有个容易踩的坑要说清楚：vLLM 引擎启动时会按比例预占显存作为 KV Cache 池，默认比例比较高，在 24G 卡上跑 7B FP16 时有可能启动失败，报显存不足。解决办法是通过额外参数把这个比例调低，具体做法是在 launch 时传--gpu-memory-utilization 0.85这类参数（不同版本参数名可能有差异，以xinference launch --help输出为准）。我一般是先 0.85 试，起不来再降到 0.8。

4.4 用 Python 客户端和 REST 接口调用模型

模型加载好之后，调用方式有两种。第一种是 Xinference 自己的 Python 客户端，适合写脚本和做集成：

from xinference.client import Client client = Client("http://127.0.0.1:9997") # 直接在客户端里申请加载，省去命令行那一步 model_uid = client.launch_model( model_name="gemma-instruct", model_format="pytorch", size_in_billions=2, ) model = client.get_model(model_uid) resp = model.chat( "用三句话解释一下什么是模型量化", generate_config={"max_tokens": 256, "temperature": 0.7} ) print(resp["choices"][0]["message"]["content"])

第二种是走 REST 接口，Xinference 提供了 OpenAI 兼容的路径，这一点很关键，意味着你现有的按 OpenAI 写的客户端代码只需要改 base_url：

curl http://127.0.0.1:9997/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "gemma-instruct-2b-xxxx", "messages": [ {"role": "user", "content": "你好，介绍一下你自己"} ], "temperature": 0.7, "max_tokens": 512 }'

注意model字段填的是 model_uid，不是gemma-instruct这个名字。这是新手最常见的 400 错误来源，报错信息一般是 model not found，很多人会误以为是模型没加载成功，其实是 ID 填错了。

流式输出也支持，在请求体里加"stream": true，接口会按 SSE 格式逐块返回。做聊天界面的时候必须用这个，否则用户要盯着空白屏等十几秒。

4.5 关键参数对效果和速度的实际影响

generate_config里有几个参数直接影响体验。max_tokens是输出上限，设太小会被截断在半句话，设太大又会拖慢响应，我一般对话场景给 512 到 1024。temperature控制随机性，做事实问答给 0.1 到 0.3，做创意写作给 0.7 到 0.9。top_p和top_k是采样范围控制，一般调其中一个就够了。

还有一个参数容易被忽略：stop。gemma-instruct 用的对话模板有特定的结束标记，如果你自己拼 prompt 而没用框架内置的模板，模型可能会在输出末尾继续吐出多余的标记符号。用框架的 chat 接口就不会有这个问题，因为它会自动套模板；但如果你调generate接口自己拼字符串，就要手动处理。

注意：gemma-instruct 是有对话模板的，格式是 user 和 model 交替。不要直接拿基座版的拼接习惯套上去，输出质量会明显下降。用 chat 接口最省心。

5. 常见报错与排查实录

5.1 显存不足：从报错信息倒推是哪一块吃多了

OOM 的报错信息通常是CUDA out of memory加上一串分配失败的数字。看到这个别急着降参数，先看报错里的"已分配"和"尝试分配"两个数字。如果已分配已经接近总显存，说明权重本身放不下，得换量化；如果已分配才用了三分之一就报错，那多半是 KV Cache 预分配要得太多，或者别的进程占着卡。

排查顺序我一般是这么走的：先nvidia-smi看有没有僵尸进程占着显存，kill -9掉；再看是不是同一个模型重复加载了多个实例，用 UI 或者xinference list查一下；最后才考虑换 gguf 量化或者降 vLLM 的显存占比。

# 查当前所有已加载模型 xinference list # 卸载掉不用的 xinference terminate --model-uid gemma-instruct-2b-xxxx

5.2 权重下载卡住不动

国内环境下最常见的现象是日志停在某一行不动，几分钟没有任何进展。原因是权重默认从境外源拉取，链路质量不稳定。解决办法是在启动服务之前设置一个可用的镜像地址：

export HF_ENDPOINT=https://hf-mirror.com xinference-local --host 0.0.0.0 --port 9997

这个变量要在启动服务的那一个 shell 里设，因为加载模型是服务进程在做。如果你是用 nohup 后台起的服务，记得把变量写在命令前面或者写进启动脚本里，别在另一个终端里 export，那样不生效。

还有一种情况是下载到一半断了，重新 launch 会从头开始。Xinference 的缓存机制是分片下载的，已经下完的分片不会重下，所以断了就再执行一次同样的命令，它会接着下。

5.3 CUDA 版本不匹配的典型表现

报错长这样：RuntimeError: Detected that PyTorch and torchvision were compiled with different CUDA versions或者The detected CUDA version mismatches the version that was used to compile PyTorch。看到这类信息，说明 torch 装错了版本。

处理方式是先卸载再按驱动支持的版本重装。假设驱动支持 12.1：

pip uninstall -y torch torchvision torchaudio pip install torch --index-url https://download.pytorch.org/whl/cu121

装完再跑一次torch.cuda.is_available()验证。如果返回 False，先别怀疑框架，检查是不是装成了 CPU 版——CPU 版的 wheel 名字里不带 cu 后缀，很多人用默认源装就会自动落到 CPU 版上。

5.4 端口占用和服务假死

9997 被占用时启动会报Address already in use。查占用：

lsof -i:9997

如果不是自己的进程，换端口；如果是上一次没关干净的服务，kill掉再起。还有一种"假死"现象：服务进程还在，但 UI 打不开、接口没响应。这种情况多数是模型加载把主线程卡住了，去看日志文件最后几十行，通常能看到正在加载哪个模型。等它加载完就好了，别急着 kill，否则又得重来一遍。

5.5 输出乱码、截断、答非所问

输出乱码一般是编码问题，接口返回的文本里混进了多余的字节。检查你的客户端是不是按 UTF-8 解析响应，requests默认会猜编码，保险做法是显式指定response.encoding = "utf-8"。

输出被截断在半句话，看max_tokens是不是设小了，或者finish_reason字段是不是length。如果是length，说明确实是用完了预算。

答非所问最典型的原因是对话模板没套对。gemma-instruct 期望的是特定格式的多轮结构，直接用一段纯文本调generate接口，模型会按"续写网页文本"的模式来回答。用chat接口或者 OpenAI 兼容的/v1/chat/completions就不会有这个问题。

5.6 问题速查表

我把上面这些整理成一张表，出问题的时候按表对一遍，能省不少时间。

提示：排查顺序建议固定成"看日志 → 看显存 → 看模型列表 → 看接口参数"，从底层往上查，比瞎试参数快得多。

6. 让服务真正可用：几个生产环境的细节打磨

6.1 模型缓存迁移和多模型共存

前面提过用XINFERENCE_HOME统一管理目录。这个变量不只是一个路径，它下面是模型缓存、虚拟环境、临时文件的集合。如果你想在已有部署上迁移到新磁盘，直接把整个目录rsync过去，改一下环境变量，重启服务就行，模型不用重下。

多模型共存是 Xinference 相对轻量方案的优势。同一个服务里你可以同时挂 gemma-instruct 2B 做轻量问答、挂一个嵌入模型做向量检索、再挂一个 7B 做复杂推理，每个模型有自己的 model_uid 和显存配额。但要注意总显存是硬约束，挂之前先算好总和，留 2GB 以上余量给框架本身。

# 查一下当前每个模型占了多少显存 xinference list

6.2 开机自启和后台常驻

开发阶段用 nohup 顶着就行，真要长期跑，建议交给系统服务管理器。核心是把启动命令、环境变量、工作目录、日志路径都固定下来，避免重启之后环境变量丢了导致模型下到系统盘上。

# 简单的后台启动脚本，把环境变量和启动命令绑在一起 cat > start_xinf.sh << 'EOF' #!/bin/bash export XINFERENCE_HOME=/data/xinference export HF_ENDPOINT=https://hf-mirror.com cd /data/xinference exec xinference-local --host 0.0.0.0 --port 9997 --log-level info EOF chmod +x start_xinf.sh nohup ./start_xinf.sh > xinf.log 2>&1 &

这个脚本的好处是所有配置在一处，换机器的时候拷贝这个文件加数据目录就行，不用回忆当时设了哪些变量。

6.3 性能调优的几个抓手

如果发现响应慢，先分清是首字延迟慢还是整体生成慢。首字延迟高通常是模型加载、模板处理、调度排队导致的；整体生成慢是解码速度不够。前者可以靠保持实例常驻、预热请求解决；后者要换引擎或者换量化。

上下文长度是一个隐藏的成本项。很多人不看这个参数，默认开很大，结果 KV Cache 把显存吃满，能支持的并发直接掉到 1。实际业务里 4K 上下文能覆盖绝大多数问答场景，没必要一上来就 32K。

最后是批处理。transformers 引擎的批处理能力有限，真要上并发，切 vLLM 引擎是更直接的路子。切换只需要在 launch 的时候加一个--model-engine vllm，业务代码一行不用改，这是 Xinference 这套抽象最值钱的地方。

我自己在实际操作中的体会是，部署大模型这件事，难的从来不是那一条 launch 命令，而是命令背后对显存、格式、引擎、接口的理解。把这些搞清楚，换任何模型都只是改几个参数的事。至于那些版本冲突和端口占用，踩过一次记下来，下次就是五分钟的事。