Lychee-Rerank-MM部署教程：Ansible自动化部署脚本编写与验证

1. 引言

如果你正在搭建一个智能的图文搜索系统，或者想提升现有检索结果的精准度，那么“重排序”这个环节你一定不陌生。简单来说，就是系统先用一个快速但可能不够精确的模型（粗排）找到一批候选结果，再用一个更强大、更精细的模型（精排）对这些结果重新打分和排序，把最相关的内容推到最前面。

今天要介绍的主角——Lychee-Rerank-MM，就是这样一个专为图文检索场景设计的“精排专家”。它基于强大的Qwen2.5-VL多模态大模型，不仅能理解纯文本，还能看懂图片，实现图文之间的深度语义匹配。想象一下，用户上传一张新款运动鞋的图片进行搜索，系统不仅能找到描述类似的商品，还能精准匹配到外观、颜色甚至设计细节都高度相似的图片，这就是Lychee-Rerank-MM的价值所在。

然而，将这样一个7B参数规模的模型部署到生产环境，尤其是在多台服务器上保持环境一致、高效运维，并不是一件简单的事。手动安装依赖、配置环境、启动服务，不仅繁琐易错，也难以规模化。这正是自动化运维工具Ansible大显身手的地方。

本教程将带你一步步走完从理解Lychee-Rerank-MM，到编写一个健壮的Ansible自动化部署脚本，再到最终验证部署成功的完整流程。无论你是运维工程师、算法工程师，还是对AI应用部署感兴趣的开发者，都能从中获得一套可立即复用的实战方案。

2. Lychee-Rerank-MM核心解析

在动手写部署脚本之前，我们先花点时间搞清楚我们要部署的是什么，它需要什么样的环境，以及它如何工作。这能帮助我们在编写Ansible任务时做出更合理的设计。

2.1 模型是什么？能做什么？

Lychee-Rerank-MM本质上是一个经过专门训练的多模态大语言模型。它的核心任务不是生成新的文本或图片，而是“打分”和“排序”。

它的工作流程可以这样理解：

1. 输入：你给它一个“查询”（可以是一段文字、一张图，或图文结合）和一堆“候选文档”（同样可以是文字、图片或图文）。
2. 理解：模型会深度理解查询和每一个候选文档的语义。
3. 计算：模型会计算查询与每个候选文档之间的相关性分数，范围在0到1之间。
4. 输出：输出这些分数，分数越高，代表相关性越强。

它主要支持两种使用模式：

• 单文档重排序：一次评估一个查询和一个文档的相关性。适合实时、交互式的场景。
• 批量重排序：一次评估一个查询和多个文档的相关性，并直接输出排序后的表格。适合离线处理或批量任务，效率更高。

2.2 部署环境需求

根据项目说明，要让它跑起来，我们需要准备好以下“食材”：

• 硬件：至少16GB显存的GPU。这是硬性要求，因为模型本身就需要大约14-15GB的显存来加载。
• 软件：
  • 操作系统：常见的Linux发行版即可，如Ubuntu 20.04/22.04。
  • Python：版本3.8或以上。
  • 深度学习框架：PyTorch 2.0+。
• 模型文件：需要提前下载好模型权重文件，并放置在指定的路径：/root/ai-models/vec-ai/lychee-rerank-mm。这是启动脚本寻找模型的默认位置。
• 网络：服务启动后默认监听7860端口，需要确保该端口在服务器防火墙中是开放的。

2.3 项目结构预览

通常，一个标准的Lychee-Rerank-MM项目目录看起来是这样的：

/root/lychee-rerank-mm/
├── app.py              # 主应用文件，Gradio Web界面和API逻辑
├── start.sh            # 推荐的启动脚本
├── requirements.txt    # Python依赖包列表
├── model/              # （通常通过软链接或指定路径指向实际的模型文件）
│   └── ...             # 模型权重、配置文件等
└── ...                 # 其他可能的配置文件或工具脚本

我们的Ansible任务将围绕搭建这个环境、安装依赖、配置模型路径和启动服务来展开。

3. Ansible部署脚本编写实战

