lychee-rerank-mm代码实例：Python调用API实现自动化重排序
1. 什么是lychee-rerank-mm：轻量多模态重排序的实用利器
立知推出的lychee-rerank-mm，是一个专注“重排序”任务的多模态模型。它不负责从海量数据里大海捞针地检索，而是专精于把已经找出来的候选内容——无论是文字、图片，还是图文混合体——按与用户查询的真实相关性，重新打分、精准排序。
你可以把它想象成一位经验丰富的编辑：检索系统像助理，快速拉来一摞初稿；而lychee-rerank-mm就是那位主编，快速翻阅每一篇，判断哪篇最切题、哪篇最生动、哪篇最值得放在头条。它解决的，正是行业里常说的“找得到，但排不准”的老大难问题。
它的定位非常清晰：轻量、高效、开箱即用。不像一些大模型动辄需要多卡GPU和数分钟加载，lychee-rerank-mm在单卡甚至消费级显卡上就能秒级响应，内存占用低，部署门槛极低。更重要的是，它真正理解“多模态”——不是简单地把图转成文字再处理，而是让文本语义和图像视觉特征在同一空间里对话、对齐。当用户搜“猫咪玩球”，它能同时看懂“猫咪”“玩”“球”的文字意图，也认得出图片里毛茸茸的猫爪是否真的碰到了彩色小球，从而给出比纯文本模型更可靠、更符合人类直觉的排序结果。
正因为这种能力，它天然成为多模态检索系统、智能推荐引擎、图文问答工具的“点睛之笔”。比如电商搜索返回的10个商品，它能把用户真正想买的那款高亮出来；客服知识库返回的5条解答，它能挑出最直接、最无歧义的那一条；设计师上传一张灵感图，它能从图库中精准召回风格、构图、色调都高度匹配的参考图。
2. 从网页交互到代码调用：三步打通自动化链路
虽然网页界面（http://localhost:7860）操作直观友好，但真实业务中，我们更需要的是可嵌入、可批量、可集成的自动化能力。幸运的是，lychee-rerank-mm不仅提供了图形界面，还开放了简洁稳定的HTTP API。下面我们就用Python，手把手完成一次从零开始的自动化调用。
2.1 启动服务与验证API可用性
第一步永远是确保后端服务已就绪。打开终端，执行：
lychee load等待10-30秒，直到终端输出类似Running on local URL: http://localhost:7860的提示，说明服务已成功启动。
接着，我们用Python快速验证API是否在线。不需要安装额外库，标准库urllib就能搞定：
import urllib.request import json # 测试API基础连通性 try: with urllib.request.urlopen("http://localhost:7860/docs") as response: if response.getcode() == 200: print(" API服务已启动，文档页可访问") else: print(" API服务未响应，请检查lychee load是否成功运行") except Exception as e: print(f" 连接失败：{e}")这段代码会尝试访问Swagger文档页。如果看到“ API服务已启动”，就说明一切准备就绪，可以进入核心调用了。
2.2 单文档评分：判断“一个问题”和“一个答案”是否匹配
这是最基础也最常用的场景，比如在客服系统中，自动判断一条回复是否准确回答了用户提问。
lychee-rerank-mm的API端点是/api/rerank/single，它接受一个JSON对象，包含query（查询）、document（待评分文档）和可选的instruction（自定义指令）。
import urllib.request import urllib.parse import json def single_rerank(query: str, document: str, instruction: str = None) -> float: """ 对单个文档进行重排序评分 Args: query: 用户查询，如 "中国的首都是哪里？" document: 待评分的文档，如 "北京是中华人民共和国的首都" instruction: 可选的自定义指令，如 "Judge whether the document answers the question" Returns: float: 相关性得分，范围通常为0.0-1.0 """ url = "http://localhost:7860/api/rerank/single" # 构建请求体 payload = { "query": query, "document": document } if instruction: payload["instruction"] = instruction # 发送POST请求 data = json.dumps(payload).encode('utf-8') req = urllib.request.Request( url, data=data, headers={'Content-Type': 'application/json'} ) try: with urllib.request.urlopen(req) as response: result = json.loads(response.read().decode('utf-8')) score = result.get("score", 0.0) print(f" 查询: '{query}'") print(f"📄 文档: '{document}'") print(f" 得分: {score:.2f}") return score except Exception as e: print(f" 调用失败: {e}") return 0.0 # 实际调用示例 if __name__ == "__main__": # 示例1：标准问答 score1 = single_rerank( query="北京是中国的首都吗？", document="是的，北京是中华人民共和国的首都。" ) # 示例2：带自定义指令的客服场景 score2 = single_rerank( query="我的订单还没发货，能查一下吗？", document="您的订单已支付成功，预计24小时内发货。", instruction="Judge whether the document answers the question" )运行这段代码，你会看到类似这样的输出：
查询: '北京是中国的首都吗？' 📄 文档: '是的，北京是中华人民共和国的首都。' 得分: 0.95 查询: '我的订单还没发货，能查一下吗？' 📄 文档: '您的订单已支付成功，预计24小时内发货。' 得分: 0.87这正是网页界面上“单文档评分”功能的代码化复现，但优势在于它可以被嵌入到任何Python脚本、Web后端或定时任务中，实现真正的无人值守。
2.3 批量重排序：让一堆候选内容自动站好队
当面对多个候选结果时，我们需要的不是一个个打分，而是让它们自动按相关性从高到低排列。API端点/api/rerank/batch就是为此而生。
def batch_rerank(query: str, documents: list, instruction: str = None) -> list: """ 对多个文档进行批量重排序 Args: query: 用户查询 documents: 文档列表，每个元素为字符串 instruction: 可选的自定义指令 Returns: list: 按得分降序排列的 (文档, 得分) 元组列表 """ url = "http://localhost:7860/api/rerank/batch" payload = { "query": query, "documents": documents } if instruction: payload["instruction"] = instruction data = json.dumps(payload).encode('utf-8') req = urllib.request.Request( url, data=data, headers={'Content-Type': 'application/json'} ) try: with urllib.request.urlopen(req) as response: result = json.loads(response.read().decode('utf-8')) # API返回的是按得分排序后的文档索引列表 # 我们需要将原始文档和得分一一对应 ranked_results = [] for item in result.get("results", []): doc_idx = item.get("index", 0) score = item.get("score", 0.0) if 0 <= doc_idx < len(documents): ranked_results.append((documents[doc_idx], score)) print(f"\n 批量重排序结果（查询: '{query}'）:") for i, (doc, score) in enumerate(ranked_results, 1): color = "🟢" if score > 0.7 else "🟡" if score >= 0.4 else "🔴" print(f"{i}. {color} [{score:.2f}] {doc[:50]}{'...' if len(doc) > 50 else ''}") return ranked_results except Exception as e: print(f" 批量调用失败: {e}") return [] # 实际调用示例 if __name__ == "__main__": query = "什么是人工智能？" docs = [ "AI是人工智能的缩写，是研究、开发用于模拟、延伸和扩展人的智能的理论、方法、技术及应用系统的一门新的技术科学。", "今天天气不错，阳光明媚。", "机器学习是AI的一个重要分支，它让计算机能够从数据中学习。", "我喜欢吃苹果，尤其是红富士。", "深度学习是机器学习的一个子集，它使用神经网络来模拟人脑的工作方式。" ] ranked = batch_rerank(query, docs, instruction="Given a web search query, retrieve relevant passages")输出效果如下：
批量重排序结果（查询: '什么是人工智能？'）: 1. 🟢 [0.92] AI是人工智能的缩写，是研究、开发用于模拟、延伸和扩展人的智能的理论、方法、技术及应用系统的一门新的技术科学。 2. 🟢 [0.88] 深度学习是机器学习的一个子集，它使用神经网络来模拟人脑的工作方式。 3. 🟡 [0.65] 机器学习是AI的一个重要分支，它让计算机能够从数据中学习。 4. 🔴 [0.21] 今天天气不错，阳光明媚。 5. 🔴 [0.15] 我喜欢吃苹果，尤其是红富士。这个函数完美复刻了网页版“批量重排序”的全部能力，并且返回结构化的Python列表，方便你后续做任何逻辑处理——比如只取前3名生成摘要，或者把得分低于0.4的文档直接过滤掉。
3. 进阶实战：处理图文混合内容与生产环境适配
lychee-rerank-mm的核心竞争力在于其多模态能力。上面的例子都是纯文本，但真实世界的数据往往是图文交织的。API同样支持图片输入，只不过方式略有不同：你需要先将图片编码为Base64字符串，再通过image字段传入。
3.1 图文混合评分：让模型“看图说话”
假设你有一个电商场景：用户用文字描述“一件蓝色牛仔外套”，系统返回了几个商品，其中一个是带图的商品详情页。我们想让lychee-rerank-mm同时评估文字描述和商品主图的相关性。
import base64 def multimodal_rerank(query: str, text_document: str, image_path: str, instruction: str = None) -> float: """ 对图文混合内容进行重排序评分 Args: query: 用户查询 text_document: 与图片配套的文字描述 image_path: 本地图片文件路径 instruction: 可选指令 Returns: float: 综合相关性得分 """ url = "http://localhost:7860/api/rerank/multimodal" # 读取并编码图片 try: with open(image_path, "rb") as f: image_b64 = base64.b64encode(f.read()).decode('utf-8') except Exception as e: print(f" 读取图片失败: {e}") return 0.0 payload = { "query": query, "text": text_document, "image": image_b64 } if instruction: payload["instruction"] = instruction data = json.dumps(payload).encode('utf-8') req = urllib.request.Request( url, data=data, headers={'Content-Type': 'application/json'} ) try: with urllib.request.urlopen(req) as response: result = json.loads(response.read().decode('utf-8')) score = result.get("score", 0.0) print(f"🖼 图文混合评分: '{query}' vs '{text_document[:30]}...' + 图片") print(f" 得分: {score:.2f}") return score except Exception as e: print(f" 图文调用失败: {e}") return 0.0 # 使用示例（请将 'path/to/jeans.jpg' 替换为你本地的一张牛仔外套图片） # score = multimodal_rerank( # query="一件蓝色牛仔外套", # text_document="经典修身剪裁，水洗蓝牛仔布，双口袋设计。", # image_path="path/to/jeans.jpg", # instruction="Given a product description and its image, judge their consistency" # )这个函数展示了如何将现实中的图片数据无缝接入自动化流程。关键点在于：图片必须是Base64编码的字符串，且API端点是/api/rerank/multimodal。通过instruction参数，你可以精确引导模型关注“图文一致性”，这比让它泛泛地判断“相关性”要精准得多。
3.2 生产环境友好实践：错误处理与性能优化
在真实的工程部署中，健壮性和效率同样重要。以下是几个关键建议：
1. 添加超时与重试机制
网络请求可能因各种原因失败，简单的try-except不够。使用urllib的timeout参数，并加入指数退避重试：
import time import random def robust_rerank(query, documents, max_retries=3, base_delay=1): """带重试机制的鲁棒调用""" for attempt in range(max_retries): try: return batch_rerank(query, documents) except Exception as e: if attempt == max_retries - 1: raise e delay = (base_delay * (2 ** attempt)) + random.uniform(0, 1) time.sleep(delay) return []2. 批量大小控制
API对单次请求的文档数量有限制。根据你的硬件，建议单次不超过20个文档。如果需要处理100个，就拆分成5个批次并行处理：
from concurrent.futures import ThreadPoolExecutor, as_completed def parallel_batch_rerank(query, all_documents, batch_size=15): """并行处理大批量文档""" batches = [all_documents[i:i+batch_size] for i in range(0, len(all_documents), batch_size)] results = [] with ThreadPoolExecutor(max_workers=3) as executor: future_to_batch = { executor.submit(batch_rerank, query, batch): batch for batch in batches } for future in as_completed(future_to_batch): results.extend(future.result()) # 最终按得分全局排序 return sorted(results, key=lambda x: x[1], reverse=True)3. 结果解读与业务决策
不要只看数字。结合你之前看到的得分颜色指南，可以在代码中直接做业务判断：
def get_business_decision(score: float) -> str: """根据得分返回业务建议""" if score > 0.7: return "直接采用，高置信度" elif score >= 0.4: return "人工复核，中等置信度" else: return "建议忽略，低置信度" # 在调用后立即使用 score = single_rerank("用户投诉物流慢", "您的包裹已在派送途中，预计明日送达。") decision = get_business_decision(score) print(f" 业务建议: {decision}")4. 总结：让重排序能力真正融入你的工作流
回顾整个过程，我们完成了从“知道有这个工具”，到“能在网页上点一点”，再到“用Python代码全自动驱动”的完整跃迁。lychee-rerank-mm的价值，不在于它有多复杂，而在于它把前沿的多模态理解能力，封装成了一个极其轻量、极易集成的接口。
- 它解决了什么问题？“找得到，但排不准”。无论是搜索引擎的最终展示页、客服系统的知识召回、还是内容平台的个性化推荐，排序质量直接决定了用户体验的天花板。
- 它为什么好用？轻量（单卡秒启）、多模态（文本+图像+图文）、易集成（标准HTTP API）、可定制（instruction灵活引导）。
- 你下一步能做什么？把上面的
single_rerank和batch_rerank函数，复制进你的项目里。替换掉原来基于关键词或TF-IDF的粗筛逻辑，用它来做最后一道“精排”关卡。你会发现，那些曾经被埋没的优质内容，开始自然地浮现在用户眼前。
技术的终极目的，是让复杂变得简单，让专业变得普适。lychee-rerank-mm正是这样一个例子——它没有炫技的架构，却用最务实的方式，把多模态AI的能力，交到了每一个开发者手中。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
