641 lines
17 KiB
Markdown
641 lines
17 KiB
Markdown
# 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日**
|