ben/liurenchaxin
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat(ui): 添加AI协作页签

Browse Source 
新增AI协作功能模块，并在主界面中添加了对应的页签。
更新了OpenBB集成文档的路径，将其从单独的Markdown文件迁移到目录结构中。
为项目添加了新的测试依赖，包括pytest相关工具、locust和memory-profiler等。
This commit is contained in:
ben
2025-08-23 14:06:22 +00:00
parent 21128299a4
commit 09de1f782a
61 changed files with 5324 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
docs/architecture/component_interaction_diagram.mermaid Normal file
View File

@@ -0,0 +1,13 @@
graph LR
A[Streamlit App] --> B[OpenBB Tab]
A --> C[Debate System]
C --> D[Immortal Agents]
D --> E[OpenBB Engine]
D --> F[Perpetual Engine]
B --> G[_load_price_data]
G --> H{OpenBB Available?}
H -- Yes --> I[OpenBB obb]
H -- No --> J[Demo/Synthetic Data]
E --> K{OpenBB Available?}
K -- Yes --> I
K -- No --> L[Error Result]

9
docs/architecture/data_flow_diagram.mermaid Normal file
View File

@@ -0,0 +1,9 @@
graph TD
A[User Request] --> B{OpenBB Installed?}
B -- Yes --> C{OpenBB Data Available?}
C -- Yes --> D[OpenBB Engine]
C -- No --> E[Fallback to Demo/Synthetic Data]
B -- No --> E
D --> F[Format Data]
E --> F
F --> G[Return to Agent/UI]

181
docs/architecture/deployment_architecture.md Normal file
View File

