我是AI时代的无业游民,我游荡在现实与意念之间


AI 编程智能体零门槛调用手册:从“能跑”到“敢放进作品集”

An abstract conceptual illustration of a central g

什么时候用这份手册

你刚学完一门语言,想让 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
新增依赖厂商 SDKhttpx 一个

代价很实在:多了一层 HTTP 手写,失去厂商 SDK 的便捷封装(如流式回调的语法糖);退避参数需要按实际限流策略调,盲目 2**i 在长任务里可能等太久。性能上单次调用几乎无差异,收益主要体现在可维护性与可移植性。


⑤ 适用边界与检查清单

不该这么改的时候:只做一次性脚本验证想法,硬编码反而更快;需要厂商独有能力(如特定多模态输入格式、专有工具调用协议)时,硬套兼容层会丢功能,此时直接用官方 SDK 更稳。

提交前检查清单:

  • 密钥来自环境变量,.env 已在 .gitignore
  • 有显式 timeout,不是默认无限等待
  • 模型名可配置,未写死在函数体内
  • 对非 200 响应有 raise_for_status
  • 解析 JSON 处有异常兜底
  • 重试有上限,不会无限循环

面试/作业常被追问的点:为什么不用 time.sleep 固定间隔?——固定间隔在服务端限流下会形成同步风暴,指数退避能自然错峰。为什么密钥不放配置文件而放环境变量?——配置文件易被误提交,环境变量是部署环境注入的最小暴露面。

把 after.py 连同 .env.example 一起放进仓库,就是一段能讲清楚“配置与业务分离”的作品集代码,比任何教程截图都有说服力。

Logo

更多推荐