保姆级教程：Lychee多模态重排序API接口调用指南

保姆级教程：Lychee多模态重排序API接口调用指南

你是不是遇到过这样的问题？在电商平台搜索“白色连衣裙”，结果里却混进了“白色T恤”和“白色衬衫”；或者在找资料时，搜索引擎返回的结果总是差那么一点意思，最相关的信息往往不在前面。

这就是“检索排序”的问题。传统的文本搜索只能看文字匹配度，但现实世界是图文并茂的。一张商品主图、一份带图表的报告、一个图文并茂的教程——这些都需要同时理解文字和图片。

今天我要介绍的Lychee多模态重排序模型，就是专门解决这个问题的。它基于Qwen2.5-VL这个强大的多模态大模型，能够同时理解文字和图片，帮你把搜索结果重新排序，让最相关的内容排在最前面。

1. 什么是Lychee多模态重排序？

简单来说，Lychee就是一个“智能排序助手”。想象一下，你有一个搜索引擎，它先返回一堆可能相关的结果（这叫“粗排”），然后Lychee接手，仔细看每个结果的内容（包括文字和图片），给它们打分，最后把最相关的排到最前面（这叫“精排”）。

1.1 它能做什么？

Lychee的核心能力可以用一句话概括：同时理解文字和图片，判断它们之间的相关性。

具体来说，它能处理四种组合：

1. 文字查询 → 文字文档：比如用“如何做红烧肉”查询，给一堆菜谱排序
2. 文字查询 → 图文文档：比如用“白色连衣裙”查询，给一堆带图的商品排序
3. 图片查询 → 文字文档：比如上传一张猫的图片，找相关的养猫文章
4. 图片查询 → 图文文档：比如上传一张家具图片，找风格相似的家居产品

1.2 为什么需要它？

你可能觉得，现在的搜索引擎不是已经很好用了吗？但仔细想想：

• 电商场景：用户搜“红色高跟鞋”，结果里混进了“红色凉鞋”、“红色运动鞋”，因为传统搜索只看文字标签
• 教育场景：学生上传一道几何题图片，想找类似的例题讲解
• 内容平台：编辑想找“夏日海滩”风格的配图，但关键词搜索总是不精准

这些问题，Lychee都能很好地解决。它不只是看文字匹配，而是真正理解图片内容，做出更智能的判断。

2. 环境准备与快速部署

好了，理论讲得差不多了，咱们直接上手。我会带你一步步把Lychee跑起来，保证小白也能跟着做。

2.1 检查你的环境

在开始之前，先确认一下你的电脑或服务器满足这些条件：

• 操作系统：Linux（推荐Ubuntu 20.04+）或macOS
• GPU：建议有16GB以上显存的NVIDIA显卡（没有GPU也能跑，但会比较慢）
• Python：3.8或更高版本
• 内存：至少32GB RAM
• 磁盘空间：模型文件大约15GB，加上依赖需要20GB左右

怎么检查？打开终端，输入这些命令：

# 检查Python版本 python3 --version # 检查GPU（如果有的话） nvidia-smi # 检查内存 free -h

2.2 一键部署Lychee

Lychee已经打包成了Docker镜像，部署起来特别简单。如果你用的是CSDN星图平台，那就更简单了——直接选择Lychee镜像，一键启动。

如果你要手动部署，跟着下面几步走：

第一步：拉取镜像

# 从镜像仓库拉取Lychee docker pull registry.cn-hangzhou.aliyuncs.com/modelscope-repo/lychee-rerank-mm:latest

第二步：启动容器

# 启动Lychee服务 docker run -d \ --name lychee-rerank \ --gpus all \ -p 7860:7860 \ -v /path/to/models:/root/ai-models \ registry.cn-hangzhou.aliyuncs.com/modelscope-repo/lychee-rerank-mm:latest

这里有几个参数需要解释一下：