@@ -0,0 +1,181 @@
# OpenBB Integration Deployment Architecture
## Environment and Dependencies
### Base Requirements
- **Python Version**: 3.8 or higher
- **Core Dependencies**: As specified in `requirements.txt` (Streamlit, etc.)
### Optional OpenBB Dependency
- **OpenBB Library**: `openbb>=4.1.0`
- **Installation**: Not included in default `requirements.txt` to maintain lightweight base installation
- **Activation**: Install via `pip install "openbb>=4.1.0"` when needed
## Configuration Management
### Environment Variables
- **Standard Project Variables**: Managed through Doppler (RAPIDAPI_KEY, GOOGLE_API_KEY, etc.)
- **OpenBB Provider Variables**:
- For public data sources (like yfinance): No specific configuration required
- For premium data sources (e.g., Polygon, FMP):
- Variables are managed by OpenBB internally
- Follow OpenBB documentation for provider-specific setup
- Example: `POLYGON_API_KEY` for Polygon.io data
### Feature Flags
- **JIXIA_MEMORY_BACKEND**: When set to "cloudflare", enables Cloudflare AutoRAG as memory backend
- **GOOGLE_GENAI_USE_VERTEXAI**: When set to "TRUE", enables Vertex AI for memory bank
## Deployment Scenarios
### 1. Base Deployment (OpenBB Not Installed)
- **Characteristics**:
- Lightweight installation
- Relies on existing RapidAPI-based perpetual engine
- UI falls back to demo or synthetic data in OpenBB tab
- **Use Cases**:
- Minimal environment setups
- Systems where OpenBB installation is not feasible
- Development environments focusing on other features
### 2. Full Deployment (With OpenBB)
- **Characteristics**:
- Enhanced data capabilities through OpenBB
- Access to multiple data providers
- Improved data quality and coverage
- **Use Cases**:
- Production environments requiring comprehensive market data
- Advanced financial analysis and debate scenarios
- Integration with premium data sources
### 3. Hybrid Deployment (Selective Features)
- **Characteristics**:
- Selective installation of OpenBB providers
- Mix of OpenBB and perpetual engine data sources
- Fallback mechanisms ensure continuous operation
- **Use Cases**:
- Cost optimization by using free providers where possible
- Gradual migration from perpetual engine to OpenBB
- Testing new data sources without full commitment
## Containerization (Docker)
### Base Image
- Python 3.10-slim or equivalent
### Multi-Stage Build
1. **Builder Stage**:
- Install build dependencies
- Install Python dependencies
2. **Runtime Stage**:
- Copy installed packages from builder
- Copy application code
- Install optional OpenBB dependencies if specified
### Docker Compose Configuration
- Service definitions for main application
- Optional service for database (if using persistent memory backends)
- Volume mounts for configuration and data persistence
## Cloud Deployment
### Google Cloud Platform (GCP)
- **App Engine**:
- Standard environment with custom runtime
- Environment variables configured through `app.yaml`
- **Cloud Run**:
- Containerized deployment
- Secrets managed through Secret Manager
- **Compute Engine**:
- Full control over VM configuration
- Persistent disks for data storage
### Considerations for Cloud Deployment
- **API Key Security**:
- Use secret management services (Google Secret Manager, Doppler)
- Never store keys in code or environment files
- **Memory Backend Configuration**:
- For Vertex AI Memory Bank: Configure GOOGLE_CLOUD_PROJECT_ID and authentication
- For Cloudflare AutoRAG: Configure CLOUDFLARE_ACCOUNT_ID and API token
- **Scalability**:
- Stateless application design allows horizontal scaling
- Memory backends provide persistence across instances
## Memory Backend Integration
### Vertex AI Memory Bank (Default/Primary)
- **Activation**: Requires GOOGLE_GENAI_USE_VERTEXAI=true and proper GCP authentication
- **Dependencies**: `google-cloud-aiplatform` (installed with google-adk)
- **Deployment**: Requires GCP project with Vertex AI API enabled
### Cloudflare AutoRAG (Alternative)
- **Activation**: Requires JIXIA_MEMORY_BACKEND=cloudflare and Cloudflare credentials
- **Dependencies**: `aiohttp` (already in requirements)
- **Deployment**: Requires Cloudflare account with Vectorize and Workers AI enabled
## Monitoring and Observability
### Health Checks
- Application startup verification
- OpenBB availability check endpoint
- Memory backend connectivity verification
### Logging
- Structured logging for data access patterns
- Error tracking for failed data retrievals
- Performance metrics for data loading times
### Metrics Collection
- API usage counters (both RapidAPI and OpenBB)
- Fallback trigger rates
- Memory backend operation statistics
## Security Posture
### Data Security
- In-memory data processing
- No persistent storage of sensitive financial data
- Secure handling of API responses
### Access Control
- Streamlit authentication (if enabled)
- API key isolation per data provider
- Memory backend access controls through provider mechanisms
### Network Security
- HTTPS for all external API calls
- Outbound firewall rules for API endpoints
- Secure credential injection mechanisms
## Disaster Recovery and Business Continuity
### Data Source Redundancy
- Multiple API providers through OpenBB
- Fallback to perpetual engine when OpenBB fails
- Synthetic data generation for UI continuity
### Memory Backend Failover
- Local simulation mode when cloud backends are unavailable
- Graceful degradation of memory features
### Recovery Procedures
- Automated restart on critical failures
- Manual intervention procedures for configuration issues
- Rollback capabilities through version control
## Performance Optimization
### Caching Strategies
- OpenBB's internal caching mechanisms
- Streamlit's built-in caching for UI components
- Memory backend for persistent agent knowledge
### Resource Management
- Asynchronous data loading where possible
- Memory-efficient data structures
- Connection pooling for API requests
### Scaling Considerations
- Horizontal scaling for handling concurrent users
- Vertical scaling for memory-intensive operations
- Load balancing for distributed deployments

168
docs/architecture/openbb_integration_architecture.md Normal file
View File

