6.6 KiB
6.6 KiB
外部API集成文档
概述
本系统集成了多个外部API服务，用于获取股票数据和进行AI分析：
- Tushare API: 中国股票财务数据和市场数据
- Yahoo Finance API: 全球股票数据（美国、香港、日本等）
- Google Gemini API: AI分析和内容生成
架构设计
数据源管理器 (DataSourceManager)
- 统一管理所有数据源
- 支持数据源切换和故障转移
- 提供健康检查和状态监控
外部API服务 (ExternalAPIService)
- 提供统一的API接口
- 处理错误和重试机制
- 支持配置动态更新
支持的数据源
1. Tushare API
- 用途: 中国股票数据（A股、港股通等）
- 数据类型: 财务数据、市场数据、基本信息
- 配置要求: 需要Tushare API Token
- 限制: 有调用频率限制，需要付费账户获取完整数据
配置示例
{
"tushare": {
"enabled": True,
"api_key": "your_tushare_token",
"base_url": "http://api.tushare.pro",
"timeout": 30,
"max_retries": 3,
"retry_delay": 1
}
}
2. Yahoo Finance API
- 用途: 全球股票数据
- 数据类型: 财务数据、市场数据、基本信息
- 配置要求: 无需API密钥
- 限制: 有调用频率限制，可能被反爬虫机制阻止
配置示例
{
"yahoo": {
"enabled": True,
"base_url": "https://query1.finance.yahoo.com",
"timeout": 30,
"max_retries": 3,
"retry_delay": 1
}
}
3. Google Gemini API
- 用途: AI分析和内容生成
- 功能: 业务分析、基本面分析、投资建议等
- 配置要求: 需要Google Cloud API密钥
- 限制: 有调用频率和配额限制
配置示例
{
"gemini": {
"enabled": True,
"api_key": "your_gemini_api_key",
"model": "gemini-pro",
"timeout": 60,
"max_retries": 3,
"retry_delay": 2,
"temperature": 0.7,
"max_output_tokens": 8192
}
}
数据源切换逻辑
市场映射
系统根据股票市场自动选择合适的数据源：
market_mapping = {
"china": "tushare", # 中国A股使用Tushare
"中国": "tushare",
"hongkong": "yahoo", # 香港股票使用Yahoo Finance
"香港": "yahoo",
"usa": "yahoo", # 美国股票使用Yahoo Finance
"美国": "yahoo",
"japan": "yahoo", # 日本股票使用Yahoo Finance
"日本": "yahoo"
}
故障转移
当主要数据源不可用时，系统会自动切换到备用数据源：
fallback_sources = {
"tushare": ["yahoo"], # Tushare失败时使用Yahoo
"yahoo": ["tushare"] # Yahoo失败时使用Tushare
}
错误处理和重试机制
错误类型
DataSourceError: 数据源相关错误AIAnalysisError: AI分析相关错误AuthenticationError: 认证失败RateLimitError: 调用频率超限APIError: 通用API错误
重试策略
- 指数退避: 重试间隔逐渐增加
- 最大重试次数: 默认3次
- 超时处理: 每个请求都有超时限制
- 错误分类: 不同错误类型采用不同的重试策略
API使用示例
1. 获取财务数据
from app.services.external_api_service import get_external_api_service
service = get_external_api_service()
# 获取平安银行财务数据
financial_data = await service.get_financial_data("000001", "中国")
print(f"数据源: {financial_data.data_source}")
print(f"总资产: {financial_data.balance_sheet.get('total_assets')}")
2. 验证股票代码
# 验证股票代码是否有效
validation = await service.validate_stock_symbol("AAPL", "美国")
if validation.is_valid:
print(f"公司名称: {validation.company_name}")
3. AI分析
# 进行业务信息分析
analysis = await service.analyze_business_info(
"000001", "中国", financial_data.dict()
)
print(f"分析内容: {analysis.content['company_overview']}")
4. 检查服务状态
# 检查所有外部服务状态
status = await service.check_all_services_status()
print(f"整体状态: {status.overall_status}")
for source in status.sources:
print(f"{source.name}: {'可用' if source.is_available else '不可用'}")
配置管理
环境变量
在.env文件中配置API密钥：
# Tushare API Token
TUSHARE_TOKEN=your_tushare_token_here
# Gemini API Key
GEMINI_API_KEY=your_gemini_api_key_here
动态配置更新
# 更新配置
new_config = {
"data_sources": {
"tushare": {
"enabled": True,
"api_key": "new_token"
}
}
}
service.update_configuration(new_config)
测试和调试
运行测试脚本
cd backend
python test_external_apis.py
测试单个数据源
# 测试Tushare连接
result = await service.test_data_source_connection("tushare", {
"api_key": "your_token",
"base_url": "http://api.tushare.pro"
})
print(f"连接成功: {result['success']}")
测试AI服务
# 测试Gemini连接
result = await service.test_ai_service_connection("gemini", {
"api_key": "your_api_key"
})
print(f"连接成功: {result['success']}")
性能优化
缓存策略
- 财务数据缓存1小时
- 市场数据缓存5分钟
- AI分析结果缓存24小时
并发控制
- 限制同时进行的API调用数量
- 使用连接池管理HTTP连接
- 实现请求队列避免频率限制
监控和日志
- 记录所有API调用和响应时间
- 监控错误率和成功率
- 设置告警机制
故障排除
常见问题
-
Tushare API调用失败
- 检查API Token是否正确
- 确认账户是否有足够的积分
- 检查网络连接
-
Gemini API调用失败
- 检查API Key是否有效
- 确认配额是否充足
- 检查请求格式是否正确
-
Yahoo Finance被限制
- 降低请求频率
- 使用代理服务器
- 切换到其他数据源
调试技巧
- 启用详细日志记录
- 使用测试脚本验证配置
- 检查网络连接和防火墙设置
- 监控API调用的响应时间和错误率
扩展性
添加新的数据源
- 继承
DataFetcher基类 - 实现必要的方法
- 在
DataFetcherFactory中注册 - 更新配置文件
添加新的AI服务
- 创建新的分析器类
- 实现统一的接口
- 在
AIAnalyzerFactory中注册 - 更新配置管理
安全考虑
- API密钥加密存储
- 使用HTTPS进行所有外部调用
- 实现访问控制和权限管理
- 定期轮换API密钥
- 监控异常访问模式