MGeo地址匹配服务化：Flask封装+Swagger文档生成教程

MGeo地址匹配服务化：Flask封装+Swagger文档生成教程

你是否在处理大量中文地址数据时，为如何判断“北京市朝阳区”和“北京朝阳”是否指向同一地点而头疼？阿里开源的MGeo模型正是为此类问题量身打造的解决方案。它专注于中文地址领域的相似度匹配与实体对齐，能够精准识别语义相近但表述不同的地址信息，在物流、电商、城市治理等场景中具有极高的实用价值。

本文将带你完成从模型推理到服务部署的完整闭环——不仅教你如何运行MGeo模型进行地址相似度计算，更进一步使用Flask将其封装为RESTful API，并通过Swagger自动生成可视化接口文档。整个过程基于CSDN星图平台提供的预置镜像环境，无需繁琐配置，10分钟即可上线一个专业级的地址匹配服务。

1. 环境准备与模型运行

在开始之前，请确保你已在CSDN星图平台成功部署MGeo镜像（推荐使用4090D单卡实例）。启动后，系统会自动加载包含MGeo推理脚本的Jupyter环境。接下来我们一步步激活运行环境并验证模型能力。

1.1 激活环境并定位脚本

登录Jupyter后，打开终端执行以下命令：

conda activate py37testmaas

该环境已预装PyTorch、Transformers等必要依赖库，以及MGeo模型权重文件。原始推理脚本位于/root/推理.py，建议将其复制到工作区便于查看和修改：

cp /root/推理.py /root/workspace

随后可在Jupyter文件浏览器中进入/root/workspace目录，找到推理.py文件并打开。这个Python脚本包含了模型加载、文本预处理和相似度预测的核心逻辑。

1.2 理解推理脚本核心逻辑

打开推理.py后，你会看到几个关键部分：

• 模型加载：使用HuggingFace风格的AutoModel和AutoTokenizer加载本地路径下的MGeo模型。
• 输入构造：将待比较的两个地址构造成特定格式的字符串对，如"地址A\t地址B"。
• 相似度预测：模型输出一个0到1之间的连续值，数值越接近1表示两地址语义越相似。

例如，脚本中可能包含如下调用示例：

from transformers import AutoModel, AutoTokenizer import torch model_path = "/root/mgeo-model" tokenizer = AutoTokenizer.from_pretrained(model_path) model = AutoModel.from_pretrained(model_path) def get_similarity(addr1, addr2): inputs = tokenizer(f"{addr1}\t{addr2}", return_tensors="pt", padding=True) with torch.no_grad(): outputs = model(**inputs) # 假设最后一层池化向量用于相似度计算 similarity = torch.cosine_similarity(outputs[0][0], outputs[0][1]).item() return similarity

注意：实际代码结构以镜像内文件为准，此处仅为示意。重点在于理解其输入输出格式及调用方式。

现在你可以直接运行该脚本，测试几组地址对的匹配效果，比如：

• ("北京市海淀区中关村大街1号", "北京中关村")
• ("上海市浦东新区张江高科园区", "上海张江")

观察输出的相似度分数，初步感受MGeo的匹配能力。

2. 使用Flask构建RESTful API服务

仅仅能在本地运行还不够，真正的工程价值在于将模型能力暴露为可远程调用的服务。我们将使用轻量级Web框架Flask，把MGeo包装成HTTP接口。

2.1 创建Flask应用骨架

新建一个文件app.py，编写基础Flask服务结构：

from flask import Flask, request, jsonify from transformers import AutoModel, AutoTokenizer import torch app = Flask(__name__) # 全局加载模型（服务启动时执行一次） model_path = "/root/mgeo-model" tokenizer = AutoTokenizer.from_pretrained(model_path) model = AutoModel.from_pretrained(model_path) @app.route('/health', methods=['GET']) def health_check(): return jsonify({"status": "healthy"}), 200 @app.route('/match', methods=['POST']) def match_addresses(): data = request.get_json() addr1 = data.get("address1") addr2 = data.get("address2") if not addr1 or not addr2: return jsonify({"error": "缺少必要参数 address1 或 address2"}), 400 # 构造输入并获取模型输出 inputs = tokenizer(f"{addr1}\t{addr2}", return_tensors="pt", padding=True) with torch.no_grad(): outputs = model(**inputs) # 简化处理：取[CLS]向量均值作为句向量（具体策略依模型设计而定） sentence_embedding = outputs.last_hidden_state.mean(dim=1).squeeze().numpy() # 实际应根据MGeo论文或代码实现正确的相似度计算方式 similarity_score = 0.95 # 占位符，替换为真实计算逻辑 return jsonify({ "address1": addr1, "address2": addr2, "similarity": float(similarity_score) }) if __name__ == '__main__': app.run(host='0.0.0.0', port=5000)