@@ -0,0 +1,168 @@
# OpenBB Integration Architecture for 炼妖壶 (Lianyaohu) - 稷下学宫AI辩论系统
## Overview
This document outlines the architecture for integrating OpenBB v4 into the Lianyaohu 稷下学宫AI辩论系统. The integration aims to provide enriched financial data to the eight immortal agents while maintaining graceful degradation when OpenBB is not installed or available.
## System Context
The Lianyaohu system is a multi-AI-agent debate platform rooted in traditional Chinese philosophy. The eight immortals (八仙) debate investment topics, leveraging data from multiple financial APIs. The system currently uses a "perpetual engine" based on 17 RapidAPI subscriptions. This architecture adds OpenBB as an optional, higher-level data source.
## Key Components and Integration Points
### 1. Core Business Logic (`src/jixia/`)
#### a. `engines/openbb_engine.py`
- **Purpose**: Primary interface to OpenBB v4 data.
- **Key Features**:
- Lazy loading of `openbb` library to prevent import errors if not installed.
- `ImmortalConfig` mapping each immortal to a primary data provider (initially `yfinance`).
- `get_immortal_data` method for agent-specific data retrieval based on specialty.
- `simulate_jixia_debate` for testing and demonstration.
- **Integration Strategy**:
- Uses `from openbb import obb` for unified routing.
- Handles different data types (price, historical, profile, news, earnings, etc.).
- Provides fallback error handling returning `APIResult` objects.
#### b. `engines/openbb_stock_data.py`
- **Purpose**: Utility functions for fetching stock and ETF data.
- **Key Features**:
- `get_stock_data` and `get_etf_data` functions.
- Lazy loading of `openbb`.
- Time window configuration.
- Data formatting utilities.
### 2. Application Entry Point (`app/`)
#### a. `tabs/openbb_tab.py`
- **Purpose**: Streamlit UI tab for visualizing market data.
- **Key Features**:
- `_check_openbb_installed` to detect availability.
- `_load_price_data` with multi-level fallback (OpenBB -> demo JSON -> synthetic data).
- KPI calculation from data.
- Interactive charting with Plotly.
- **Integration Strategy**:
- Prioritizes `obb.equity.price.historical`, falling back to `obb.etf.price.historical`.
- Handles various data frame formats and column names from different providers.
- Graceful UI degradation with informative messages.
### 3. Data Models (`src/jixia/models/`)
*(Note: This directory and specific model files were not found in the current codebase.)*
- **Purpose**: Standardized data models for financial data.
- **Proposed Implementation**:
- Define `FinancialDataPoint`, `StockQuote`, `HistoricalPrice`, etc.
- Used by both OpenBB engine and existing perpetual engine for data abstraction.
### 4. Configuration (`config/settings.py`)
- **Purpose**: Centralized configuration management.
- **Key Features**:
- No direct OpenBB configuration currently, but designed for extensibility.
- Validates environment for hybrid AI provider modes.
## Data Flow Architecture
```mermaid
graph TD
A[User Request] --> B{OpenBB Installed?}
B -- Yes --> C{OpenBB Data Available?}
C -- Yes --> D[OpenBB Engine]
C -- No --> E[Fallback to Demo/Synthetic Data]
B -- No --> E
D --> F[Format Data]
E --> F
F --> G[Return to Agent/UI]
```
1. **Agent Request**: An immortal agent requests data via `OpenBBEngine.get_immortal_data`.
2. **OpenBB Check**: The engine checks if OpenBB is available via lazy import.
3. **Data Retrieval**: If available, the engine calls the appropriate `obb.*` function.
4. **Data Processing**: The engine processes the result into a standardized `APIResult`.
5. **Fallback**: If OpenBB is not installed or the call fails, an error result is returned.
6. **UI Request**: The OpenBB tab requests data via `_load_price_data`.
7. **UI Fallback Chain**:
- Tries `obb.equity.price.historical`.
- Falls back to `obb.etf.price.historical`.
- Falls back to loading demo JSON files.
- Finally falls back to generating synthetic data.
8. **Data Formatting**: The UI formats the data for display, handling various column names and structures.
## Component Interaction Diagram
```mermaid
graph LR
A[Streamlit App] --> B[OpenBB Tab]
A --> C[Debate System]
C --> D[Immortal Agents]
D --> E[OpenBB Engine]
D --> F[Perpetual Engine]
B --> G[_load_price_data]
G --> H{OpenBB Available?}
H -- Yes --> I[OpenBB obb]
H -- No --> J[Demo/Synthetic Data]
E --> K{OpenBB Available?}
K -- Yes --> I
K -- No --> L[Error Result]
```
## Deployment Architecture
### Environment Requirements
- Python 3.8+
- Optional: `openbb>=4.1.0` (not in default requirements)
- Standard project dependencies (Streamlit, etc.)
### Configuration
- No specific OpenBB configuration required for basic `yfinance` use.
- Advanced providers (e.g., Polygon) would require provider-specific environment variables.
### Scalability and Performance
- OpenBB's provider system handles its own rate limiting and caching.
- The lazy loading approach prevents unnecessary overhead if OpenBB is not used.
- Fallback to demo/synthetic data ensures UI responsiveness.
## Failure Handling and Degradation
### OpenBB Not Installed
- `ImportError` is caught in lazy loading.
- Engine returns `APIResult(success=False, error="OpenBB not installed...")`.
- UI falls back to demo/synthetic data gracefully.
### OpenBB API Call Failure
- Exception is caught in `get_immortal_data`.
- Engine returns `APIResult(success=False, error="OpenBB call failed...")`.
- Agent can decide how to handle the failure (e.g., switch to another engine).
### UI Data Loading Failure
- Multi-level fallback ensures data is always available for visualization.
- Users are informed via UI messages if demo/synthetic data is being used.
## Monitoring and Observability
### Logging
- OpenBB engine logs data requests and responses.
- UI logs fallback events.
### Metrics
- Not currently implemented, but could track:
- OpenBB usage frequency.
- Fallback trigger rates.
- Data load times.
## Security Considerations
### API Keys
- OpenBB handles provider API keys internally.
- Standard project security practices (Doppler, no hardcoded keys) apply.
### Data Handling
- Data is processed in memory and not persisted by the OpenBB integration components.
## Future Enhancements
1. **Unified Data Model**: Create standardized data models in `src/jixia/models/` for seamless integration between OpenBB and other data sources.
2. **Provider Configuration**: Allow dynamic configuration of data providers for each immortal.
3. **Enhanced UI Components**: Add more detailed financial data visualizations and analysis tools.
4. **Debate Integration**: Directly link debate outcomes to specific data points from OpenBB.
5. **Advanced OpenBB Routes**: Integrate fundamental data, news, and alternative data sources from OpenBB.
## Conclusion
This architecture successfully integrates OpenBB v4 into the Lianyaohu system while maintaining its core principles of graceful degradation and modular design. The lazy loading approach ensures that the system remains functional and performant regardless of whether OpenBB is installed, providing a robust foundation for future enhancements.

