高德地址解析服务

高德地址解析サービス

Claude AI と高德地図 MCP に基づいたインテリジェント住所解析サービスです。強力な住所解析、ジオコーディング、位置情報クエリ機能を提供します。

🚀 機能特性

• インテリジェント住所解析: Claude AI を使用して自然言語の住所クエリを理解します
• 高德地図統合: MCP プロトコルを通じて高德地図 API を統合します
• 複数のクエリ方法: 住所から座標への変換、座標から住所への変換、POI 検索などをサポートします
• 複数ラウンドのツール呼び出し: 複雑なマルチラウンドツール呼び出しをサポートし、連続的なタスクを完了できます
• 複数の LLM サポート: Claude や OpenAI などの大規模言語モデルをサポートします
• RESTful API: 完全な HTTP API インターフェースを提供します
• 非同期処理: 高性能非同期アーキテクチャで並行リクエストをサポートします
• ヘルスモニタリング: 充実したヘルスチェックと監視メカニズム
• エラーハンドリング: 充実した例外処理とエラー復旧メカニズム

📋 システム要件

• Python 3.10 以上
• Node.js 16 以上（高德 MCP サーバー用）
• 高德地図 API キー
• Claude API キー

🛠️ インストールと設定

1. プロジェクトをクローン

git clone <repository-url>
cd address-parser-service

2. Python 環境を作成

方法 1: pip を使用（推奨）

# 创建虚拟环境
python -m venv address-parser-env

# 激活虚拟环境
# Windows:
address-parser-env\Scripts\activate
# macOS/Linux:
source address-parser-env/bin/activate

# 安装依赖
pip install -r requirements.txt

方法 2: conda を使用

# 方法1: 使用environment.yml文件（推荐）
conda env create -f environment.yml
conda activate address-parser

# 方法2: 手动创建环境
conda create -n address-parser python=3.11
conda activate address-parser

# 安装依赖
pip install -r requirements.txt

# 或者使用conda安装部分依赖
conda install fastapi uvicorn pydantic
pip install mcp anthropic structlog pydantic-settings

3. 環境変数を設定

環境変数テンプレートをコピーします：

cp .env.example .env

.env ファイルを編集して API キーを入力します：

# Claude API配置
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# 高德地图API配置  
AMAP_MAPS_API_KEY=your_amap_api_key_here

# 其他配置保持默认即可

4. API キーを取得

高德地図 API キー

1. 高德オープンプラットフォームにアクセス
2. アカウントを登録してアプリケーションを作成
3. ウェブサービス API キーを取得

Claude API キー

1. Anthropic Consoleにアクセス
2. アカウントを作成して API キーを取得

🚀 クイックスタート

方法 1: サンプルスクリプトを使用

# 激活环境（如果使用虚拟环境）
# pip环境:
source address-parser-env/bin/activate  # macOS/Linux
# 或
address-parser-env\Scripts\activate     # Windows

# conda环境:
conda activate address-parser

# 运行基础使用示例
python examples/basic_usage.py

方法 2: API サービスを起動

# 启动FastAPI服务
python api/main.py

サービス起動後、以下にアクセスしてください：

• API ドキュメント: http://localhost:8000/docs
• ヘルスチェック: http://localhost:8000/api/v1/health

方法 3: MCP クライアントを直接使用

import asyncio
from src.mcp_client import AmapMCPClient, ClaudeHandler

async def main():
    # 创建MCP客户端
    async with AmapMCPClient() as amap_client:
        # 创建Claude处理器
        claude_handler = ClaudeHandler(amap_client)
        
        # 处理查询
        result = await claude_handler.process_query(
            "请帮我解析这个地址：北京市朝阳区三里屯太古里"
        )
        
        print(result["final_answer"])

asyncio.run(main())

📖 API ドキュメント

住所解析インターフェース

POST /api/v1/address/parse

リクエストボディ：

{
    "address": "北京市朝阳区三里屯太古里",
    "context": {
        "city": "北京",
        "preferences": "详细地址信息"
    },
    "system_prompt": "请提供详细的地址解析结果"
}

