Skip to content

第 1 章:第一次调用——从网页聊天到 API ​

本章目标:不管你会不会写代码,读完都能让程序去问模型,并拿到第一份周报草稿。

开篇:周五下午的半小时 ​

周五四点,该交周报了。你打开 DeepSeek 网页版,把这周记在备忘录里的几行流水账粘进去,说「帮我整理成周报」。它写得挺像样,你复制、粘贴到邮件里,发出去。

下周五,同样的事再做一遍。再下周,还是一遍。

每一步都是你在搬:从备忘录搬到网页,从网页搬到邮件。模型其实早就能干这活了,缺的是一个不用你搬的入口。 这个入口就是 API。

这一章结束时,你会有一个十几行的 Python 脚本:读进你这周的记录文件,打印出一份周报草稿。

学完这一章,你能:

  • 说清网页聊天和 API 调用的区别
  • 拿到 API Key,并用一行 curl 问模型一句话
  • 用 Python 读一个文件、交给模型、打印回答

1.1 网页和 API,差在哪 ​

同一个模型的两个入口:网页聊天返回给人看的文字,API 调用返回给程序处理的 JSON

两条路通向的是同一个模型,回答的质量没有区别。差别只在最后一格:

  • 网页的回答是给你看的。想用,得你自己复制。
  • API 的回答是一段 JSON,给程序看的。程序拿到之后,想存成文件、发邮件、每周五定时跑,都只是再多写几行代码。

所以学 API 不是为了「更高级」,是为了把你自己从流程里拿出来。


1.2 拿到 API Key ​

API Key 是一串 sk- 开头的字符,相当于你账户的钥匙:带着它的请求,花的是你的余额。

  1. 打开 DeepSeek 开放平台(platform.deepseek.com),用手机号注册登录
  2. 左侧菜单进「API keys」,点「创建 API key」,名字随便起,比如 weekly-report
  3. 立刻复制保存:这串 Key 只在创建时完整显示一次
  4. 到「充值」页充几块钱,学完整门课够用

DeepSeek 开放平台的 API keys 页:右上角「创建 API key」,列表里的 Key 只显示首尾几位

列表里的 Key 只显示首尾几位,完整的那串只在创建时出现一次,所以第 3 步一定要当场存好。

DeepSeek 开放平台的充值页:选金额和支付方式,最低一档 10 元

预设金额最低一档是 10 元。按第 5 章算的账,一份周报不到一分钱,10 元够学完整门课还绰绰有余。

踩坑:Key 等于钱

Key 不要发到群里、不要截图外传、不要写进代码再提交到 GitHub。公开仓库里的 Key 会被扫描程序很快捡走。万一泄露,回到「API keys」页把它删掉、重新创建一个。

接下来把 Key 放进环境变量,后面的命令和代码都从这里读,不用把 Key 写进文件:

bash
export DEEPSEEK_API_KEY="sk-你的Key"
powershell
$env:DEEPSEEK_API_KEY="sk-你的Key"

这样设置只在当前终端窗口有效,关掉就没了。第 6 章再讲怎么长期保存。


1.3 不写代码,先用 curl 问一句 ​

curl 是终端里发网络请求的工具,macOS、Linux 和 Windows 10 以上都自带。在同一个终端窗口里粘贴:

bash
curl https://api.deepseek.com/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -d '{
    "model": "deepseek-flash",
    "messages": [{"role": "user", "content": "用一句话介绍你自己"}]
  }'

Windows PowerShell 里 curl 是别的命令的别名,引号规则也不同。Windows 读者可以跳过这一节,直接看 1.5 的 Python 版本。

几秒后,屏幕上会出现一大段 JSON。下面是我写这一章时真实跑出来的结果,去掉了几个暂时用不上的字段:

json
{
  "model": "deepseek-flash",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "我是DeepSeek,由深度求索公司创造的AI助手,致力于用热情细腻的方式帮你解答问题、处理任务。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 8, "completion_tokens": 26, "total_tokens": 34 }
}

