📚 课程目录第2章大模型接口基础

2. 大模型接口基础

说实话，搞大模型接口集成，第一关就是认证。你想想看，大模型厂商又不是做慈善的，谁都能随便调？他们得知道你是谁、有没有额度、能不能访问。所以，理解 API 认证机制，是咱们这门课的基石。

我刚开始接触大模型 API 时，也踩过不少坑。有一次，我直接把 API Key 硬编码在 GitHub 公开仓库里，结果半小时内就被爬虫扫到，账户被刷爆了。嗯，从那以后，我再也不敢小看认证这回事了。

RESTful API：大模型接口的通用语言

现在主流的大模型 API，几乎都遵循 RESTful 风格。说白了，就是用 HTTP 方法（GET、POST、PUT、DELETE）来操作资源。对于大模型来说，最常见的操作就是「发送请求，获取回复」，所以基本只用 POST。

一个典型的 RESTful API 请求包含这几部分：

端点（Endpoint）：API 的 URL 地址，比如 https://api.openai.com/v1/chat/completions
请求头（Headers）：携带认证信息、内容类型等元数据
请求体（Body）：实际发送的数据，通常是 JSON 格式
响应（Response）：模型返回的结果，也是 JSON

核心原则：RESTful API 是无状态的。每次请求都包含所有必要信息，服务器不会记住你之前的请求。这对大模型接口来说特别重要——你每次调用都是独立的，不用担心上下文混乱。

API Key：最简单的认证方式

API Key 是最基础的认证方式。你注册平台后，后台会给你一串密钥。每次请求时，把它放在请求头里就行。

我个人习惯用环境变量来管理 API Key，而不是写死在代码里。这样既安全又灵活。

import os
import requests

# 从环境变量读取 API Key
api_key = os.environ.get("OPENAI_API_KEY")

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

data = {
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "你好"}]
}

response = requests.post(
    "https://api.openai.com/v1/chat/completions",
    headers=headers,
    json=data
)

print(response.json())

⚠️ 安全警告：我曾经见过有人把 API Key 写在代码注释里提交到 Git。结果被 CI/CD 工具自动扫描到，触发了安全告警。记住：API Key 就是你的钱，丢了就是真金白银的损失。

Bearer Token：比 API Key 更灵活

API Key 虽然简单，但有个问题——它通常是永久有效的。一旦泄露，后果很严重。Bearer Token 解决了这个问题：它有时效性，过期后需要刷新。

Bearer Token 的格式通常是 JWT（JSON Web Token）。它包含三部分：Header、Payload、Signature。你可以解码看看里面有什么信息。

import jwt

# 解码 JWT Token（不验证签名）
token = "eyJhbGciOiJIUzI1NiIs..."
decoded = jwt.decode(token, options={"verify_signature": False})
print(decoded)
# 输出：{'sub': 'user_123', 'exp': 1712345678, 'iat': 1712342078}

你想想看，有了过期时间，就算 Token 泄露了，攻击者也用不了多久。这就是为什么很多大模型平台开始推荐使用 Bearer Token 而不是纯 API Key。

OAuth 2.0：企业级认证方案

当你的应用需要代表用户去调用大模型 API 时，OAuth 2.0 就派上用场了。比如你开发了一个 AI 写作助手，用户授权后，你的应用可以用用户的额度调用模型。

OAuth 2.0 有四种授权模式，但大模型场景最常用的是 客户端凭证模式（Client Credentials） 和 授权码模式（Authorization Code）。

模式	适用场景	流程
客户端凭证	服务端到服务端，无需用户参与	应用直接拿 client_id + client_secret 换 token
授权码模式	需要用户授权的 Web 应用	用户登录 → 授权 → 拿授权码 → 换 token
隐式模式	纯前端应用（已不推荐）	直接返回 token，安全性较低
密码模式	高度信任的客户端（已不推荐）	直接拿用户名密码换 token

💡 实战建议：我建议你优先使用客户端凭证模式。它简单、安全，适合大多数大模型集成场景。除非你的应用需要代表不同用户操作，才考虑授权码模式。

三种认证方式对比

为了让你一目了然，我把三种方式的核心差异整理成了一张表：

特性	API Key	Bearer Token	OAuth 2.0
复杂度	低	中	高
安全性	中（永久有效）	高（有时效）	高（支持刷新）
适用场景	个人项目、快速原型	生产环境、移动端	企业级、多用户
实现成本	几分钟	几小时	几天

实战：完整认证流程

下面我带你走一遍完整的 OAuth 2.0 客户端凭证模式实战。这是我在实际项目中用得最多的方案。

import requests

# 第一步：获取 Token
def get_access_token(client_id, client_secret, token_url):
    payload = {
        "grant_type": "client_credentials",
        "client_id": client_id,
        "client_secret": client_secret
    }
    response = requests.post(token_url, data=payload)
    return response.json()["access_token"]

# 第二步：使用 Token 调用 API
def call_llm_api(access_token, api_url, messages):
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    }
    data = {
        "model": "gpt-4",
        "messages": messages
    }
    response = requests.post(api_url, headers=headers, json=data)
    return response.json()

# 第三步：处理 Token 过期
def call_with_auto_refresh(client_id, client_secret, token_url, api_url, messages):
    # 实际项目中，这里应该缓存 token 并检查过期时间
    token = get_access_token(client_id, client_secret, token_url)
    result = call_llm_api(token, api_url, messages)
    
    # 如果返回 401，刷新 token 重试
    if result.get("error") and "unauthorized" in str(result).lower():
        token = get_access_token(client_id, client_secret, token_url)
        result = call_llm_api(token, api_url, messages)
    
    return result

⚠️ 避坑指南：我曾经在生产环境中忘记处理 Token 过期，结果凌晨三点服务挂了。用户反馈说「AI 助手突然不说话了」。排查后发现是 Token 过期了，但代码没有自动刷新。从那以后，我每次都会加上 Token 过期重试逻辑。

知识结构图：API 认证体系

下面这张图帮你理清整个认证体系的关系：

常见问题与避坑

做 API 集成这么多年，我总结了几条血泪教训：

不要硬编码密钥：用环境变量或密钥管理服务，比如 Vault、AWS Secrets Manager
注意速率限制：大模型 API 通常有每分钟/每天的调用上限，超出会返回 429 错误
处理 Token 过期：OAuth 2.0 的 Token 通常 1 小时过期，记得实现自动刷新
日志脱敏：打印日志时，把 API Key 和 Token 用星号替换，防止泄露
使用 HTTPS：永远不要在 HTTP 上传输认证信息，这是底线

💡 我的习惯：每次新建项目，我第一件事就是建一个 .env 文件，把所有密钥放进去，然后在 .gitignore 里把它排除掉。这个习惯救了我无数次。

好了，API 认证这块的内容就这些。你掌握了这些，后面调用任何大模型接口都不会被卡在第一步。记住：认证是安全的基石，别嫌麻烦，该做的防护一步都不能少。