レスポンス：

{
    "success": true,
    "request_id": "1642123456789_abc12345",
    "data": {
        "formatted_address": "北京市朝阳区三里屯太古里",
        "location": "116.397428,39.90923",
        "province": "北京市",
        "city": "北京市",
        "district": "朝阳区"
    },
    "response": "根据您提供的地址，我已经成功解析出详细信息...",
    "tool_calls": [...],
    "processing_time": 2.5
}

ヘルスチェックインターフェース

GET /api/v1/health

レスポンス：

{
    "status": "healthy",
    "mcp_connected": true,
    "claude_available": true,
    "tools_count": 5,
    "uptime": 3600.0
}

ツールリストインターフェース

GET /api/v1/tools

レスポンス：

{
    "success": true,
    "tools": [
        {
            "name": "geocode",
            "description": "地理编码，将地址转换为坐标",
            "input_schema": {...}
        }
    ],
    "count": 1
}

🔧 高度な設定

MCP サーバー管理

組み込みのサーバー管理スクリプトを使用します：

# 启动高德MCP服务器
python scripts/start_amap_server.py start

# 停止服务器
python scripts/start_amap_server.py stop

# 重启服务器
python scripts/start_amap_server.py restart

# 查看状态
python scripts/start_amap_server.py status

# 监控模式（自动重启）
python scripts/start_amap_server.py monitor

設定パラメータ説明

パラメータ	デフォルト値	説明
LLM_PROVIDER	claude	大規模言語モデルプロバイダー（claude または openai）
ANTHROPIC_API_KEY	必須	Claude API キー
CLAUDE_MODEL	claude-3-7-sonnet-20250219	Claude モデルバージョン
CLAUDE_MAX_TOKENS	1000	Claude 最大出力トークン数
ENABLE_TOKEN_EFFICIENT_TOOLS	false	Claude トークン効率的ツール呼び出しを有効にするかどうか
TOOL_MAX_ITERATIONS	10	ツール呼び出し最大反復回数
OPENAI_API_KEY	オプション	OpenAI API キー
OPENAI_MODEL	gpt-4	OpenAI モデルバージョン
OPENAI_MAX_TOKENS	1000	OpenAI 最大出力トークン数
MCP_SERVER_TIMEOUT	30	MCP サーバータイムアウト（秒）
MCP_RETRY_COUNT	3	リトライ回数
MCP_RETRY_DELAY	1.0	リトライ遅延（秒）
LOG_LEVEL	INFO	ログレベル
API_HOST	127.0.0.1	API サービスホスト
API_PORT	8000	API サービスポート

🧪 テスト

ユニットテストを実行

# 运行所有测试
pytest tests/

# 运行特定测试文件
pytest tests/test_mcp_client.py -v

# 运行集成测试（需要API密钥）
pytest tests/ -m integration

# 运行多轮工具调用测试
python tests/run_tests.py --claude    # 仅运行Claude测试
python tests/run_tests.py --openai    # 仅运行OpenAI测试
python tests/run_tests.py --complex   # 仅运行复杂多轮测试
python tests/run_tests.py --all       # 运行所有测试

テストカバレッジ

# 生成测试覆盖率报告
pytest --cov=src tests/

📁 プロジェクト構造

address-parser-service/
├── src/                    # 核心源代码
│   ├── mcp_client/        # MCP客户端模块
│   │   ├── amap_client.py # 高德MCP客户端
│   │   ├── claude_handler.py # Claude处理器
│   │   └── openai_handler.py # OpenAI处理器
│   ├── core/              # 核心模块
│   │   ├── config.py      # 配置管理
│   │   ├── logger.py      # 日志配置
│   │   └── exceptions.py  # 异常定义
│   └── utils/             # 工具函数
│       └── helpers.py     # 辅助函数
├── api/                   # API服务模块
│   ├── main.py           # FastAPI主应用
│   ├── routes/           # API路由
│   └── schemas/          # 数据模型
├── tests/                # 测试代码
│   ├── test_mcp_client.py # MCP客户端测试
│   ├── test_multi_tool_calls.py # 多轮工具调用测试
│   ├── test_complex_multi_tool_calls.py # 复杂多轮工具调用测试
│   └── test_openai_multi_tool_calls.py # OpenAI多轮工具调用测试
├── scripts/              # 脚本文件
├── examples/             # 使用示例
├── logs/                 # 日志文件
├── requirements.txt      # Python依赖
├── .env.example         # 环境变量模板
└── README.md            # 项目文档

