第一次调用大模型 API：从零开始（以 DeepSeek 为主）

理论读再多，不如跑一次代码。本篇的目标是让你在 30 分钟内完成第一次 LLM API 调用，拿到真实的模型响应，理解请求和响应的结构。

每段代码之后都有"你应该看到什么输出"说明，让你清楚知道成功是什么样子。

1.1 准备工作

1.1.1 第一步：获取 API Key

API Key（密钥）是你访问 AI 服务的凭证，就像账号密码一样，有了它你的程序才能调用大模型。

DeepSeek（推荐，国内直连）：访问 platform.deepseek.com，注册账号后在 API Keys 页面创建一个 Key。Key 格式为 sk-...，创建后只显示一次，立即保存。

OpenAI：访问 platform.openai.com，在 API Keys 页面创建，格式也是 sk-...。需要国际信用卡充值。

学习阶段推荐使用 DeepSeek——价格是 OpenAI 的 1/30，国内直连，同样的 OpenAI SDK 格式，换个 base_url 即可。

1.1.2 第二步：安装 SDK

SDK（Software Development Kit，软件开发工具包）是官方提供的代码库，帮你省去手写网络请求的麻烦。DeepSeek 兼容 OpenAI SDK，统一使用 openai 包：

bash

# 推荐使用 uv 管理虚拟环境（比 pip 更快）
uv init my-first-llm
cd my-first-llm
uv add openai python-dotenv

# 或者用 pip
pip install openai python-dotenv

python-dotenv 用于从 .env 文件加载 API Key，是管理密钥的最佳实践。

1.1.3 第三步：配置 API Key（用 .env 文件）

不要把 Key 硬编码在代码里。 一旦代码提交到 git，密钥就等于泄露了。

在项目根目录创建 .env 文件：

bash

# .env
DEEPSEEK_API_KEY=sk-你的key

然后把 .env 加入 .gitignore：

bash

echo ".env" >> .gitignore

这样密钥就不会被提交到代码仓库。

大模型 API 完整调用流程——从客户端发起请求到解析返回结果

1.2 第一次调用

1.2.1 这段代码在做什么

下面的代码做了三件事：

从环境变量读取 API Key，创建客户端
构建一个消息列表（包含角色和内容），发送给模型
从响应中提取文本内容并打印

python

import os
from openai import OpenAI
from dotenv import load_dotenv

# 从 .env 文件加载环境变量（包括 API Key）
load_dotenv()

# 创建客户端：指向 DeepSeek 的 API 端点
client = OpenAI(
    base_url="https://api.deepseek.com",
    api_key=os.environ.get("DEEPSEEK_API_KEY")
)

# 发送请求
response = client.chat.completions.create(
    model="deepseek-chat",           # 使用 DeepSeek 通用对话模型
    max_tokens=1024,                  # 最大输出 token 数
    messages=[
        {"role": "user", "content": "你好，用一句话介绍一下你自己。"}
    ]
)

# 提取并打印模型的回答
print(response.choices[0].message.content)

1.2.2 你应该看到什么输出

运行后，你会看到模型的自我介绍，类似：

code

你好！我是 DeepSeek，一个由深度求索公司研发的 AI 助手，致力于通过人工智能技术帮助用户解决问题和获取知识。

这就完成了你的第一次 LLM API 调用。

python

# ⚠️ 生产环境建议补充错误处理（本篇后面"错误处理"章节有完整示例）：
# import time
# from openai import OpenAI, RateLimitError, APITimeoutError, AuthenticationError
#
# try:
#     response = client.chat.completions.create(
#         model="deepseek-chat",
#         max_tokens=1024,
#         messages=[{"role": "user", "content": "你好"}]
#     )
# except AuthenticationError:
#     raise  # API Key 无效，无需重试，直接抛出
# except RateLimitError:
#     time.sleep(60)  # 限流，等待后重试
#     raise
# except APITimeoutError:
#     raise  # 超时，向上抛出由调用方决定是否重试
# except Exception as e:
#     raise  # 其他未知错误，向上抛出

1.3 理解响应结构

响应对象包含的信息比你以为的多很多：

python

# 打印完整的响应对象
print(response)

1.3.1 你应该看到什么输出

code

ChatCompletion(
  id='msg_xxx',
  choices=[
    Choice(
      finish_reason='stop',      # 'stop'=正常结束，'length'=达到token上限
      index=0,
      message=ChatCompletionMessage(
        content='你好！我是 DeepSeek...',
        role='assistant'
      )
    )
  ],
  model='deepseek-chat',
  usage=CompletionUsage(
    completion_tokens=32,         # 模型输出的 token 数
    prompt_tokens=15,             # 输入（Prompt）的 token 数
    total_tokens=47               # 总计
  )
)

几个关键字段：

choices[0].message.content：模型的回答文本，这是你最常用的字段
choices[0].finish_reason：
- 'stop'：正常结束，模型说完了
- 'length'：达到 max_tokens 上限被截断——如果输出不完整，先检查这个字段
usage：本次调用消耗的 token 数，直接影响费用

1.3.2 查看 token 消耗

python

print(f"输入 tokens: {response.usage.prompt_tokens}")
print(f"输出 tokens: {response.usage.completion_tokens}")
print(f"总计 tokens: {response.usage.total_tokens}")

1.4 理解请求参数

python

