AI+物流应用教程：从零搭建一个智能运单查询接口
很多人搜索 AI+物流应用教程，是想知道怎么把 AI 能力真正接到自己的物流业务里，而不是只看概念。
这篇教程就带你从零搭建一个最小可用的智能运单查询接口：用户输入一个中文地址，程序自动调用地图服务的地址解析功能拿到经纬度，再计算两个地址之间的直线距离，最后返回结构化的物流距离信息。
整个过程不需要你懂深度学习，只要会一点 Python 基础就能跟着做。
先明确这个接口能做什么、不能做什么
这个接口适合以下场景：
- 物流报价系统需要根据收发货地址估算运输距离
- 运单录入时自动补全地址坐标，减少人工填写错误
- 配送调度页面展示两个网点之间的参考距离
需要提前说明的是，它不负责实时路况、车辆轨迹和路径规划。
地址解析和距离计算依赖第三方地图服务，不同服务商的精度和配额限制不一样，正式上线前需要根据业务量评估。
如果你需要完整的路径规划或 AI 预测到达时间，那属于更复杂的系统集成，不在本篇范围内。
环境准备与依赖安装
操作前提：一台能上网的 Linux 或 Windows 机器，已安装 Python 3.8 及以上版本。
下面以 Linux 为例，Windows 用户把命令换成对应的 PowerShell 写法即可。
先创建项目目录并安装依赖：
mkdir ai-logistics-demo && cd ai-logistics-demo
python3 -m venv venv
source venv/bin/activate
pip install flask requests这里用到两个库：flask 用来提供 HTTP 接口，requests 用来调用地图服务。
接着去你选择的地图开放平台注册账号，申请一个 Web 服务 API Key。不要直接把 Key 写死在代码里，建议用环境变量保存：
export MAP_API_KEY="你的APIKey"如果你用的是宝塔面板，可以在“网站”对应项目的环境变量配置中添加，或者在启动脚本里通过 export 设置。
编写地址解析与距离计算代码
新建文件 app.py，写入以下核心逻辑。
代码里用注释标出了每一步的输入和输出，方便你对照检查。
import os
import requests
from flask import Flask, request, jsonify
app = Flask(__name__)
API_KEY = os.environ.get("MAP_API_KEY")
GEO_URL = "https://restapi.amap.com/v3/geocode/geo"
def geocode(address):
"""输入中文地址，返回 (经度, 纬度)；失败返回 None"""
params = {"key": API_KEY, "address": address}
resp = requests.get(GEO_URL, params=params, timeout=5)
data = resp.json()
if data.get("status") != "1" or not data.get("geocodes"):
return None
location = data["geocodes"][0]["location"]
lng, lat = location.split(",")
return float(lng), float(lat)
def distance_km(p1, p2):
"""用 Haversine 公式计算两点球面距离，单位公里"""
from math import radians, sin, cos, asin, sqrt
lng1, lat1 = map(radians, p1)
lng2, lat2 = map(radians, p2)
dlon = lng2 - lng1
dlat = lat2 - lat1
a = sin(dlat/2)**2 + cos(lat1)*cos(lat2)*sin(dlon/2)**2
return 2 * 6371 * asin(sqrt(a))
@app.route("/distance")
def get_distance():
origin = request.args.get("from")
dest = request.args.get("to")
if not origin or not dest:
return jsonify({"error": "缺少 from 或 to 参数"}), 400
p1 = geocode(origin)
p2 = geocode(dest)
if not p1 or not p2:
return jsonify({"error": "地址解析失败，请检查地址是否完整"}), 422
km = round(distance_km(p1, p2), 2)
return jsonify({"from": origin, "to": dest, "distance_km": km})
if __name__ == "__main__":
app.run(host="0.0.0.0", port=5000)启动服务：
python app.py看到 Running on http://0.0.0.0:5000 就说明启动成功。
避坑指南：这几个地方最容易出错
地址解析返回空结果。
常见原因是地址写得太模糊，比如只写“朝阳区”而不写城市。
建议在调用前对地址做简单清洗，至少保留“省+市+区+详细地址”的结构。
API Key 无效或配额超限。
地图服务通常有免费调用额度，超出后会返回错误码。
生产环境建议在代码里加一层缓存，对相同地址的解析结果缓存一段时间，减少重复调用。
经纬度顺序写反。
不同地图服务返回的坐标顺序可能不同，高德返回的是“经度,纬度”，如果你的业务系统习惯纬度在前，一定要在代码里显式转换，否则距离会算错。
防火墙拦截端口。
如果服务部署在云服务器上，记得在安全组放行 5000 端口；
如果用 Nginx 反向代理，检查 proxy_pass 是否指向正确的本地端口。
验证接口是否正常工作
服务启动后，用 curl 发一个测试请求：
curl "http://127.0.0.1:5000/distance?from=北京市朝阳区&to=上海市浦东新区"预期返回类似下面的 JSON：
{"from":"北京市朝阳区","to":"上海市浦东新区","distance_km":1067.5}如果返回 422，说明地址解析失败，先检查地址是否完整、Key 是否有效；
如果返回 400，检查 URL 参数是否漏传。
距离数值只作为参考，和实际道路里程会有差异，业务上如果要用于计费，建议结合地图服务商的道路距离接口做二次校准。
常见疑问
这个接口需要 GPU 吗？ 不需要。
地址解析和距离计算都是普通 HTTP 调用加数学公式，普通云服务器就能跑。
能不能批量处理运单？ 可以，把接口改成接收地址列表，循环调用解析函数即可，但要注意控制并发，避免触发地图服务的频率限制。
地址解析不准怎么办？ 先确认地址完整性，再检查 API Key 是否绑定了正确的服务类型。
如果业务对精度要求高，可以接入专业地址库做标准化预处理。
到这里，一个最小可用的 AI+物流地址距离查询接口就完成了。
你可以在这个基础上继续扩展，比如接入运单数据库自动读取地址、增加缓存层、或者把返回结果接到前端调度页面。
建议先在测试环境跑通整个流程，确认地址解析和距离计算符合预期后，再部署到正式环境。
