AutoControlCourse/API_CONFIG.md

# API 配置指南

> 本文档详细说明如何为自动控制理论AI+数智平台配置 DeepSeek 和 Gemini API，包括密钥获取、配置方法、参数调优与常见问题排查。

---

## 一、API 概述

### 1.1 平台支持的 AI API

本平台目前支持以下 AI API 提供商：

| API 提供商 | 支持模型 | 访问地区 | 推荐程度 |
|------------|----------|----------|----------|
| DeepSeek | deepseek-chat / deepseek-coder | 中国大陆 | ⭐⭐⭐⭐⭐ 首选 |
| Gemini (Google) | gemini-1.5-flash / gemini-1.5-pro | 部分受限 | ⭐⭐⭐ |

### 1.2 为什么需要 API

AI 智能问答模块依赖外部大语言模型 API 来实现：
- 自动控制理论专业问题的理解和回答
- LaTeX 数学公式的正确生成
- 多轮对话的上下文记忆

### 1.3 配置优先级

```
┌─────────────────────────────────────────┐
│  推荐配置顺序                            │
├─────────────────────────────────────────┤
│                                         │
│  1. DeepSeek API（国内访问，速度快）    │
│         ↓                               │
│  2. Gemini API（需要代理）              │
│         ↓                               │
│  3. 本地部署（需高配置服务器）          │
│                                         │
└─────────────────────────────────────────┘
```

---

## 二、DeepSeek API 配置

### 2.1 DeepSeek 简介

DeepSeek 是国内领先的 AI 大模型服务提供商，提供：
- **deepseek-chat**：通用对话模型，适合教育场景
- **deepseek-coder**：代码专用模型，适合技术问题
- **价格优惠**：相比 OpenAI 等海外服务商更具性价比
- **国内访问**：无需代理，网络延迟低

### 2.2 获取 API 密钥

**Step 1：访问 DeepSeek 平台**

打开浏览器，访问：https://platform.deepseek.com/

**Step 2：注册/登录账号**

- 使用手机号或邮箱注册
- 已注册用户直接登录

**Step 3：进入 API Keys 管理页面**

登录后，点击顶部导航栏的 "API Keys"：
```
https://platform.deepseek.com/api_keys
```

**Step 4：创建新密钥**

1. 点击 "创建新密钥" 按钮
2. 输入密钥名称（可自定义，如 "AutoControlCourse"）
3. 点击确认
4. **立即复制密钥**（只显示一次！）

**密钥格式示例：**
```
sk-2292af2428d7419897ca1fb6e99ba6bc
```

### 2.3 配置到项目

**方法一：直接编辑 config.py（最简单）**

1. 打开项目根目录下的 `config.py` 文件
2. 找到 API 配置区域
3. 将 `API_KEY` 替换为您的密钥

```python
# ==================== API 配置 ====================
API_KEY = "sk-2292af2428d7419897ca1fb6e99ba6bc"  # 替换为您的密钥
API_BASE_URL = "https://api.deepseek.com/v1"
API_MODEL = "deepseek-chat"  # 或 "deepseek-coder"
API_TYPE = "deepseek"
# ==================================================
```

**方法二：使用环境变量（推荐用于生产环境）**

1. **Windows PowerShell：**
```powershell
$env:DEEPSEEK_API_KEY="sk-2292af2428d7419897ca1fb6e99ba6bc"
python app.py
```

2. **Linux / macOS：**
```bash
export DEEPSEEK_API_KEY="sk-2292af2428d7419897ca1fb6e99ba6bc"
python app.py
```

3. **在 config.py 中读取环境变量：**
```python
import os

API_KEY = os.environ.get("DEEPSEEK_API_KEY", "")
```

**方法三：创建独立配置文件**

1. 在项目根目录创建 `config.json`：
```json
{
  "api_key": "sk-2292af2428d7419897ca1fb6e99ba6bc",
  "api_base_url": "https://api.deepseek.com/v1",
  "api_model": "deepseek-chat",
  "api_type": "deepseek"
}
```

2. 在 `config.py` 中加载：
```python
import json
import os

config_path = os.path.join(os.path.dirname(__file__), "config.json")
if os.path.exists(config_path):
    with open(config_path, "r") as f:
        config_data = json.load(f)
        API_KEY = config_data.get("api_key", "")
        API_BASE_URL = config_data.get("api_base_url", "https://api.deepseek.com/v1")
        API_MODEL = config_data.get("api_model", "deepseek-chat")
        API_TYPE = config_data.get("api_type", "deepseek")
else:
    API_KEY = ""
    API_BASE_URL = "https://api.deepseek.com/v1"
    API_MODEL = "deepseek-chat"
    API_TYPE = "deepseek"
```

### 2.4 DeepSeek 可用模型

