✨使用 vLLM + Docker 部署 Qwen3-Embedding-8B 并实现高效文本向量生成（附 `curl` 测试）_qwen3-embedding docker

技术文档

🚀 使用 vLLM + Docker 部署 Qwen3-Embedding-8B 并实现高效文本 向量生成（附 `curl` 测试）

在大模型的落地过程中，构建高吞吐、易部署的向量生成服务变得尤为重要。本文将介绍如何基于 vLLM 框架，通过 Docker 快速部署 Qwen3-Embedding-8B 模型，并实现高效嵌入（embedding）接口服务。

🧱 环境准备

操作系统：Linux（推荐 Ubuntu 20.04+）
GPU：NVIDIA 显卡，推荐 A100/V100，显存 ≥ 40GB
NVIDIA 驱动：版本 ≥ 470，需支持 CUDA 11.8+
Docker：版本 ≥ 20.10
NVIDIA Docker Runtime：确保你已安装 nvidia-container-toolkit

安装文档：https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html

📦 模型准备

Qwen3-Embedding-8B 可以从以下平台获取：

ModelScope 模型库
Hugging Face

假设你已下载并解压模型至如下目录：

/data/models/Qwen3-Embedding-8B

目录下应包含：

config.jsontokenizer/pytorch_model-00001-of-00002.bin...

🐳 Docker 部署（单卡版，使用 GPU 4）

基于 vllm/vllm-openai:v0.9.1 镜像，仅使用第 4 张 GPU 来加载模型并启动嵌入服务：

docker run -itd \\ --gpus \'device=4\' \\ --restart always \\ -p 7100:8000 \\ -v /data/models/Qwen3-Embedding-8B:/models \\ --name qwen3-8b-embd \\ vllm/vllm-openai:v0.9.1 \\ --model /models \\ --served-model-name qwen3-8b-embd \\ --tensor-parallel-size 1 \\ --trust-remote-code \\ --max-model-len 32768 \\ --task embed

参数说明

参数含义 --gpus \'device=4\' 仅使用第 4 张 GPU -p 7100:8000 宿主机 7100 映射到容器服务端口 8000 -v 挂载模型文件到容器路径 /models --served-model-name 用于 API 中 model 字段匹配 --task embed 启动 embedding 模式服务

🧪 使用 curl 进行接口测试

服务启动后，我们可以通过兼容 OpenAI 接口的方式请求向量生成。

✅ 单条文本请求

curl http://localhost:7100/v1/embeddings \\ -H \"Content-Type: application/json\" \\ -d \'{ \"input\": \"你好，世界\", \"model\": \"qwen3-8b-embd\" }\'

✅ 批量请求（多条文本）

curl http://localhost:7100/v1/embeddings \\ -H \"Content-Type: application/json\" \\ -d \'{ \"input\": [\"今天天气不错\", \"大模型真的很强大\"], \"model\": \"qwen3-8b-embd\" }\'

📝 如何对应拿到每条文本的向量？

接口返回结果类似：

{ \"data\": [ { \"embedding\": [0.012, -0.023, ..., 0.045], \"index\": 0, \"object\": \"embedding\" }, { \"embedding\": [0.034, 0.056, ..., -0.012], \"index\": 1, \"object\": \"embedding\" } ], \"model\": \"qwen3-8b-embd\", \"object\": \"list\"}

data 数组中的每一项对应输入 input 数组中的一条文本。
通过 index 字段可确定哪条向量对应哪个输入文本。

Python 示例代码：对应输入文本与向量

import requestsurl = \"http://localhost:7100/v1/embeddings\"inputs = [\"今天天气不错\", \"大模型真的很强大\"]payload = { \"input\": inputs, \"model\": \"qwen3-8b-embd\"}resp = requests.post(url, json=payload).json()embeddings = resp[\"data\"]for item in embeddings: idx = item[\"index\"] vector = item[\"embedding\"] print(f\"文本：{inputs[idx]}\") print(f\"向量（前5维）：{vector[:5]}\")

🛠 常见问题排查

❌ 端口被占用

Bind for 0.0.0.0:9001 failed: port is already allocated

解决：

lsof -i :9001 # 查找占用进程docker ps # 查看容器占用

或修改端口映射，如 -p 7101:8000。

❌ GPU 设置错误

cannot set both Count and DeviceIDs on device request

原因：混用了 --gpus all 和 --gpus \'device=...\'，应只用一种：

--gpus \"device=4\"

📈 性能建议

多卡部署可设置 --tensor-parallel-size 大于 1，提升性能。
批量输入提升吞吐，避免频繁单条请求。
结合 FastAPI 等框架封装更灵活的业务接口。

✅ 总结

本文介绍了如何使用 vLLM 和 Docker 部署 Qwen3-Embedding-8B 嵌入模型服务，并通过标准 OpenAI 兼容接口进行调用和结果解析。

如果你在部署中遇到任何问题，欢迎留言讨论！

👍 喜欢这篇文章的话，欢迎点赞、收藏和分享！

✨使用 vLLM + Docker 部署 Qwen3-Embedding-8B 并实现高效文本向量生成（附 `curl` 测试）_qwen3-embedding docker