• --gpus all：使用所有GPU（如果没有GPU，去掉这个参数）
• -p 7860:7860：把容器的7860端口映射到主机的7860端口
• -v /path/to/models:/root/ai-models：把本地的模型目录挂载到容器里（如果模型已经下载好了）

第三步：等待启动

第一次启动需要下载模型文件，大概15GB，根据网速不同需要等一会儿。你可以看日志了解进度：

# 查看启动日志 docker logs -f lychee-rerank

看到类似这样的输出，就说明启动成功了：

INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:7860

2.3 访问Web界面

服务启动后，打开浏览器，访问：

• 本地访问：http://localhost:7860
• 远程访问：http://你的服务器IP:7860

你会看到一个简洁的Web界面，左边是输入区，右边是结果展示区。界面长这样：

+----------------------+----------------------+ | | | | [指令输入框] | | | [查询输入框] | [结果展示区] | | [文档输入框] | | | [提交按钮] | | | | | +----------------------+----------------------+

3. 基础使用：从单文档到批量处理

现在服务跑起来了，咱们来试试它的核心功能。我会用实际的例子带你一步步操作。

3.1 单文档重排序：最简单的用法

单文档模式就是：我给你一个查询（文字或图片），再给一个文档（文字或图片），你告诉我它们有多相关。

场景举例：电商商品匹配

假设你是一个电商平台的运营，用户搜索“白色蕾丝连衣裙”，你的商品库里有一个商品描述是“夏季新款白色蕾丝长裙”，你想知道这个商品和用户的搜索有多匹配。

操作步骤：

1. 在Web界面的“指令”框输入：

   Given a product search query, retrieve relevant products that match the query

2. 在“查询”框输入：

   白色蕾丝连衣裙

3. 在“文档”框输入：

   夏季新款白色蕾丝长裙，修身设计，适合各种场合

4. 点击“提交”按钮

你会看到的结果：

相关性得分：0.87

这个分数在0到1之间，越接近1表示越相关。0.87是个不错的分数，说明这个商品和用户的搜索意图匹配度很高。

3.2 批量重排序：实际工作中的用法

单文档模式适合测试，但实际工作中我们通常要处理很多文档。这时候就要用批量模式。

场景举例：搜索引擎结果优化

假设用户搜索“Python数据分析教程”，你的搜索引擎返回了10个结果，你想把这些结果按相关性重新排序。

操作步骤：

1. 准备一个文本文件，比如叫results.txt，内容如下：

Given a web search query, retrieve relevant passages that answer the query Python数据分析教程 Python数据分析从入门到实践，适合初学者 机器学习中的数据分析方法，包含Python代码示例 Excel数据分析技巧大全，附带案例讲解 Python pandas库使用指南，包含数据分析实例 统计学基础与Python实现，适合数据分析师 数据可视化教程，用matplotlib和seaborn Python爬虫教程，如何获取分析数据 SQL数据分析实战，与Python结合使用 商业智能BI工具使用指南 Python numpy数组操作教程

注意格式：

• 第一行是指令
• 第二行是查询
• 第三行开始，每个文档占一行

2. 在Web界面选择“批量模式”，上传这个文件，或者直接把内容粘贴到输入框

3. 点击“提交”

你会看到的结果：

Lychee会返回一个表格，类似这样：

看，最相关的“Python数据分析从入门到实践”排在了第一位，而“Excel数据分析技巧大全”虽然也相关，但因为不是Python相关的，排名就靠后了。

4. 多模态实战：文字和图片的混合查询

Lychee最厉害的地方就是能同时处理文字和图片。咱们来看几个实际的例子。

4.1 用图片找相似商品（图→图）

场景：你在网上看到一件喜欢的衣服，想找同款或相似款。

操作步骤：

1. 准备一张商品图片（比如一件蓝色条纹衬衫）

2. 在“查询”区域上传这张图片

3. 在“文档”区域，你可以：

   • 上传多张候选商品图片
   • 或者输入图文描述，比如：

     [图片]蓝色条纹衬衫，棉质材料 [图片]蓝色格子衬衫，休闲款式 [图片]白色条纹衬衫，商务风格