| 模型名称 | 适用场景 | 特点 | 推荐场景 |
|----------|----------|------|----------|
| deepseek-chat | 通用对话 | 平衡性能与成本 | ⭐ 日常学习问答 |
| deepseek-coder | 代码相关 | 代码理解能力强 | 专业开发者 |

### 2.5 费用说明

| 项目 | 说明 |
|------|------|
| 新用户优惠 | 通常有免费额度 |
| 计费方式 | 按 token 用量计费 |
| 价格水平 | 比 OpenAI 低约 80% |
| 查看用量 | https://platform.deepseek.com/usage |
| 详细定价 | https://platform.deepseek.com/pricing |

### 2.6 速率限制

| 账户类型 | RPM（每分钟请求数） | TPM（每分钟 Token 数） |
|----------|---------------------|------------------------|
| 免费用户 | 60 | 100,000 |
| 付费用户 | 最高可达 2000 | 根据套餐 |

---

## 三、Gemini API 配置

### 3.1 Gemini 简介

Gemini 是 Google 开发的 AI 大模型，具备：
- **gemini-1.5-flash**：快速响应，适合实时交互
- **gemini-1.5-pro**：更强大的理解和生成能力
- **多模态**：支持文本、图像等多种输入

**注意：** Gemini API 在中国大陆可能需要网络代理才能访问。

### 3.2 获取 API 密钥

**Step 1：访问 Google AI Studio**

打开浏览器，访问：https://aistudio.google.com/app/apikey

**Step 2：登录 Google 账号**

使用您的 Google 账号登录。

**Step 3：获取 API 密钥**

1. 点击 "Get API Key"
2. 选择或创建项目
3. 点击 "Create API Key"
4. 复制生成的密钥

**密钥格式示例：**
```
AIzaSy-your-gemini-api-key-here
```

### 3.3 配置到项目

编辑 `config.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"  # 或 "gemini-1.5-pro"
API_TYPE = "gemini"
# ==================================================
```

### 3.4 Gemini 可用模型

| 模型名称 | 特点 | 适用场景 | 响应速度 |
|----------|------|----------|----------|
| gemini-1.5-flash | 快速响应 | 实时交互 | ⚡⚡⚡⚡⚡ |
| gemini-1.5-pro | 更强能力 | 复杂问题 | ⚡⚡⚡ |
| gemini-pro | 经典版本 | 一般对话 | ⚡⚡⚡⚡ |

### 3.5 网络访问说明

| 地区 | 访问状态 | 解决方案 |
|------|----------|----------|
| 中国大陆 | 可能受限 | 使用 DeepSeek API 或配置代理 |
| 港澳台 | 基本正常 | 直连或使用代理 |
| 其他地区 | 正常 | 直连 |

---

## 四、配置参数详解

### 4.1 完整配置参数表

| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| API_KEY | string | "" | API 密钥，必填 |
| API_BASE_URL | string | "https://api.deepseek.com/v1" | API 基础 URL |
| API_MODEL | string | "deepseek-chat" | 模型名称 |
| API_TYPE | string | "deepseek" | API 类型：deepseek 或 gemini |
| SERVER_NAME | string | "0.0.0.0" | 监听网络接口 |
| SERVER_PORT | int | 7860 | 监听端口 |
| SHARE | bool | True | 是否创建公开链接 |

### 4.2 API_KEY 配置

**格式：** `sk-` 开头（DeepSeek）或 `AIzaSy` 开头（Gemini）

**常见错误：**
- 密钥包含多余空格（复制时容易带入）
- 密钥过期或被删除
- 密钥未激活对应服务

**排查方法：**
1. 确认密钥完整复制（无前后空格）
2. 在官网控制台确认密钥状态
3. 确认密钥已绑定正确的产品/服务

### 4.3 API_BASE_URL 配置

| API 类型 | 正确 URL | 错误示例 |
|----------|----------|----------|
| DeepSeek | https://api.deepseek.com/v1 | https://api.deepseek.com/ |
| Gemini | https://generativelanguage.googleapis.com/v1beta | 其他 URL |

### 4.4 API_MODEL 配置

**DeepSeek 模型：**

| 模型 | 上下文长度 | 适用场景 |
|------|------------|----------|
| deepseek-chat | 64K tokens | 通用对话，推荐 |
| deepseek-coder | 64K tokens | 代码相关问题 |

**Gemini 模型：**

| 模型 | 上下文长度 | 适用场景 |
|------|------------|----------|
| gemini-1.5-flash | 1M tokens | 快速响应 |
| gemini-1.5-pro | 1M tokens | 复杂任务 |
| gemini-pro | 32K tokens | 一般对话 |

---

## 五、流式响应配置

### 5.1 什么是流式响应

