02 · 第一次调用大模型 API

🎯 难度：初级⏱ 预计：60 分钟# OpenAI SDK# 环境变量

这一课建立后面各课共用的 config.py，避免复制一堆客户端初始化代码。

准备项目

继续使用 agent-lab，或者新建：

uv init agent-lab --python 3.12
cd agent-lab
uv add "openai>=1.68,<2" "python-dotenv>=1,<2" "pydantic>=2,<3"

本教程示例以 OpenAI Python SDK 1.x 的 Chat Completions 接口为基线；限制主版本可以减少学习中途 API 漂移。不是声称这是最新版。安装后提交 uv.lock，同一项目始终用 uv run。

根据 环境准备 创建 .env。创建配置模块：

import os
from dotenv import load_dotenv
from openai import OpenAI, AsyncOpenAI

load_dotenv()


def required(name: str) -> str:
    value = os.getenv(name)
    if not value:
        raise RuntimeError(f"请在 .env 中配置 {name}")
    return value


def get_client() -> OpenAI:
    return OpenAI(
        api_key=required("LLM_API_KEY"),
        base_url=required("LLM_BASE_URL"),
        timeout=30,
        max_retries=1,
    )


def get_async_client() -> AsyncOpenAI:
    return AsyncOpenAI(
        api_key=required("LLM_API_KEY"),
        base_url=required("LLM_BASE_URL"),
        timeout=30,
        max_retries=1,
    )


def model_name() -> str:
    return required("LLM_MODEL")

os.getenv() 类似 process.env；load_dotenv() 把本地文件加载到环境变量。timeout 限制网络等待，max_retries 避免无限重试；它们不是整个任务的总耗时上限。

发送请求

from config import get_client, model_name

client = get_client()
response = client.chat.completions.create(
    model=model_name(),
    messages=[
        {"role": "system", "content": "你是耐心的 Python 老师，用前端类比解释概念。"},
        {"role": "user", "content": "用 100 字介绍 Python 的 dict。"},
    ],
    max_tokens=300,
)

print(response.choices[0].message.content)
print("计量信息：", response.usage)

uv run hello.py

SDK 已经帮你完成 HTTP 请求、身份验证、JSON 解析和错误分类。choices[0] 是第一个候选回答；它里面的 message 是 SDK 对象，因此可以用 .content。前面自己组装的消息是 dict，所以用 ["content"]。两种写法不是矛盾，是数据类型不同。

错误如何处理？

from openai import APIConnectionError, APIStatusError

# 示意片段：放在发请求的位置
try:
    response = client.chat.completions.create(
        model=model_name(), messages=[{"role": "user", "content": "你好"}]
    )
except APIConnectionError:
    print("连接失败，请检查网络与 base_url")
except APIStatusError as error:
    print(f"平台返回 HTTP {error.status_code}，请检查配置或额度")

• 401：Key 错误、过期或平台不匹配。
• 404：URL/模型名错误。
• 429：频率或额度限制。区别限流和余额不足，不要无脑重试。
• 400：参数或模型能力不支持，例如某模型不支持 max_tokens。

Key 只在服务端

这份文档站不调用模型。练习代码在本地 Python 中执行。以后做前端聊天页面时，也不能把 .env 的 Key 打包进网页；前端只能调用你自己的后端。

练习与验收

把 system 改成「只用三条要点回答」，提问同一个问题。观察格式是否更稳定，再查看 usage。

验收：能独立解释 model / messages / choices / usage，并能区分「网络问题」与「参数不被模型支持」。