基于启发式算法（VRP）+ 高德地图 + Bosch 内部 LLM 的智能物流调度 MVP
适用于多站点配送、异构车型调度、拆单运输与调度方案解释等本地化物流计划场景。
- 多车型支持：4.2t / 8.3t / 12t / 19t / 49t 厢式货车，可配置各型数量
- 智能路径规划：最近邻 + 2-opt 启发式算法，生成前 N 个候选方案
- 货物拆分：自动处理单点货量超出单车容量的情况（按比例拆分）
- 时间窗约束：支持配送时间窗，支持"不限时"选项
- 地图可视化：高德地图 2.0，路线颜色区分，POI 搜索
- AI 助手：基于 Bosch 内部 LLM（doubao-pro-32k），提供方案解读与风险分析
- 地址库：支持常用地址管理、Excel 批量导入
- 输入校验：必填项检查，问题行高亮提示
Log_AI/
├── app.py # FastAPI 后端主程序
├── config_loader.py # 统一配置加载器（读取 config.ini）
├── config.ini.example # 配置文件模板（复制并改名为 config.ini 后填写）
├── requirements.txt # Python 依赖
├── 启动系统.bat # Windows 一键启动脚本
├── Bosch_LLM_API/
│ ├── client.py # Bosch LLM OAuth2 客户端
│ └── settings.json.example # LLM 配置模板
├── GaoDe_API/
│ ├── gaode_client.py # 高德 Web 服务封装
│ └── gaode_config.json # 高德 API 配置（由 config.ini 自动生成）
├── static/
│ ├── index.html # 前端主页面（纯 HTML + CSS + JS）
│ └── js/
│ ├── app.js # 主应用逻辑
│ ├── solver.js # VRP 求解器（前端启发式算法）
│ ├── map.js # 高德地图模块
│ └── ai.js # AI 助手模块
└── data/
└── create_template.py # Excel 导入模板生成脚本
当前系统采用 前端交互 + FastAPI 服务层 + 外部能力集成 的轻量化架构，适合本地部署、业务验证与后续逐步升级到工业级求解器。
- 前端界面（
static/index.html+static/js/*.js）：负责站点录入、地址库选择、地图展示、结果可视化、AI 交互 - 前端求解器（
static/js/solver.js）：负责当前 MVP 阶段的启发式 VRP 求解 - 后端服务（
app.py）：负责地理服务代理、地址库管理、Excel 导入导出、AI 调用封装、静态页面服务 - 配置层（
config_loader.py）：负责从config.ini读取统一配置并同步到各子模块 - 地图能力（
GaoDe_API/）：负责地理编码、距离矩阵和地图底图能力 - AI 能力（
Bosch_LLM_API/）：负责调用 Bosch 内部 LLM 完成解释、审核和问答 - 数据层（
data/）：负责地址库、Excel 模板、车型配置等本地数据文件
┌────────────────────────────────────────────────────────────┐
│ 浏览器前端界面 │
│ 站点录入 / 地址库 / 地图可视化 / 结果卡片 / AI 对话 │
└───────────────┬───────────────────────────┬────────────────┘
│ │
│ HTTP / JSON │ 地图 JS API
│ │
┌───────▼──────────────────────────────────────┐
│ FastAPI 后端 (`app.py`) │
│ geo / ai / address-book / import / export │
└───────┬─────────────────┬────────────────────┘
│ │
│ │
┌──────────▼─────────┐ ┌──▼─────────────────────┐
│ 本地数据文件 │ │ 外部能力服务 │
│ address_book.json │ │ 高德地图 / Bosch LLM │
│ vehicle_types.json│ │ │
│ Excel 模板 │ │ │
└────────────────────┘ └────────────────────────┘
┌──────────────────────────────┐
│ 前端求解器 (`solver.js`) │
│ 当前：启发式 CVRP │
│ 后续：可切换 OR-Tools 后端 │
└──────────────────────────────┘
- Windows 10/11
- Python 3.9+（推荐 conda 环境）
- 高德开放平台账号（申请地址）
- （可选）Bosch 内网账号，用于 AI 功能
🌐 网络说明： 高德 API 需要访问外网。公司内网无需 VPN，系统自动通过 Windows 域凭据认证代理（依赖
pywin32）；已连 VPN 或家庭网络直连即可，无需额外配置。
git clone https://github.com/Zhang-Hanliang/Logistic_AI.git
cd Logistic_AI# 复制模板文件
copy config.ini.example config.ini用记事本打开 config.ini，填写以下内容：
| 配置项 | 说明 | 获取方式 |
|---|---|---|
[python] python_path |
Python 可执行文件路径 | 在 cmd 中运行 where python |
[gaode_api] js_key |
高德 JS API Key | 高德控制台 → Web端(JS API) |
[gaode_api] js_security_code |
JS API 安全密钥 | 高德控制台 → 我的Key → 数字签名 |
[gaode_api] web_service_key |
高德 Web服务 Key | 高德控制台 → Web服务 |
[bosch_llm] * |
Bosch LLM 凭证 | 联系 Bosch IT / AIGC 团队（非必填） |
双击 启动系统.bat
脚本会自动完成：
- ✅ Python 环境检查
- ✅ 依赖包安装
- ✅ 端口占用检测与释放
- ✅ 关键文件完整性检查
- ✅ 数据目录初始化
- ✅ 高德 API 连通性测试
- ✅ Bosch LLM 连通性测试
浏览器将自动打开 http://localhost:8000
pip install -r requirements.txt所有配置集中在 config.ini（从 config.ini.example 复制），不要将真实的 config.ini 提交到 Git（已加入 .gitignore）。
当前后端由 FastAPI 提供接口，前端通过 fetch 调用。下面是基于 app.py 的实际接口清单。
| 方法 | 路径 | 说明 |
|---|---|---|
POST |
/api/geo/geocode |
批量地址转经纬度 |
POST |
/api/geo/distance-matrix |
构建驾车距离/时间矩阵 |
| 方法 | 路径 | 说明 |
|---|---|---|
POST |
/api/ai/chat |
调用 Bosch LLM，支持方案解释与问答 |
GET |
/api/health |
系统健康检查，返回高德 / LLM 可用状态 |
| 方法 | 路径 | 说明 |
|---|---|---|
GET |
/api/address-book |
查询地址库，支持关键词搜索 |
POST |
/api/address-book |
新增地址库条目 |
PUT |
/api/address-book/{entry_id} |
更新地址库条目 |
DELETE |
/api/address-book/{entry_id} |
删除地址库条目 |
POST |
/api/address-book/use/{entry_id} |
标记地址已使用，更新使用次数 |
POST |
/api/address-book/batch-save |
将当前规划站点批量保存到地址库 |
| 方法 | 路径 | 说明 |
|---|---|---|
GET |
/api/import/template |
下载配送明细导入模板 |
POST |
/api/import/delivery-excel |
上传并解析配送站点 Excel |
POST |
/api/export/sites-excel |
将当前站点表导出为 Excel |
| 方法 | 路径 | 说明 |
|---|---|---|
GET |
/api/vehicle-types |
获取当前车型配置 |
GET |
/api/vehicle-types/template |
下载车型配置模板 |
POST |
/api/import/vehicle-types |
上传并导入车型配置 Excel |
| 方法 | 路径 | 说明 |
|---|---|---|
GET |
/ |
返回前端首页 |
GET |
/static/* |
返回前端静态资源 |
| 版本 | 日期 | 说明 |
|---|---|---|
| v0.5 | 2026-03 | 高德 API 网络自适应：公司内网自动 WinHTTP 域认证，VPN/直连自动降级，无需手动配置代理 |
| v0.4 | 2026-03 | 车型 Excel 导入、站点 Excel 导出、README 增补 OPL / 主算法与 AI 最佳实践说明 |
| v0.3 | 2026-03 | 新增 49t 车型、货物拆分算法、时间窗不限时选项、输入校验、结果缩略卡片、统一配置文件 |
| v0.2 | 2026-03 | 可选仓库、地图/结果/AI 三栏布局、地址库、Excel 导入 |
| v0.1 | 2026-03 | MVP 初版：FastAPI + 高德地图 + VRP 启发式求解器 |
本版本定位： 在 v0.3 MVP 的基础上，补强配置化、可维护性和后续算法升级文档，为后端精确求解器接入做准备。
功能更新：
- 支持车型配置通过 Excel 模板导入，减少手工维护默认车型参数
- 支持将前端站点一键导出为 Excel，便于数据沉淀和复盘
- 页面按钮分组重排，交互更接近实际业务操作流程
- README 增补 OPL（Open Problem List），保留后续算法升级 Prompt
- README 增补“主算法 + 二重校验 + AI 最佳实践”设计建议
当前算法结论：
- 仍以
static/js/solver.js中的前端启发式 CVRP 为主 - 已支持容量约束、货物拆分、最大工时、多车型组合、基础路径优化
- 时间窗字段已采集，但尚未进入实际求解约束
后续升级重点：
- 接入 OR-Tools 作为主求解器
- 增加规则校验器和影子求解器，形成二重校验链路
- 将 AI 从“解释助手”扩展到“输入审核 + 交互式改约束”
已实现约束：
| 约束 | 状态 | 说明 |
|---|---|---|
| 容量约束（重量 / 体积 / 托盘） | ✅ 生效 | 三维同时约束，超限自动拆分 |
| 最大工时约束 | ✅ 生效 | 行驶时间 + 服务时间 ≤ 设定工时 |
| 多车型混合组合 | ✅ 生效 | 枚举最多 15 个车型组合 |
| 最近邻路径排序 | ✅ 生效 | 每车内按距离最近贪心排序 |
| 2-opt 路线局部优化 | ✅ 生效 | 减少单车路线总里程 10~20% |
| 返仓 / 不返仓 | ✅ 生效 | 影响最后一段里程和成本 |
| 真实驾车距离矩阵 | ✅ 生效 | 高德驾车 API，非直线距离 |
| 时间窗约束 | ❌ 未生效 | 字段已收集，算法未使用 |
已知局限：
- 贪心分配不回溯，可能错过全局最优的车辆分配方案
- 各车路线独立优化，无跨车交换站点（需 LKH / OR-Tools CVRP）
- 车辆组合枚举上限 15 个，站点数 > 20 时质量下降
问题描述： 当前填写窗起/窗止对算法无影响，"不限时"勾选也只是将字段置 null，均不约束路线排序。
期望行为：
- 在路线时间推进模拟中，检查每个站点的预计到达时间是否在
[time_window_start, time_window_end]内 - 早到则等待至窗起（增加等待时间），晚到则标记该路线为
feasible: false - 无时间窗（null）或勾选"不限时"的站点不做约束
升级 Prompt：
在 solver.js 的 solveForCombo() 函数中，为每辆车的路线增加时间推进模拟：
从出发时间（config.departureTime，格式 "HH:MM"）开始，
按 route 顺序累加行驶时间（timeMatrix）和服务时间（service_duration_min），
对每个站点检查 time_window_start / time_window_end：
- 若提前到达，当前时间推进到 time_window_start（等待），不标记为不可行
- 若超出 time_window_end，将本车的 feasible 设为 false，并在 sites 结果里记录 tw_violated: true
整体方案的 feasible = 所有车辆均 feasible。
同时在结果详情里展示每个站点的预计到达时间和时间窗状态（✅准时 / ⏳等待Xmin / ❌超窗）。
问题描述： 当前求解器为前端 JS 启发式，站点数 > 20 时质量下降，无法保证最优解。
期望行为：
- 在
app.py新增POST /api/solve接口，接收 distMatrix、sites、vehicles、config - 使用 Python
ortools.constraint_solver(CP-SAT / Routing) 求解 CVRPTW（含时间窗） - 前端
solver.js的solveVRP()接口保持不变，新增config.useBackend = true开关切换
升级 Prompt：
在 app.py 中新增 POST /api/solve 接口：
接收请求体 { distMatrix, timeMatrix, sites, vehicleQuotas, config }，
使用 Google OR-Tools ortools.constraint_solver.routing_enums_pb2 求解 CVRPTW：
- 每辆车容量约束：weight / volume / pallets 三维
- 时间窗约束：time_window_start / time_window_end（null = 不限）
- 最大工时约束：maxWorkHours
- 目标：最小化总行驶距离（成本模式下加权）
返回与前端 solveVRP() 相同格式的 solutions 数组。
在 solver.js 中新增 async solveVRPBackend() 函数，
通过 fetch('/api/solve') 调用后端，结果格式与 solveVRP() 完全相同。
在 index.html 优化设置区增加"求解模式"切换：前端启发式 / 后端精确（OR-Tools）。
问题描述： 当前 2-opt 只优化单车内部路线，不同车辆之间没有协调。
升级 Prompt：
在 solver.js 的 solveForCombo() 完成各车独立 2-opt 后，
新增 crossRouteImprove() 函数：
对任意两辆车 (vi, vj) 的站点列表，尝试以下操作并检查是否降低总成本：
1. 单点转移：将 vi 的站点 s 移入 vj（需满足 vj 容量约束）
2. 两点互换：vi 的站点 s1 与 vj 的站点 s2 互换（需双方都满足容量约束）
如有改善则接受，循环直到无改善为止（最多迭代 50 次防止超时）。
升级 Prompt：
在站点表格增加"优先级"列（下拉：普通 / 优先 / 最后）。
在 solver.js greedyAssign() 中，优先级为"优先"的站点排在路线最前，
"最后"的站点排在路线最末（在 nearestNeighbor 排序前/后强制插入）。
收集时在 collectSitesFromTable() 读取 priority 字段并传入 site 对象。
对于物流计划类系统，推荐采用 “一个主算法求解 + 一个独立校验链路复核” 的架构，而不是只依赖单一求解器。
正式版建议采用：
- Google OR-Tools 作为主求解器
- 建模方向：
- HVRP：异构车型
- SDVRP：允许拆单
- VRPTW：时间窗
- 必要时扩展 PDPTW：提货/送货先后关系
适用原因：
- 工业界成熟，稳定性高
- 支持容量、时间窗、最大工时、返仓等硬约束
- 适合作为生产环境的主优化引擎
- 后续可平滑替换当前前端启发式求解器
建议增加一条与主算法相互独立的复核链路，用于识别“建模错误、数据错误、异常结果”。
可采用两层：
对主算法输出结果逐项审核：
- 是否超重 / 超体积 / 超托盘
- 是否违反时间窗
- 是否超最大工时
- 是否违反返仓设置
- 是否存在拆单后遗漏、重复配送
- 是否存在提送货顺序错误
- 是否存在不可达、异常绕路、极端偏差
使用另一套较独立的启发式算法做对照，例如：
- ALNS
- Tabu Search
- 更强的局部搜索（跨车 Relocate / Swap / Cross Exchange）
其目标不是替代主算法，而是用于：
- 对比 KPI（总里程、总成本、总工时）
- 检查主算法结果是否异常偏差
- 在主算法不可用时提供降级方案
- 主算法：OR-Tools
- 校验器：规则校验器 + 影子启发式求解器
- 告警条件示例：
- 主算法判可行，但规则校验不通过
- 影子求解器结果比主算法低成本超过 8%~15%
- 主算法结果出现极端空驶、超长单车路线、装载率异常偏低
对于本项目，最佳实践不是“AI 直接替代算法”，而是：
确定性优化器负责求解，独立校验链路负责复核，AI 负责理解、整理、解释、交互。
AI 适合插入物流计划系统，但 不建议让 AI 直接作为主优化器。 最佳实践是让 AI 作为 计划前处理 + 计划后解释 + 异常协同助手。
用于把人工输入、Excel、邮件、文本整理成标准结构数据：
- 识别站点名称、地址、联系人、电话
- 抽取重量、体积、托盘数
- 补齐缺失字段提示
- 标记明显异常值
- 地址归一化、别名合并
价值：
减少人工录入错误，提高主算法输入质量。
AI 可作为“输入审核助手”：
- 检查地址是否模糊或重复
- 检查货量是否异常
- 检查时间窗是否冲突
- 检查车型配置是否明显不合理
- 提示是否需要拆单、是否可能需要更多车辆
注意：
AI 只做提示，不直接改数据。
这是 AI 最适合的场景之一：
- 用自然语言解释为什么推荐方案 1
- 对比前 10 个方案差异
- 解释成本、里程、工时、装载率变化
- 标记风险点和建议人工关注项
价值：
让业务人员更容易理解优化结果。
当用户提出：
- “这个站点必须优先送”
- “这个客户下午才能收货”
- “这辆车今天不能跑远程”
- “长沙和武汉单独派车”
AI 可以把自然语言转成结构化约束，再交给求解器重新计算。
原则：
AI 负责把话“翻译成规则”，不是直接给最终路线。
AI 可用于：
- 总结历史调度案例
- 归纳异常原因
- 生成日报 / 周报
- 形成可搜索的运营知识库
- AI 直接输出最终路线并跳过求解器
- AI 自主修改硬约束
- AI 直接判定是否可行而不经过规则校验
- 规则引擎 / 校验器：负责硬约束判定
- 优化求解器：负责路线与车辆分配
- AI：负责输入整理、异常提示、方案解释、交互改约束
业务输入 / Excel / 地址库
↓
AI 结构化整理 + 数据审核
↓
规则校验器（必填、格式、约束预检查）
↓
主算法求解器（OR-Tools）
↓
独立规则复核 + 影子求解器对照
↓
AI 结果解释 / 风险分析 / 对话式调整
↓
人工确认 / 导出执行
- 前端启发式求解器可完成基础多车型配送规划
- 支持货物拆分、候选方案展示、地图可视化与 AI 解释
- 支持地址库、配送 Excel 导入、站点导出、车型 Excel 导入
- README 已补充 OPL、架构说明、API 清单与算法升级建议
- 高德 API 网络层自适应：公司内网 WinHTTP 域认证 → VPN/直连自动降级
- 前端启发式算法继续保留，适合作为 MVP 与交互验证
- AI 主要用于输入审核、解释、问答
- 时间窗约束正式进入求解过程
- 增加规则校验器，对输出结果做独立复核
- 补齐站点优先级、异常告警与更多业务校验
- 后端接入 OR-Tools 作为主求解器
- 增加规则校验器
- 增加影子启发式求解器做二重校验
- AI 接入“自然语言改约束 → 重新求解”流程
- 形成“主算法 + 二重校验 + AI 协同”的生产级闭环
- 支持更复杂的时间窗、优先级、提送货和多仓场景
- 具备更清晰的接口边界和稳定版本维护机制
- 接入历史订单与执行反馈
- 做滚动重规划
- 做异常预警与经验知识沉淀
config.ini含有密码和 API Key，绝对不要提交到公开仓库- 高德 API 有每日调用配额限制，测试时请避免频繁大批量地理编码
- Bosch LLM 功能仅在 Bosch 内网环境可用，外部使用时 AI 功能自动降级
- 公司内网访问高德 API 依赖
pywin32（已列入requirements.txt），首次安装请执行pip install -r requirements.txt
项目维护：@Zhang-Hanliang