现在，我们进入核心环节——编写Ansible Playbook。我们将这个Playbook命名为 deploy_lychee.yml。我们的目标是实现：一键完成从干净系统到服务可用的全过程。

3.1 Playbook设计思路

我们将部署流程分解为几个清晰的阶段，每个阶段对应Ansible的一个或多个任务（task）：

1. 环境初始化：安装系统级依赖（如GPU驱动、CUDA基础工具）。
2. Python环境搭建：安装特定版本的Python和PyTorch。
3. 项目部署：从代码仓库拉取或拷贝项目文件到目标服务器。
4. 模型文件准备：处理模型权重文件（假设已提前下载到Ansible控制机）。
5. 依赖安装：安装项目所需的Python包。
6. 服务配置与启动：配置启动脚本，并以守护进程方式启动服务。
7. 健康检查：验证服务是否正常启动并监听端口。

3.2 完整的Ansible Playbook示例

下面是一个详细且具备较强鲁棒性的Playbook示例。请根据你的实际环境（如服务器IP、模型文件路径、内网仓库地址等）修改其中的变量。

---
- name: 部署 Lychee-Rerank-MM 多模态重排序服务
  hosts: lychee_servers # 在Ansible inventory文件中定义的主机组
  become: yes # 使用sudo权限执行任务
  vars:
    project_dir: /root/lychee-rerank-mm
    model_target_dir: /root/ai-models/vec-ai/lychee-rerank-mm
    service_port: 7860

  tasks:
    # 任务 1: 安装系统基础依赖
    - name: 安装系统基础工具和依赖
      apt: # 如果是CentOS/RHEL，使用 `yum` 模块
        name:
          - git
          - wget
          - curl
          - python3-pip
          - python3-venv
          - build-essential
        state: present
        update_cache: yes

    # 任务 2: 检查并安装NVIDIA驱动和CUDA工具包（如果尚未安装）
    - name: 检查NVIDIA驱动
      shell: nvidia-smi
      register: nvidia_check
      ignore_errors: yes
      changed_when: false

    - name: 安装NVIDIA驱动和CUDA（如果未安装）
      block:
        - name: 添加NVIDIA CUDA仓库
          apt_repository:
            repo: "deb https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/ /"
            state: present
          when: ansible_distribution == 'Ubuntu' and ansible_distribution_version == '22.04'
        - name: 安装CUDA工具包
          apt:
            name: cuda-toolkit-12-1
            state: present
            update_cache: yes
      when: nvidia_check.rc != 0 # 仅在未检测到驱动时执行
      # 注意：生产环境建议使用预装好驱动和CUDA的镜像，此任务可能需根据实际情况调整。

    # 任务 3: 创建项目目录
    - name: 确保项目目录存在
      file:
        path: "{{ project_dir }}"
        state: directory
        mode: '0755'

    # 任务 4: 从Git仓库同步项目代码（方式一）
    - name: 从Git克隆或更新项目代码
      git:
        repo: 'https://github.com/vec-ai/lychee-rerank-mm.git' # 假设的仓库地址，请替换为真实地址
        dest: "{{ project_dir }}"
        version: main # 指定分支或标签
        force: yes
      # 如果代码已在控制机，可使用 `copy` 或 `synchronize` 模块（方式二）

    # 任务 5: 创建模型存储目录
    - name: 确保模型目录存在
      file:
        path: "{{ model_target_dir }}"
        state: directory
        mode: '0755'

    # 任务 6: 传输模型文件（假设模型文件在Ansible控制机的本地目录）
    - name: 上传模型文件到目标服务器
      copy:
        src: /path/to/your/local/lychee-rerank-mm-model/ # 控制机上的模型文件夹路径
        dest: "{{ model_target_dir }}"
        mode: '0644'
        # 注意：模型文件很大，此操作可能耗时。生产环境建议将模型放在共享存储或使用对象存储提前下发。

    # 任务 7: 安装Python依赖（使用项目requirements.txt）
    - name: 安装Python依赖包
      pip:
        requirements: "{{ project_dir }}/requirements.txt"
        executable: pip3
        extra_args: --upgrade
      environment: # 设置环境变量，确保能找到CUDA
        LD_LIBRARY_PATH: /usr/local/cuda-12.1/lib64

    # 任务 8: 创建或修改启动脚本
    - name: 创建自定义启动脚本
      copy:
        content: |
          #!/bin/bash
          cd {{ project_dir }}
          # 设置环境变量，确保使用正确的Python和库路径
          export PYTHONPATH={{ project_dir }}:$PYTHONPATH
          export LD_LIBRARY_PATH=/usr/local/cuda-12.1/lib64:$LD_LIBRARY_PATH
          # 启动服务，指定模型路径
          python3 app.py --model_path {{ model_target_dir }}
        dest: /usr/local/bin/start-lychee.sh
        mode: '0755'

    # 任务 9: 配置Systemd服务（实现开机自启和进程管理）
    - name: 创建Systemd服务单元文件
      copy:
        content: |
          [Unit]
          Description=Lychee Rerank MM Service
          After=network.target

          [Service]
          Type=simple
          User=root
          WorkingDirectory={{ project_dir }}
          Environment="PYTHONPATH={{ project_dir }}"
          Environment="LD_LIBRARY_PATH=/usr/local/cuda-12.1/lib64"
          ExecStart=/usr/bin/python3 {{ project_dir }}/app.py --model_path {{ model_target_dir }}
          Restart=on-failure
          RestartSec=10
          StandardOutput=journal
          StandardError=journal

          [Install]
          WantedBy=multi-user.target
        dest: /etc/systemd/system/lychee-rerank.service
        mode: '0644'

    - name: 重载Systemd配置
      systemd:
        daemon_reload: yes

    - name: 启用并启动Lychee服务
      systemd:
        name: lychee-rerank
        enabled: yes
        state: started

    # 任务 10: 等待服务启动并检查端口
    - name: 等待服务端口就绪
      wait_for:
        port: "{{ service_port }}"
        delay: 10
        timeout: 120
      register: port_check

    - name: 检查服务进程
      shell: ps aux | grep -v grep | grep "python.*app.py"
      register: process_check
      changed_when: false

    - name: 打印部署结果
      debug:
        msg:
          - "Lychee-Rerank-MM 服务部署完成！"
          - "服务端口: {{ service_port }}"
          - "端口检查: {{ '成功' if port_check is succeeded else '失败' }}"
          - "进程检查: {{ '进程存在' if process_check.stdout != '' else '未找到进程' }}"
          - "请访问 http://{{ ansible_host }}:{{ service_port }} 使用Web界面。"

