DeepSeek API 优先使用与课堂配置规范

生效日期：2026-09-02
适用范围：V2 正式主课、AI 校园助手内训，以及后续使用 LLM API 的课程资产。V1 历史材料和已经形成的历史调用证据不倒改。

1. 全局决定

课程涉及真实大模型 API 调用时，默认优先使用 DeepSeek API。教学代码仍通过 Provider Adapter（供应商适配层）访问模型，业务代码不得直接依赖某一家供应商的专有字段。

这条规则同时保留两件事：

学生第一次真实接入有统一主路径，不需要在多个平台注册和配置之间来回切换；
当网络、账号、模型能力或企业客户环境发生变化时，只替换 Adapter 和配置，不重写业务逻辑。

其他 Provider 只用于经讲师批准的兼容性验证、横向比较或 DeepSeek 不可用时的补救，不再与 DeepSeek 并列为默认课堂路线。

2. 当前默认配置

项目	当前课堂默认	使用边界
Provider	`deepseek`	真实模型调用主路径
Base URL	`https://api.deepseek.com`	进入 Adapter 配置，不散落到业务代码
常规模型	`deepseek-v4-flash`	结构化提取、工具调用、客服问答和低成本关键证据
复杂推理模型	`deepseek-v4-pro`	只有任务确实需要、学生已确认预算时才使用
视觉实验模型	官方当前实验模型	不进入当前全班核心验收

模型名称、能力和价格会变化。讲师必须在开课前 G0 检查官方模型页；课件不写死单次调用金额，也不继续使用已经下线的旧模型别名。

3. 标准环境变量

提交到 Git 的 .env.example 使用下面的默认值，真实 Key 保持为空：

LLM_PROVIDER_ID=deepseek
LLM_MODEL_ID=deepseek-v4-flash
LLM_API_BASE_URL=https://api.deepseek.com
LLM_API_KEY=

应用如已有 W05_MODEL、LLM_BASE_URL 等局部变量名，可以保留原合同，但默认值必须等价。禁止把真实 Key 写进 .env.example、源码、Notebook、日志、截图、Prompt 或 Git 历史。

4. 最小真实调用

DeepSeek 提供 OpenAI 兼容接口。下面代码只用于讲清调用边界；正式项目仍从 Adapter 调用，不把它复制到每个业务模块。

import os
 
from openai import OpenAI
 
client = OpenAI(
    api_key=os.environ["LLM_API_KEY"],
    base_url=os.getenv("LLM_API_BASE_URL", "https://api.deepseek.com"),
)
 
response = client.chat.completions.create(
    model=os.getenv("LLM_MODEL_ID", "deepseek-v4-flash"),
    messages=[
        {"role": "system", "content": "你是商城客服，只使用给定业务事实回答。"},
        {"role": "user", "content": "500 元以内，想找通勤耳机。"},
    ],
    stream=False,
    # 常规结构化实验关闭思考模式，减少延迟、Token 和输出波动。
    extra_body={"thinking": {"type": "disabled"}},
)
 
print(response.choices[0].message.content)
print(response.usage)

2026-10-03核对DeepSeek合同：思考模式下temperature不生效；top_p仅在思考模式生效，有效范围0.95—1，低于0.95按0.95处理；非思考模式top_p固定为1，传值会忽略。不能把两者笼统写成“思考模式都不生效”。W04结构化提取、Function Calling和固定评测仍默认关闭思考模式，以temperature作为有效变量；比较推理能力时单独记录模式、Token和耗时。top_k未列为Chat Completions支持参数，不向DeepSeek强塞扩展字段。详见官方模式说明，模型升级后重新核验。

5. 各阶段怎样使用

阶段	默认路线	能证明什么
日常开发与回归	Replay / Mock / Fixture	本地协议、解析、校验、错误和业务流程可复现
关键真实验收	学生本人 DeepSeek API	当前账号、网络、模型和代码真实联通，并产生真实 usage/latency
兼容性实验	其他经批准 Provider Adapter	适配层可替换；不取代 DeepSeek 主路径

Replay 失败要修本地代码；DeepSeek 真实调用失败要记录原始错误并登记 Pending。不得用教师账号、同伴截图或另一个聊天产品代签学生本人 Evidence。

6. G0 与证据字段

每次真实调用至少记录：

provider=deepseek
model=
request_id=
input_tokens=
output_tokens=
cached_tokens=
latency_ms=
estimated_cost=
thinking_mode=enabled/disabled
status=passed/pending/failed

开课前必须验证账号可用、模型存在、结构化输出/Tool Calls/Streaming 等当天能力可用、Key 不泄露、请求能在预算上限内停止。价格与模型目录只引用当天官方页面，不把过期价格抄进长期课件。

众元AI学习空间

课程目录

11_DeepSeek API优先使用与课堂配置规范