增加了一版花里胡哨的
This commit is contained in:
-121
@@ -1,121 +0,0 @@
|
|||||||
# 🚀 5分钟快速上手指南
|
|
||||||
|
|
||||||
本指南帮助您快速配置并运行自动控制原理AI+数智平台。
|
|
||||||
|
|
||||||
## ⚡ 快速开始（3 步完成）
|
|
||||||
|
|
||||||
### 步骤 1：安装依赖
|
|
||||||
|
|
||||||
```bash
|
|
||||||
pip install gradio numpy control matplotlib aiohttp
|
|
||||||
```
|
|
||||||
|
|
||||||
### 步骤 2：配置 API
|
|
||||||
|
|
||||||
编辑 `app.py` 第 24 行，填入您的 DeepSeek API 密钥：
|
|
||||||
|
|
||||||
```python
|
|
||||||
API_KEY = "sk-your-api-key-here" # 替换为您的密钥
|
|
||||||
```
|
|
||||||
|
|
||||||
**获取密钥**：访问 https://platform.deepseek.com/api_keys
|
|
||||||
|
|
||||||
### 步骤 3：运行应用
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python app.py
|
|
||||||
```
|
|
||||||
|
|
||||||
浏览器会自动打开 http://localhost:7860
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🎯 第一次使用
|
|
||||||
|
|
||||||
### 试试时域分析
|
|
||||||
|
|
||||||
1. 在"时域分析"标签页
|
|
||||||
2. 输入传递函数：
|
|
||||||
- 分子：`1`
|
|
||||||
- 分母：`1,2,1`
|
|
||||||
3. 点击"开始分析"
|
|
||||||
4. 观察阶跃响应曲线和性能指标
|
|
||||||
|
|
||||||
### 试试 AI 问答
|
|
||||||
|
|
||||||
1. 切换到"智能问答"标签页
|
|
||||||
2. 输入问题：`什么是 PID 控制器？`
|
|
||||||
3. 点击"发送"
|
|
||||||
4. AI 会实时回复并渲染数学公式
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 💡 常用传递函数示例
|
|
||||||
|
|
||||||
### 一阶系统
|
|
||||||
```
|
|
||||||
分子: 1
|
|
||||||
分母: 1,1
|
|
||||||
G(s) = 1/(s+1)
|
|
||||||
```
|
|
||||||
|
|
||||||
### 二阶欠阻尼系统
|
|
||||||
```
|
|
||||||
分子: 4
|
|
||||||
分母: 1,2,4
|
|
||||||
G(s) = 4/(s²+2s+4)
|
|
||||||
阻尼比 ζ = 0.5，超调量约 16%
|
|
||||||
```
|
|
||||||
|
|
||||||
### 三阶系统
|
|
||||||
```
|
|
||||||
分子: 1
|
|
||||||
分母: 1,6,11,6
|
|
||||||
G(s) = 1/[(s+1)(s+2)(s+3)]
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔧 故障排查
|
|
||||||
|
|
||||||
### 问题 1：模块导入错误
|
|
||||||
|
|
||||||
```
|
|
||||||
ModuleNotFoundError: No module named 'gradio'
|
|
||||||
```
|
|
||||||
|
|
||||||
**解决**：重新安装依赖
|
|
||||||
```bash
|
|
||||||
pip install -r requirements.txt
|
|
||||||
```
|
|
||||||
|
|
||||||
### 问题 2：API 密钥错误
|
|
||||||
|
|
||||||
```
|
|
||||||
❌ 错误：API_KEY 未配置
|
|
||||||
```
|
|
||||||
|
|
||||||
**解决**：确认 `app.py` 第 24 行已填入有效密钥
|
|
||||||
|
|
||||||
### 问题 3：中文乱码
|
|
||||||
|
|
||||||
**解决**：确保终端支持 UTF-8 编码
|
|
||||||
```powershell
|
|
||||||
# Windows PowerShell
|
|
||||||
chcp 65001
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📚 下一步
|
|
||||||
|
|
||||||
- 阅读完整 [README.md](README.md)
|
|
||||||
- 查看 [API 配置详细说明](API_CONFIG.md)
|
|
||||||
- 探索四大功能模块
|
|
||||||
- 调整系统增益观察变化
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**需要帮助？** 查看 [常见问题](API_CONFIG.md#常见问题) 或提交 Issue。
|
|
||||||
|
|
||||||
祝学习愉快！🎓
|
|
||||||
@@ -0,0 +1,284 @@
|
|||||||
|
# 自动控制原理AI+数智平台 - 模块化架构说明
|
||||||
|
|
||||||
|
## 📁 项目结构
|
||||||
|
|
||||||
|
```
|
||||||
|
AutoControl/
|
||||||
|
├── app.py # 原始完整程序（已废弃，保留作参考）
|
||||||
|
├── app_main.py # 新的主程序入口 ⭐ 使用这个启动
|
||||||
|
├── config.py # 配置文件：API密钥、系统参数
|
||||||
|
├── utils.py # 工具函数：解析、验证、格式化
|
||||||
|
├── analysis.py # 分析功能：时域、频域、根轨迹
|
||||||
|
├── ai_chat.py # AI聊天：DeepSeek/Gemini接口
|
||||||
|
├── ui_styles.py # CSS样式：480+行现代化样式
|
||||||
|
├── ui_components.py # UI组件：横幅、知识卡片HTML
|
||||||
|
└── README_MODULE.md # 本文件
|
||||||
|
```
|
||||||
|
|
||||||
|
## 🚀 快速开始
|
||||||
|
|
||||||
|
### 方法1：使用新的模块化主程序（推荐）
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python app_main.py
|
||||||
|
```
|
||||||
|
|
||||||
|
### 方法2：使用原始完整程序
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python app.py
|
||||||
|
```
|
||||||
|
|
||||||
|
## 📦 模块说明
|
||||||
|
|
||||||
|
### 1. `config.py` - 配置管理
|
||||||
|
**功能：** 集中管理所有配置常量
|
||||||
|
|
||||||
|
**内容：**
|
||||||
|
- `API_KEY`: DeepSeek API密钥
|
||||||
|
- `API_BASE_URL`: API基础URL
|
||||||
|
- `API_MODEL`: 使用的模型名称
|
||||||
|
- `DEFAULT_NUM_COEFFS`: 默认分子系数
|
||||||
|
- `DEFAULT_DEN_COEFFS`: 默认分母系数
|
||||||
|
- `TIME_SPAN`: 时间范围设置
|
||||||
|
- `SERVER_PORT`: 服务器端口
|
||||||
|
- `PROJECT_INFO`: 项目信息字典
|
||||||
|
|
||||||
|
**修改配置：**
|
||||||
|
```python
|
||||||
|
# 在 config.py 中修改
|
||||||
|
API_KEY = "你的API密钥"
|
||||||
|
SERVER_PORT = 8080 # 更改端口
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. `utils.py` - 工具函数库
|
||||||
|
**功能：** 提供数据处理和格式化工具
|
||||||
|
|
||||||
|
**主要函数：**
|
||||||
|
- `coeffs_to_latex(coeffs, var='s')`: 系数转LaTeX多项式
|
||||||
|
- `parse_coefficients(coeffs_str)`: 解析系数字符串
|
||||||
|
- `validate_transfer_function(num, den)`: 验证传递函数
|
||||||
|
- `format_complex_number(c)`: 格式化复数显示
|
||||||
|
|
||||||
|
**使用示例：**
|
||||||
|
```python
|
||||||
|
from utils import parse_coefficients, validate_transfer_function
|
||||||
|
|
||||||
|
num = parse_coefficients("1,2,3")
|
||||||
|
den = parse_coefficients("1,4,5,2")
|
||||||
|
is_valid, msg = validate_transfer_function(num, den)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. `analysis.py` - 核心分析功能
|
||||||
|
**功能：** 控制系统的时域、频域、根轨迹分析
|
||||||
|
|
||||||
|
**主要函数：**
|
||||||
|
- `display_transfer_function(num_str, den_str)`: 显示传递函数
|
||||||
|
- `time_domain_analysis(num_str, den_str)`: 时域分析（阶跃/脉冲响应）
|
||||||
|
- `frequency_domain_analysis(num_str, den_str, K)`: 频域分析（Bode/Nyquist图）
|
||||||
|
- `root_locus_analysis(num_str, den_str, log_k)`: 根轨迹分析
|
||||||
|
|
||||||
|
**返回值：**
|
||||||
|
- 图表：matplotlib Figure对象
|
||||||
|
- 文本：性能指标、极点位置等
|
||||||
|
|
||||||
|
### 4. `ai_chat.py` - AI聊天功能
|
||||||
|
**功能：** 与DeepSeek/Gemini大模型交互
|
||||||
|
|
||||||
|
**主要函数：**
|
||||||
|
- `chat_with_ai(message, history)`: 异步聊天函数（支持流式输出）
|
||||||
|
|
||||||
|
**特点：**
|
||||||
|
- 支持对话历史记录
|
||||||
|
- 流式响应（实时显示）
|
||||||
|
- 自动错误处理
|
||||||
|
- Emoji状态指示
|
||||||
|
|
||||||
|
**系统提示词：**
|
||||||
|
```
|
||||||
|
你是一位精通自动控制原理的专家教授，擅长用通俗易懂的方式解释复杂概念。
|
||||||
|
回答要准确、专业，适当使用LaTeX公式，并举例说明。
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. `ui_styles.py` - CSS样式定义
|
||||||
|
**功能：** 提供480+行现代化CSS样式
|
||||||
|
|
||||||
|
**函数：**
|
||||||
|
- `get_custom_css()`: 返回完整CSS字符串
|
||||||
|
|
||||||
|
**样式特点：**
|
||||||
|
- 渐变背景和阴影效果
|
||||||
|
- 动画过渡效果
|
||||||
|
- 响应式设计（移动端适配）
|
||||||
|
- 暗色主题支持
|
||||||
|
- Emoji彩色显示修复
|
||||||
|
|
||||||
|
### 6. `ui_components.py` - UI组件库
|
||||||
|
**功能：** 提供HTML组件和知识卡片
|
||||||
|
|
||||||
|
**主要函数：**
|
||||||
|
- `get_main_title()`: 主标题
|
||||||
|
- `get_subtitle()`: 副标题
|
||||||
|
- `get_project_info_banner()`: 项目信息横幅
|
||||||
|
- `get_tab_tip(tab_name)`: 标签页提示
|
||||||
|
- `get_time_domain_knowledge_card()`: 时域知识卡片
|
||||||
|
- `get_frequency_domain_knowledge_card()`: 频域知识卡片
|
||||||
|
- `get_root_locus_knowledge_card()`: 根轨迹知识卡片
|
||||||
|
- `get_ai_example_questions()`: AI示例问题
|
||||||
|
|
||||||
|
### 7. `app_main.py` - 主程序入口
|
||||||
|
**功能：** 简化的主程序，组装所有模块
|
||||||
|
|
||||||
|
**代码行数：** ~350行（相比原来的2134行减少84%）
|
||||||
|
|
||||||
|
**结构：**
|
||||||
|
```python
|
||||||
|
# 导入所有模块
|
||||||
|
from config import *
|
||||||
|
from utils import *
|
||||||
|
from analysis import *
|
||||||
|
from ai_chat import *
|
||||||
|
from ui_styles import *
|
||||||
|
from ui_components import *
|
||||||
|
|
||||||
|
# 使用Gradio构建UI
|
||||||
|
with gr.Blocks(css=get_custom_css()) as demo:
|
||||||
|
# UI布局
|
||||||
|
# 事件绑定
|
||||||
|
pass
|
||||||
|
|
||||||
|
# 启动服务器
|
||||||
|
demo.launch()
|
||||||
|
```
|
||||||
|
|
||||||
|
## 🎯 模块化的优势
|
||||||
|
|
||||||
|
### 1. 易于维护
|
||||||
|
- 每个模块职责单一，代码清晰
|
||||||
|
- 修改某个功能只需编辑对应模块
|
||||||
|
- 减少代码重复，提高复用性
|
||||||
|
|
||||||
|
### 2. 易于扩展
|
||||||
|
- 添加新功能：创建新模块或在现有模块添加函数
|
||||||
|
- 添加新UI：在`ui_components.py`添加新函数
|
||||||
|
- 添加新样式：在`ui_styles.py`修改CSS
|
||||||
|
|
||||||
|
### 3. 易于调试
|
||||||
|
- 模块独立，可单独测试
|
||||||
|
- 错误定位更快速
|
||||||
|
- 日志和异常处理更精确
|
||||||
|
|
||||||
|
### 4. 团队协作友好
|
||||||
|
- 不同开发者可并行工作在不同模块
|
||||||
|
- 代码冲突减少
|
||||||
|
- 代码审查更高效
|
||||||
|
|
||||||
|
## 📝 常见修改场景
|
||||||
|
|
||||||
|
### 场景1：更改API密钥
|
||||||
|
**文件：** `config.py`
|
||||||
|
```python
|
||||||
|
API_KEY = "sk-新的密钥"
|
||||||
|
```
|
||||||
|
|
||||||
|
### 场景2：添加新的分析功能
|
||||||
|
**文件：** `analysis.py`
|
||||||
|
```python
|
||||||
|
def new_analysis_function(num_str, den_str):
|
||||||
|
"""新的分析功能"""
|
||||||
|
# 实现代码
|
||||||
|
return figure, metrics
|
||||||
|
```
|
||||||
|
|
||||||
|
**文件：** `app_main.py`（添加UI和事件绑定）
|
||||||
|
```python
|
||||||
|
from analysis import new_analysis_function
|
||||||
|
|
||||||
|
# 添加UI组件
|
||||||
|
new_button = gr.Button("新分析")
|
||||||
|
new_output = gr.Plot()
|
||||||
|
|
||||||
|
# 绑定事件
|
||||||
|
new_button.click(fn=new_analysis_function, inputs=[...], outputs=[...])
|
||||||
|
```
|
||||||
|
|
||||||
|
### 场景3：修改知识卡片内容
|
||||||
|
**文件：** `ui_components.py`
|
||||||
|
```python
|
||||||
|
def get_time_domain_knowledge_card():
|
||||||
|
return """
|
||||||
|
<div class='knowledge-card'>
|
||||||
|
<!-- 修改HTML内容 -->
|
||||||
|
</div>
|
||||||
|
"""
|
||||||
|
```
|
||||||
|
|
||||||
|
### 场景4：调整样式颜色
|
||||||
|
**文件：** `ui_styles.py`
|
||||||
|
```python
|
||||||
|
def get_custom_css():
|
||||||
|
return """
|
||||||
|
.main-title {
|
||||||
|
background: linear-gradient(135deg, #新颜色1, #新颜色2);
|
||||||
|
}
|
||||||
|
"""
|
||||||
|
```
|
||||||
|
|
||||||
|
### 场景5：更改默认参数
|
||||||
|
**文件：** `config.py`
|
||||||
|
```python
|
||||||
|
DEFAULT_DEN_COEFFS = "1,8,15,8" # 更改默认分母系数
|
||||||
|
SERVER_PORT = 8080 # 更改服务器端口
|
||||||
|
```
|
||||||
|
|
||||||
|
## 🔧 依赖库
|
||||||
|
|
||||||
|
```txt
|
||||||
|
gradio>=5.0.0
|
||||||
|
numpy>=1.21.0
|
||||||
|
matplotlib>=3.5.0
|
||||||
|
scipy>=1.7.0
|
||||||
|
control>=0.9.0
|
||||||
|
aiohttp>=3.8.0 # AI聊天功能
|
||||||
|
```
|
||||||
|
|
||||||
|
**安装命令：**
|
||||||
|
```bash
|
||||||
|
pip install gradio numpy matplotlib scipy control aiohttp
|
||||||
|
```
|
||||||
|
|
||||||
|
## ⚠️ 注意事项
|
||||||
|
|
||||||
|
1. **首次运行：** 需要在`config.py`中配置DeepSeek API密钥才能使用AI聊天功能
|
||||||
|
2. **端口冲突：** 如果7860端口被占用，修改`config.py`中的`SERVER_PORT`
|
||||||
|
3. **模块导入：** 所有模块必须在同一目录下
|
||||||
|
4. **Python版本：** 建议使用Python 3.8+
|
||||||
|
|
||||||
|
## 📊 代码对比
|
||||||
|
|
||||||
|
| 指标 | 原版 (app.py) | 模块化版本 |
|
||||||
|
|-----|--------------|-----------|
|
||||||
|
| 总代码行数 | 2134行 | 分散在7个文件 |
|
||||||
|
| 主程序行数 | 2134行 | 350行 (↓84%) |
|
||||||
|
| 可维护性 | ⭐⭐ | ⭐⭐⭐⭐⭐ |
|
||||||
|
| 可扩展性 | ⭐⭐ | ⭐⭐⭐⭐⭐ |
|
||||||
|
| 团队协作 | ⭐⭐ | ⭐⭐⭐⭐⭐ |
|
||||||
|
|
||||||
|
## 🎓 学习建议
|
||||||
|
|
||||||
|
1. **初学者：** 先运行`app_main.py`，熟悉整体功能
|
||||||
|
2. **进阶学习：** 阅读各模块代码，理解功能实现
|
||||||
|
3. **高级应用：** 尝试添加新功能或修改现有模块
|
||||||
|
4. **问题排查：** 参考模块注释和本文档
|
||||||
|
|
||||||
|
## 📮 联系方式
|
||||||
|
|
||||||
|
**项目负责人：** 魏鹏飞 教授
|
||||||
|
**邮箱：** pengfeiwei@nwpu.edu.cn
|
||||||
|
**单位：** 西北工业大学
|
||||||
|
**资助：** 2025年校级本科生建设项目
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**最后更新：** 2025年1月
|
||||||
|
**版本：** 2.0 (模块化架构)
|
||||||
Reference in New Issue
Block a user