学习目标: 理解 HTTP 协议的核心概念------请求/响应模型、方法、状态码、Header、Body,掌握 RESTful 设计原则,能看懂并构造 API 请求。 为什么重要: AI Agent 开发中,一切模型调用、工具调用、API 交互都走 HTTP 协议。调用 OpenAI / DeepSeek 是 HTTP 请求,FastAPI 服务是 HTTP 请求,MCP 工具协议底层也是 HTTP / SSE。不理解 HTTP 就去写 Agent,就像不懂交通规则就上路------能跑两步,但迟早翻车。
2.1.0 先建立直觉:你在浏览器里做了什么?
打开浏览器,输入 https://api.openai.com/v1/models,回车------发生了什么?
lua
你(客户端) OpenAI 服务器
| ---- 能告诉我有哪些模型吗? -----> |
| |
| | 查数据库...
| |
| <---- 好的,这是模型列表 --------- |
这就是 HTTP 的全部本质:客户端发请求,服务端返回响应。 一应一答,没有废话。
你在浏览器里看到的是渲染后的页面,但底层跑的是一段文本协议。下面是一个真实的 HTTP 请求长什么样:
http
GET /v1/models HTTP/1.1
Host: api.openai.com
Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
服务端返回:
http
HTTP/1.1 200 OK
Content-Type: application/json
{
"object": "list",
"data": [
{"id": "gpt-5.6-luna", "object": "model", "created": 1687882411, "owned_by": "openai"},
{"id": "gpt-5.5", "object": "model", "created": 1677610602, "owned_by": "openai"}
]
}
这就是 HTTP 的全部------看懂上面两段文本的结构 = 看懂 80% 的 API 文档。下面的内容,本质上就是把这两段文本的"零件"拆开讲清楚。
2.1.1 HTTP 请求的结构
一个 HTTP 请求由三部分组成:
yaml
┌──────────────────────────────────────────┐
│ 请求行:方法 + 路径 + 协议版本 │
├──────────────────────────────────────────┤
│ 请求头(Headers):key: value 格式的元信息 │
│ Host: api.example.com │
│ Content-Type: application/json │
│ Authorization: Bearer xxx │
├──────────────────────────────────────────┤
│ 空行(Headers 和 Body 的分界线) │
├──────────────────────────────────────────┤
│ 请求体(Body):要发给服务端的数据(可选) │
│ {"model": "gpt-4o", "messages": [...]} │
└──────────────────────────────────────────┘
用 Python httpx 构造请求
我们不用手写文本协议------Python 的 httpx 库帮我们封装好了:
python
import httpx
# 这就是上面那段文本协议的 Python 版本
response = httpx.get(
"https://api.openai.com/v1/models",
headers={
"Authorization": "Bearer sk-xxxxxxxxxxxxxxxxxxxx",
"Content-Type": "application/json",
},
)
print(response.status_code) # 200
print(response.json()) # {"object": "list", "data": [...]}
python
# POST 请求------带 Body
response = httpx.post(
"https://api.openai.com/v1/chat/completions",
headers={
"Authorization": "Bearer sk-xxxxxxxxxxxxxxxxxxxx",
"Content-Type": "application/json",
},
json={ # ← 这个 json 参数会自动序列化并放进 Body
"model": "gpt-5.6-luna", # 也可以用 gpt-5.5",
"messages": [{"role": "user", "content": "Hello"}],
},
)
前端同学对照:
httpx.get(url, headers, json)≈fetch(url, { method: "GET", headers, body: JSON.stringify(data) })。本质完全一样,只是语法不同。 运维同学对照:httpx.get()就是脚本化的curl https://api.example.com,但返回的是一等公民对象,可以直接.json()/.status_code,不用再| jq了。
2.1.2 HTTP 方法------告诉服务端"我要干什么"
HTTP 方法(也叫动词)是请求行的第一个字段,告诉服务端你想对这个资源做什么操作。
核心方法
| 方法 | 含义 | 类比 SQL | 有 Body 吗? | 幂等性 |
|---|---|---|---|---|
| GET | 获取资源 | SELECT |
❌ 没有 | ✅ 是 |
| POST | 创建资源 | INSERT |
✅ 有 | ❌ 否 |
| PUT | 完整替换资源 | UPDATE ... SET |
✅ 有 | ✅ 是 |
| PATCH | 部分更新资源 | UPDATE ... SET(部分字段) |
✅ 有 | ❌ 否 |
| DELETE | 删除资源 | DELETE |
❌ 通常没有 | ✅ 是 |
幂等性(Idempotent): 同一个请求发 1 次和发 10 次,结果一样(除了第一次)就是幂等。GET / PUT / DELETE 是幂等的,POST 不是------连发 10 次 POST 会创建 10 条重复数据。
各语言对照
| 操作 | Python (httpx) | JavaScript (fetch) | curl | 用在哪 |
|---|---|---|---|---|
| 查模型列表 | httpx.get(url, headers=...) |
fetch(url) |
curl url |
获取信息 |
| 发起对话 | httpx.post(url, json=...) |
fetch(url, {method:"POST", body}) |
curl -X POST -d '{...}' url |
创建任务 |
| 更新配置 | httpx.put(url, json=...) |
fetch(url, {method:"PUT", body}) |
curl -X PUT -d '{...}' url |
全量覆盖 |
| 删除资源 | httpx.delete(url) |
fetch(url, {method:"DELETE"}) |
curl -X DELETE url |
清理数据 |
AI Agent 开发中要关注的点
在 Agent 开发中,你会大量使用:
- GET: 查询知识库、获取任务状态、拉取模型列表
- POST: 调用 LLM(Chat Completions API 用 POST)、触发任务执行、上传文件
- PATCH: 部分更新 Agent 配置、修改任务优先级
一个常见错误: 用 GET 发送 Body。按 HTTP 规范,GET 请求不应该携带 Body(很多服务端会忽略或拒绝)。需要传数据?用 POST。
2.1.3 HTTP 响应------服务端的"回信"
HTTP 响应同样由三部分组成:
yaml
┌──────────────────────────────────────────┐
│ 状态行:协议版本 + 状态码 + 状态文本 │
│ HTTP/1.1 200 OK │
├──────────────────────────────────────────┤
│ 响应头(Headers):元信息 │
│ Content-Type: application/json │
│ Content-Length: 256 │
│ X-Request-Id: abc-123 │
├──────────────────────────────────────────┤
│ 空行 │
├──────────────────────────────────────────┤
│ 响应体(Body):服务端返回的数据 │
│ {"choices": [...], "usage": {...}} │
└──────────────────────────────────────────┘
状态码------快速判断"成功还是失败"
状态码是一个三位数,看第一位就够了:
| 范围 | 含义 | 典型场景 | 怎么处理 |
|---|---|---|---|
| 2xx | 成功 | 200 OK、201 Created |
正常解析返回数据 |
| 3xx | 重定向 | 301 Moved Permanently、302 Found |
跟随新地址(httpx 自动处理) |
| 4xx | 客户端错误 | 400 Bad Request、401 Unauthorized、429 Too Many Requests |
检查你的请求------参数错了?Key 过期了?限流了? |
| 5xx | 服务端错误 | 500 Internal Server Error、503 Service Unavailable |
服务端的问题------重试或等修复 |
Agent 开发中最常遇到的 10 个状态码
python
# 调用 LLM API 时,这些状态码会和你不期而遇
STATUS_MAP = {
200: "OK --- 一切正常,解析 data 就行",
201: "Created --- POST 创建资源成功",
400: "Bad Request --- 你的请求格式有问题,检查 JSON / 参数名",
401: "Unauthorized --- API Key 不对或过期了",
403: "Forbidden --- 有 Key 但没权限访问这个资源",
404: "Not Found --- 请求的资源不存在(接口路径拼错了?模型名写错了?)",
429: "Too Many Requests --- 被限流了!等几秒再重试(这是 Agent 最常见的问题)",
500: "Internal Server Error --- 服务端挂了,重试(加 exponential backoff)",
502: "Bad Gateway --- 网关/代理出问题,同上",
503: "Service Unavailable --- 服务暂时不可用,等一会重试",
}
python
# 实战:健壮的 LLM API 调用
import httpx
import time
def call_llm_with_retry(url: str, headers: dict, body: dict, max_retries: int = 3):
"""调用 LLM API,自动处理常见错误"""
for attempt in range(max_retries):
response = httpx.post(url, headers=headers, json=body, timeout=60)
if response.status_code == 200:
return response.json()
elif response.status_code == 429:
# 限流------等 Retry-After 头或指数退避
wait = int(response.headers.get("Retry-After", 2 ** attempt))
print(f"[429] 限流,{wait}秒后重试(第 {attempt + 1} 次)")
time.sleep(wait)
elif response.status_code in (500, 502, 503):
# 服务端错误------指数退避重试
wait = 2 ** attempt
print(f"[{response.status_code}] 服务端错误,{wait}秒后重试")
time.sleep(wait)
elif response.status_code == 401:
raise Exception("API Key 无效!请检查密钥。")
else:
raise Exception(f"请求失败 [{response.status_code}]: {response.text}")
raise Exception(f"重试 {max_retries} 次后仍失败")
DBA 同学对照: HTTP 状态码 ≈ 数据库错误码。
200像SELECT成功返回结果集,4xx像 SQL 语法错误(你的锅),5xx像数据库宕机(服务端的锅)。
2.1.4 HTTP Headers------请求的"元信息"
Headers 是 key: value 格式的键值对,携带请求/响应的元信息。你用不到全部------但以下 8 个是 AI Agent 开发中最常见的:
请求头(Request Headers)
python
headers = {
# 1. 认证 --- 最常用,每次调 LLM API 必带
"Authorization": "Bearer sk-xxxxxxxxxxxxxxxxxxxx",
# 2. 告诉服务端 Body 是什么格式
"Content-Type": "application/json",
# 3. 告诉服务端我能接收什么格式(通常也用 json)
"Accept": "application/json",
# 4. User-Agent --- 标明调用方身份(OpenAI 可能会根据这个限流/过滤)
"User-Agent": "MyAgent/1.0",
# 5. 自定义头 --- 某些 API 用自定义头传 API Key(如 Anthropic)
"x-api-key": "sk-ant-xxxxxxxxxxxxxxxxxxxx",
}
响应头(Response Headers)
python
response = httpx.get("https://api.openai.com/v1/models", headers={"Authorization": f"Bearer {key}"})
# Agent 开发中最有用的几个响应头:
print(response.headers.get("Content-Type")) # application/json --- 返回的是什么格式
print(response.headers.get("X-Request-Id")) # 请求 ID --- 排查问题时告诉 OpenAI
print(response.headers.get("Retry-After")) # 限流时服务器建议等几秒再重试
print(response.headers.get("X-RateLimit-Remaining")) # 还剩下多少次调用配额
Content-Type 速查
| Content-Type | 数据格式 | 什么时候用 |
|---|---|---|
application/json |
JSON | 最常用------LLM API、RESTful API 几乎都用 |
application/x-www-form-urlencoded |
key1=val1&key2=val2 |
传统 Web 表单 |
multipart/form-data |
表单 + 文件上传 | 上传图片/文件给模型 |
text/plain |
纯文本 | 简单文本传输 |
application/octet-stream |
二进制 | 文件下载 |
python
# multipart/form-data 示例:上传图片给多模态模型
with open("screenshot.png", "rb") as f:
response = httpx.post(
"https://api.openai.com/v1/files",
headers={"Authorization": f"Bearer {api_key}"},
files={"file": ("screenshot.png", f, "image/png")}, # ← httpx 自动处理 Content-Type
data={"purpose": "vision"},
)
2.1.5 JSON------API 世界的"通用语"
JSON(JavaScript Object Notation)是现代 API 最通用的数据交换格式。它不是 Python 专有的,而是所有语言都能读写的纯文本格式。
JSON vs Python dict
python
import json
# Python dict → JSON 字符串(序列化)
data = {
"model": "gpt-4o",
"messages": [{"role": "user", "content": "Hello"}],
"temperature": 0.7,
"max_tokens": 4096,
}
json_str = json.dumps(data, indent=2, ensure_ascii=False)
print(json_str)
输出:
json
{
"model": "gpt-4o",
"messages": [
{
"role": "user",
"content": "Hello"
}
],
"temperature": 0.7,
"max_tokens": 4096
}
python
# JSON 字符串 → Python dict(反序列化)
response_str = '{"id": "chatcmpl-123", "choices": [{"message": {"content": "Hi!"}}]}'
parsed = json.loads(response_str)
print(parsed["choices"][0]["message"]["content"]) # Hi!
JSON 数据类型对照表
| JSON 类型 | Python | JavaScript | Java | 示例 |
|---|---|---|---|---|
string |
str |
string |
String |
"hello" |
number |
int / float |
number |
int / double |
42, 3.14 |
boolean |
bool |
boolean |
boolean |
true / false |
null |
None |
null |
null |
null |
array |
list |
Array |
List |
[1, 2, 3] |
object |
dict |
Object |
Map |
{"key": "value"} |
**注意 JSON 的真/假是
true/false(小写),Python 是True/False(大写)。用json.dumps()/json.loads()时自动转换,用httpx的json=参数也是自动处理------但自己拼字符串时容易写错。 另外一个陷阱: JSON 不支持注释和尾随逗号。{"key": "value",}在 Python 里合法,在 JSON 里报错。
JSON Schema------给 JSON 加"类型约束"
在 Agent 开发中,你不只是"发 JSON",还需要"约定 JSON 的结构"------这就是 JSON Schema 的作用:
json
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "用户要搜索的关键词"
},
"max_results": {
"type": "integer",
"description": "最多返回多少条结果",
"default": 10,
"minimum": 1,
"maximum": 100
},
"source": {
"type": "string",
"enum": ["web", "news", "academic"],
"description": "搜索来源"
}
},
"required": ["query"]
}
这个 JSON Schema 定义了一个搜索工具的输入格式。它的作用是:
- 给 LLM 看: 模型知道应该生成什么样的参数调用这个工具
- 给程序看: 在工具执行前校验参数是否合法
- 给人看: 这是一个工具的"接口说明书"
python
# Pydantic 可以用 Python 代码生成同样的 JSON Schema
from pydantic import BaseModel, Field
from typing import Literal
class SearchInput(BaseModel):
query: str = Field(description="用户要搜索的关键词")
max_results: int = Field(default=10, ge=1, le=100, description="最多返回多少条结果")
source: Literal["web", "news", "academic"] = Field(default="web", description="搜索来源")
# 生成 JSON Schema
print(SearchInput.model_json_schema())
在 1.5 节你会深入学习 Pydantic------这里只需要建立一个认知:Agent 工具的参数用 JSON Schema 定义,Pydantic 是最方便的生成方式。
2.1.6 RESTful 设计原则------不只是"怎么调",还要"怎么设计"
REST(Representational State Transfer)是最主流的 API 设计风格。你不需要一开始就设计 API,但需要能看懂 RESTful API 文档------这也是正式课程中所有 API 的设计规范。
六大核心原则(一句话版)
- 统一接口(Uniform Interface): 同一个资源(如"用户")的增删改查用同一套 URL + 不同 HTTP 方法,不乱起名
- 无状态(Stateless): 每个请求包含所有必要信息,服务端不记住"你上次做了什么"------Agent 的记忆是你自己管理的
- 资源导向(Resource-Based): URL 是名词(资源名),不是动词(动作名)------
/users而不是/getUsers - 表现层转换: 服务端可以返回 JSON / XML / HTML 等不同格式,客户端通过
Accept头指定 - 分层系统: 客户端不关心经过了几层代理/网关/负载均衡
- 按需代码(可选): 服务端可以返回可执行代码(如 JavaScript)------在 API 中不常用
URL 设计速成
bash
✅ RESTful(推荐): ❌ 非 RESTful(不推荐):
GET /agents # 查所有 Agent GET /getAllAgents
GET /agents/42 # 查 Agent #42 GET /getAgent?id=42
POST /agents # 新建 Agent POST /createAgent
PUT /agents/42 # 全量更新 POST /updateAgent?id=42
PATCH /agents/42 # 部分更新 POST /agents/42/updatePartial
DELETE /agents/42 # 删除 GET /deleteAgent?id=42
GET /agents/42/tools # 查 Agent #42 的工具 GET /agentTools?agentId=42
POST /agents/42/tools # 给 Agent #42 添加工具 POST /addToolToAgent
规则就三条: (1) URL 用名词,不用动词;(2) 用 HTTP 方法表达操作;(3) 层级关系用
/表示。
一张表记住 RESTful 资源设计
| 资源 | GET(查) | POST(增) | PUT(全量改) | PATCH(部分改) | DELETE(删) |
|---|---|---|---|---|---|
/users |
用户列表 | 新增用户 | --- | --- | --- |
/users/1 |
用户#1详情 | --- | 覆盖用户#1 | 修改用户#1部分字段 | 删除用户#1 |
/users/1/orders |
用户#1的订单 | 建新订单 | --- | --- | --- |
/agents |
Agent 列表 | 注册新 Agent | --- | --- | --- |
/agents/1/tools |
Agent#1的工具列表 | 添加工具 | --- | --- | --- |
Agent 开发中 RESTful 的实际应用
当你给 FastAPI 服务设计接口时,几乎就是在"翻译"上面这张表。比如正式课里的 Tool Runtime:
python
from fastapi import FastAPI
app = FastAPI()
# ✅ RESTful
@app.get("/tools") # 列出所有已注册工具
@app.get("/tools/{tool_name}") # 查看某个工具的详情(参数、描述、Schema)
@app.post("/tools") # 注册新工具
@app.delete("/tools/{tool_name}") # 移除工具
# 这就是 RESTful 的全部实战用法------用资源名 + HTTP 方法表达操作
2.1.7 HTTP URL 的结构
你可能每天都在用 URL,但未必知道它的每一部分叫什么:
bash
https://api.openai.com:443/v1/chat/completions?model=gpt-4o#usage
└─┬─┘ └──────┬──────┘ └┬┘ └─────────┬─────────┘ └────┬────┘ └─┬─┘
Scheme Host Port Path Query Fragment
(协议) (主机) (端口) (路径) (查询参数) (片段)
| 组成部分 | 含义 | 是否必填 | 示例 |
|---|---|---|---|
| Scheme | 协议 | ✅ | http / https |
| Host | 服务器地址 | ✅ | api.openai.com |
| Port | 端口号 | ❌(默认 80/443) | :8080 / :3000 |
| Path | 资源路径 | ✅ | /v1/chat/completions |
| Query | 查询参数 | ❌ | ?model=gpt-4o&stream=true |
| Fragment | 页面锚点 | ❌(浏览器用) | #usage |
Query 参数 vs Path 参数 vs Body
这是 API 设计中最容易混淆的三个概念。用一张表讲清楚:
python
# 同一个逻辑用三种不同的方式传参------哪种是对的?
post_id = "abc123"
# 方式 A:Path 参数(URL 的一部分)
GET /posts/abc123
# 方式 B:Query 参数(URL 中 ? 后面)
GET /posts?id=abc123
# 方式 C:Body(POST 请求体)
POST /posts
{"id": "abc123"}
| 参数类型 | 放在哪里 | 用在哪 | 例子 |
|---|---|---|---|
| Path 参数 | URL 路径中 | 定位一个具体资源 | GET /users/42(用户 ID=42) |
| Query 参数 | URL 中 ? 后面 |
过滤、排序、分页 | GET /users?role=admin&page=2 |
| Body | 请求体中 | 传递复杂/大量数据 | POST /users + {"name":"Alice"} |
简单判断法: 这个东西是"你要操作的资源是谁" → Path。是"怎么筛选/排序" → Query。是"你要传的一坨数据" → Body。
2.1.8 从开发者工具看懂 HTTP
最直观的学习方式:打开浏览器的开发者工具(F12),切到 Network(网络)标签。
操作步骤:
- 打开 Chrome/Edge → F12 → Network 标签
- 访问
https://api.github.com/users/octocat - 点击那个请求,你就能看到:
vbscript
Request Headers: Request (没有 Body,因为是 GET):
GET /users/octocat (空)
Host: api.github.com
Accept: application/json
Response Headers: Response Body:
Content-Type: application/json
Status: 200 OK
{
"login": "octocat",
"id": 583231,
"name": "The Octocat",
...
}
这就是本节所有概念的实物演示。 请求行/请求头/Body → 响应行/响应头/Body,一一对应。把 Network 面板当成你的 HTTP 实验室,遇到不认识的接口就打开看。
2.1.9 curl:命令行里的"浏览器"
curl 是一个命令行 HTTP 客户端,调试 API 时非常实用。在 Agent 开发中,你经常用它快速验证"这个 API 到底能不能通"。
bash
# GET 请求------最简单的用法
curl https://api.github.com/users/octocat
# 只看响应头(调试状态码、Headers)
curl -I https://api.github.com/users/octocat
# POST 请求------发 JSON
curl -X POST https://api.openai.com/v1/chat/completions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o",
"messages": [{"role": "user", "content": "Hello"}]
}'
# 静默模式------只看 HTTP 状态码(用于脚本中判断)
curl -s -o /dev/null -w "%{http_code}" https://api.github.com
# 查看完整的请求/响应过程(调试神器)
curl -v https://api.github.com/users/octocat
| curl 参数 | 作用 | 用途 |
|---|---|---|
-X METHOD |
指定 HTTP 方法 | 默认是 GET |
-H "Key: Value" |
添加请求头 | 认证、Content-Type |
-d '...' |
指定 Body(同时自动变为 POST) | 传 JSON 数据 |
-I |
只看响应头 | 快速查状态码 |
-v |
Verbose 模式(显示完整请求/响应) | 调试 |
-s -o /dev/null -w "%{http_code}" |
静默,只输出状态码 | Shell 脚本 |
curl → Python 转换技巧: 很多 API 文档给的是 curl 示例。你可以直接把 curl 贴给大模型说"翻译成 Python httpx",一行代码都不用自己写。
2.1.10 本章核心概念速查
一句话总结 HTTP
HTTP = 方法(干什么) + URL(对谁干) + Header(带什么身份牌) + Body(传什么数据) → 得到状态码(成了没?) + 响应 Body(结果是什么)
Agent 开发者最常用 HTTP 速查卡
python
# ===== 调用 LLM API =====
response = httpx.post(
"https://api.openai.com/v1/chat/completions",
headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
json={"model": "gpt-4o", "messages": [{"role": "user", "content": prompt}]},
timeout=60,
)
data = response.json()
content = data["choices"][0]["message"]["content"]
# ===== 查工具状态 =====
response = httpx.get(f"{base_url}/tools/{tool_name}")
tools = response.json()
# ===== 注册新工具 =====
response = httpx.post(
f"{base_url}/tools",
json={"name": "search_web", "description": "...", "parameters": {...}},
)
# ===== 检查响应 =====
if response.status_code == 200:
return response.json()
elif response.status_code == 401:
raise ValueError("API Key 无效")
elif response.status_code == 429:
time.sleep(int(response.headers.get("Retry-After", 5)))
各语言 HTTP 请求对照
| 操作 | Python (httpx) | JavaScript (fetch) | curl | 用在哪 |
|---|---|---|---|---|
| GET | httpx.get(url, headers=h) |
fetch(url, {headers:h}) |
curl url |
查数据 |
| POST | httpx.post(url, json=d, headers=h) |
fetch(url, {method:"POST", body:JSON.stringify(d), headers:h}) |
curl -X POST -d '{...}' url |
创建/调用 |
| 解析 JSON | r.json() |
await r.json() |
\| jq |
获取返回数据 |
| 状态码 | r.status_code |
r.status |
curl -s -o /dev/null -w "%{http_code}" |
判断结果 |
| 响应头 | r.headers["X-Id"] |
r.headers.get("X-Id") |
curl -I \| grep X-Id |
元信息 |
最容易踩的 5 个坑
- GET 请求带 Body: HTTP 规范不鼓励 GET 请求有 Body,很多服务端直接忽略。需要传数据用 POST。
- 状态码只看数字、不看含义:
200不是唯一成功的状态码------201 Created也是成功;4xx是你的请求有问题,不是服务端问题。 - 忘记设置 Content-Type: 发 JSON 不设
Content-Type: application/json,服务端可能当成纯文本处理。 - 把 API Key 写死在代码里:
Authorization: "Bearer sk-abc123"硬编码是安全灾难。用.env文件 + 环境变量管理(2.2 节会讲)。 - 不检查状态码就解析 JSON: 服务端返回 500 时 Body 可能是 HTML 错误页面,
response.json()直接抛异常。先检查response.status_code再解析。
2.1.11 练习
基础练习
- curl 入门: 用 curl 访问
https://api.github.com/users/octocat。观察响应中的 Headers 和 Body。找出Content-Type和状态码。 - Python 调用: 将上面的 curl 命令改写成 Python httpx 代码。打印状态码、
Content-Type和login字段。 - HTTP 方法判断: 以下操作应该用什么 HTTP 方法?为什么?
- a) 查询今天的所有新闻头条
- b) 新建一条用户记录
- c) 修改用户的邮箱地址
- d) 删除一条评论
- e) 让 LLM 生成一段代码
- JSON 练习: 将以下 Python dict 转为 JSON 字符串,再转回来:
python
task = {
"id": "task-001",
"title": "写一个 Agent",
"completed": False,
"tools_used": ["search", "read_file", "execute"],
"duration_seconds": 45.6,
"result": None
}
进阶练习
- 健壮的 LLM API 调用: 写一个函数
call_llm_api(prompt: str, api_key: str) -> str,功能是调用 OpenAI Chat Completions API。要求:
- 正确处理
200、401、429、500四种状态码 - 对
429实现指数退避重试(最多 3 次) - 对
500实现固定 2 秒间隔重试(最多 2 次) - 设置 30 秒超时
- 使用
https://api.openai.com/v1/chat/completions作为 URL
python
# 框架代码
import httpx
import time
def call_llm_api(prompt: str, api_key: str) -> str:
url = "https://api.openai.com/v1/chat/completions"
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
}
body = {
"model": "gpt-4o",
"messages": [{"role": "user", "content": prompt}],
}
# TODO: 实现你的重试逻辑
pass
- RESTful URL 设计: 为一个"AI Agent 工具管理系统"设计 RESTful API。资源包括:
- Agent(有 id、name、model 属性)
- Tool(有 name、description、parameters 属性)
- Agent 和 Tool 是多对多关系(一个 Agent 可以注册多个 Tool)
请画出 URL 表(类似 2.1.6 的表),至少包含 8 个接口。
- JSON Schema 实战: 为"发邮件"这个工具写一个 JSON Schema。工具参数包括:
to:收件人邮箱(必填,字符串)subject:邮件主题(必填,字符串)body:邮件正文(必填,字符串)cc:抄送(可选,字符串数组)priority:优先级(可选,只能是 "low" / "normal" / "high" 之一,默认 "normal")
分别用纯 JSON Schema 和 Pydantic 各写一版。
参考资料
- MDN HTTP 文档 ------ 最好的 HTTP 入门参考
- httpx 官方文档 ------ Python HTTP 客户端
- RESTful API 设计指南(阮一峰) ------ 中文社区经典
- JSON Schema 官方文档 ------ 定义 JSON 结构的标准
- GitHub REST API ------ 教科书级的 RESTful API 设计范例
- OpenAI API 文档 ------ 你马上要调的第一个 LLM API