nlp_structbert_sentence-similarity_chinese-large实战教程FastAPI封装Swagger文档生成1. 项目介绍与核心价值nlp_structbert_sentence-similarity_chinese-large 是一个基于阿里达摩院开源StructBERT模型的中文句子相似度计算工具。这个工具能够将中文句子转换为高质量的特征向量然后通过余弦相似度算法精确计算两个句子之间的语义相关程度。StructBERT相比传统的BERT模型有了重要升级它通过词序目标和句子序目标等结构化预训练策略在处理中文语序、语法结构和深层语义理解方面表现更加出色。这意味着它能更好地理解中文的语言特点比如词语顺序变化对语义的影响以及句子间的逻辑关系。在实际应用中这个工具可以帮你解决很多实际问题检查两段文字是否表达相同的意思、在海量文本中快速找到相似内容、判断用户问题与知识库答案的匹配程度等。无论是做文本去重、语义搜索还是构建智能客服系统这都是一个非常实用的工具。2. 环境准备与模型部署2.1 安装必要依赖首先需要安装运行所需的Python库pip install fastapi uvicorn transformers torch sentence-transformers这些库各自有不同的作用fastapi和uvicorn用于构建API服务和运行服务器transformers和torch是深度学习模型的核心依赖sentence-transformers提供了方便的句子编码接口2.2 模型文件准备确保你已经下载了StructBERT模型权重文件并放置在正确的路径下。通常模型文件应该包含config.json模型配置文件pytorch_model.bin模型权重文件vocab.txt词汇表文件建议将模型文件放在统一的目录中比如/models/nlp_structbert_sentence-similarity_chinese-large/2.3 验证模型可用性在开始封装API之前先写个简单的测试脚本验证模型能正常工作from sentence_transformers import SentenceTransformer # 加载模型 model SentenceTransformer(你的模型路径/models/nlp_structbert_sentence-similarity_chinese-large) # 测试句子 sentences1 [今天天气真好] sentences2 [天气真不错啊] # 计算相似度 embeddings1 model.encode(sentences1) embeddings2 model.encode(sentences2) from sklearn.metrics.pairwise import cosine_similarity similarity cosine_similarity(embeddings1, embeddings2)[0][0] print(f相似度得分: {similarity:.4f})如果一切正常你会看到一个0到1之间的相似度分数。3. FastAPI服务封装实战3.1 创建基础API结构我们来创建一个完整的FastAPI应用封装句子相似度计算功能from fastapi import FastAPI, HTTPException from pydantic import BaseModel from sentence_transformers import SentenceTransformer from sklearn.metrics.pairwise import cosine_similarity import numpy as np import torch # 定义请求数据模型 class SimilarityRequest(BaseModel): text1: str text2: str # 定义响应数据模型 class SimilarityResponse(BaseModel): similarity_score: float semantic_relation: str status: str # 创建FastAPI应用 app FastAPI( title中文句子相似度API, description基于StructBERT的中文句子相似度计算服务, version1.0.0 ) # 全局模型变量 model None app.on_event(startup) async def load_model(): 启动时加载模型 global model try: model_path /root/ai-models/iic/nlp_structbert_sentence-similarity_chinese-large model SentenceTransformer(model_path) # 使用半精度浮点数加速推理 if torch.cuda.is_available(): model model.half() print(模型加载成功) except Exception as e: print(f模型加载失败: {str(e)}) raise e app.post(/similarity, response_modelSimilarityResponse) async def calculate_similarity(request: SimilarityRequest): 计算两个句子的语义相似度 if model is None: raise HTTPException(status_code503, detail模型未就绪) try: # 编码句子 embeddings model.encode([request.text1, request.text2]) # 计算余弦相似度 similarity cosine_similarity( embeddings[0].reshape(1, -1), embeddings[1].reshape(1, -1) )[0][0] # 判断语义关系 if similarity 0.85: relation 语义非常相似 elif similarity 0.5: relation 语义相关 else: relation 语义不相关 return SimilarityResponse( similarity_scorefloat(similarity), semantic_relationrelation, statussuccess ) except Exception as e: raise HTTPException(status_code500, detailf计算失败: {str(e)}) app.get(/health) async def health_check(): 健康检查端点 return {status: healthy, model_loaded: model is not None}3.2 批量处理功能扩展在实际应用中我们经常需要批量处理多个句子对添加这个功能会让API更实用from typing import List class BatchSimilarityRequest(BaseModel): pairs: List[dict] class BatchSimilarityResponse(BaseModel): results: List[dict] total_pairs: int processing_time: float app.post(/batch_similarity, response_modelBatchSimilarityResponse) async def batch_calculate_similarity(request: BatchSimilarityRequest): 批量计算句子相似度 if model is None: raise HTTPException(status_code503, detail模型未就绪) import time start_time time.time() results [] for pair in request.pairs: try: embeddings model.encode([pair[text1], pair[text2]]) similarity cosine_similarity( embeddings[0].reshape(1, -1), embeddings[1].reshape(1, -1) )[0][0] results.append({ text1: pair[text1], text2: pair[text2], similarity_score: float(similarity), semantic_relation: 非常相似 if similarity 0.85 else 相关 if similarity 0.5 else 不相关 }) except Exception as e: results.append({ text1: pair[text1], text2: pair[text2], error: str(e) }) processing_time time.time() - start_time return BatchSimilarityResponse( resultsresults, total_pairslen(request.pairs), processing_timeprocessing_time )4. Swagger文档自动生成4.1 利用FastAPI的自动文档功能FastAPI的一大优势就是自动生成API文档。我们上面写的代码已经包含了足够的注释和类型提示FastAPI会自动为我们生成交互式文档。启动服务后你可以通过以下地址访问文档http://localhost:8000/docs- Swagger UI交互式文档http://localhost:8000/redoc- ReDoc alternative文档4.2 增强API文档描述为了让文档更加友好我们可以在代码中添加更详细的描述app.post( /similarity, response_modelSimilarityResponse, summary计算句子相似度, description ## 功能描述 计算两个中文句子的语义相似度得分 ## 使用示例 - 输入: 今天天气真好 和 天气真不错啊 - 输出: 相似度0.92判定为语义非常相似 ## 评分标准 - 0.85: 语义非常相似绿色 - 0.5 - 0.85: 语义相关橙色 - 0.5: 语义不相关红色 ) async def calculate_similarity(request: SimilarityRequest): # 函数实现保持不变4.3 添加更多API元数据我们还可以在FastAPI应用初始化时添加更多元信息让文档更加完整app FastAPI( titleStructBERT中文句子相似度API, description ## 基于StructBERT的中文语义相似度计算服务 本服务使用阿里达摩院开源的StructBERT大型预训练模型能够精准计算两个中文句子的语义相似度。 ### 主要特性 - 基于最先进的StructBERT模型 - ⚡ 支持GPU加速推理 - 提供详细的相似度分数和语义关系判定 - 支持单次和批量处理模式 - 自动生成交互式API文档 ### 适用场景 - 文本去重和相似内容检测 - 智能客服问答匹配 - 语义搜索和推荐系统 - 内容审核和版权保护 , version1.0.0, contact{ name: 技术支持, email: supportexample.com, }, license_info{ name: Apache 2.0, url: https://www.apache.org/licenses/LICENSE-2.0.html, } )5. 服务部署与性能优化5.1 启动FastAPI服务创建一个启动脚本run_api.pyimport uvicorn if __name__ __main__: uvicorn.run( main:app, host0.0.0.0, port8000, reloadTrue, # 开发时开启热重载 workers1, # 生产环境可以根据需要调整 timeout_keep_alive300 )然后运行python run_api.py5.2 性能优化建议为了提高API的响应速度和处理能力可以考虑以下优化措施# 添加缓存机制 from functools import lru_cache lru_cache(maxsize1000) def cached_encode(text: str): 带缓存的句子编码 return model.encode([text])[0] # 在API端点中使用缓存 app.post(/similarity_cached) async def calculate_similarity_cached(request: SimilarityRequest): 使用缓存的相似度计算 emb1 cached_encode(request.text1) emb2 cached_encode(request.text2) similarity cosine_similarity( emb1.reshape(1, -1), emb2.reshape(1, -1) )[0][0] return {similarity_score: float(similarity)}5.3 添加监控和日志为了更好地监控API运行状态添加日志记录import logging logging.basicConfig(levellogging.INFO) logger logging.getLogger(__name__) app.middleware(http) async def log_requests(request, call_next): 日志中间件 logger.info(f请求: {request.method} {request.url}) response await call_next(request) logger.info(f响应: {response.status_code}) return response app.get(/stats) async def get_stats(): 获取API统计信息 return { model_loaded: model is not None, gpu_available: torch.cuda.is_available(), device: str(torch.cuda.get_device_name(0)) if torch.cuda.is_available() else CPU }6. 完整代码示例以下是完整的API服务代码from fastapi import FastAPI, HTTPException from pydantic import BaseModel from sentence_transformers import SentenceTransformer from sklearn.metrics.pairwise import cosine_similarity from typing import List, Optional import torch import logging from functools import lru_cache # 配置日志 logging.basicConfig(levellogging.INFO) logger logging.getLogger(__name__) # 定义数据模型 class SimilarityRequest(BaseModel): text1: str text2: str class SimilarityResponse(BaseModel): similarity_score: float semantic_relation: str status: str class BatchPair(BaseModel): text1: str text2: str class BatchSimilarityRequest(BaseModel): pairs: List[BatchPair] class BatchResult(BaseModel): text1: str text2: str similarity_score: float semantic_relation: str class BatchSimilarityResponse(BaseModel): results: List[BatchResult] total_pairs: int processing_time: float # 创建FastAPI应用 app FastAPI( titleStructBERT中文句子相似度API, description基于阿里达摩院StructBERT模型的中文句子相似度计算服务, version1.0.0 ) # 全局模型变量 model None app.on_event(startup) async def load_model(): 启动时加载模型 global model try: model_path /root/ai-models/iic/nlp_structbert_sentence-similarity_chinese-large model SentenceTransformer(model_path) if torch.cuda.is_available(): model model.half().cuda() logger.info(模型加载成功) except Exception as e: logger.error(f模型加载失败: {str(e)}) raise e lru_cache(maxsize1000) def cached_encode(text: str): 带缓存的句子编码 return model.encode([text])[0] app.post(/similarity, response_modelSimilarityResponse) async def calculate_similarity(request: SimilarityRequest): 计算两个句子的语义相似度 if model is None: raise HTTPException(status_code503, detail模型未就绪) try: # 编码句子 emb1 cached_encode(request.text1) emb2 cached_encode(request.text2) # 计算余弦相似度 similarity cosine_similarity( emb1.reshape(1, -1), emb2.reshape(1, -1) )[0][0] # 判断语义关系 if similarity 0.85: relation 语义非常相似 elif similarity 0.5: relation 语义相关 else: relation 语义不相关 return SimilarityResponse( similarity_scorefloat(similarity), semantic_relationrelation, statussuccess ) except Exception as e: logger.error(f相似度计算错误: {str(e)}) raise HTTPException(status_code500, detailf计算失败: {str(e)}) app.get(/health) async def health_check(): 健康检查端点 return { status: healthy, model_loaded: model is not None, gpu_available: torch.cuda.is_available() } if __name__ __main__: import uvicorn uvicorn.run(app, host0.0.0.0, port8000)7. 总结通过这个实战教程我们成功将nlp_structbert_sentence-similarity_chinese-large模型封装成了一个完整的FastAPI服务并自动生成了漂亮的Swagger文档。这个服务现在具备了以下特点易于使用清晰的API接口和自动文档新手也能快速上手功能完整支持单句相似度计算和批量处理两种模式性能优化通过缓存和GPU加速提升响应速度可扩展性强代码结构清晰容易添加新功能监控完善包含健康检查和日志记录方便运维你现在可以通过访问http://localhost:8000/docs来查看和测试API的所有功能。无论是单独使用还是集成到更大的系统中这个服务都能为你的中文文本处理需求提供强大的语义相似度计算能力。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。