2.2 部署前的关键调整

上述代码中的相似度计算部分需要根据MGeo的实际推理逻辑进行修正。建议回到推理.py中确认以下几点：

• 模型输出的具体形式（是直接输出相似度还是双塔句向量？）
• 是否需要特殊的池化操作（如Mean Pooling、CLS Token提取等）
• 是否有归一化或缩放步骤

一旦确认清楚，替换掉占位符逻辑即可。例如，若模型采用双塔结构输出句向量，则应分别编码两个地址后再计算余弦相似度：

inputs1 = tokenizer(addr1, return_tensors="pt") inputs2 = tokenizer(addr2, return_tensors="pt") with torch.no_grad(): vec1 = model(**inputs1).last_hidden_state.mean(dim=1) vec2 = model(**inputs2).last_hidden_state.mean(dim=1) similarity = torch.cosine_similarity(vec1, vec2).item()

2.3 启动API服务

保存app.py后，在终端执行：

python app.py

如果一切正常，你会看到类似提示：

* Running on http://0.0.0.0:5000/

此时服务已在容器内部5000端口监听。你可以通过curl命令测试接口：

curl -X POST http://localhost:5000/match \ -H "Content-Type: application/json" \ -d '{"address1": "北京市朝阳区", "address2": "北京朝阳"}'

预期返回JSON格式结果，包含两个地址及其相似度评分。

3. 集成Swagger生成可视化API文档

有了API还不足以让团队成员快速上手。我们需要一份清晰、交互式的接口文档。这里引入flasgger库，它可以基于注释自动生成Swagger UI界面。

3.1 安装Flasgger并集成

首先安装依赖：

pip install flasgger

然后修改app.py，引入Flasgger并添加接口描述：

from flasgger import Swagger, swag_from app = Flask(__name__) swagger = Swagger(app) # ...（保持原有模型加载代码不变） @app.route('/match', methods=['POST']) @swag_from({ 'tags': ['地址匹配'], 'description': '计算两个中文地址的语义相似度', 'parameters': [ { 'name': 'body', 'in': 'body', 'required': True, 'schema': { 'type': 'object', 'properties': { 'address1': { 'type': 'string', 'example': '北京市海淀区中关村大街1号' }, 'address2': { 'type': 'string', 'example': '北京中关村' } }, 'required': ['address1', 'address2'] } } ], 'responses': { '200': { 'description': '成功返回相似度结果', 'examples': { 'application/json': { 'address1': '北京市海淀区', 'address2': '北京海淀', 'similarity': 0.96 } } } } }) def match_addresses(): # 保持原有函数体不变 pass

3.2 访问Swagger UI界面

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

http://<你的服务器IP>:5000/apidocs

你将看到自动生成的Swagger UI页面，包含：

• 所有API端点列表
• 每个接口的详细参数说明
• 可视化请求示例构造器
• “Try it out”按钮支持在线调试

这意味着任何使用者都不再需要阅读代码就能理解如何调用你的地址匹配服务，极大提升了协作效率。

4. 总结

通过本文的实践，我们完成了MGeo地址匹配模型的服务化全流程：从最基础的脚本运行，到使用Flask封装为RESTful API，再到借助Flasgger生成专业的可视化文档。这一套组合拳不仅适用于MGeo，也完全可以迁移到其他NLP模型的服务部署中。

这套方案的优势在于：

• 低门槛：基于预置镜像，省去复杂环境配置
• 高可用：HTTP接口易于集成进各类业务系统
• 易维护：Swagger文档随代码更新自动同步
• 可扩展：后续可加入缓存、限流、日志等企业级功能

当你面对下一个AI模型落地任务时，不妨沿用这个“推理→封装→文档化”的三步法，快速将算法能力转化为生产力。

获取更多AI镜像

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