158
docs/architecture/performance_optimization.md Normal file
View File

@@ -0,0 +1,158 @@
# OpenBB Integration Performance Optimization Architecture
## Overview
This document outlines the performance optimization strategies for the OpenBB integration in the 炼妖壶 (Lianyaohu) - 稷下学宫AI辩论系统. The goal is to ensure the system can handle high concurrency while maintaining low latency and optimal resource utilization.
## Asynchronous Data Architecture
### 1. Asynchronous Data Retrieval
- **Implementation**: Use Python's `asyncio` framework for non-blocking data access
- **Key Components**:
- `DataAbstractionLayer.get_quote_async()` method
- Asynchronous providers (where supported by the underlying library)
- Executor-based fallback for synchronous providers
- **Benefits**:
- Improved responsiveness for UI components
- Better resource utilization for concurrent requests
- Non-blocking operations for agent debates
### 2. Concurrent Provider Access
- **Implementation**: Parallel requests to multiple providers with first-wins semantics
- **Strategy**:
- Launch requests to all configured providers simultaneously
- Return the first successful response
- Cancel remaining requests to conserve resources
- **Benefits**:
- Reduced perceived latency
- Automatic failover without delay
- Optimal use of available bandwidth
## Caching Strategy
### 1. Multi-Level Caching
- **In-Memory LRU Cache**:
- Decorator-based caching for frequently accessed data (quotes, profiles)
- Configurable size limits to prevent memory exhaustion
- Time-to-live (TTL) settings based on data volatility
- **Shared Cache Layer** (Future):
- Redis or Memcached for distributed deployments
- Consistent cache invalidation across instances
- Support for cache warming strategies
### 2. Cache Key Design
- **Granular Keys**: Separate cache entries for different data types and time windows
- **Parameterized Keys**: Include relevant parameters (symbol, date range, provider) in cache keys
- **Versioned Keys**: Incorporate data schema version to handle model changes
### 3. Cache Invalidation
- **Time-Based Expiration**: Automatic expiration based on TTL settings
- **Event-Driven Invalidation**: Clear cache entries when underlying data sources are updated
- **Manual Invalidation**: API endpoints for cache management
## Load Balancing Mechanism
### 1. Provider Selection Algorithm
- **Priority-Based Routing**: Route requests to providers based on configured priorities
- **Health-Based Routing**: Consider provider health metrics when selecting providers
- **Round-Robin for Equal Priority**: Distribute load among providers with the same priority
### 2. Adaptive Load Distribution
- **Real-Time Monitoring**: Track response times and error rates for each provider
- **Dynamic Weight Adjustment**: Adjust provider weights based on performance metrics
- **Circuit Breaker Pattern**: Temporarily disable poorly performing providers
## Resource Management
### 1. Connection Pooling
- **HTTP Connection Reuse**: Maintain pools of HTTP connections for API clients
- **Database Connection Pooling**: Reuse database connections for cache backends
- **Provider-Specific Pools**: Separate connection pools for different data providers
### 2. Memory Management
- **Efficient Data Structures**: Use memory-efficient data structures for caching
- **Object Reuse**: Reuse objects where possible to reduce garbage collection pressure
- **Streaming Data Processing**: Process large datasets in chunks to minimize memory footprint
### 3. Thread and Process Management
- **Async-Appropriate Threading**: Use threads for I/O-bound operations that aren't natively async
- **Process Isolation**: Isolate resource-intensive operations in separate processes
- **Resource Limits**: Configure limits on concurrent threads and processes
## Monitoring and Performance Metrics
### 1. Key Performance Indicators
- **Response Time**: Measure latency for data retrieval operations
- **Throughput**: Track requests per second for different data types
- **Error Rate**: Monitor failure rates for data access operations
- **Cache Hit Ratio**: Measure effectiveness of caching strategies
### 2. Provider Performance Metrics
- **Individual Provider Metrics**: Track performance for each data provider
- **Health Status**: Monitor uptime and responsiveness of providers
- **Cost Metrics**: Track usage and costs associated with different providers
### 3. System-Level Metrics
- **Resource Utilization**: CPU, memory, and network usage
- **Concurrency Levels**: Track active requests and queue depths
- **Garbage Collection**: Monitor GC activity and its impact on performance
## Optimization Techniques
### 1. Data Pre-fetching
- **Predictive Loading**: Pre-fetch data for likely subsequent requests
- **Batch Operations**: Combine multiple requests into single batch operations where possible
- **Background Refresh**: Refresh cached data proactively before expiration
### 2. Data Compression
- **Response Compression**: Use gzip compression for API responses
- **Cache Compression**: Compress cached data to reduce memory usage
- **Efficient Serialization**: Use efficient serialization formats (e.g., Protocol Buffers, MessagePack)
### 3. Database Optimization
- **Indexing Strategy**: Create appropriate indexes for cache lookup operations
- **Query Optimization**: Optimize database queries for performance
- **Connection Management**: Efficiently manage database connections
## Scalability Considerations
### 1. Horizontal Scaling
- **Stateless Design**: Ensure data access components are stateless for easy scaling
- **Load Balancer Integration**: Work with external load balancers for traffic distribution
- **Shared Caching**: Use distributed cache for consistent data across instances
### 2. Vertical Scaling
- **Resource Allocation**: Optimize resource usage for efficient vertical scaling
- **Performance Tuning**: Tune system parameters for better performance on larger instances
- **Memory Management**: Efficiently manage memory to take advantage of larger instances
### 3. Auto-scaling
- **Metrics-Driven Scaling**: Use performance metrics to trigger auto-scaling events
- **Graceful Degradation**: Maintain functionality during scaling operations
- **Cost Optimization**: Balance performance with cost considerations
## Implementation Roadmap
### Phase 1: Core Async Implementation
- Implement `DataAbstractionLayer.get_quote_async()`
- Add async support to provider adapters where possible
- Add executor-based fallback for synchronous providers
### Phase 2: Caching Layer
- Implement in-memory LRU cache
- Add cache key design and invalidation strategies
- Integrate cache with data abstraction layer
### Phase 3: Monitoring and Metrics
- Implement data quality monitoring
- Add performance metrics collection
- Create dashboards for monitoring key metrics
### Phase 4: Advanced Optimizations
- Implement predictive pre-fetching
- Add database optimization for cache backends
- Implement distributed caching for scalability
## Conclusion
This performance optimization architecture provides a comprehensive approach to ensuring the OpenBB integration in the Lianyaohu system can handle high concurrency while maintaining optimal performance. By implementing asynchronous data access, multi-level caching, intelligent load balancing, and comprehensive monitoring, the system will be able to deliver fast, reliable financial data to the eight immortal agents even under heavy load.

