1. 大模型接口基础：OpenAI API 入门、API Key 管理与安全、请求与响应结构解析

各位同学，咱们今天正式开课。说实话，每次带新人入门大模型，我第一件事就是让他们把 API 调通。不是因为我喜欢折腾，而是因为——你连接口都调不通，后面那些工具编排、Agent 设计全是空中楼阁。

这一章，咱们就死磕三个东西：怎么拿到 API Key、怎么发请求、怎么读懂响应。嗯，听起来简单，但我在项目里见过太多人在这上面翻车了。

1.1 OpenAI API 入门：先跑通再说

先别管什么架构设计、什么高并发。第一步，让模型回你一句话。

我个人习惯用 Python 的 openai 库，版本 >= 1.0。安装就一行：

pip install openai

然后，写个最简单的调用：

from openai import OpenAI

client = OpenAI(api_key="你的key")
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "user", "content": "你好，请用一句话介绍大模型接口"}
    ]
)
print(response.choices[0].message.content)

跑完这段，如果控制台输出了中文回答，恭喜你，入门了。

1.2 API Key 管理与安全：别把钥匙挂门上

API Key 是什么？说白了，就是你家大门的钥匙。谁拿到它，谁就能用你的账号调用模型，花你的钱。

我曾经见过一个团队，把 API Key 直接写在代码里，还上传到了 GitHub 公开仓库。结果呢？半夜被人扫到，一晚上跑了上千次调用，账单多了几千美金。嗯，血的教训。

所以，请记住这几条铁律：

• 永远不要硬编码 Key。用环境变量，或者专门的密钥管理服务。
• 设置用量限制。OpenAI 后台可以设月度上限，我一般设一个略高于预期的值，防止异常暴涨。
• 定期轮换 Key。我每三个月换一次，旧 Key 及时吊销。
• 区分开发和生产 Key。别混用，否则调试时误操作可能影响线上。

环境变量用法示例：

import os
from openai import OpenAI

client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

1.3 请求与响应结构解析：看懂黑盒子里在传什么

调通了，也安全了。接下来，咱们得搞清楚——你发出去的是什么，收回来的是什么。

请求结构

一个典型的 Chat Completion 请求，核心就三个部分：

messages 数组里，每个元素都有 role 和 content。role 有三种：

• system：设定模型的行为和角色。比如“你是一个资深的 Python 工程师”。
• user：用户的输入。就是你要问的问题。
• assistant：模型的回复。在多轮对话中，你需要把之前的回复也传回去。

举个例子，一个带上下文的请求：

messages = [
    {"role": "system", "content": "你是一个幽默的助手"},
    {"role": "user", "content": "给我讲个笑话"},
    {"role": "assistant", "content": "为什么程序员总是混淆万圣节和圣诞节？因为 Oct 31 == Dec 25！"},
    {"role": "user", "content": "再来一个"}
]

响应结构

响应体看起来有点复杂，但核心就几个字段：

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "这是模型的回答"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 10,
    "total_tokens": 35
  }
}

你真正关心的，其实就两个：

• choices[0].message.content —— 模型的回答文本
• usage.total_tokens —— 这次调用花了多少 token，直接跟钱挂钩

1.4 核心流程：一张图看懂

下面这张图，把整个调用链路串起来了。你每次调 API，本质上就是走这个流程：

1.5 常见错误与排查

调接口嘛，哪有不报错的。我整理了几个最常见的，你遇到了别慌：