API 与密钥:用最朴素的方式打通第一个 LLM 调用

API 与密钥:用最朴素的方式打通第一个 LLM 调用

本节摘要:所有 AI API 都遵循同一个套路——发请求、拿响应;变的只是细节,不变的是模式。从第 11 章起你会频繁调用 LLM API(Anthropic、OpenAI、Google),第 13~16 章更要在循环里把它们编排成 Agent。本节先把这件基础事做扎实:如何用环境变量与 .env 文件安全存放 API 密钥(绝不写进代码),如何用官方 SDK 与裸 HTTP 两种方式各发一次 LLM 调用并对比响应格式,以及如何识别与处理鉴权失败、限流这类常见错误。读完本节,你能在十分钟内打通任意一家厂商的第一个 API 调用,并能从裸 HTTP 层面读懂报错根因。

对应原课程:Phase 00 · Lesson 04 · apis-and-keys(原英文 phases/00-setup-and-tooling/04-apis-and-keys/docs/en.md)。前置:第 01 节「开发环境」。

学习目标

阅读完本节,你应当能够:

1. 用环境变量与 .env 文件安全存放 API 密钥,并确保 .env 被 .gitignore 排除。
2. 用 Anthropic Python SDK 与裸 HTTP 两种方式各发一次 LLM API 调用。
3. 对比 SDK 与裸 HTTP 的请求/响应格式,能在报错时从底层看懂根因。
4. 识别并处理鉴权失败(401)与限流(429)等常见 API 错误。

一、问题与直觉

从第 11 章开始,你会调用 LLM API(Anthropic、OpenAI、Google);第 13~16 章,你要构建在循环里反复调用这些 API 的 Agent。在此之前,你必须搞懂三件事:API 密钥怎么工作、怎么安全存放、怎么发出你的第一次调用。

每一次 API 调用都是一次请求-响应:

任何一次 API 调用都有四个要素:

1. 端点(Endpoint):一个 URL,告诉你「请求往哪儿发」。
2. API 密钥:身份认证,「你有没有权限调」。
3. 请求体:你要什么(模型名、提示、参数)。
4. 响应体:服务器返回的内容(生成的文本、token 计数、延迟等)。

💡 记住这个「四要素」心智模型。后面无论 Anthropic、OpenAI 还是 Google,无论 SDK 还是裸 HTTP,无非都是这四样东西在不同细节上的展开。

二、从零实现

Step 1 安全存放密钥

永远不要把 API 密钥写进代码。用环境变量:

export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
​

或者用一个 .env 文件(务必把它加进 .gitignore,见第 02 节):

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
​

代码里用 python-dotenv 自动加载 .env,这样密钥只活在本地文件,不进版本库,不进日志。

⚠️ 设计警示:把密钥误提交到 GitHub 是工业界最高频的安全事故之一。哪怕几秒钟也不行——爬虫会立刻抓走并在几分钟内消耗你的额度。一旦误提交,立刻去厂商后台吊销并重置那把密钥,再清 git 历史。

Step 2 第一次 API 调用(Python,用 SDK)

import os, anthropic
client = anthropic.Anthropic()                                   # 自动从环境变量读密钥
MODEL = os.environ.get("LLM_MODEL", "claude-sonnet-5")
response = client.messages.create(
    model=MODEL,
    max_tokens=256,
    messages=[{"role": "user", "content": "用一句话解释神经网络是什么?"}]
)
print(response.content[0].text)
​

LLM_MODEL 用来选 Anthropic 的模型 id,默认是 claude-sonnet-5 这个无日期别名。其他厂商(OpenAI、Google 等)遵循同样的「密钥 + 模型 id」模式,但各有各的 SDK、端点和请求/响应 schema。

Step 3 第一次 API 调用(TypeScript)

import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();                                  // 同样自动读环境变量
const MODEL = process.env.LLM_MODEL ?? "claude-sonnet-5";
const response = await client.messages.create({
    model: MODEL,
    max_tokens: 256,
    messages: [{ role: "user", content: "用一句话解释神经网络是什么?" }],
});
console.log(response.content[0].text);
​