4. 使用这个指令：

   Given a product image, retrieve similar products

效果：Lychee会分析你的查询图片（蓝色条纹衬衫），然后给候选图片打分，把最相似的排在最前面。

4.2 用文字找配图（文→图）

场景：你在写一篇关于“夏日海滩”的文章，需要找配图。

操作步骤：

1. 在“查询”框输入：

   夏日海滩，阳光，椰子树，蓝色海水

2. 在“文档”区域上传多张候选图片，或者输入图文描述

3. 使用这个指令：

   Given an article description, retrieve relevant images

效果：Lychee会理解你的文字描述，然后判断哪张图片最符合“夏日海滩”的感觉。

4.3 混合查询的实际代码示例

如果你想通过API调用，而不是Web界面，这里有一个完整的Python示例：

import requests import base64 from PIL import Image import io # 1. 准备图片（转换为base64） def image_to_base64(image_path): with Image.open(image_path) as img: buffered = io.BytesIO() img.save(buffered, format="JPEG") return base64.b64encode(buffered.getvalue()).decode() # 2. 构建请求 url = "http://localhost:7860/api/rerank" headers = {"Content-Type": "application/json"} # 示例1：文字查询 + 图文文档 data1 = { "instruction": "Given a product search query, retrieve relevant products", "query": "白色连衣裙", "documents": [ "夏季新款白色蕾丝连衣裙，修身设计", f"白色雪纺连衣裙[图片]{image_to_base64('dress1.jpg')}", "黑色连衣裙，经典款式", f"白色棉质连衣裙[图片]{image_to_base64('dress2.jpg')}" ] } # 示例2：图片查询 + 图文文档 data2 = { "instruction": "Given a product image, retrieve similar products", "query": f"[图片]{image_to_base64('query_dress.jpg')}", "documents": [ f"类似款式连衣裙[图片]{image_to_base64('candidate1.jpg')}", "不同风格的连衣裙描述", f"同款不同色[图片]{image_to_base64('candidate2.jpg')}" ] } # 3. 发送请求 response = requests.post(url, json=data1, headers=headers) results = response.json() # 4. 处理结果 print("排序结果：") for i, (doc, score) in enumerate(zip(results["documents"], results["scores"]), 1): print(f"{i}. 得分：{score:.4f} - {doc[:50]}...")

这段代码展示了如何通过API调用Lychee。你可以灵活地组合文字和图片，构建各种查询。

5. 高级技巧与优化建议

用了一段时间后，你可能会想：怎么能让Lychee的效果更好？怎么提高处理速度？这部分就是为你准备的。

5.1 指令调优：让模型更懂你

Lychee是指令感知的，这意味着不同的指令会影响它的判断。下面是一些场景和推荐的指令：

小技巧：如果你有特定的业务场景，可以自己设计指令。比如做菜谱搜索，可以用：“Given a dish name or description, retrieve relevant recipes with cooking steps”。

5.2 性能优化：让处理更快

如果你要处理大量数据，这些优化技巧会很有用：

批量处理：

# 不好的做法：一个个处理 for doc in documents: score = rerank(query, doc) # 每次都要加载模型 # 好的做法：批量处理 scores = rerank_batch(query, documents) # 一次处理所有

Lychee的批量模式已经做了优化，一次处理100个文档比处理100次要快得多。

文本长度控制：

# 在调用API时，可以指定最大长度 data = { "instruction": "...", "query": "...", "documents": [...], "max_length": 1024 # 限制文本长度，加快处理速度 }

默认的最大长度是3200个token，对于大多数场景够用了。如果你的文档特别长，可以适当调大，但会影响速度。

GPU内存优化： 如果你发现处理大量文档时GPU内存不足，可以：

1. 减小批量大小
2. 使用更短的文本
3. 启用CPU卸载（如果支持）

5.3 实际应用中的注意事项