130
docs/architecture/technical_specification.md Normal file
View File

@@ -0,0 +1,130 @@
# 炼妖壶-稷下学宫AI辩论系统 OpenBB集成文档整合
## 概述
本文档整合了"炼妖壶-稷下学宫AI辩论系统"中OpenBB集成的所有关键设计和实现文档，为开发团队提供一个全面的参考指南。
## 架构设计
### 1. 整体架构
系统采用分层架构设计，将OpenBB集成在数据访问层，通过抽象层为上层应用提供统一的数据接口。
### 2. 核心组件
- **OpenBB引擎** (`src/jixia/engines/openbb_engine.py`)：主要的数据访问接口
- **数据抽象层** (`src/jixia/engines/data_abstraction_layer.py`)：统一的数据访问接口
- **Provider适配器**：为不同数据源实现的适配器
- **数据模型** (`src/jixia/models/financial_data_models.py`)：标准化的数据结构定义
### 3. 数据流
```
[八仙智能体] -> [数据抽象层] -> [Provider适配器] -> [OpenBB引擎] -> [OpenBB库]
\-> [永动机引擎] -> [RapidAPI]
```
## 实现细节
### 1. 数据模型
定义了标准化的金融数据结构：
- `StockQuote`：股票报价
- `HistoricalPrice`：历史价格数据
- `CompanyProfile`：公司概况
- `FinancialNews`：金融新闻
### 2. 抽象接口
定义了`DataProvider`抽象基类，所有数据提供商都需要实现该接口：
- `get_quote()`：获取股票报价
- `get_historical_prices()`：获取历史价格数据
- `get_company_profile()`：获取公司概况
- `get_news()`：获取相关新闻
### 3. Provider适配器
为OpenBB和RapidAPI分别实现了适配器：
- `OpenBBDataProvider`：OpenBB数据提供商适配器
- `RapidAPIDataProvider`：RapidAPI数据提供商适配器
### 4. 八仙数据映射
定义了八仙与数据源的智能映射关系，每个八仙都有其专属的数据源和类型偏好。
## 性能优化
### 1. 异步处理
实现了异步数据访问机制，提高系统并发处理能力。
### 2. 缓存策略
采用多级缓存策略，包括内存LRU缓存和未来可扩展的分布式缓存。
### 3. 负载均衡
实现了基于优先级和健康状态的数据源选择算法。
## 测试验证
### 1. 功能测试
- Provider适配器测试
- 数据抽象层测试
- 引擎组件测试
- UI组件测试
- 集成测试
### 2. 性能测试
- 响应时间测试
- 并发访问测试
### 3. 验证标准
- 功能验证标准
- 性能验证标准
- 兼容性验证标准
## 部署架构
### 1. 环境要求
- Python 3.8+
- 可选的OpenBB库 (>=4.1.0)
### 2. 配置管理
- 通过环境变量管理配置
- 支持多种部署场景（基础部署、完整部署、混合部署）
### 3. 安全考虑
- API密钥安全管理
- 数据安全处理
- 访问控制
## 故障处理与降级
### 1. 故障转移机制
当主数据源不可用时，系统能自动切换到备用数据源。
### 2. 优雅降级
当OpenBB未安装时，系统能正常运行并使用演示数据。
## 监控与可观测性
### 1. 关键指标
- 数据源可用性
- 响应时间
- 错误率
- 缓存命中率
### 2. 告警策略
定义了多维度的告警策略，确保系统稳定性。
## 未来发展规划
### 1. 统一数据模型
创建更完善的标准化数据模型。
### 2. Provider配置
实现动态配置数据提供商。
### 3. 增强UI组件
添加更多详细的金融数据可视化和分析工具。
### 4. 辩论集成
直接将辩论结果链接到OpenBB的具体数据点。
### 5. 高级路由
集成OpenBB的更多数据源，如基本面数据、新闻和另类数据。
## 结论
通过以上架构设计和实现，OpenBB集成成功地为"炼妖壶-稷下学宫AI辩论系统"提供了丰富而可靠的金融数据支持，同时保持了系统的可扩展性和稳定性。这套集成方案不仅满足了当前需求，也为未来功能扩展奠定了坚实基础。

