千问（Qwen）模型Linux部署操作手册

基于实际环境：Ubuntu 22.04 + 双 RTX 4090 + llama.cpp + Qwen GGUF 模型

一、环境准备

1.1 基础依赖安装

复制代码

sudo apt update
sudo apt install -y build-essential cmake git wget curl

1.2 安装 CUDA Toolkit（已装可跳过）

复制代码

# 查看驱动支持的最高 CUDA 版本
nvidia-smi

# 添加 NVIDIA 仓库（以 Ubuntu 22.04 + CUDA 12.4 为例）
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt update
sudo apt install -y cuda-toolkit-12-4

# 环境变量（永久生效）
echo 'export PATH=/usr/local/cuda-12.4/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.4/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc

# 验证
nvcc --version

二、编译 llama.cpp（启用 CUDA）

注意：新版已经废弃 make LLAMA_CUDA=1，必须使用 CMake。

复制代码

cd /your/workspace   # 例如 /qxq/code/Qwen
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp

# 创建构建目录
mkdir -p build && cd build

# 配置（开启 CUDA，指定 GPU 架构，RTX 4090 为 89）
cmake .. \
    -DGGML_CUDA=ON \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_CUDA_ARCHITECTURES="89" \
    -DGGML_NATIVE=ON

# 编译（利用全部 CPU 核心）
cmake --build . --config Release -j $(nproc)

# 验证编译成功
./bin/llama-cli --help

三、下载 Qwen GGUF 模型

3.1 配置国内镜像（解决网络超时）

复制代码

# 临时设置（每次新终端需重新执行）
export HF_ENDPOINT=https://hf-mirror.com

# 或永久生效
echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.bashrc
source ~/.bashrc

3.2 登录 Hugging Face（如需授权模型）

复制代码

huggingface-cli login
# 粘贴从 https://huggingface.co/settings/tokens 生成的 Read 权限 token
huggingface-cli whoami   # 验证

3.3 下载模型文件

正确的仓库 ID 和文件名 （注意 Qwen_Qwen3.6 中的下划线）：

复制代码

cd /your/workspace/llama.cpp/models

huggingface-cli download bartowski/Qwen_Qwen3.6-35B-A3B-GGUF Qwen_Qwen3.6-35B-A3B-Q4_K_M.gguf --local-dir . --local-dir-use-symlinks False

如果下载中断，可使用 wget 直链（同样走镜像）：

复制代码

wget https://hf-mirror.com/bartowski/Qwen_Qwen3.6-35B-A3B-GGUF/resolve/main/Qwen_Qwen3.6-35B-A3B-Q4_K_M.gguf

3.4 检查文件完整性

复制代码

ls -lh *.gguf

四、命令行交互式推理（测试）

复制代码

cd /your/workspace/llama.cpp/build

./bin/llama-cli -m ../models/Qwen_Qwen3.6-35B-A3B-Q4_K_M.gguf \
    --n-gpu-layers 999 \
    --color \
    --interactive \
    -p "你好，请介绍一下自己"

退出交互模式：按 Ctrl + C 或输入 /bye
如果显存不足，减少 --n-gpu-layers 的值（如 --n-gpu-layers 28）

五、启动 HTTP 服务（API 模式）

5.1 处理端口占用（关键步骤）

启动服务前先检查端口是否被占用（以 8888 为例）：

复制代码

netstat -tulnp | grep 8888

如果显示被其他进程占用（例如 python3.8 PID 32），则终止它：

复制代码

kill -9 32   # 替换为实际 PID

5.2 启动服务（指定单张 GPU）

如果你的服务器有双显卡但只想用一张，设置环境变量：

复制代码

export CUDA_VISIBLE_DEVICES=0   # 使用

然后启动：

复制代码

./bin/llama-server -m ../models/Qwen_Qwen3.6-35B-A3B-Q4_K_M.gguf \
    --n-gpu-layers 999 \
    --host 0.0.0.0 \
    --port 8888

成功日志示例：

复制代码

HTTP server listening

5.3 后台持久运行（可选）

复制代码

nohup ./bin/llama-server -m ../models/Qwen_Qwen3.6-35B-A3B-Q4_K_M.gguf --n-gpu-layers 999 --host 0.0.0.0 --port 8888 > server.log 2>&1 &

六、外部访问测试

6.1 确定访问地址

服务器 IP ：192.168.2.55（你 SSH 连接的 IP）
宿主机映射端口 ：根据你的环境，容器的 8888 映射到了宿主机的 49433（见 SSH 端口信息：8888→49433）

