我用百度地图 Skills 体系重构了物流调度系统，节省了 90% 的人力

本文记录一次将 AI Agent 接入地图能力的完整工程实践，包括踩过的坑、选型过程和最终架构。

起因：一个让人头疼的问题

我们团队在给一家同城物流公司做 AI 调度系统时，遇到了一个经典问题：

大模型会"编"地图 API。

具体表现是：让 GPT / Claude 写地图 API 调用代码，生成的代码看起来很合理，但实际运行时频繁报错------字段不存在、接口已下线、参数格式不对。

根本原因很简单：模型的训练数据有时效性，它"记住"的 API 文档可能是一两年前的版本。百度地图接口迭代频繁，字段变更、新接口上线，模型完全不知道。

我们调研了哪些方案

方案 A：手动维护 Prompt 中的 API 文档

可行，但维护成本极高。每次接口更新都要人工同步，容易遗漏，长期不可持续。

方案 B：让 AI 实时爬取文档

不稳定。文档页面结构随时变化，解析成本高，线上环境也不适合频繁外部请求。

方案 C：百度地图 Docs-MCP

官方维护的 MCP 数据源，文档与线上 API 版本同步，AI 通过标准协议实时检索。

最终选了方案 C，理由很简单：官方维护 > 自己维护。

最终技术架构

css 复制代码

┌─────────────────────────────────────┐
│              用户指令输入              │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│          AI Agent（Claude）           │
│  ┌─────────────────────────────┐    │
│  │       Docs-MCP 上下文注入    │    │  ← 实时接口文档
│  └─────────────────────────────┘    │
└──────────────┬──────────────────────┘
               │ 工具调用
┌──────────────▼──────────────────────┐
│           MAPYA SDK / CLI            │
│   地理编码 / 路线规划 / POI 检索       │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│         百度地图 REST API             │
└─────────────────────────────────────┘

三个核心组件各司其职：

组件	解决的问题
Docs-MCP	AI 调用 API 时引用过期文档，导致字段错误
MAPYA CLI / SDK	参数复杂，手动拼接成本高、容易出错
Map Agent Plan	多步骤地图操作的 Agent 编排门槛高

核心组件详解

Docs-MCP：让 AI 用上最新的接口文档

工作原理：

复制代码

传统模式：AI → 训练时记忆的文档快照 → 生成可能过期的调用代码

Docs-MCP：AI → 实时检索官方最新文档 → 生成符合当前版本的调用代码

Docs-MCP 将百度地图开放平台的接口文档、字段定义、参数规范整合为 MCP 标准数据源，AI 每次生成调用代码前，先检索当前有效版本。

工程效果：

接口迭代后，AI 的调用行为自动适配，无需人工维护 Prompt
字段废弃、参数改名等变更对 Agent 透明
消除版本漂移导致的调用错误

MAPYA CLI：自然语言驱动 API 调用

直接调用百度地图 REST API 需要熟悉大量参数细节：

bash 复制代码

# 直接调用原始 API，需要手动处理以下所有细节：
# - 坐标系转换（BD-09 / GCJ-02 / WGS-84）
# - 参数名和枚举值的正确写法
# - 签名和鉴权逻辑
# - 响应数据解析

curl "https://api.map.baidu.com/directionlite/v1/driving?\
origin=39.8656,116.3784\
&destination=39.9824,116.3121\
&coord_type=bd09ll\
&output=json\
&ak=YOUR_AK"

用 MAPYA CLI 之后：

bash 复制代码

# 描述需求即可，参数映射由工具完成
mapya route "北京南站 到 中关村 驾车"

mapya geocode "北京市海淀区中关村大街1号"

mapya poi --query "咖啡馆" --region "海淀区" --limit 10

# 坐标系转换（多系统数据源混用时必备）
mapya convert --from gcj02 --to bd09 116.3975,39.9085

Map Agent Plan：出行场景的低代码编排

对于路线规划、出行推荐等多步骤场景，Map Agent Plan 提供自然语言配置界面，自动生成 Agent 工作流，不需要手写编排代码。

配置示例：

json 复制代码

{
  "agent_name": "出行助手",
  "capabilities": ["route_planning", "poi_search", "transport_compare"],
  "behavior": {
    "route_strategy": "prefer_public_transit",
    "fallback": "若公共交通不可达，提供驾车方案"
  },
  "output_format": {
    "include_duration": true,
    "include_cost": true
  }
}

完整集成代码：物流调度 Agent

python 复制代码

from fastapi import FastAPI
from mapya import Client
from anthropic import Anthropic
import os