流式响应（Streaming）是指 AI 边生成答案边返回，用户可以实时看到回答内容，而不必等待完整答案生成完毕。

**优点：**
- 减少等待感
- 及时了解回答方向
- 支持长答案的快速预览

### 5.2 当前配置

本平台默认启用流式响应，配置位于 `chatbot.py`：

```python
payload = {
    "model": config.API_MODEL,
    "messages": messages_for_api,
    "stream": True,        # 启用流式响应
    "temperature": 0.7,   # 创造性参数
    "max_tokens": 2048    # 最大 Token 数
}
```

### 5.3 参数调优

| 参数 | 取值范围 | 说明 | 调整建议 |
|------|----------|------|----------|
| temperature | 0.0 ~ 2.0 | 创造性控制，值越低越确定 | 学习问答建议 0.3~0.7 |
| max_tokens | 1 ~ 32768 | 单次回复最大 Token 数 | 长回答设为 4096 |
| top_p | 0.0 ~ 1.0 | 核采样参数 | 通常保持默认 1.0 |
| frequency_penalty | -2.0 ~ 2.0 | 频率惩罚 | 保持默认 0.0 |
| presence_penalty | -2.0 ~ 2.0 | 存在惩罚 | 保持默认 0.0 |

---

## 六、系统提示词配置

### 6.1 系统提示词的作用

系统提示词（System Prompt）定义了 AI 助手的角色定位、回答风格和专业范围。本平台的默认提示词位于 `chatbot.py`。

### 6.2 默认提示词

```python
system_prompt = """你是一位精通自动控制原理的专家教授。请用清晰、准确、专业的中文来回答有关自动控制课程内容的问题。

重要规则：
1. 当需要表达数学公式时，必须使用 LaTeX 格式
2. 行内公式使用 $公式$ 或 \\(公式\\)
3. 独立公式使用 $$公式$$ 或 \\[公式\\]
4. 例如：传递函数可以写成 $G(s) = \\frac{K}{s(s+1)}$
5. 二阶系统标准形式：$$G(s) = \\frac{\\omega_n^2}{s^2 + 2\\zeta\\omega_n s + \\omega_n^2}$$

请在适当的时候使用公式和示例来辅助解释。"""
```

### 6.3 自定义提示词

根据教学需求，您可以修改系统提示词：

**修改方法：** 编辑 `chatbot.py` 中的 `system_prompt` 变量。

**示例1：强化公式推导**
```python
system_prompt = """你是一位严谨的自动控制原理教授。在回答问题时：
1. 注重公式的推导过程
2. 每一步推导都要清晰呈现
3. 适当使用 LaTeX 公式
4. 结合实例帮助理解"""
```

**示例2：简化回答风格**
```python
system_prompt = """你是一位friendly的自动控制课程助教。请用简洁、易懂的语言回答问题：
1. 尽量少用专业术语
2. 多用生活实例类比
3. 重要公式用 LaTeX 展示"""
```

**示例3：英文问答模式**
```python
system_prompt = """You are an expert professor of Automatic Control Theory.
Answer questions in English using LaTeX for mathematical formulas.
Focus on clarity and practical examples."""
```

---

## 七、安全建议

### 7.1 密钥安全原则

**❌ 不要做的事情：**
- 在代码中硬编码密钥并提交到 Git
- 在公开场合分享密钥
- 使用过于简单的密钥

**✅ 推荐的做法：**
- 使用环境变量存储密钥
- 将敏感配置文件加入 .gitignore
- 定期更换密钥
- 为不同项目使用不同的密钥

### 7.2 .gitignore 配置

确保以下文件不会被提交到 Git：

```
# API 配置文件
config.json
secrets.json
.env

# Python
__pycache__/
*.pyc
*.pyo

# IDE
.vscode/
.idea/

# 模型权重（较大文件）
Model/data/*.pth
```

### 7.3 生产环境部署

**推荐做法：**

1. **使用环境变量**
```bash
# Docker 部署
docker run -p 7860:7860 \
  -e DEEPSEEK_API_KEY="sk-xxx" \
  autocontrol-course
```

2. **使用配置服务**
- AWS Secrets Manager
- Azure Key Vault
- HashiCorp Vault

3. **限制 API 访问**
- 设置 API 密钥的使用 IP 白名单
- 配置请求频率限制
- 开启使用量告警

---

## 八、常见问题排查

### 8.1 API 请求失败

**问题1：401 Unauthorized**

| 可能原因 | 解决方法 |
|----------|----------|
| API 密钥无效 | 检查密钥是否正确复制 |
| 密钥已过期 | 在平台控制台重新创建密钥 |
| 密钥未激活 | 确认密钥已绑定正确服务 |

**问题2：403 Forbidden**