response = client.chat.completions.create(
    model="deepseek-chat",        # 模型选择
    max_tokens=1024,               # 最大输出 token 数
    temperature=0.7,               # 随机性（0=确定性，1=最大随机）
    messages=[
        {"role": "system", "content": "你是一个专业的 Python 教师，回答要简洁清晰。"},
        {"role": "user", "content": "什么是列表推导式？"}
    ]
)

model：选择哪个版本的模型。

deepseek-chat：DeepSeek 通用对话模型，性价比最高
deepseek-reasoner：推理增强版，适合数学、逻辑推理等复杂任务，更慢更贵

max_tokens：输出的最大 token 数。设太小会截断输出（这是新手最常踩的坑）。通常 1024-2048 足够，需要长输出时设到 4096 或更高。

temperature：控制输出的随机性。0 接近确定性（适合代码生成、数据提取），0.7-1 有更多创意变化（适合写作、头脑风暴）。详见第 6 章第 06 篇。

messages 中的 system 角色：系统提示（System Prompt），在对话开始前给模型下达的"总指令"，定义模型的角色和行为。格式要求放在 System Prompt 里比放在 User Prompt 里稳定得多。

1.5 切换到 OpenAI

DeepSeek 和 OpenAI 使用完全相同的 SDK，只需切换 base_url 和 api_key：

python

from openai import OpenAI
import os

# DeepSeek（推荐）
client = OpenAI(
    base_url="https://api.deepseek.com",
    api_key=os.environ.get("DEEPSEEK_API_KEY")
)

# OpenAI（切换非常简单，只改两行）
# client = OpenAI()  # 自动读取 OPENAI_API_KEY 环境变量

response = client.chat.completions.create(
    model="deepseek-chat",    # OpenAI 改成 "gpt-4o" 或 "gpt-4o-mini"
    max_tokens=1024,
    messages=[
        {"role": "system", "content": "你是一个专业的 Python 教师。"},
        {"role": "user", "content": "什么是列表推导式？"}
    ]
)

print(response.choices[0].message.content)
print(f"输入 tokens: {response.usage.prompt_tokens}")
print(f"输出 tokens: {response.usage.completion_tokens}")

两者的接口完全一致，切换模型提供商只需改两行代码。

1.6 错误处理

1.6.1 这段代码在做什么

捕获最常见的几种 API 错误，给出对应的处理方式：

python

import os
from openai import OpenAI, APIConnectionError, RateLimitError, APIStatusError, AuthenticationError
from dotenv import load_dotenv

load_dotenv()

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

try:
    response = client.chat.completions.create(
        model="deepseek-chat",
        max_tokens=1024,
        messages=[{"role": "user", "content": "你好"}]
    )
    print(response.choices[0].message.content)

except AuthenticationError as e:
    print(f"API Key 无效，请检查 .env 文件中的密钥: {e}")
except APIConnectionError as e:
    print(f"网络连接失败，检查网络连接或 base_url: {e}")
except RateLimitError as e:
    print(f"请求速率超限，等待几秒后重试: {e}")
except APIStatusError as e:
    print(f"API 返回错误 {e.status_code}: {e.message}")

1.6.2 你应该看到什么输出

正常情况：模型的回答。

1.6.3 常见错误和解决方法

错误类型	出现场景	解决方法
`AuthenticationError`	API Key 无效或未设置	检查 `.env` 文件，确认 Key 格式正确
`APIConnectionError`	网络问题	检查网络连接；国内用 DeepSeek 而非 OpenAI
`RateLimitError`	请求太频繁	等待几秒后重试；添加重试逻辑
`APIStatusError 400`	请求参数有误	检查 messages 格式；检查 model 名称
`APIStatusError 429`	额度用完	充值或等待重置
输出被截断（`finish_reason='length'`）	max_tokens 设太小	增大 max_tokens

1.7 估算费用

python

# 估算本次调用费用（DeepSeek Chat，价格可能变化，以官方文档为准）
# 参考价格：输入约 ¥1/百万 tokens，输出约 ¥2/百万 tokens

input_tokens = response.usage.prompt_tokens
output_tokens = response.usage.completion_tokens

input_cost = input_tokens * 1 / 1_000_000    # ¥/token
output_cost = output_tokens * 2 / 1_000_000
total_cost = input_cost + output_cost

print(f"本次调用费用约：¥{total_cost:.6f}")
print(f"（约 {total_cost * 10000:.4f} 分钱）")

1.7.1 你应该看到什么输出

code

本次调用费用约：¥0.000047
（约 0.0047 分钱）

DeepSeek 的费用极低，学习阶段不需要担心成本。

1.8 完整示例：一个简单的问答程序

python

import os
from openai import OpenAI
from dotenv import load_dotenv

load_dotenv()

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

def ask(question: str, system_prompt: str = "你是一个有帮助的 AI 助手。") -> str:
    """
    这段代码在做什么：
    封装一个简单的问答函数，支持自定义系统提示
    返回模型的回答文本
    """
    messages = [
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": question}
    ]

    response = client.chat.completions.create(
        model="deepseek-chat",
        max_tokens=1024,
        temperature=0.7,
        messages=messages
    )
    return response.choices[0].message.content


# 使用示例
answer = ask(
    "Python 中 list 和 tuple 的主要区别是什么？",
    system_prompt="用简洁的中文回答，不超过 100 字。"
)
print(answer)

# 你应该看到：
# list 可变（可增删改元素），tuple 不可变（创建后不能修改）。
# list 用方括号 []，tuple 用圆括号 ()。
# tuple 通常比 list 略快，常用于固定数据的场景。

跑通这段代码，你就完成了第一次 LLM API 调用。下一篇讲如何实现多轮对话。