✨使用 vLLM + Docker 部署 Qwen3-Embedding-8B 并实现高效文本向量生成（附 `curl` 测试）
🚀 使用 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.json
tokenizer/
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 requests
url = "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 兼容接口进行调用和结果解析。
如果你在部署中遇到任何问题，欢迎留言讨论！
👍 喜欢这篇文章的话，欢迎点赞、收藏和分享！