content 里那句话,就是模型的回答。你已经完成了第一次 API 调用。

模型名会变,以模型列表为准

写这一章时(2026 年 11 月),DeepSeek 的模型列表里只有两个:deepseek-flash(Flash 轻量版,本课默认用它)和 deepseek-v4-pro(Pro 版)。两者差多少钱,第 5 章再算。网上很多教程还在写旧名 deepseek-chat,我试过,现在还能用,但响应里的 model 字段会显示 deepseek-flash:旧名只是转发到了新模型。

如果哪天请求报「model not found」,用下面这条命令查当前可用的模型,换掉名字就行:

bash
curl https://api.deepseek.com/models -H "Authorization: Bearer $DEEPSEEK_API_KEY"

1.4 拆开看:发出去什么,拿回来什么 ​

刚才那条命令和那段 JSON,拆开就是这几样:

一次 API 调用的结构:请求包含地址、Key、模型名、消息;响应包含回答正文、结束原因、token 用量、模型名

这一章只需要盯住红色那一行:choices[0].message.content 就是回答。 其余字段后面几章会一个个用上:

字段什么时候用到
messages第 2 章:多轮对话、给模型定角色,都是在这里做文章
finish_reason第 3 章:回答被截断时,它不是 stop
usage第 5 章:算这次花了多少钱

1.5 换成 Python ​

curl 适合试一下,真要干活还是写代码。先装官方 SDK:

bash
pip install openai

装的是 OpenAI 的包,因为 DeepSeek 的接口和 OpenAI 是同一套格式,只要把地址换成 DeepSeek 的。这也是第 7 章「换一家模型只改两行」的伏笔。

新建 hello.py:

python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],  # 从环境变量读 Key
    base_url="https://api.deepseek.com",     # 换成 DeepSeek 的地址
)

resp = client.chat.completions.create(
    model="deepseek-flash",
    messages=[{"role": "user", "content": "用一句话介绍你自己"}],
)
print(resp.choices[0].message.content)

在设过环境变量的终端里运行 python hello.py,4 秒左右打印出一句自我介绍。我这次拿到的是:

text
我是乐于用中文为你提供信息和帮助的AI助手。

和 1.3 里 curl 那次的措辞不一样,这是正常的:每次调用都是模型重新生成一遍。SDK 替你拼好了请求、解析好了 JSON,resp.choices[0].message.content 和图里红色那一行是同一个东西。


1.6 第一份周报草稿 ​

现在让它干正事。新建 notes.md,写几行这周的流水账,不用讲究格式:

markdown
- 周一 修登录页偶发 500,查到是 Redis 连接池满了,调大到 50
- 周二 和产品对月报导出需求,要支持 Excel
- 周二 review 小王的 PR,提了 3 条意见
- 周三 月报导出写完一半,Excel 样式还没调
- 周四 线上又报一次 500,这次不是连接池,日志里是超时,还在查
- 周五 下午周会

再新建 weekly.py,和 hello.py 只差两处:读文件,把内容拼进问题里。

python
import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(api_key=os.environ["DEEPSEEK_API_KEY"], base_url="https://api.deepseek.com")

notes = Path("notes.md").read_text(encoding="utf-8")

resp = client.chat.completions.create(
    model="deepseek-flash",
    messages=[{"role": "user", "content": f"把下面这周的工作记录整理成一份周报:\n\n{notes}"}],
)
print(resp.choices[0].message.content)

运行 python weekly.py,7 秒左右,一份像模像样的周报就出来了:分「本周完成情况 / 风险与待跟进 / 下周计划」三块,6 条流水账逐条展开,还替你想好了下周要做什么。

展开看完整输出(真实运行结果,未改一字)
markdown
# 本周工作周报

**周期:** 本周  
**汇报人:** [姓名]  

## 一、本周工作完成情况

1. **登录页偶发 500 问题处理**
   - 定位到 Redis 连接池满导致,已将连接池调大至 50。
   - 后续需持续观察线上运行情况,确认问题是否稳定解决。