相关性不等于质量： Lychee判断的是相关性，不是质量。一个完全相关的垃圾内容可能得分很高。在实际应用中，你通常需要结合相关性分数和其他质量指标。

分数解释：

• 0.9以上：高度相关
• 0.7-0.9：相关
• 0.5-0.7：有一定相关性
• 0.5以下：基本不相关

但这个阈值要根据你的具体场景调整。有些严格场景可能要求0.8以上才算相关，有些宽松场景0.6就可以。

多语言支持： Lychee基于Qwen2.5-VL，对中文和英文都有很好的支持。其他语言可能效果会差一些。

6. 常见问题与解决方案

在实际使用中，你可能会遇到一些问题。这里我整理了一些常见问题和解决方法。

6.1 服务启动问题

问题：启动时提示“模型加载失败”

解决：

# 1. 检查模型路径 ls /root/ai-models/vec-ai/lychee-rerank-mm # 2. 如果模型不存在，手动下载 # 首先进入容器 docker exec -it lychee-rerank bash # 然后下载模型（在容器内执行） cd /root/lychee-rerank-mm python download_model.py # 3. 检查GPU内存 nvidia-smi # 如果内存不足，尝试用CPU模式启动，或者减小模型加载的精度

问题：服务启动很慢

解决：第一次启动需要下载15GB的模型文件，耐心等待。后续启动会快很多。

6.2 API调用问题

问题：API返回错误或超时

解决：

import requests import time # 增加超时时间 response = requests.post(url, json=data, headers=headers, timeout=60) # 重试机制 def call_with_retry(url, data, max_retries=3): for i in range(max_retries): try: response = requests.post(url, json=data, timeout=30) return response.json() except Exception as e: print(f"第{i+1}次尝试失败：{e}") time.sleep(2 ** i) # 指数退避 return None

问题：处理大量文档时内存不足

解决：

# 分批处理 def batch_rerank(query, documents, batch_size=50): results = [] for i in range(0, len(documents), batch_size): batch = documents[i:i+batch_size] batch_results = rerank_batch(query, batch) results.extend(batch_results) time.sleep(1) # 给GPU一点休息时间 return results

6.3 效果调优问题

问题：分数都很高，区分度不够

解决：

1. 检查指令是否合适
2. 尝试不同的指令
3. 对分数做后处理，比如归一化或放大差异

# 分数归一化示例 scores = [0.85, 0.87, 0.86, 0.84] min_score = min(scores) max_score = max(scores) if max_score > min_score: normalized = [(s - min_score) / (max_score - min_score) for s in scores] else: normalized = [1.0] * len(scores) # 所有分数一样

问题：图文混合查询效果不好

解决：

1. 确保图片质量不要太差
2. 对于图文文档，文字描述要准确
3. 尝试纯文字或纯图片查询，看是哪个部分的问题

7. 总结

Lychee多模态重排序模型是一个强大的工具，它让计算机能像人一样，同时理解文字和图片，做出更智能的相关性判断。

通过这篇教程，你应该已经掌握了：

1. Lychee是什么：一个基于Qwen2.5-VL的多模态重排序模型，能同时处理文字和图片
2. 如何部署：用Docker一键部署，或者手动安装
3. 基础使用：单文档模式和批量模式，分别适合测试和生产
4. 多模态实战：四种查询-文档组合的实际应用
5. 高级技巧：指令调优、性能优化、实际注意事项
6. 问题解决：常见问题的排查和解决方法

最后给几个实用建议：

• 从小开始：先用少量数据测试，确保效果符合预期
• 指令很重要：花时间找到最适合你场景的指令
• 批量处理：生产环境一定要用批量模式，效率差很多
• 监控效果：定期检查排序效果，必要时调整阈值或指令

Lychee的开源地址是：https://modelscope.cn/models/vec-ai/lychee-rerank-mm，如果你遇到问题，可以去这里找答案或者提问。

获取更多AI镜像

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