3.3 关键任务详解

1. 模型文件传输（任务6）：这是部署中最耗时的部分。剧本中使用了copy模块，适用于模型文件在Ansible控制机本地的场景。对于超大文件，建议：
   • 提前将模型文件放到服务器的对象存储（如S3/MinIO）或网络共享存储（NFS）上，然后用get_url或mount模块处理。
   • 在服务器镜像中预置模型文件。
2. 依赖安装（任务7）：使用pip模块并指定requirements.txt文件，可以精确复现Python环境。通过environment参数设置LD_LIBRARY_PATH，确保PyTorch等库能找到CUDA动态库。
3. 服务化（任务8&9）：这是将应用变成可靠服务的关键。我们创建了一个Systemd服务单元文件。这样做的好处是：
   • 自动重启：如果服务意外崩溃，Systemd会自动重启它（Restart=on-failure）。
   • 集中日志：输出被重定向到journal，方便使用journalctl -u lychee-rerank查看日志。
   • 开机自启：服务会在服务器重启后自动启动（enabled: yes）。
   • 统一管理：可以使用systemctl start/stop/restart/status lychee-rerank命令管理服务。
4. 健康检查（任务10）：使用wait_for模块检查7860端口是否开放，并用shell命令检查相关进程是否存在，为部署成功提供双重验证。

4. 部署验证与测试

剧本执行完成后，显示“部署完成”并不代表万事大吉。我们需要进行一系列验证，确保服务不仅“跑起来了”，而且“跑对了”。

4.1 基础状态检查

首先，通过Ansible或直接登录服务器，执行一些基础命令：

# 1. 检查服务状态
systemctl status lychee-rerank