Step 4 裸 HTTP(不用 SDK)

import os, urllib.request, json
url = "https://api.anthropic.com/v1/messages"
headers = {
    "Content-Type": "application/json",
    "x-api-key": os.environ["ANTHROPIC_API_KEY"],                # 注意是 x-api-key
    "anthropic-version": "2023-06-01",                            # Anthropic 要求带版本号
}
body = json.dumps({
    "model": os.environ.get("LLM_MODEL", "claude-sonnet-5"),
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "用一句话解释神经网络是什么?"}],
}).encode()
req = urllib.request.Request(url, data=body, headers=headers, method="POST")
with urllib.request.urlopen(req) as resp:
    print(json.loads(resp.read())["content"][0]["text"])
​

这段就是 SDK 在底层做的事。理解裸 HTTP 调用,在排查问题时极其有用——SDK 把细节藏起来,但报错信息往往只在 HTTP 层才看得清。

设计要点:不同厂商鉴权头不同。Anthropic 用 x-api-key,OpenAI 用 Authorization: Bearer <key>。这种差异,SDK 会替你抹平;但用裸 HTTP 时必须自己处理。

三、框架对比:各家 API 的接入时机

这门课你会用到下面这几家,不必现在全配齐,用到哪节配哪家即可:

💡 共同模式:每家都是「一把密钥 + 一个模型 id + 一段请求体」。学会一家,迁移到另一家通常只需换个 SDK 和改几行字段名。第 12 章会专门讲跨厂商提示设计的工程心法。

常见错误识别

• 401 Unauthorized:密钥错了、过期了,或忘了设环境变量。先 echo $ANTHROPIC_API_KEY 确认。
• 403 Forbidden:密钥有效但没权限调这个模型/区域。
• 429 Rate Limit / overloaded:触发限流,或模型过载。退避重试(exponential backoff),必要时降并发。
• 5xx:服务端错,通常是临时的,重试即可。

四、可复用产物

本节产出(原课程 outputs/):

• prompt-api-troubleshooter.md:一个提示词,把你遇到的 API 报错(状态码、响应体、你用的 SDK 与代码片段)贴进去,让 AI 助手帮你诊断根因并给出修复命令。覆盖鉴权、限流、模型不存在、参数缺失这几类高频问题。

五、练习

1. (Easy) 申请一把 Anthropic API 密钥,放进 .env,用 Python SDK 发出你的第一次 LLM 调用,打印返回的文本。
2. (Medium) 改用裸 HTTP(Step 4 那段)再发一次同样请求,把响应 JSON 完整打印出来,与 SDK 返回的对象逐字段对照,理解 SDK 帮你封装了哪些字段。
3. (Hard) 故意把密钥改错一位,记录返回的 HTTP 状态码与错误信息结构;再写一段带指数退避的重试逻辑,在 429 限流时自动等待重试,最多重试 5 次。

本节要点回顾

1. API 套路统一:发请求、拿响应;四要素——端点、密钥、请求体、响应体。
2. 密钥绝不入码:用环境变量或 .env,并把 .env 加进 .gitignore;误提交立即吊销重置。
3. SDK 自动读密钥:从环境变量取,无需手动传;Anthropic 默认模型用 claude-sonnet-5 这类无日期别名。
4. 裸 HTTP 是排错利器:SDK 藏细节,报错时往往只有退到 HTTP 层才看得清;各家鉴权头不同(Anthropic 用 x-api-key,OpenAI 用 Authorization: Bearer)。
5. 常见错误:401 鉴权失败、429 限流(退避重试)、5xx 服务端错(直接重试)。
6. 按需配密钥:用到哪节配哪家;学会一家,迁移到另一家只换 SDK 与字段名。
7. Token 是计费单位:输入与输出 token 分开计数计费,这是后面成本优化的基础。

下一节,我们将进入「Jupyter Notebook」——把这套 API 调用与实验代码装进交互式笔记本,让探索式 AI 开发更顺手。