因此外部访问地址为：http://192.168.2.55:49433

6.2 使用 curl 测试流式输出（包含 `<thinking>` 标签）

如果想看到模型的推理过程（<thinking> 内容），需要在提示词中明确要求，并开启流式：

复制代码

curl -N http://192.168.2.55:49433/completion \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "请将你的推理过程放在 <thinking> 标签内，然后再输出最终答案。\n用户问题：1+1等于几？",
    "temperature": 0.7,
    "stream": true
  }'

6.3 使用浏览器访问简易 Web UI

在浏览器打开 http://192.168.2.55:49433，可以看到一个简单的测试页面。输入提示词，点击 Submit 即可（注意该 UI 默认非流式，且可能不显示 <thinking>，建议使用 API 方式）。

七、常见问题及解决方法

问题现象	原因	解决方法
`make: *** No targets`	旧版 make 命令已废弃	改用 CMake 构建（见第二章）
下载模型 401 Unauthorized	未登录或 token 无效	`huggingface-cli login` 并粘贴 Read token
下载模型 404 Not Found	仓库 ID 或文件名错误	访问 `https://hf-mirror.com` 确认正确名称，注意 `Qwen_Qwen3.6` 中的下划线
连接超时 (ConnectTimeout)	国内访问 Hugging Face 慢	设置 `export HF_ENDPOINT=https://hf-mirror.com`
`couldn't bind HTTP server socket, port: 8888`	端口被占用	`netstat -tulnp
外部无法访问 8888 端口	容器端口未映射到宿主机	联系管理员添加映射，或使用已映射的端口（如本例中的 49433 对应容器 8888）
双卡都想用一张卡	默认 llama.cpp 会用所有可见 GPU	启动前设置 `export CUDA_VISIBLE_DEVICES=0`（或 1）
`CUDA error: out of memory`	显存不足	减小 `--n-gpu-layers`，或换用更小量化版本（如 Q4_K_S）

八、附录：一键安装脚本

复制代码

#!/bin/bash
# 完整安装脚本（假设在 /qxq/code 下执行）

set -e

WORK_DIR="/qxq/code"
MODEL_REPO="bartowski/Qwen_Qwen3.6-35B-A3B-GGUF"
MODEL_FILE="Qwen_Qwen3.6-35B-A3B-Q4_K_M.gguf"
export HF_ENDPOINT=https://hf-mirror.com

# 1. 克隆并编译
cd $WORK_DIR
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
mkdir -p build && cd build
cmake .. -DGGML_CUDA=ON -DCMAKE_BUILD_TYPE=Release -DCMAKE_CUDA_ARCHITECTURES="89" -DGGML_NATIVE=ON
cmake --build . --config Release -j $(nproc)

# 2. 下载模型
cd ../models
huggingface-cli download $MODEL_REPO $MODEL_FILE --local-dir . --local-dir-use-symlinks False

echo "安装完成！"
echo "启动服务命令（单卡）:"
echo "cd $WORK_DIR/llama.cpp/build && export CUDA_VISIBLE_DEVICES=0 && ./bin/llama-server -m ../models/$MODEL_FILE --n-gpu-layers 999 --host 0.0.0.0 --port 8888"

复制代码

注意事项：

所有命令路径请根据你的实际目录调整。
如果使用容器环境，确保容器启动时已映射所需端口（例如 -p 49433:8888）。
双卡改单卡时，CUDA_VISIBLE_DEVICES 只在当前 shell 生效，如需永久可写入 ~/.bashrc。

千问（Qwen）模型Linux部署操作手册

一、环境准备

1.1 基础依赖安装

1.2 安装 CUDA Toolkit（已装可跳过）

二、编译 llama.cpp（启用 CUDA）

三、下载 Qwen GGUF 模型

3.1 配置国内镜像（解决网络超时）

3.2 登录 Hugging Face（如需授权模型）

3.3 下载模型文件

3.4 检查文件完整性

四、命令行交互式推理（测试）

五、启动 HTTP 服务（API 模式）

5.1 处理端口占用（关键步骤）

5.2 启动服务（指定单张 GPU）

5.3 后台持久运行（可选）

六、外部访问测试

6.1 确定访问地址

6.2 使用 curl 测试流式输出（包含 <thinking> 标签）

6.3 使用浏览器访问简易 Web UI

七、常见问题及解决方法

八、附录：一键安装脚本

6.2 使用 curl 测试流式输出（包含 `<thinking>` 标签）