Skip to content

API_INTEGRATION_GUIDE.md

Latest commit

 

History

History
322 lines (238 loc) · 5.96 KB

API_INTEGRATION_GUIDE.md

File metadata and controls

322 lines (238 loc) · 5.96 KB
Raw

TradingAgents API 整合指南

本指南説明如何整合 TradingAgents 核心功能到 API 服務中。

🔧 系統要求

基本要求

  • Python 3.10+
  • Redis 6.0+
  • Node.js 16+ (僅 WebSocket 測試需要)

推薦配置

  • 8GB+ RAM
  • 4+ CPU 核心
  • 20GB+ 可用磁碟空間

📦 安裝步驟

1. 克隆和設置專案

# 克隆 API 專案
git clone [your-repo-url] trading-agents-api
cd trading-agents-api

# 克隆 TradingAgents 核心
git clone https://github.com/TauricResearch/TradingAgents.git ../TradingAgents

# 安裝依賴
pip install -r requirements.txt

2. 整合 TradingAgents 核心

# 方法 1: 使用符號連結 (推薦)
python scripts/copy_tradingagents.py ../TradingAgents . --symlink --verify

# 方法 2: 直接複製
python scripts/copy_tradingagents.py ../TradingAgents . --verify

3. 配置環境

# 複製環境配置
cp .env.example .env

# 編輯配置檔案
nano .env

必要的環境變數：

# API 密鑰
OPENAI_API_KEY=your-openai-api-key
FINNHUB_API_KEY=your-finnhub-api-key

# Redis 配置
REDIS_HOST=localhost
REDIS_PORT=6379

# 應用配置
APP_ENV=development
DEBUG=True

4. 啟動服務

# 啟動 Redis
redis-server

# 啟動 Celery Worker
celery -A tasks.celery_app worker --loglevel=info

# 啟動 API 服務
uvicorn api.main:app --reload --host 0.0.0.0 --port 8000

🧪 測試整合

運行整合測試

# 完整測試套件
python scripts/test_integration.py

# 測試特定組件
python -m pytest tests/test_trading_service.py -v

手動測試

# 健康檢查
curl http://localhost:8000/health

# 測試分析 API (需要認證)
curl -X POST "http://localhost:8000/api/v1/analysis" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "ticker": "AAPL",
    "date": "2024-01-15",
    "config": {
      "max_debate_rounds": 2,
      "online_tools": true
    }
  }'

🏗️ 架構概覽

核心組件

  1. TradingAgentsWrapper (core/trading_agents_wrapper.py)

    • 封裝原始 TradingAgents 功能
    • 提供異步接口
    • 管理配置和生命週期

  2. AgentsManager (core/agents_manager.py)

    • 管理所有代理狀態
    • 追蹤任務進度
    • 提供監控數據

  3. TradingService (api/services/trading_service.py)

    • 服務層封裝
    • 與 Celery 任務系統整合
    • 提供 API 接口

  4. Celery Tasks (tasks/trading_tasks.py)

    • 異步任務處理
    • 長時間運行的分析工作
    • 進度追蹤和錯誤處理

數據流

API Request → TradingService → Celery Task → TradingAgentsWrapper → Original TradingAgents
     ↓              ↓              ↓                ↓                      ↓
WebSocket Push ← Progress Update ← Task Status ← Agent Status ← Analysis Progress

📋 API 使用指南

認證

from api.dependencies import create_access_token

# 創建測試 Token
token = create_access_token({
    "sub": "test_user",
    "user_id": "test_123"
})

headers = {"Authorization": f"Bearer {token}"}

提交分析任務

import requests

response = requests.post(
    "http://localhost:8000/api/v1/analysis",
    json={
        "ticker": "NVDA",
        "date": "2024-01-15",
        "config": {
            "max_debate_rounds": 2,
            "online_tools": True
        }
    },
    headers=headers
)

task_id = response.json()["task_id"]

監控任務進度

# 查詢任務狀態
status_response = requests.get(
    f"http://localhost:8000/api/v1/analysis/{task_id}",
    headers=headers
)

print(status_response.json())

WebSocket 實時更新

const ws = new WebSocket(`ws://localhost:8000/ws/analysis/${task_id}?token=${token}`);

ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    console.log('Progress:', data.data.progress);
    console.log('Step:', data.data.step);
};

🔍 故障排除

常見問題

  1. TradingAgents 導入失敗

    # 檢查符號連結
ls -la tradingagents/

# 重新整合
python scripts/copy_tradingagents.py ../TradingAgents . --symlink --verify

  2. Redis 連接失敗

    # 檢查 Redis 狀態
redis-cli ping

# 重啟 Redis
redis-server --daemonize yes

  3. Celery Worker 無法啟動

    # 檢查 Celery 配置
celery -A tasks.celery_app inspect stats

# 重啟 Worker
celery -A tasks.celery_app worker --loglevel=info

  4. API 密鑰錯誤

    # 檢查環境變數
echo $OPENAI_API_KEY
echo $FINNHUB_API_KEY

# 重新載入環境
source .env

日誌檢查

# API 日誌
tail -f logs/app.log

# Celery 日誌
tail -f logs/celery_worker.log

# Redis 日誌
redis-cli monitor

🚀 生產部署

Docker 部署

# 使用 Docker Compose
docker-compose up -d

# 檢查服務狀態
docker-compose ps

性能優化

  1. 增加 Worker 數量

    celery -A tasks.celery_app worker --concurrency=4

  2. 啟用 Redis 持久化

    redis-server --appendonly yes

  3. 配置負載均衡

    • 使用 Nginx 進行反向代理
    • 配置多個 API 實例

監控設置

  1. Prometheus 指標

    # 啟用指標收集
export ENABLE_METRICS=true

# 訪問指標
curl http://localhost:8000/metrics

  2. Flower 監控

    # 啟動 Flower
celery -A tasks.celery_app flower

# 訪問監控面板
# http://localhost:5555

📚 相關資源

🤝 支援

如果遇到問題，請：

  1. 檢查 故障排除 部分
  2. 運行整合測試：python scripts/test_integration.py
  3. 查看日誌文件
  4. 在 GitHub 上提交 Issue