287
docs/architecture/test_validation_plan.md Normal file
View File

@@ -0,0 +1,287 @@
# 炼妖壶-稷下学宫AI辩论系统 OpenBB集成测试与验证方案
## 概述
本文档定义了"炼妖壶-稷下学宫AI辩论系统"中OpenBB集成的测试用例和验证标准，确保集成的正确性、可靠性和性能。
## 测试环境配置
### 基础环境
- Python 3.8+
- 系统依赖：如 requirements.txt 中定义
- 测试框架：pytest
### OpenBB环境变体
1. **未安装OpenBB**：测试降级机制
2. **安装OpenBB但未配置提供商**：测试基本功能
3. **完整配置OpenBB**：测试所有功能
## 测试用例
### 1. 数据抽象层测试
#### 1.1 Provider适配器测试
```python
# tests/test_provider_adapters.py
def test_openbb_provider_initialization():
"""测试OpenBB提供商适配器初始化"""
from src.jixia.engines.openbb_adapter import OpenBBDataProvider
provider = OpenBBDataProvider()
assert provider.name == "OpenBB"
assert provider.priority == 1
def test_rapidapi_provider_initialization():
"""测试RapidAPI提供商适配器初始化"""
from src.jixia.engines.rapidapi_adapter import RapidAPIDataProvider
provider = RapidAPIDataProvider()
assert provider.name == "RapidAPI"
assert provider.priority == 2
def test_provider_data_retrieval():
"""测试提供商数据检索功能"""
# 使用模拟数据测试各提供商的数据获取方法
pass
```
#### 1.2 数据抽象层管理器测试
```python
# tests/test_data_abstraction_layer.py
def test_dal_initialization():
"""测试数据抽象层初始化"""
from src.jixia.engines.data_abstraction_layer import DataAbstractionLayer
dal = DataAbstractionLayer()
# 验证提供商是否正确加载
assert len(dal.providers) >= 1
def test_dal_quote_retrieval():
"""测试数据抽象层报价获取"""
from src.jixia.engines.data_abstraction_layer import DataAbstractionLayer
dal = DataAbstractionLayer()
quote = dal.get_quote("AAPL")
# 验证返回数据结构
if quote is not None:
assert hasattr(quote, 'symbol')
assert hasattr(quote, 'price')
def test_dal_fallback_mechanism():
"""测试故障转移机制"""
# 模拟主提供商失败，验证是否能正确切换到备用提供商
pass
```
### 2. 引擎组件测试
#### 2.1 OpenBB引擎测试
```python
# tests/test_openbb_engine.py
def test_openbb_engine_initialization():
"""测试OpenBB引擎初始化"""
from src.jixia.engines.openbb_engine import OpenBBEngine
engine = OpenBBEngine()
# 验证引擎是否正确初始化
assert engine is not None
def test_openbb_engine_data_retrieval():
"""测试OpenBB引擎数据获取"""
from src.jixia.engines.openbb_engine import OpenBBEngine
engine = OpenBBEngine()
result = engine.get_immortal_data("吕洞宾", "price", "AAPL")
# 验证返回结果结构
assert hasattr(result, 'success')
if result.success:
assert result.data is not None
def test_openbb_engine_unavailable():
"""测试OpenBB不可用时的行为"""
# 通过模拟环境测试OpenBB未安装时的降级行为
pass
```
#### 2.2 永动机引擎测试
```python
# tests/test_perpetual_engine.py
def test_perpetual_engine_initialization():
"""测试永动机引擎初始化"""
from src.jixia.engines.perpetual_engine import JixiaPerpetualEngine
# 注意：需要提供有效的RapidAPI密钥进行测试
pass
def test_perpetual_engine_data_retrieval():
"""测试永动机引擎数据获取"""
pass
```
### 3. UI组件测试
#### 3.1 OpenBB标签页测试
```python
# tests/test_openbb_tab.py
def test_openbb_tab_data_loading():
"""测试OpenBB标签页数据加载"""
# 验证在不同环境下的数据加载行为
pass
def test_openbb_tab_fallback():
"""测试OpenBB标签页降级机制"""
# 验证当OpenBB不可用时是否正确显示演示数据
pass
```
### 4. 集成测试
#### 4.1 八仙智能体数据访问测试
```python
# tests/test_baxian_data_access.py
def test_immortal_data_mapping():
"""测试八仙与数据源的映射关系"""
from src.jixia.engines.baxian_data_mapping import immortal_data_mapping
# 验证所有八仙都有正确的数据源映射
assert len(immortal_data_mapping) == 8
for immortal in ['吕洞宾', '何仙姑', '张果老', '韩湘子', '汉钟离', '蓝采和', '铁拐李', '曹国舅']:
assert immortal in immortal_data_mapping
def test_immortal_data_retrieval():
"""测试八仙智能体数据获取"""
# 验证每个八仙都能通过数据抽象层获取到所需数据
pass
```
#### 4.2 端到端辩论流程测试
```python
# tests/test_debate_flow_with_openbb.py
def test_debate_with_openbb_data():
"""测试使用OpenBB数据的完整辩论流程"""
# 验证辩论系统能正确使用OpenBB提供的数据
pass
```
## 性能测试
### 1. 响应时间测试
```python
# tests/performance/test_response_time.py
def test_quote_retrieval_response_time():
"""测试报价获取响应时间"""
import time
from src.jixia.engines.data_abstraction_layer import DataAbstractionLayer
dal = DataAbstractionLayer()
start_time = time.time()
quote = dal.get_quote("AAPL")
end_time = time.time()
response_time = end_time - start_time
# 验证响应时间在可接受范围内
assert response_time < 2.0 # 假设2秒为阈值
```
### 2. 并发访问测试
```python
# tests/performance/test_concurrent_access.py
def test_concurrent_quote_retrieval():
"""测试并发报价获取"""
import asyncio
from src.jixia.engines.data_abstraction_layer import DataAbstractionLayer
async def get_quote(symbol):
dal = DataAbstractionLayer()
return await dal.get_quote_async(symbol)
async def get_multiple_quotes():
symbols = ["AAPL", "GOOGL", "MSFT", "TSLA"]
tasks = [get_quote(symbol) for symbol in symbols]
return await asyncio.gather(*tasks)
# 运行并发测试
quotes = asyncio.run(get_multiple_quotes())
# 验证所有请求都成功返回
assert len(quotes) == 4
```
## 验证标准
### 功能验证标准
1. **数据准确性**：返回的数据格式和内容符合预期
2. **故障转移**：当主数据源不可用时，系统能自动切换到备用数据源
3. **优雅降级**：当OpenBB未安装时，系统能正常运行并使用演示数据
4. **八仙映射**：每个八仙都能访问其专属的数据源和类型
### 性能验证标准
1. **响应时间**：单次数据请求响应时间不超过2秒
2. **并发处理**：系统能同时处理至少10个并发数据请求
3. **资源使用**：内存使用在合理范围内，无内存泄漏
4. **缓存效率**：缓存命中率应达到80%以上
### 兼容性验证标准
1. **Python版本**：支持Python 3.8及以上版本
2. **OpenBB版本**：支持OpenBB v4.1.0及以上版本
3. **环境变量**：正确处理各种环境变量配置
4. **依赖管理**：OpenBB作为可选依赖，不影响主系统安装
## 持续集成/持续部署(CI/CD)集成
### GitHub Actions工作流
```yaml
# .github/workflows/openbb_integration_test.yml
name: OpenBB Integration Test
on:
push:
branches: [ main, develop ]
pull_request:
branches: [ main ]
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: [3.8, 3.9, '3.10', '3.11']
openbb-installed: [true, false]
steps:
- uses: actions/checkout@v3
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v4
with:
python-version: ${{ matrix.python-version }}
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install -r requirements.txt
if [ "${{ matrix.openbb-installed }}" = "true" ]; then
pip install "openbb>=4.1.0"
fi
- name: Run tests
run: |
pytest tests/test_openbb_*.py
pytest tests/test_data_abstraction_*.py
```
## 监控和告警
### 关键指标监控
1. **数据源可用性**：监控各数据提供商的可用性
2. **响应时间**：监控数据请求的平均响应时间
3. **错误率**：监控数据访问的错误率
4. **缓存命中率**：监控缓存的使用效率
### 告警策略
1. **可用性告警**：当数据源可用性低于95%时触发告警
2. **性能告警**：当平均响应时间超过阈值时触发告警
3. **错误率告警**：当错误率超过1%时触发告警
4. **缓存告警**：当缓存命中率低于70%时触发告警
## 结论
这套测试和验证方案确保了OpenBB集成的高质量交付，通过全面的功能测试、性能测试和持续集成，能够及时发现和修复潜在问题，保证系统的稳定性和可靠性。