| 可能原因 | 解决方法 |
|----------|----------|
| 账户余额不足 | 充值或等待免费额度刷新 |
| 权限不足 | 检查账户权限设置 |
| 服务未开通 | 在控制台开通对应服务 |

**问题3：429 Rate Limit**

| 可能原因 | 解决方法 |
|----------|----------|
| 请求过于频繁 | 降低请求频率 |
| 超出 TPM/RPM 限制 | 等待或升级套餐 |
| 并发数过高 | 减少并发请求数 |

**解决方法：**
1. 等待一段时间后重试
2. 配置请求间隔（如每次提问间隔 2 秒）
3. 升级到更高配额套餐

### 8.2 网络连接问题

**问题：Connection Error / Timeout**

**排查步骤：**

1. **检查网络连接**
```bash
# 测试 API 端点是否可达
curl -I https://api.deepseek.com/v1
```

2. **检查代理设置（如需要）**
```python
# 在 chatbot.py 中配置代理
import os
os.environ["HTTP_PROXY"] = "http://proxy.example.com:8080"
os.environ["HTTPS_PROXY"] = "http://proxy.example.com:8080"
```

3. **增加超时时间**
```python
# 在 aiohttp 请求中增加 timeout
async with session.post(api_url, json=payload, headers=headers,
                        timeout=aiohttp.ClientTimeout(total=120)) as response:
```

### 8.3 回复质量问题

**问题：回复内容不准确**

**解决方法：**

1. **优化系统提示词**
   - 明确指定回答风格
   - 强调专业领域要求
   - 添加示例回答

2. **调整 temperature 参数**
   - 降低 temperature（0.3~0.5）使回答更确定
   - 提高 temperature（0.7~1.0）使回答更有创造性

3. **优化提问方式**
   - 提供更多上下文
   - 明确问题范围
   - 指出具体困惑点

**问题：回复速度慢**

**解决方法：**

1. **使用较轻量的模型**
   - DeepSeek：选择 deepseek-chat 而非 deepseek-coder
   - Gemini：选择 gemini-1.5-flash

2. **减少 max_tokens**
   - 根据实际需求设置合理的最大长度
   - 避免生成过长的回答

3. **检查网络延迟**
   - 选择距离更近的 API 端点
   - 考虑使用 CDN 加速

### 8.4 公式渲染问题

**问题：LaTeX 公式不显示**

**可能原因：**

1. **Chatbot 未启用 LaTeX**
2. **MathJax 加载失败**
3. **公式语法错误**

**解决方法：**

1. 确认 `gr.Chatbot` 配置包含 `latex_delimiters`：
```python
chatbot = gr.Chatbot(
    latex_delimiters=[
        {"left": "$$", "right": "$$", "display": True},
        {"left": "$", "right": "$", "display": False},
        {"left": "\\[", "right": "\\]", "display": True},
        {"left": "\\(", "right": "\\)", "display": False}
    ]
)
```

2. 刷新页面重试

3. 检查 LaTeX 语法是否正确

---

## 九、API 使用成本优化

### 9.1 成本构成

API 使用成本主要由以下因素决定：

| 因素 | 说明 | 优化建议 |
|------|------|----------|
| 输入 Token 数 | 问题文本长度 | 精简提问 |
| 输出 Token 数 | 回答文本长度 | 限制 max_tokens |
| 请求次数 | 提问频率 | 减少无效请求 |
| 模型单价 | 不同模型价格不同 | 选择性价比模型 |

### 9.2 优化策略

**策略1：精简提问**
- 移除问题中不必要的修饰词
- 明确指出核心疑问
- 提供必要的上下文但不过度

**策略2：合理限制输出长度**
- 根据问题类型设置 max_tokens
- 简单问题设置较短限制
- 复杂问题允许更长回答

**策略3：缓存常用回答**
- 实现本地缓存机制
- 避免重复提问相同问题
- 减少 API 调用次数

**策略4：选择合适模型**
- 日常问答：使用轻量模型（flash 版本）
- 复杂问题：按需使用强大模型

### 9.3 预算设置

在 DeepSeek 控制台设置用量限制：

1. 访问 https://platform.deepseek.com/
2. 进入 "用量限制" 设置
3. 设置月度预算上限
4. 开启用量告警

---

## 十、获取帮助

### 10.1 官方文档

| 资源 | 链接 |
|------|------|
| DeepSeek 文档 | https://platform.deepseek.com/docs |
| Gemini 文档 | https://ai.google.dev/docs |
| Gradio 文档 | https://gradio.app/docs |

### 10.2 技术支持

| 渠道 | 联系方式 |
|------|----------|
| 项目问题 | GitHub Issues |
| API 问题 | 平台官方支持 |
| 使用咨询 | 课程教师/助教 |

---

**最后更新：2026年4月7日**