Lychee-Rerank-MM快速上手：curl命令直连7860端口测试重排序API调用
1. 什么是Lychee多模态重排序模型？
你可能已经用过一些文本搜索工具，输入关键词后返回一堆网页链接。但有没有遇到过这样的问题：前几条结果看起来和你的问题关系不大？或者图片搜索时，明明想找“穿红裙子的猫”，却跳出一堆橘猫照片？这就是传统检索系统在“精排”环节的短板——它能粗略匹配，但很难判断哪条结果真正贴合你的意图。
Lychee-Rerank-MM就是为解决这个问题而生的。它不是从零开始找内容的“初筛员”，而是站在已有检索结果后面的“专业评委”。它会把初步筛选出的几十甚至上百个图文候选结果，重新打分、排序，把最相关、最精准的那个推到第一位。
更关键的是，它不只看文字。你可以拿一张商品图去搜相似款，也可以用一段描述去匹配带图的说明书，甚至让一张医学影像和一段诊断报告“对话”。这种能力，让它特别适合电商搜索、知识库问答、跨模态内容推荐等真实业务场景。
它背后的技术底座是Qwen2.5-VL——一个经过深度优化的7B规模多模态大模型。别被“7B”吓到，实际参数量约8.29B，但团队通过BF16精度推理、Flash Attention 2加速等工程手段，让它能在单张16GB显存的GPU上稳稳跑起来。服务默认监听7860端口，开箱即用，不需要你从头搭环境、调参数。
2. 为什么用curl直连比网页界面更实用？
很多AI模型都配了Gradio网页界面，点点鼠标就能试。Lychee-Rerank-MM也提供了这个选项，访问http://localhost:7860就能看到一个简洁的交互页面。但如果你真想把它集成进自己的系统里，比如加到搜索后台、嵌入客服机器人、或者写个自动化脚本批量处理数据，光靠点鼠标就远远不够了。
这时候，curl就成了你的“万能钥匙”。它不依赖浏览器，不依赖图形界面，一条命令就能把查询发出去，拿到结构化结果。更重要的是，它能轻松融入Shell脚本、Python程序、CI/CD流程，甚至定时任务。你不用关心按钮在哪、表单怎么填，只需要明确三件事：往哪发（URL）、发什么（JSON数据）、怎么发（HTTP方法）。
下面我们就从最基础的单文档测试开始，一步步带你用curl把Lychee的重排序能力“拧开”。
3. 准备工作：确认服务已启动并可访问
在敲下第一条curl命令之前，得先确保服务真的在跑。这就像开车前要确认引擎已启动，否则再好的方向盘也没用。
3.1 检查服务状态
打开终端，执行以下命令：
# 查看是否已有进程在监听7860端口 lsof -i :7860 # 或者用更通用的方式 netstat -tuln | grep :7860如果看到类似python app.py的进程，说明服务已启动。如果没有输出，那就需要手动启动它。
3.2 启动服务（如未运行）
根据你手头的部署方式，选择一种：
# 方式1：使用推荐的启动脚本（最省心） cd /root/lychee-rerank-mm ./start.sh # 方式2：直接运行主程序（适合调试） cd /root/lychee-rerank-mm python app.py # 方式3：后台静默运行（生产环境常用） cd /root/lychee-rerank-mm nohup python app.py > /tmp/lychee_server.log 2>&1 &启动后，稍等10-20秒，模型加载完成，服务就绪了。你可以用浏览器打开http://localhost:7860看一眼界面是否正常，但这一步只是为了验证，后续所有操作我们都用curl。
3.3 验证基础连通性
在终端里执行这条最简单的健康检查命令：
curl -X GET http://localhost:7860/health如果返回{"status":"healthy"}，恭喜，服务心跳正常。如果报错Connection refused，请回头检查端口、路径和GPU内存（建议16GB+）。
4. 第一次实战：用curl调用单文档重排序API
现在，我们来完成第一个真正的重排序请求。目标很明确：给定一个搜索指令、一个查询（文本），和一个待评估的文档（也是文本），让Lychee给出一个0到1之间的相关性得分。
4.1 构建标准请求体
Lychee的API要求一个结构清晰的JSON对象。我们以“查找中国首都”为例，构建如下数据：
{ "instruction": "Given a web search query, retrieve relevant passages that answer the query", "query": "What is the capital of China?", "documents": ["The capital of China is Beijing."] }注意三个字段：
instruction是“裁判规则”，告诉模型你希望它扮演什么角色；query是你的原始问题或搜索词；documents是一个数组，即使只有一个文档，也必须用方括号包起来。
4.2 发送curl命令
把上面的JSON数据，用curl的-d参数发送出去：
curl -X POST http://localhost:7860/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 China?", "documents": ["The capital of China is Beijing."] }'4.3 解读返回结果
成功执行后，你会看到类似这样的响应：
{ "scores": [0.9523], "reranked_documents": ["The capital of China is Beijing."], "time_cost_ms": 1245 }核心信息一目了然：
scores: 相关性得分，0.9523意味着模型认为这个答案高度相关；reranked_documents: 按得分从高到低排列的文档列表（单文档时顺序不变）；time_cost_ms: 整个推理耗时，单位毫秒，1245ms即约1.2秒。
这个速度对于单次精排来说完全可接受。如果你追求极致性能，后面我们会介绍批量模式。
5. 进阶技巧：处理图文混合与批量请求
单文档测试只是热身。真实世界里，你的数据往往是混合的：用户上传一张截图提问，或者搜索结果里既有文字又有图片。Lychee的强大之处，正在于它原生支持这些组合。
5.1 图文混合请求：用base64编码图片
假设你想用一张“苹果手机”的图片，去搜索描述它的文字说明。Lychee API允许你把图片转成base64字符串，直接塞进query或documents字段。
先准备一张本地图片，比如/path/to/iphone.jpg，然后用命令行转码：
# Linux/macOS base64 -i /path/to/iphone.jpg | tr -d '\n' # Windows PowerShell [Convert]::ToBase64String((Get-Content -Path "C:\path\to\iphone.jpg" -Encoding Byte))得到一长串字符后，构造请求体：
{ "instruction": "Given a product image and description, retrieve similar products", "query": { "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...", "text": "iPhone 15 Pro" }, "documents": [ "A high-end smartphone with titanium frame and A17 chip.", "Budget Android phone with plastic body." ] }注意：query字段现在是一个对象，包含image和text两个键；documents仍是纯文本数组。发送命令时，只需把整个JSON粘贴进-d参数即可。
5.2 批量重排序：一次处理多个文档
单次请求只能打一个分，效率太低。Lychee的批量模式（Batch Reranking）才是生产力核心。它允许你在一次请求中提交10个、50个甚至100个文档，API会一次性返回所有得分，并按从高到低排序。
构造一个包含5个不同答案的请求体：
{ "instruction": "Given a question, retrieve factual passages that answer it", "query": "What is the largest planet in our solar system?", "documents": [ "Jupiter is the largest planet in our solar system.", "Mars is known as the Red Planet.", "Saturn is famous for its ring system.", "Neptune is the eighth and farthest planet from the Sun.", "Earth is the only known planet to support life." ] }发送命令：
curl -X POST http://localhost:7860/rerank/batch \ -H "Content-Type: application/json" \ -d '{ "instruction": "Given a question, retrieve factual passages that answer it", "query": "What is the largest planet in our solar system?", "documents": [ "Jupiter is the largest planet in our solar system.", "Mars is known as the Red Planet.", "Saturn is famous for its ring system.", "Neptune is the eighth and farthest planet from the Sun.", "Earth is the only known planet to support life." ] }'返回结果会是一个Markdown格式的表格，清晰列出每个文档的得分和排名：
{ "markdown_table": "| Rank | Score | Document |\n|------|-------|----------|\n| 1 | 0.9872 | Jupiter is the largest planet in our solar system. |\n| 2 | 0.2105 | Earth is the only known planet to support life. |\n| 3 | 0.1893 | Saturn is famous for its ring system. |\n| 4 | 0.0921 | Neptune is the eighth and farthest planet from the Sun. |\n| 5 | 0.0764 | Mars is known as the Red Planet. |", "time_cost_ms": 2876 }你会发现，批量处理5个文档只花了2.8秒，平均每个不到600ms，比5次单请求快得多。这是因为它充分利用了GPU的并行计算能力，避免了反复加载模型的开销。
6. 实用小贴士：绕过常见坑，提升调用体验
在实际使用中，你可能会遇到几个高频问题。这里不是罗列错误代码，而是给你一套“防踩坑指南”。
6.1 指令（Instruction）不是摆设，选对才有效
很多人把instruction当成固定模板，复制粘贴完事。但Lychee的“指令感知”特性意味着，换一句更贴切的指令，得分可能天差地别。
比如，同样是搜商品，用通用指令：
Given a web search query, retrieve relevant passages that answer the query
和用专用指令：
Given a product image and description, retrieve similar products
后者会让模型更关注“相似性”而非“问答匹配”，从而在商品推荐场景下给出更优排序。官方推荐的三类指令（Web搜索、商品推荐、知识问答）已经覆盖大部分需求，直接选用即可。
6.2 性能调优：三个关键开关
当你发现响应变慢或显存爆满时，优先检查这三个参数：
max_length：默认3200，控制文本最大长度。如果你的文档都很短（<500字），可以安全降到1024，显著提速。- Flash Attention 2：确保启动时没有报错。如果看到
flash_attn is not available，说明没装好，需运行pip install flash-attn --no-build-isolation。 - GPU内存分配：服务启动后，用
nvidia-smi观察显存占用。如果接近100%，尝试减少batch_size（虽然API本身不暴露此参数，但批量请求时，文档数就是隐式batch size）。
6.3 错误排查：从日志里找真相
当curl返回空或报错，别急着重装。先看服务日志：
# 如果用了nohup后台启动 tail -f /tmp/lychee_server.log # 如果是前台运行，直接看终端输出最常见的错误有两类：
FileNotFoundError: [Errno 2] No such file or directory: '/root/ai-models/vec-ai/lychee-rerank-mm'：模型路径不对，用ls /root/ai-models/vec-ai/确认真实路径；CUDA out of memory：GPU显存不足，要么清理其他进程，要么换更大显存的卡。
7. 总结：从命令行到生产集成的下一步
到这里，你应该已经能熟练地用curl命令，把Lychee-Rerank-MM的重排序能力“召唤”出来。从最基础的单文本测试，到图文混合、批量处理，再到指令选择和性能调优，每一步都是为了一个目标：让这个强大的模型，真正为你所用，而不是停留在Demo层面。
接下来，你可以顺着这个路径继续深入：
- 把curl命令封装成Python函数，用
requests库调用，方便集成进你的搜索服务； - 写一个Shell脚本，定时从数据库拉取新文档，批量重排序后更新索引；
- 结合Gradio，做一个内部团队可用的“重排序效果对比工具”，直观展示优化前后的差异。
技术的价值，从来不在它有多炫酷，而在于它能否安静、稳定、高效地解决你手头那个具体的问题。Lychee-Rerank-MM正是这样一款工具——它不声张，但当你需要它的时候，总能给出那个最精准的答案。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
