Qwen3-Embedding-4B 本地部署实战：llama.cpp 与 vLLM 集成指南

3.1 准备工作

llama.cpp 是一个用 C/C++ 编写的轻量级大模型推理框架，支持 CPU/GPU 混合计算，特别适合资源受限环境下的模型部署。它原生支持 GGUF 格式的量化模型，而 Qwen3-Embedding-4B 已发布官方 GGUF 镜像，可直接加载运行。

所需工具：

• Git
• CMake / Make
• GCC 或 Clang 编译器
• CUDA SDK（若启用 GPU 加速）
• Python 3.8+

步骤一：克隆并编译 llama.cpp

首先克隆仓库并进入目录，然后清理旧构建并重新编译。如果启用了 NVIDIA GPU 加速，需确保已安装 CUDA 驱动和 cuBLAS 库。

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
make clean && make LLAMA_CUBLAS=1 -j

步骤二：下载 Qwen3-Embedding-4B 的 GGUF 模型

前往 Hugging Face 获取已转换的 GGUF 模型文件。推荐使用 Q4_K_M 或 Q5_K_S 量化等级，在精度与性能之间取得良好平衡。

wget https://huggingface.co/Qwen/Qwen3-Embedding-4B-GGUF/resolve/main/Qwen3-Embedding-4B-GGUF-Q4_K_M.gguf

步骤三：启动嵌入服务

使用 main 可执行程序运行嵌入服务。这里我们开启 HTTP API 模式，以便后续调用。

./main \
  -m ./models/Qwen3-Embedding-4B-GGUF-Q4_K_M.gguf \
  --port 8080 \
  --embedding \
  --n-gpu-layers 35 \
  --batch-size 512 \
  --threads 8

参数说明：

• --embedding：启用向量输出模式
• --n-gpu-layers 35：尽可能多地将层卸载到 GPU（适用于 12GB 显存以上设备）
• --batch-size：批处理大小，影响吞吐量
• --port：HTTP API 端口

服务启动后可通过以下接口获取向量：

POST http://localhost:8080/embedding
Content-Type: application/json
{
  "content": "这是一段需要编码的中文文本"
}

响应示例：

{
  "embedding": [0.123, -0.456, ..., 0.789],
  "length": 2560,
  "model": "Qwen3-Embedding-4B"
}

4. 使用 vLLM + Open WebUI 构建可视化知识库系统

虽然 llama.cpp 提供了轻量级部署方案，但对于需要图形界面、用户交互和知识库管理的应用场景，推荐使用 vLLM + Open WebUI 组合构建完整的语义搜索平台。

4.1 技术栈概述

• vLLM：高性能推理引擎，支持 PagedAttention，显著提升吞吐和显存利用率。
• Open WebUI：前端友好的 Web 界面，支持聊天、知识库上传、RAG 检索等功能。
• Qwen3-Embedding-4B：作为底层 embedding 模型，负责文档切片向量化。

4.2 部署步骤

步骤一：拉取并运行 Open WebUI 容器

docker run -d \
  -p 3000:8080 \
  -p 8888:8888 \
  -e OPENAI_API_KEY=dummy \
  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
  -v open-webui:/app/backend/data \
  --name open-webui \
  ghcr.io/open-webui/open-webui:main

注意：若使用 Docker Desktop，host.docker.internal 可访问宿主机服务；Linux 用户需替换为实际 IP。

步骤二：部署支持 Qwen3-Embedding-4B 的 vLLM 服务

目前 vLLM 尚未内置 Qwen3-Embedding-4B 支持，但可通过自定义模型注册方式加载。我们需要编写一个简单的 FastAPI 包装器来暴露标准 Embedding 接口。

创建 embedding_model.py：

from vllm import LLM, SamplingParams
import torch

class Qwen3EmbeddingModel:
    def __init__(self, model_path="Qwen/Qwen3-Embedding-4B"):
        self.llm = LLM(
            model=model_path,
            tensor_parallel_size=1,
            dtype="half",
            gpu_memory_utilization=0.9,
            enforce_eager=True,
            max_model_len=32768
        )

    def encode(self, texts):
        sampling_params = SamplingParams(temperature=0, max_tokens=1)
        outputs = self.llm.generate(texts, sampling_params, use_tqdm=False)
        embeddings = []
        for output in outputs:
            # 获取最后一层 [EDS] token 的隐藏状态
            last_hidden_state = output.outputs[0].logprobs[-1]
            embeddings.append(last_hidden_state.tolist())
        return embeddings

启动 FastAPI 包装服务：

from fastapi import FastAPI
import uvicorn

app = FastAPI()
model = Qwen3EmbeddingModel()

@app.post("/v1/embeddings")
def get_embeddings(request: dict):
    texts = request["input"]
    vectors = model.encode(texts)
    return {
        "data": [
            {"embedding": vec, "index": i} for i, vec in enumerate(vectors)
        ],
        "model": "Qwen3-Embedding-4B",
        "object": "list"
    }

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)

步骤三：配置 Open WebUI 使用自定义 Embedding 接口

进入 Open WebUI 设置页面 → Model Settings → Embedding Provider：

• Provider: Custom
• Base URL: http://<your-host-ip>:8000/v1
• Model: Qwen3-Embedding-4B

保存后即可在知识库上传功能中选择该模型进行文档向量化。

5. 效果验证与接口调试

5.1 设置 Embedding 模型

在 Open WebUI 中完成上述配置后，进入 Knowledge 页面，点击'Add Knowledge Base'，选择刚刚注册的 Qwen3-Embedding-4B 模型作为编码器。

[图示：Open WebUI 知识库设置界面]

5.2 上传文档并验证检索效果

上传一份包含技术文档或多语言内容的 PDF 文件，系统会自动分块并调用 embedding 接口生成向量索引。

随后可在聊天窗口输入相关问题，例如：

'请总结这篇文档中关于气候变化的主要观点'

系统将执行 RAG 流程：

1. 对问题进行向量化
2. 在向量数据库中检索最相似的文本片段
3. 将上下文注入 LLM 进行回答

结果准确率明显优于传统 TF-IDF 或小尺寸 embedding 模型。

[图示：RAG 检索结果展示]

5.3 查看接口请求日志

可通过浏览器开发者工具或代理工具（如 Charles）监控 /v1/embeddings 请求：

{
  "input": [
    "全球变暖是由于温室气体排放增加引起的。",
    "Climate change poses risks to biodiversity."
  ]
}

返回的向量可用于进一步分析余弦相似度、聚类效果等。

[图示：API 请求日志]

6. 总结

Qwen3-Embedding-4B 凭借其 4B 参数、32k 上下文、2560 维高维向量、多语言支持和优异的 MTEB 表现，已成为当前开源社区中最值得尝试的中等规模 embedding 模型之一。无论是个人项目还是企业级应用，都可以借助其出色的性能和灵活的部署方式快速构建语义搜索系统。

本文介绍了两种主流部署路径：

1. 轻量级方案：使用 llama.cpp + GGUF 模型，在 RTX 3060 等消费级显卡上实现低延迟、高吞吐的嵌入服务；
2. 全功能平台：结合 vLLM + Open WebUI，打造支持知识库管理、RAG 检索和可视化交互的企业级 AI 助手。

此外，模型支持 指令感知 和 在线维度压缩，极大提升了工程实用性。Apache 2.0 协议也为其商业化应用扫清了法律障碍。对于希望快速体验的开发者，建议直接从官方渠道拉取预置环境镜像，一键部署完整系统。