Hongru/AutoControlCourse

Fork 0

Files

T

Hongru 0500304584 说明文档更新

2026-04-07 19:33:49 +08:00

17 KiB

Raw Blame History

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：创建新密钥

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

密钥格式示例：

sk-2292af2428d7419897ca1fb6e99ba6bc

2.3 配置到项目

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

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

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

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

Windows PowerShell：

$env:DEEPSEEK_API_KEY="sk-2292af2428d7419897ca1fb6e99ba6bc"
python app.py

Linux / macOS：

export DEEPSEEK_API_KEY="sk-2292af2428d7419897ca1fb6e99ba6bc"
python app.py

在 config.py 中读取环境变量：

import os

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

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

在项目根目录创建 config.json：

{
  "api_key": "sk-2292af2428d7419897ca1fb6e99ba6bc",
  "api_base_url": "https://api.deepseek.com/v1",
  "api_model": "deepseek-chat",
  "api_type": "deepseek"
}

在 config.py 中加载：

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 密钥

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

密钥格式示例：

AIzaSy-your-gemini-api-key-here

3.3 配置到项目

编辑 config.py 文件：

# ==================== 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）

常见错误：

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

排查方法：

确认密钥完整复制（无前后空格）
在官网控制台确认密钥状态
确认密钥已绑定正确的产品/服务

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：

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 默认提示词

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：强化公式推导

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

示例2：简化回答风格

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

示例3：英文问答模式

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 生产环境部署

推荐做法：

使用环境变量

# Docker 部署
docker run -p 7860:7860 \
  -e DEEPSEEK_API_KEY="sk-xxx" \
  autocontrol-course

使用配置服务

AWS Secrets Manager
Azure Key Vault
HashiCorp Vault

限制 API 访问

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

八、常见问题排查

8.1 API 请求失败

问题1：401 Unauthorized

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

问题2：403 Forbidden

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

问题3：429 Rate Limit

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

解决方法：

等待一段时间后重试
配置请求间隔（如每次提问间隔 2 秒）
升级到更高配额套餐

8.2 网络连接问题

问题：Connection Error / Timeout

排查步骤：

检查网络连接

# 测试 API 端点是否可达
curl -I https://api.deepseek.com/v1

检查代理设置（如需要）

# 在 chatbot.py 中配置代理
import os
os.environ["HTTP_PROXY"] = "http://proxy.example.com:8080"
os.environ["HTTPS_PROXY"] = "http://proxy.example.com:8080"

增加超时时间

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

8.3 回复质量问题

问题：回复内容不准确

解决方法：

优化系统提示词
- 明确指定回答风格
- 强调专业领域要求
- 添加示例回答
调整 temperature 参数
- 降低 temperature（0.3~0.5）使回答更确定
- 提高 temperature（0.7~1.0）使回答更有创造性
优化提问方式
- 提供更多上下文
- 明确问题范围
- 指出具体困惑点

问题：回复速度慢

解决方法：

使用较轻量的模型
- DeepSeek：选择 deepseek-chat 而非 deepseek-coder
- Gemini：选择 gemini-1.5-flash
减少 max_tokens
- 根据实际需求设置合理的最大长度
- 避免生成过长的回答
检查网络延迟
- 选择距离更近的 API 端点
- 考虑使用 CDN 加速

8.4 公式渲染问题

问题：LaTeX 公式不显示

可能原因：

Chatbot 未启用 LaTeX
MathJax 加载失败
公式语法错误

解决方法：

确认 gr.Chatbot 配置包含 latex_delimiters：

chatbot = gr.Chatbot(
    latex_delimiters=[
        {"left": "$$", "right": "$$", "display": True},
        {"left": "$", "right": "$", "display": False},
        {"left": "\\[", "right": "\\]", "display": True},
        {"left": "\\(", "right": "\\)", "display": False}
    ]
)

刷新页面重试
检查 LaTeX 语法是否正确

九、API 使用成本优化

9.1 成本构成

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

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

9.2 优化策略

策略1：精简提问

移除问题中不必要的修饰词
明确指出核心疑问
提供必要的上下文但不过度

策略2：合理限制输出长度

根据问题类型设置 max_tokens
简单问题设置较短限制
复杂问题允许更长回答

策略3：缓存常用回答

实现本地缓存机制
避免重复提问相同问题
减少 API 调用次数

策略4：选择合适模型

日常问答：使用轻量模型（flash 版本）
复杂问题：按需使用强大模型

9.3 预算设置

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

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

十、获取帮助

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日

17 KiB Raw Blame History Unescape Escape

API 配置指南

一、API 概述

1.1 平台支持的 AI API

1.2 为什么需要 API

1.3 配置优先级

二、DeepSeek API 配置

2.1 DeepSeek 简介

2.2 获取 API 密钥

2.3 配置到项目

2.4 DeepSeek 可用模型

2.5 费用说明

2.6 速率限制

三、Gemini API 配置

3.1 Gemini 简介

3.2 获取 API 密钥

3.3 配置到项目

3.4 Gemini 可用模型

3.5 网络访问说明

四、配置参数详解

4.1 完整配置参数表

4.2 API_KEY 配置

4.3 API_BASE_URL 配置

4.4 API_MODEL 配置

五、流式响应配置

5.1 什么是流式响应

5.2 当前配置

5.3 参数调优

六、系统提示词配置

6.1 系统提示词的作用

6.2 默认提示词

6.3 自定义提示词

七、安全建议

7.1 密钥安全原则

7.2 .gitignore 配置

7.3 生产环境部署

八、常见问题排查

8.1 API 请求失败

8.2 网络连接问题

8.3 回复质量问题

8.4 公式渲染问题

九、API 使用成本优化

9.1 成本构成

9.2 优化策略

9.3 预算设置

十、获取帮助

10.1 官方文档

10.2 技术支持

17 KiB

Raw Blame History