211 lines
5.7 KiB
Markdown
211 lines
5.7 KiB
Markdown
# 🔄 Google ADK 迁移指南
|
||
|
||
## 📋 迁移概述
|
||
|
||
本指南将帮助您将项目从当前的 OpenRouter/OpenAI Swarm 架构迁移到 Google Agent Development Kit (ADK)。
|
||
|
||
## 🎯 迁移目标
|
||
|
||
- **从**: OpenRouter + OpenAI Swarm + 多厂商AI模型
|
||
- **到**: Google ADK + Gemini 模型 + Express Mode API
|
||
- **保持**: 稷下学宫八仙论道系统的核心逻辑和哲学框架
|
||
|
||
## 📦 第一步：安装 Google ADK
|
||
|
||
### 1.1 更新 Python 环境要求
|
||
|
||
<mcreference link="https://google.github.io/adk-docs/get-started/quickstart/" index="1">1</mcreference>
|
||
|
||
```bash
|
||
# 确保 Python 3.9+ 版本
|
||
python --version
|
||
|
||
# 创建新的虚拟环境（推荐）
|
||
python -m venv .venv
|
||
|
||
# 激活虚拟环境
|
||
# macOS/Linux:
|
||
source .venv/bin/activate
|
||
# Windows CMD:
|
||
# .venv\Scripts\activate.bat
|
||
# Windows PowerShell:
|
||
# .venv\Scripts\Activate.ps1
|
||
```
|
||
|
||
### 1.2 安装 Google ADK
|
||
|
||
<mcreference link="https://pypi.org/project/google-adk/" index="2">2</mcreference>
|
||
|
||
```bash
|
||
# 安装稳定版本
|
||
pip install google-adk
|
||
|
||
# 或安装最新开发版本
|
||
pip install git+https://github.com/google/adk-python.git@main
|
||
```
|
||
|
||
## 🔑 第二步：配置 API 密钥
|
||
|
||
### 2.1 获取 Gemini API 密钥
|
||
|
||
<mcreference link="https://google.github.io/adk-docs/get-started/quickstart/" index="1">1</mcreference>
|
||
|
||
您有三种选择：
|
||
|
||
**选项A: Google AI Studio (推荐开发环境)**
|
||
- 前往 [Google AI Studio](https://aistudio.google.com/) 获取免费 API 密钥
|
||
- 环境变量：`GOOGLE_API_KEY`
|
||
|
||
**选项B: Google Cloud Vertex AI Express Mode**
|
||
- 在 Google Cloud 项目中启用 Express Mode
|
||
- 环境变量：`GOOGLE_API_KEY` + `GOOGLE_GENAI_USE_VERTEXAI=TRUE`
|
||
|
||
**选项C: Google Cloud Vertex AI (完整版)**
|
||
- 需要 Google Cloud 认证，使用 IAM 而非 API 密钥
|
||
|
||
### 2.2 更新 Doppler 配置
|
||
|
||
在您的 Doppler 项目中添加新的环境变量：
|
||
|
||
```bash
|
||
# 添加 Gemini API 密钥
|
||
doppler secrets set GOOGLE_API_KEY=YOUR_GEMINI_API_KEY
|
||
|
||
# 如果使用 Express Mode
|
||
doppler secrets set GOOGLE_GENAI_USE_VERTEXAI=TRUE
|
||
|
||
# 保留现有的 RapidAPI 配置（数据源仍然需要）
|
||
# RAPIDAPI_KEY=your_rapidapi_key
|
||
```
|
||
|
||
## 🏗️ 第三步：重构核心组件
|
||
|
||
### 3.1 更新配置管理
|
||
|
||
需要更新 `config/settings.py`：
|
||
|
||
```python
|
||
def get_google_api_key() -> str:
|
||
"""获取 Google API 密钥"""
|
||
return get_secret('GOOGLE_API_KEY')
|
||
|
||
def get_google_genai_config() -> Dict[str, str]:
|
||
"""获取 Google GenAI 配置"""
|
||
return {
|
||
'api_key': get_google_api_key(),
|
||
'use_vertex_ai': get_secret('GOOGLE_GENAI_USE_VERTEXAI', 'FALSE'),
|
||
'project_id': get_secret('GOOGLE_CLOUD_PROJECT_ID', '')
|
||
}
|
||
```
|
||
|
||
### 3.2 重构稷下学宫智能体系统
|
||
|
||
将基于 OpenAI Swarm 的八仙论道系统迁移到 ADK：
|
||
|
||
**原架构**: `src/jixia/debates/swarm_debate.py` (OpenAI Swarm)
|
||
**新架构**: `src/jixia/debates/adk_debate.py` (Google ADK)
|
||
|
||
### 3.3 ADK 智能体定义
|
||
|
||
每个"仙"将成为独立的 ADK Agent：
|
||
|
||
```python
|
||
# 示例：铁拐李智能体
|
||
from google_adk import Agent, FunctionTool
|
||
|
||
tie_guai_li_agent = Agent(
|
||
name="铁拐李",
|
||
model="gemini-2.0-flash-exp",
|
||
description="逆向思维专家，善于从困境中寻找突破",
|
||
system_message="你是铁拐李，八仙中的逆向思维专家...",
|
||
tools=[
|
||
FunctionTool(name="逆向分析", function=reverse_analysis),
|
||
FunctionTool(name="困境突破", function=breakthrough_analysis)
|
||
]
|
||
)
|
||
```
|
||
|
||
## 🔄 第四步：分阶段迁移策略
|
||
|
||
### 阶段1：基础设施迁移 (第1-2天)
|
||
- [ ] 安装 Google ADK
|
||
- [ ] 配置 API 密钥
|
||
- [ ] 创建简单的测试智能体
|
||
- [ ] 验证基本功能
|
||
|
||
### 阶段2：核心逻辑迁移 (第3-5天)
|
||
- [ ] 重构八仙智能体定义
|
||
- [ ] 迁移论道逻辑
|
||
- [ ] 保持数据源 (RapidAPI) 集成
|
||
- [ ] 测试单个智能体功能
|
||
|
||
### 阶段3：系统集成 (第6-7天)
|
||
- [ ] 多智能体协作
|
||
- [ ] Streamlit 界面适配
|
||
- [ ] 完整功能测试
|
||
- [ ] 性能优化
|
||
|
||
### 阶段4：部署和监控 (第8天)
|
||
- [ ] 部署配置
|
||
- [ ] 监控设置
|
||
- [ ] 文档更新
|
||
|
||
## 📊 功能对照表
|
||
|
||
| 当前 (OpenRouter/Swarm) | 迁移后 (Google ADK) | 状态 |
|
||
|-------------------------|-------------------|------|
|
||
| OpenAI Swarm 多智能体 | ADK Multi-Agent | ✅ 等价替换 |
|
||
| OpenRouter 模型池 | Gemini 模型系列 | ✅ 统一模型 |
|
||
| 自定义 Tool 系统 | ADK FunctionTool | ✅ 等价替换 |
|
||
| 论道逻辑 | ADK Agent协作 | ✅ 保持逻辑 |
|
||
| RapidAPI 数据源 | 保持不变 | ✅ 无需改动 |
|
||
| Streamlit 界面 | ADK Dev UI + Streamlit | ✅ 双界面 |
|
||
|
||
## 🎛️ 开发工具对比
|
||
|
||
### 当前工具
|
||
- OpenRouter API 测试
|
||
- 自定义调试脚本
|
||
- Streamlit 界面
|
||
|
||
### ADK 工具
|
||
<mcreference link="https://google.github.io/adk-docs/get-started/quickstart/" index="1">1</mcreference>
|
||
|
||
```bash
|
||
# ADK 开发界面 (推荐)
|
||
adk web
|
||
|
||
# 命令行运行
|
||
adk run multi_tool_agent
|
||
|
||
# API 服务器模式
|
||
adk api_server
|
||
```
|
||
|
||
## 🚨 注意事项
|
||
|
||
### 保留的组件
|
||
- **RapidAPI 数据源**: 继续使用，无需更改
|
||
- **MongoDB 数据库**: 继续使用
|
||
- **Doppler 配置管理**: 继续使用，仅添加新密钥
|
||
- **稷下学宫哲学框架**: 完全保持
|
||
|
||
### 移除的组件
|
||
- OpenAI Swarm 依赖
|
||
- OpenRouter API 调用
|
||
- 多厂商 API 密钥管理
|
||
|
||
### 新增优势
|
||
- **统一的模型生态**: 专注 Gemini 系列
|
||
- **更强的 Google 服务集成**: Search、Cloud 等
|
||
- **官方支持的框架**: 长期维护保证
|
||
- **更好的开发工具**: ADK Dev UI
|
||
|
||
## 📝 下一步行动
|
||
|
||
1. **立即开始**: 运行第一步的环境配置
|
||
2. **获取 API 密钥**: 访问 Google AI Studio
|
||
3. **阅读 ADK 文档**: [官方文档](https://google.github.io/adk-docs/)
|
||
4. **测试简单智能体**: 验证基本功能
|
||
|
||
准备好开始迁移了吗？我可以帮您逐步执行每个阶段！ |