AI 编程智能体零门槛调用手册:从“能跑”到“敢放进作品集”
我是AI时代的无业游民,我游荡在现实与意念之间
AI 编程智能体零门槛调用手册:从“能跑”到“敢放进作品集”

什么时候用这份手册
你刚学完一门语言,想让 AI 帮你写代码,结果发现:调用示例抄下来跑不通、密钥硬编码在文件里、换个模型就全崩。这份手册按使用频率排序,每条给出用途、最小示例和一条坑点,30 秒内能定位到你需要的片段。
前置知识只需两样:会用命令行安装依赖、知道什么是环境变量。掌握后你能产出的作品集能力是:一个可配置、可切换模型、密钥不入库的小型智能体调用脚本——这正是面试里“你如何安全地集成大模型”的常见追问点。
① 重构前的症状
新手最常见的调用代码长这样,能复现:
# before.py
import openai
openai.api_key = "sk-abc123..." # 密钥直接写死
def ask(q):
r = openai.ChatCompletion.create(
model="gpt-3.5-turbo",
messages=[{"role": "user", "content": q}]
)
return r["choices"][0]["message"]["content"]
print(ask("写个快排"))
痛在哪里:
| 症状 | 后果 |
|---|---|
| 密钥硬编码 | 推到 GitHub 即泄露,被刷爆额度 |
| 旧版 SDK 写法 | 新版库直接 AttributeError |
| 模型名写死 | 换模型要改代码,无法灰度对比 |
| 无超时/重试 | 网络抖动时脚本卡死 |
| 无结构化输出 | 下游要解析字符串,脆弱 |
② 问题诊断
根因不是“代码写得丑”,而是把配置、协议、业务三层揉进了一个函数。密钥属于环境配置,模型名与接口版本属于协议适配,提示词与解析属于业务。三者耦合后,任何一层变动都要动主逻辑。
另一个隐蔽根因:直接依赖某家厂商的 SDK 对象。一旦你想对比不同模型(当前主流如 GPT-5.5、Qwen3.6 Max、GLM 5.1、DeepSeek 4.0 Pro 等),代码就得重写。统一走 OpenAI 兼容的 HTTP 接口,是目前多数平台都支持的最小公约数。
③ 重构后的写法
关键改动用注释标出:
# after.py
import os, json, time
import httpx
# 改动1:配置全部来自环境变量
BASE_URL = os.getenv("LLM_BASE_URL", "https://api.example.com/v1")
API_KEY = os.environ["LLM_API_KEY"] # 缺失即报错,不静默
MODEL = os.getenv("LLM_MODEL", "qwen3.6-max")
def ask(prompt: str, retries: int = 2) -> str:
payload = {
"model": MODEL,
"messages": [{"role": "user", "content": prompt}],
"temperature": 0.2,
}
for i in range(retries + 1):
try:
# 改动2:显式超时 + 统一协议
r = httpx.post(
f"{BASE_URL}/chat/completions",
headers={"Authorization": f"Bearer {API_KEY}"},
json=payload, timeout=30,
)
r.raise_for_status()
return r.json()["choices"][0]["message"]["content"]
except (httpx.TimeoutException, httpx.HTTPStatusError) as e:
if i == retries:
raise
time.sleep(2 ** i) # 改动3:指数退避
配套的 .env(加入 .gitignore):
LLM_API_KEY=sk-你的密钥
LLM_BASE_URL=https://api.example.com/v1
LLM_MODEL=qwen3.6-max
需要结构化结果时,加一段解析模板而非改主逻辑:
def ask_json(prompt: str) -> dict:
raw = ask(prompt + "\n只输出JSON,不要解释。")
return json.loads(raw.strip().strip("`").removeprefix("json"))
注意点:JSON 模式不是所有模型都严格保证,务必在调用侧做 try/except json.JSONDecodeError 兜底。
④ 收益与代价
| 维度 | 之前 | 之后 |
|---|---|---|
| 换模型 | 改代码重测 | 改一个环境变量 |
| 密钥泄露风险 | 高 | 低(不入库) |
| 网络异常 | 卡死 | 30s 超时 + 退避重试 |
| 代码行数 | ~15 | ~30 |
| 新增依赖 | 厂商 SDK | httpx 一个 |
代价很实在:多了一层 HTTP 手写,失去厂商 SDK 的便捷封装(如流式回调的语法糖);退避参数需要按实际限流策略调,盲目 2**i 在长任务里可能等太久。性能上单次调用几乎无差异,收益主要体现在可维护性与可移植性。
⑤ 适用边界与检查清单
不该这么改的时候:只做一次性脚本验证想法,硬编码反而更快;需要厂商独有能力(如特定多模态输入格式、专有工具调用协议)时,硬套兼容层会丢功能,此时直接用官方 SDK 更稳。
提交前检查清单:
- 密钥来自环境变量,
.env已在.gitignore - 有显式
timeout,不是默认无限等待 - 模型名可配置,未写死在函数体内
- 对非 200 响应有
raise_for_status - 解析 JSON 处有异常兜底
- 重试有上限,不会无限循环
面试/作业常被追问的点:为什么不用 time.sleep 固定间隔?——固定间隔在服务端限流下会形成同步风暴,指数退避能自然错峰。为什么密钥不放配置文件而放环境变量?——配置文件易被误提交,环境变量是部署环境注入的最小暴露面。
把 after.py 连同 .env.example 一起放进仓库,就是一段能讲清楚“配置与业务分离”的作品集代码,比任何教程截图都有说服力。
更多推荐


所有评论(0)