【免费下载链接】carrel

Ontology-Augmented Generation for AI agents.

项目地址: https://gitcode.com/gh_mirrors/ca/carrel
点击查看 免费下载

Carrel 是一套本地知识库系统,支持把 Qwen3 系列模型完整部署在自己机器上:文本向量、文本重排、视觉向量、视觉重排和视觉语言模型五个服务全部跑在自有 GPU,不依赖任何外部 API。本文介绍如何用一条命令完成本地模型部署,以及 GPU 显存、启动顺序等关键细节。

🧩 五个模型服务一览

Carrel 通过 Docker Compose 的 local-models profile 启动五个基于 vLLM 的模型服务,全部使用 Qwen3 家族模型:

服务容器名模型默认端口用途
文本向量carrel-embeddingQwen3-Embedding-0.6B8101文档入库与向量检索
文本重排carrel-rerankerQwen3-Reranker-0.6B8102搜索结果精排
视觉向量carrel-vl-embeddingQwen3-VL-Embedding-2B8103图片像素级检索
视觉重排carrel-vl-rerankerQwen3-VL-Reranker-2B8104图文分路重排
视觉语言模型carrel-vlmQwen3-VL-8B-Instruct-FP88105图片与插图描述

服务定义在 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):

  1. 检测 GPU 并写入 deployment/compose/.env,启用 COMPOSE_PROFILES=local-models;有 GPU 时同时叠加 compose.gpu.yml 给解析器预留显存;
  2. 把生成的应用配置写进 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/v1
    • VISUAL_EMBEDDING_ENABLED=1、KB_SEARCH_VISUAL=1,开启图片向量通道
    • KB_CONSOLE_SERVICES 加入 embedding,visual_embedding,vlm,reranker,控制台可直接查看和重启这些模型服务
  3. 构建解析镜像并逐个等待容器健康。

💡 重新运行 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_UTILIZATION0.10文本向量显存占比
QWEN3_RERANKER_GPU_MEMORY_UTILIZATION0.10文本重排显存占比
QWEN3_VL_EMBEDDING_GPU_MEMORY_UTILIZATION0.12视觉向量显存占比
QWEN3_VL_RERANKER_GPU_MEMORY_UTILIZATION0.15视觉重排显存占比
QWEN3_VL_INSTRUCT_GPU_MEMORY_UTILIZATION0.188B 视觉语言模型显存占比

另外两个值得知道的开关:

  • 确定性模式: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.

项目地址: https://gitcode.com/gh_mirrors/ca/carrel
点击查看 免费下载
Logo

聚焦RDK与具身智能,汇集机器人开发教程、开源案例和技术交流

更多推荐