千问（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。