# 预期的健康状态应该是 `active (running)`
# 同时可以查看最近的日志
journalctl -u lychee-rerank -n 50 --no-pager

# 2. 检查端口监听
netstat -tlnp | grep :7860
# 或使用 ss 命令
ss -tlnp | grep :7860
# 应该能看到python进程正在监听7860端口

# 3. 检查GPU是否被使用
nvidia-smi
# 查看是否有python进程占用了可观的GPU显存（约14-15GB）

4.2 功能接口测试

服务状态正常后，我们需要测试其核心功能。你可以通过命令行工具curl进行API测试。

测试1：单文档重排序（文本到文本）

curl -X POST http://<你的服务器IP>:7860/api/v1/rerank \
  -H "Content-Type: application/json" \
  -d '{
    "instruction": "Given a web search query, retrieve relevant passages that answer the query",
    "query": "What is the capital of France?",
    "document": "Paris is the capital and most populous city of France."
  }'

预期响应：应该返回一个JSON，包含一个score字段，值在0到1之间，且对于这个高度相关的问题，得分应该接近1（例如0.98）。

测试2：批量重排序（使用示例数据） 创建一个文件 batch_test.json：

{
  "instruction": "Given a web search query, retrieve relevant passages that answer the query",
  "query": "How to bake a chocolate cake?",
  "documents": [
    "A step-by-step guide to baking a moist chocolate cake with frosting.",
    "The history and evolution of French cuisine.",
    "Top 10 tips for maintaining a healthy garden.",
    "Ingredients needed: flour, sugar, cocoa powder, eggs, butter. Mix dry ingredients first."
  ]
}

然后发送请求：

curl -X POST http://<你的服务器IP>:7860/api/v1/rerank_batch \
  -H "Content-Type: application/json" \
  --data @batch_test.json

预期响应：返回一个Markdown表格字符串或JSON数组，其中与“烘焙巧克力蛋糕”相关的文档（第1条和第4条）应该获得更高的分数，并被排在前面。

4.3 Web界面访问

最后，打开你的浏览器，访问 http://<你的服务器IP>:7860。你应该能看到Lychee-Rerank-MM的Gradio Web界面。在这里，你可以：

1. 在“Instruction”框输入指令（或使用默认的）。
2. 在“Query”框输入文本或上传图片作为查询。
3. 在“Document”框输入文本或上传图片作为待排序文档。
4. 点击“Submit”，界面会直接返回相关性得分。

通过Web界面进行直观测试，是验证多模态功能（如图文互搜）最直接的方式。

5. 总结

通过本教程，我们完成了一次从零开始的Lychee-Rerank-MM自动化部署之旅。我们不仅编写了一个功能完备、具备生产级考量的Ansible Playbook，涵盖了环境准备、代码部署、模型管理、服务化配置和健康检查，还详细阐述了每一步背后的设计思路和最佳实践。

回顾核心要点：

1. 理解先行：在自动化之前，充分理解应用（Lychee-Rerank-MM）的架构、依赖和环境需求，是编写正确Playbook的前提。
2. 分而治之：将复杂的部署过程分解为初始化、安装、配置、启动、验证等清晰阶段，使Playbook结构清晰，易于维护和排错。
3. 追求鲁棒性：通过添加状态检查（如检查GPU驱动）、使用Systemd进行服务管理、实现健康检查等，让部署脚本不仅仅是“能运行”，更是“可靠运行”。
4. 验证不可或缺：部署完成后，从服务状态、端口监听、核心API功能到Web界面，进行多层次验证，确保交付物符合预期。

这份Ansible Playbook是一个强大的起点。你可以根据实际需求进一步扩展它，例如：

• 集成变量文件：将服务器IP、模型路径、版本号等提取到group_vars或host_vars中，提高灵活性。
• 添加角色（Role）：如果部署逻辑非常复杂，可以将其重构为Ansible Role，实现更好的代码复用。
• 结合CI/CD：将Playbook集成到Jenkins、GitLab CI等流水线中，实现代码提交后自动测试和部署。

自动化部署是AI工程化的重要一环。掌握这项技能，能让你更高效、更可靠地将优秀的AI模型转化为实际可用的服务。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。