app = FastAPI()
map_client = Client(ak=os.environ["BAIDU_MAP_AK"])
ai_client = Anthropic()

@app.post("/dispatch")
async def create_dispatch(orders: list[dict]):
    # Step 1：批量地理编码
    addresses = [o["address"] for o in orders]
    geocoded = map_client.batch_geocode(addresses)

    # Step 2：AI Agent 生成调度方案（注入 Docs-MCP 上下文）
    response = ai_client.messages.create(
        model="claude-opus-4-7",
        max_tokens=2048,
        system=load_docs_mcp_context(),  # 实时地图文档上下文
        messages=[{
            "role": "user",
            "content": f"为以下 {len(orders)} 个收货地址生成 5 辆车的最优调度方案，最小化总行驶里程：\n{geocoded}"
        }]
    )

    # Step 3：解析方案并规划每辆车路线
    plan = parse_dispatch_plan(response.content)
    routes = [map_client.route_multi(stops) for stops in plan.vehicle_stops]

    return {"plan": plan, "routes": routes}

踩坑记录

坑 1：坐标系混用导致 500m 偏移

从第三方 ERP 系统导入的地址数据，经纬度是 GCJ-02（高德坐标系），直接传给百度地图 API 会产生约 500m 定位偏差。

修复方案： 数据入库前统一转换，一劳永逸。

python 复制代码

from mapya.utils import convert_coords

def normalize_address(raw_address: dict) -> dict:
    if raw_address.get("coord_system") == "gcj02":
        raw_address["lng"], raw_address["lat"] = convert_coords(
            raw_address["lng"], raw_address["lat"],
            from_sys="gcj02", to_sys="bd09"
        )
    return raw_address

坑 2：批量地理编码触发限流

一次性提交 500 个地址，触发了 QPS 限制，部分请求失败且无明确报错提示。

修复方案： 分批提交 + 指数退避重试。

python 复制代码

import time

def batch_geocode_safe(addresses: list[str], batch_size: int = 50) -> list:
    results = []
    for i in range(0, len(addresses), batch_size):
        batch = addresses[i:i + batch_size]
        for attempt in range(3):
            try:
                result = map_client.batch_geocode(batch)
                results.extend(result)
                break
            except RateLimitError:
                time.sleep(2 ** attempt)
    return results

坑 3：Agent 调度方案输出不稳定

相同输入，Agent 有时输出 5 辆车方案，有时输出 4 辆车方案，结构也不一致。

修复方案： Prompt 中强制约束输出格式，加 JSON Schema 校验。

python 复制代码

DISPATCH_SCHEMA = {
    "type": "object",
    "properties": {
        "vehicles": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "vehicle_id": {"type": "string"},
                    "stops": {"type": "array", "items": {"type": "string"}}
                },
                "required": ["vehicle_id", "stops"]
            }
        }
    },
    "required": ["vehicles"]
}

# 在 Prompt 中明确指定输出格式要求
system_prompt = f"""
你是一个物流调度助手。
输出必须严格符合以下 JSON Schema，不允许有额外字段：
{json.dumps(DISPATCH_SCHEMA, ensure_ascii=False)}
"""

上线数据

接入 Skills 体系两周后的效果对比：

指标	改造前	改造后
日均调度耗时	3.5 小时	18 分钟
调度员人力	2 人	0.5 人（仅审核）
路线总里程	基准值	降低约 12%
API 调用错误率	约 8%	约 0.3%

API 调用错误率的大幅下降直接来自 Docs-MCP 的接入，这是最立竿见影的改善。

选型建议

markdown 复制代码

遇到 AI 生成地图 API 代码频繁报错？
    → 先接 Docs-MCP，这是最高优先级

需要快速验证业务逻辑？
    → MAPYA CLI，分钟级验证，不用啃文档

要做出行类 AI 产品，不想写编排代码？
    → Map Agent Plan，低代码配置

做企业级物流 / 调度系统？
    → Skills 完整体系 + 人工审核节点（别让 Agent 全自动执行）

小结

这次实践最大的收获是：AI 能力 × 基础设施质量 = 实际落地效果。

模型本身再强，如果调用的工具数据不准确、接口不稳定，最终结果依然会差。Docs-MCP 的价值不在于它有多"先进"，而在于它让 AI 调用地图 API 这件事变得可靠。

可靠，才是工程落地的第一要求。

Tags： AI Agent MCP 百度地图 工程实践 物流调度 LBS 踩坑记录 大模型落地 MAPYA Python