2. **月报导出需求对接**
   - 与产品沟通月报导出需求,明确需要支持 Excel 导出。

3. **代码评审**
   - Review 小王 PR,提出 3 条修改意见,待跟进修改情况。

4. **月报导出功能开发**
   - 已完成约一半开发工作。
   - Excel 样式尚未调整,后续继续完善。

5. **线上 500 问题跟进**
   - 周四线上再次出现 500,经排查不是 Redis 连接池问题,日志显示为超时。
   - 目前仍在继续排查中。

6. **会议**
   - 参加周五下午周会,同步本周工作进展。

## 二、风险与待跟进事项

- 周四线上 500 超时问题尚未定位闭环,需继续排查并关注线上稳定性。
- 月报导出功能尚未完成,Excel 样式和后续联调需继续推进。
- 登录页 Redis 连接池调整后需观察是否还有偶发 500。

## 三、下周工作计划

1. 继续排查线上 500 超时问题,推动问题闭环。
2. 完成月报导出功能开发及 Excel 样式调整,推进联调验证。
3. 跟进小王 PR 意见修改及合入情况。
4. 持续关注登录页 Redis 连接池调整后的线上表现。

这就是周报生成器的第一版。 十几行代码,以后每周五改一下 notes.md、跑一次就行。

但别急着交。我用同一份 notes.md 连跑了三次,结果是这样的:

第几次一级标题长度
1本周工作完成情况 / 风险与待跟进事项 / 下周工作计划667 字符
2本周工作完成与推进情况 / 风险与待跟进事项 / 下周初步计划593 字符
3本周工作概览 / 重点工作明细(再按线上问题、需求、评审、会议分 4 组)/ 问题与风险 / 下周计划615 字符

输入只有 6 行、164 个字符。对着这张表和上面的完整输出,能看出三个问题:

  1. 太长,还会替你加话:164 个字符变成 600 多字符,翻了将近 4 倍,多出来一行「汇报人:[姓名]」,还有「后续需持续观察线上运行情况」这种你没写过的话。想让它「精简一点、别加我没做的事」,现在只能改代码里那句问题,整个重跑
  2. 格式每次都不一样:三次三种结构,第 3 次还多分了一层。交给领导的周报,不能这周一个样、下周一个样
  3. 要干等:每次 7 秒左右,回答是整段一次性出来的。记录越长,盯着空白终端的时间越长

这三个问题,正好对应接下来的第 2、3、4 章。


试一试 ​

花 5 分钟,每条只改一处,看结果怎么变:

  • [ ] 把 notes.md 换成你自己这周真实的记录,跑一次
  • [ ] 把问题改成「……整理成一份周报,不超过 100 字」,对比长度
  • [ ] 把 print(resp.choices[0].message.content) 换成 print(resp),看看完整的响应里还有什么

踩坑:三个最常见的报错

  • 401 / Authentication Fails:Key 不对。最常见的原因是换了个终端窗口,环境变量没了,重新 export 一次
  • 402 / Insufficient Balance:余额不足,去充值页看一眼
  • KeyError: 'DEEPSEEK_API_KEY':Python 没读到环境变量。确认你是在设置过它的同一个终端窗口里运行的

本章小结 ​

要点说明
API 是什么同一个模型的另一个入口,回答交给程序而不是交给你
API Keysk- 开头,等于你的余额;放环境变量,不进代码、不进 Git
一次调用发出去:地址 + Key + 模型名 + 消息;拿回来:重点看 choices[0].message.content
Python SDKpip install openai,base_url 指向 DeepSeek
周报生成器 v1读 notes.md → 拼进问题 → 打印回答

下一章预告 ​

周报能出来了,但想让它「问题排查放最前面、再精简一点」,现在只能整个重来。原因是模型根本不记得上一句——每次调用,它看到的都是一张白纸。

下一章拆开 messages:给模型定一个固定角色,再让它在上一版的基础上改。

👉 第 2 章:消息结构——模型其实没有记忆

本文阅读--次|全站访问--次|访客--人