🔍 使用例

基本的な住所解析

# 地址转坐标
query = "北京市朝阳区三里屯太古里"
result = await claude_handler.process_query(query)

# 坐标转地址
query = "116.397428,39.90923 这个坐标对应的地址是什么？"
result = await claude_handler.process_query(query)

# POI搜索
query = "帮我查找北京大学的地理坐标"
result = await claude_handler.process_query(query)

マルチラウンドツール呼び出しの例

# 多轮次工具调用示例 - 天气比较
query = "查询一下北京市和上海市今天的天气，并告诉我在这两个城市中，哪个城市更适合户外活动？"
result = await claude_handler.process_query(query)

# 复杂多轮工具调用 - 旅行规划
query = """请帮我规划一次从北京到上海的旅行路线：
1. 首先查询北京和上海的天气情况
2. 然后查询北京市区到上海市区的驾车路线
3. 再查询途经城市杭州市的著名景点
4. 最后给我一个综合考虑天气和路线的详细旅行计划建议
"""
result = await claude_handler.process_query(query)

バッチ処理

curl -X POST "http://localhost:8000/api/v1/address/batch" \
     -H "Content-Type: application/json" \
     -d '[
       {"address": "北京市朝阳区三里屯"},
       {"address": "上海市浦东新区陆家嘴"},
       {"address": "广州市天河区珠江新城"}
     ]'

🐛 トラブルシューティング

よくある質問

1. MCP 接続失敗

   • AMAP_MAPS_API_KEY が正しく設定されているか確認
   • ネットワーク接続が正常か確認
   • ログファイルを参照して詳細なエラー情報を取得

2. Claude API 呼び出し失敗

   • ANTHROPIC_API_KEY が正しく設定されているか確認
   • API キーに十分なクォータがあるか確認
   • ネットワーク接続を確認

3. ツール呼び出しタイムアウト

   • MCP_SERVER_TIMEOUT 設定値を増加させる
   • 高德地図 API サービスのステータスを確認

4. 依存パッケージの競合

   • 仮想環境を使用して依存関係を分離：python -m venv address-parser-env
   • または conda 環境を使用：conda create -n address-parser python=3.11
   • pip キャッシュをクリア：pip cache purge

5. conda 環境の問題

   • 正しい環境がアクティブ化されていることを確認：conda activate address-parser
   • 依存関係の競合が発生した場合、混合インストールを試してみてください：

     conda install fastapi uvicorn pydantic
     pip install mcp anthropic structlog pydantic-settings
     

ログの表示

# 查看应用日志
tail -f logs/app.log

# 查看API访问日志
tail -f logs/api.log

🤝 貢献ガイド

1. プロジェクトをフォーク
2. 機能ブランチを作成 (git checkout -b feature/AmazingFeature)
3. 変更をコミット (git commit -m 'Add some AmazingFeature')
4. ブランチにプッシュ (git push origin feature/AmazingFeature)
5. プルリクエストを開く

📄 ライセンス

本プロジェクトは MIT ライセンスの下で公開されています - 詳細は LICENSE ファイルを参照してください。

🙏 謝辞

• Anthropic - Claude AI API
• 高德地図 - 地図サービス API
• Model Context Protocol - MCP プロトコル
• FastAPI - ウェブフレームワーク

📞 サポート

問題が発生した場合や提案がある場合は、以下を参照してください：

1. FAQを確認
2. 既存の Issues を検索
3. 新しい Issue を作成

---

注意: 本プロジェクトは学習および研究目的でのみ使用してください。関連する API サービスの利用規約を遵守してください。