feat: 初始化自动控制原理AI+数智平台项目

- 添加时域分析、频域分析、根轨迹分析功能 - 集成 AI 智能问答（DeepSeek/Gemini API） - 现代化 UI 设计，支持 LaTeX 公式渲染 - 完整的项目文档和配置文件
2025-10-15 20:37:30 +08:00
parent 9b4b3072a5
commit 7edbda02f6
8 changed files with 979 additions and 0 deletions
@@ -0,0 +1,201 @@
+# API 配置指南
+
+本文档详细说明如何配置 DeepSeek 和 Gemini API。
+
+## 📋 目录
+
+- [DeepSeek API 配置](#deepseek-api-配置)
+- [Gemini API 配置](#gemini-api-配置)
+- [常见问题](#常见问题)
+
+---
+
+## 🚀 DeepSeek API 配置
+
+### 1. 获取 API 密钥
+
+1. 访问 [DeepSeek 平台](https://platform.deepseek.com/)
+2. 注册账号并登录
+3. 进入 [API Keys 页面](https://platform.deepseek.com/api_keys)
+4. 点击"创建新密钥"
+5. 复制生成的 API 密钥（格式：`sk-xxxxxxxxxxxxxxxx`）
+
+### 2. 配置到应用
+
+编辑 `app.py` 文件的配置区域（第 7-28 行）：
+
+```python
+# ==================== API 配置 ====================
+API_KEY = "sk-your-api-key-here"  # 粘贴您的 DeepSeek API 密钥
+API_BASE_URL = "https://api.deepseek.com/v1"
+API_MODEL = "deepseek-chat"  # 或 "deepseek-coder"
+API_TYPE = "deepseek"
+# ==================================================
+```
+
+### 3. 可用模型
+
+| 模型名称 | 适用场景 | 特点 |
+|---------|---------|------|
+| `deepseek-chat` | 通用对话 | 平衡性能，推荐使用 |
+| `deepseek-coder` | 代码相关 | 代码理解和生成能力强 |
+
+### 4. 费用说明
+
+- 新用户通常有免费额度
+- 按 token 计费，价格实惠
+- 详见 [定价页面](https://platform.deepseek.com/pricing)
+
+---
+
+## 🌐 Gemini API 配置
+
+### 1. 获取 API 密钥
+
+1. 访问 [Google AI Studio](https://aistudio.google.com/app/apikey)
+2. 使用 Google 账号登录
+3. 点击"Get API Key"
+4. 创建或选择项目
+5. 复制生成的 API 密钥
+
+### 2. 配置到应用
+
+编辑 `app.py` 文件的配置区域：
+
+```python
+# ==================== API 配置 ====================
+API_KEY = "AIzaSy-your-gemini-api-key-here"
+API_BASE_URL = "https://generativelanguage.googleapis.com/v1beta"
+API_MODEL = "gemini-1.5-flash"  # 或其他可用模型
+API_TYPE = "gemini"
+# ==================================================
+```
+
+### 3. 可用模型
+
+| 模型名称 | 特点 |
+|---------|------|
+| `gemini-1.5-flash` | 快速响应，适合实时交互 |
+| `gemini-1.5-pro` | 更强大的理解和生成能力 |
+| `gemini-pro` | 经典版本 |
+
+### 4. 注意事项
+
+- Gemini API 在某些地区可能需要网络代理
+- 中国大陆用户推荐使用 DeepSeek API
+
+---
+
+## 🔒 安全建议
+
+### 方法 1：环境变量（推荐）
+
+不要直接在代码中硬编码 API 密钥，使用环境变量：
+
+**Windows PowerShell：**
+```powershell
+$env:DEEPSEEK_API_KEY="sk-your-key"
+python app.py
+```
+
+**Linux/Mac：**
+```bash
+export DEEPSEEK_API_KEY="sk-your-key"
+python app.py
+```
+
+然后在代码中读取：
+```python
+import os
+API_KEY = os.environ.get("DEEPSEEK_API_KEY", "")
+```
+
+### 方法 2：配置文件
+
+创建 `config.json`（不要提交到 Git）：
+
+```json
+{
+  "api_key": "sk-your-key",
+  "api_base_url": "https://api.deepseek.com/v1",
+  "api_model": "deepseek-chat",
+  "api_type": "deepseek"
+}
+```
+
+在代码中加载：
+```python
+import json
+
+with open('config.json', 'r') as f:
+    config = json.load(f)
+    API_KEY = config['api_key']
+    API_BASE_URL = config['api_base_url']
+    # ...
+```
+
+---
+
+## ❓ 常见问题
+
+### Q1: API 请求失败，显示 401 错误
+
+**原因**：API 密钥无效或未配置
+
+**解决**：
+1. 检查 API 密钥是否正确复制（无多余空格）
+2. 确认密钥未过期或被删除
+3. 重新生成密钥并更新配置
+
+### Q2: 网络连接错误
+
+**原因**：网络问题或 API 服务不可达
+
+**解决**：
+1. DeepSeek 用户：检查国内网络连接
+2. Gemini 用户：可能需要配置网络代理
+3. 尝试切换到 DeepSeek API（国内友好）
+
+### Q3: 回复速度慢或超时
+
+**原因**：网络延迟或 API 负载高
+
+**解决**：
+1. 检查网络连接速度
+2. 调整超时设置（app.py 中的 `ClientTimeout`）
+3. 尝试切换模型（如 flash 版本）
+
+### Q4: 公式不渲染
+
+**原因**：Chatbot 未启用 LaTeX 支持
+
+**解决**：
+确认 `gr.Chatbot` 包含 `latex_delimiters` 参数：
+```python
+chatbot = gr.Chatbot(
+    latex_delimiters=[
+        {"left": "$$", "right": "$$", "display": True},
+        {"left": "$", "right": "$", "display": False}
+    ]
+)
+```
+
+### Q5: 如何限制 API 调用成本？
+
+**建议**：
+1. 在 API 平台设置使用限额
+2. 代码中添加 `max_tokens` 限制
+3. 监控 API 使用情况
+4. 使用轻量级模型（如 flash 版本）
+
+---
+
+## 📞 获取帮助
+
+- **DeepSeek 文档**：https://platform.deepseek.com/docs
+- **Gemini 文档**：https://ai.google.dev/docs
+- **项目 Issues**：[GitHub Issues 链接]
+
+---
+
+最后更新：2025年10月15日