Lychee-Rerank实战教程集成至FastAPI服务提供HTTP接口调用能力1. 项目简介与核心价值Lychee-Rerank是一个基于Qwen2.5-1.5B模型的本地检索相关性评分工具专门用于处理查询-文档匹配度打分场景。这个工具的核心价值在于能够完全在本地环境中运行无需网络连接确保数据隐私和安全。与传统的云端服务不同Lychee-Rerank提供了以下几个关键优势完全本地化所有计算都在本地完成敏感数据不会上传到任何服务器无使用限制不像很多API服务有调用次数限制可以无限次使用可视化结果内置进度条和颜色分级直观展示相关性分数批量处理支持一次性处理多个候选文档提高工作效率这个工具特别适合需要处理大量文档检索任务的场景比如企业内部知识库搜索、学术文献检索、或者任何需要对查询和文档进行相关性排序的应用。2. 环境准备与安装部署2.1 系统要求在开始之前请确保你的系统满足以下基本要求Python 3.8或更高版本至少8GB内存处理大量文档时建议16GB以上10GB可用磁盘空间用于存储模型文件支持CUDA的GPU可选但能显著加速处理速度2.2 安装依赖包首先创建并激活一个Python虚拟环境python -m venv lychee-env source lychee-env/bin/activate # Linux/Mac # 或者 lychee-env\Scripts\activate # Windows然后安装必要的依赖包pip install fastapi uvicorn transformers torch streamlit这些包的作用分别是fastapi和uvicorn用于创建HTTP接口和服务器transformers和torch用于加载和运行AI模型streamlit用于可视化界面如果你需要保留原功能2.3 下载模型文件Lychee-Rerank使用Qwen2.5-1.5B模型作为基础。如果你还没有这个模型可以通过以下方式获取from transformers import AutoModel, AutoTokenizer model_name Qwen/Qwen2.5-1.5B model AutoModel.from_pretrained(model_name) tokenizer AutoTokenizer.from_pretrained(model_name) # 保存到本地目录 model.save_pretrained(./qwen_model) tokenizer.save_pretrained(./qwen_model)这个过程可能会需要一些时间因为需要下载大约3GB的模型文件。3. FastAPI服务集成实战3.1 创建基础FastAPI应用首先我们创建一个简单的FastAPI应用来提供HTTP接口from fastapi import FastAPI, HTTPException from pydantic import BaseModel from typing import List import torch from transformers import AutoModel, AutoTokenizer app FastAPI(titleLychee-Rerank API, version1.0.0) # 定义请求数据模型 class RerankRequest(BaseModel): instruction: str 基于查询检索相关文档 query: str documents: List[str] top_k: int 5 # 加载模型在实际应用中应该做成单例 app.on_event(startup) async def load_model(): global model, tokenizer try: model AutoModel.from_pretrained(./qwen_model) tokenizer AutoTokenizer.from_pretrained(./qwen_model) print(模型加载成功) except Exception as e: print(f模型加载失败: {e})3.2 实现核心评分逻辑接下来实现最重要的相关性评分功能def calculate_relevance_score(instruction, query, document): 计算查询与文档的相关性分数 # 构建输入文本遵循Lychee官方格式 input_text fInstruct{instruction}/Instruct\nQuery{query}/Query\nDocument{document}/Document # 编码输入文本 inputs tokenizer(input_text, return_tensorspt, truncationTrue, max_length1024) # 模型推理 with torch.no_grad(): outputs model(**inputs) # 计算yes的概率作为相关性分数 logits outputs.logits yes_token_id tokenizer.convert_tokens_to_ids(yes) yes_logit logits[0, -1, yes_token_id] # 使用softmax获取概率 probs torch.softmax(torch.tensor([yes_logit, -yes_logit]), dim0) relevance_score probs[0].item() return relevance_score app.post(/rerank) async def rerank_documents(request: RerankRequest): 重排序接口对文档按相关性进行排序 try: results [] # 对每个文档计算相关性分数 for doc in request.documents: score calculate_relevance_score( request.instruction, request.query, doc ) results.append({ document: doc, score: round(score, 6) }) # 按分数降序排序 results.sort(keylambda x: x[score], reverseTrue) # 只返回top_k个结果 top_results results[:request.top_k] return { query: request.query, total_documents: len(request.documents), results: top_results } except Exception as e: raise HTTPException(status_code500, detailf处理失败: {str(e)})3.3 添加健康检查接口为了方便监控服务状态添加一个健康检查接口app.get(/health) async def health_check(): 服务健康检查接口 return { status: healthy, model_loaded: model is not None, service: lychee-rerank-api } app.get(/) async def root(): 根目录接口提供基础信息 return { message: Lychee-Rerank API服务运行中, version: 1.0.0, endpoints: { rerank: POST /rerank - 文档重排序, health: GET /health - 健康检查 } }4. 服务部署与运行4.1 启动FastAPI服务现在我们可以启动HTTP服务了。创建一个启动脚本start_server.pyimport uvicorn if __name__ __main__: uvicorn.run( main:app, # 假设上面的代码保存在main.py中 host0.0.0.0, # 允许所有IP访问 port8000, # 服务端口 reloadTrue # 开发时自动重载 )然后通过命令行启动服务python start_server.py服务启动后你会在控制台看到类似这样的输出INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRLC to quit)4.2 测试HTTP接口服务启动后我们可以测试一下接口是否正常工作。使用curl命令测试# 测试健康检查接口 curl http://localhost:8000/health # 测试重排序接口 curl -X POST http://localhost:8000/rerank \ -H Content-Type: application/json \ -d { query: 人工智能的发展历史, documents: [ 人工智能是计算机科学的一个分支致力于创建智能机器。, 西红柿是一种红色的水果常用于烹饪。, 深度学习是机器学习的一个分支使用神经网络模拟人脑。, 篮球是一种流行的团队运动需要投篮得分。, 人工智能的历史可以追溯到20世纪50年代当时提出了图灵测试。 ], top_k: 3 }你应该会得到一个JSON响应包含按相关性排序的文档列表。4.3 使用Python客户端调用你也可以创建一个Python客户端来调用这个服务import requests import json def rerank_documents(query, documents, instruction基于查询检索相关文档, top_k5): 调用Lychee-Rerank API进行文档重排序 url http://localhost:8000/rerank payload { instruction: instruction, query: query, documents: documents, top_k: top_k } try: response requests.post(url, jsonpayload) response.raise_for_status() return response.json() except requests.exceptions.RequestException as e: print(fAPI调用失败: {e}) return None # 使用示例 results rerank_documents( query机器学习的基本概念, documents[ 机器学习是人工智能的一个分支让计算机通过数据学习。, 巴黎是法国的首都以其艺术和文化闻名。, 监督学习需要标注数据来训练模型。, 披萨是意大利的传统食物有多种口味。, 无监督学习用于发现数据中的隐藏模式。 ] ) print(json.dumps(results, indent2, ensure_asciiFalse))5. 实际应用场景与技巧5.1 常见应用场景Lychee-Rerank的HTTP接口可以在多种场景下发挥作用企业知识库搜索# 在企业内部系统中集成搜索功能 def search_knowledge_base(user_query, knowledge_docs): results rerank_documents( queryuser_query, documentsknowledge_docs, instruction根据用户问题找到最相关的知识文档 ) return results[results][:3] # 返回最相关的3个文档学术文献检索# 帮助研究人员找到相关论文 def find_relevant_papers(research_topic, paper_abstracts): results rerank_documents( queryresearch_topic, documentspaper_abstracts, instruction找出与研究方向最相关的学术论文 ) return results[results]5.2 性能优化技巧如果你需要处理大量文档可以考虑以下优化措施批量处理优化# 一次性处理大量文档时可以考虑分批次处理 def batch_rerank(query, documents, batch_size10): all_results [] for i in range(0, len(documents), batch_size): batch_docs documents[i:ibatch_size] results rerank_documents(query, batch_docs) all_results.extend(results[results]) # 对所有结果重新排序 all_results.sort(keylambda x: x[score], reverseTrue) return all_results缓存优化# 对于重复的查询可以添加缓存机制 from functools import lru_cache lru_cache(maxsize1000) def cached_rerank(query, instruction, documents_tuple): 使用缓存避免重复计算相同查询 documents需要转换为元组才能被缓存 documents list(documents_tuple) return rerank_documents(query, documents, instruction)5.3 错误处理与监控在生产环境中良好的错误处理和监控很重要import logging import time # 配置日志 logging.basicConfig(levellogging.INFO) logger logging.getLogger(__name__) def robust_rerank(query, documents, max_retries3): 带重试机制的稳健调用函数 for attempt in range(max_retries): try: start_time time.time() result rerank_documents(query, documents) elapsed time.time() - start_time logger.info(f重排序成功: 查询长度{len(query)}, 文档数{len(documents)}, 耗时{elapsed:.2f}s) return result except Exception as e: logger.warning(f第{attempt1}次尝试失败: {str(e)}) if attempt max_retries - 1: logger.error(f所有{max_retries}次尝试都失败了) raise time.sleep(2 ** attempt) # 指数退避6. 总结与下一步建议通过本教程你已经学会了如何将Lychee-Rerank集成到FastAPI服务中提供一个完整的HTTP接口用于文档相关性评分。这种集成方式有几个显著优点标准化接口提供统一的RESTful API方便各种编程语言调用易于扩展可以轻松添加身份验证、速率限制、监控等功能部署灵活可以在本地服务器、云服务器或容器环境中部署生态集成能够与其他系统无缝集成形成完整的工作流下一步学习建议学习如何为API添加身份验证和授权机制探索使用Docker容器化部署提高部署效率考虑添加速率限制和负载均衡处理高并发请求集成监控和日志系统更好地掌握服务运行状态现在你已经有了一个功能完整的文档重排序服务可以开始将其集成到你的实际项目中提升搜索和检索体验了。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。