Carrel 本地模型部署:Qwen3 向量、重排与视觉模型跑在自有 GPU 上
【免费下载链接】carrel
Ontology-Augmented Generation for AI agents.
Carrel 是一套本地知识库系统,支持把 Qwen3 系列模型完整部署在自己机器上:文本向量、文本重排、视觉向量、视觉重排和视觉语言模型五个服务全部跑在自有 GPU,不依赖任何外部 API。本文介绍如何用一条命令完成本地模型部署,以及 GPU 显存、启动顺序等关键细节。
🧩 五个模型服务一览
Carrel 通过 Docker Compose 的 local-models profile 启动五个基于 vLLM 的模型服务,全部使用 Qwen3 家族模型:
| 服务 | 容器名 | 模型 | 默认端口 | 用途 |
|---|---|---|---|---|
| 文本向量 | carrel-embedding | Qwen3-Embedding-0.6B | 8101 | 文档入库与向量检索 |
| 文本重排 | carrel-reranker | Qwen3-Reranker-0.6B | 8102 | 搜索结果精排 |
| 视觉向量 | carrel-vl-embedding | Qwen3-VL-Embedding-2B | 8103 | 图片像素级检索 |
| 视觉重排 | carrel-vl-reranker | Qwen3-VL-Reranker-2B | 8104 | 图文分路重排 |
| 视觉语言模型 | carrel-vlm | Qwen3-VL-8B-Instruct-FP8 | 8105 | 图片与插图描述 |
服务定义在 docker-compose.yml,每个服务挂载对应权重目录、只绑定 127.0.0.1,并配置了健康检查。
✅ 部署前准备
硬件与软件要求:
- 一块 NVIDIA GPU,且已安装 NVIDIA 驱动和 NVIDIA Container Toolkit(没有 toolkit 时 Docker 无法把 GPU 传入容器)
- Docker 与 Docker Compose v2
- 先把模型权重放到
models/目录
第一步:确认 GPU 可用。 运行检测命令,它只打印决策、不做任何修改:
./deploy.sh detect
输出中若出现 gpu: ... -> parser flavour gpu,说明驱动和容器 toolkit 都就绪。
第二步:下载五个模型的权重:
pip install -U huggingface_hub
for m in Qwen/Qwen3-Embedding-0.6B Qwen/Qwen3-Reranker-0.6B Qwen/Qwen3-VL-Embedding-2B \
Qwen/Qwen3-VL-Reranker-2B Qwen/Qwen3-VL-8B-Instruct-FP8; do
huggingface-cli download "$m" --local-dir "models/$(basename "$m")"
done
权重来源的自动选择逻辑(HuggingFace / ModelScope)见 deployment/compose/README.md。
🚀 一键启动本地模型服务
权重就位后,只需在仓库根目录执行:
./deploy.sh --with-local-models
这条命令会自动完成一串容易出错的工作(实现见 deploy.sh):
- 检测 GPU 并写入
deployment/compose/.env,启用COMPOSE_PROFILES=local-models;有 GPU 时同时叠加 compose.gpu.yml 给解析器预留显存; - 把生成的应用配置写进
config/knowledge-base.env,自动填充:EMBEDDING_BASE_URL=http://127.0.0.1:8101/v1(模板见 knowledge-base.env.example)RERANKER_BASE_URL=http://127.0.0.1:8102/v1、VISUAL_RERANKER_BASE_URL=http://127.0.0.1:8104/v1VISUAL_EMBEDDING_ENABLED=1、KB_SEARCH_VISUAL=1,开启图片向量通道KB_CONSOLE_SERVICES加入embedding,visual_embedding,vlm,reranker,控制台可直接查看和重启这些模型服务
- 构建解析镜像并逐个等待容器健康。
💡 重新运行
deploy.sh是安全的:已有.env会被保留,只有定义变化的容器才会重建。
⏱️ 启动顺序与健康检查
五个模型服务不是同时启动,而是排队加载:每个服务启动后先轮询前一个服务的 /health(WAIT_FOR_URL 机制),确认它加载完成才开始加载自己的模型。队列顺序为:embedding → reranker → vl-embedding → vl-reranker → vlm。
为什么要排队?如果同时启动,每个 vLLM 进程在显存还未稳定时做内存探测,会接连失败重启(README 记录过每台服务重启 1~8 次的情况)。排队机制让首次启动时间约为各模型加载时间之和,因此请耐心等待——健康检查的 start_period 设置为 900 秒。
查看状态的小技巧:
./deploy.sh status # 容器与 console 健康
docker logs -f carrel-embedding # 查看第一个模型的加载日志
某容器显示 health: starting 表示它还在排队等待前面的服务;如果第一个服务一直起不来,后面的会全部卡住,优先排查队头容器。
🎛️ GPU 显存分配调优
.env.example 中各 *_GPU_MEMORY_UTILIZATION 参数是按 121 GB 统一内存机器调校的(五个模型服务合计约占 0.65,加上解析器约 0.71)。如果你的显存较小,需要按比例调大这些参数,例如:
| 参数 | 默认值 | 说明 |
|---|---|---|
QWEN3_EMBEDDING_GPU_MEMORY_UTILIZATION | 0.10 | 文本向量显存占比 |
QWEN3_RERANKER_GPU_MEMORY_UTILIZATION | 0.10 | 文本重排显存占比 |
QWEN3_VL_EMBEDDING_GPU_MEMORY_UTILIZATION | 0.12 | 视觉向量显存占比 |
QWEN3_VL_RERANKER_GPU_MEMORY_UTILIZATION | 0.15 | 视觉重排显存占比 |
QWEN3_VL_INSTRUCT_GPU_MEMORY_UTILIZATION | 0.18 | 8B 视觉语言模型显存占比 |
另外两个值得知道的开关:
- 确定性模式:embedding、reranker、vl-embedding 三个服务默认开启
VLLM_BATCH_INVARIANT=1,保证同一输入在任何批处理方式下得到位级一致的向量与分数,搜索结果排序稳定可复现。若视觉向量太慢可在.env中设VLLM_BATCH_INVARIANT=0关闭。 - 绑定地址:所有模型端口默认只监听
127.0.0.1。把MODEL_BIND_ADDRESS改成0.0.0.0会把无认证的推理接口暴露到局域网,除非清楚风险否则不要改。
🧰 常见问题排查
| 现象 | 原因与处理 |
|---|---|
detect 提示 Docker cannot use it | 缺少 NVIDIA Container Toolkit,安装后重跑 ./deploy.sh |
解析器提示 cannot see the GPU 并回退 CPU | 容器内 torch 探测不到 GPU,deploy.sh 会自动移除 GPU 叠加层,检查驱动与 CDI 配置 |
模型容器长时间 starting | 仍在排队加载权重,属正常现象;首台起不来时先查它的 docker logs |
| 想换回外部 API | 不加 --with-local-models 重新部署,把 EMBEDDING_*、VLM_* 等指向服务商端点即可 |
📌 更多细节可查阅:Compose 部署说明、中文配置文档 以及 中文示例搭建指南。
【免费下载链接】carrel
Ontology-Augmented Generation for AI agents.
更多推荐
所有评论(0)