第一次调用大模型 API：环境变量、请求与错误排查

本教程演示一种常见的 Chat Completions 风格接口。它是通用示例，不是经过验证的 RunAPI 接入教程，也不保证所有模型平台兼容。你需要从所选服务的文档确认端点、认证方式与请求结构。

1. 准备三项配置

在服务商官方文档中找到完整请求地址、可用模型标识与账号密钥。仅使用有权限的账号。密钥应在本机或服务端配置，不要上传到公共仓库。

# PowerShell：只影响当前终端进程
$env:LLM_ENDPOINT = "https://服务商域名/文档指定的完整端点"
$env:LLM_MODEL = "文档中的模型标识"
$env:LLM_API_KEY = "你的密钥"

这里的域名和模型名必须替换，不能原样运行。输入密钥前留意终端历史记录和屏幕共享；生产环境优先使用受控的密钥管理方式。

2. 用标准库发起请求

import json
import os
from urllib.request import Request, urlopen
from urllib.error import HTTPError, URLError

payload = {
    "model": os.environ["LLM_MODEL"],
    "messages": [{"role": "user", "content": "用两句话解释什么是 Token。"}]
}
req = Request(
    os.environ["LLM_ENDPOINT"],
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + os.environ["LLM_API_KEY"],
        "Content-Type": "application/json"
    },
    method="POST"
)
try:
    with urlopen(req, timeout=60) as response:
        result = json.load(response)
    print(result["choices"][0]["message"]["content"])
except HTTPError as exc:
    print("HTTP 错误：", exc.code)
except URLError:
    print("网络连接失败，请检查地址和网络。")
except (KeyError, IndexError, TypeError):
    print("配置缺失或响应结构不同，请对照服务商文档。")

如果平台使用不同的认证头、消息格式或响应字段，需要相应修改。这里没有自动重试，避免新手在错误配置下重复产生消费。

3. 从错误定位问题

401：常见原因是密钥无效、过期或认证格式错误。
403：检查权限、地区限制与平台说明。
404：检查端点路径；某些服务也用它表示模型不存在。
429：可能涉及速率或额度限制，先读服务商错误信息。
5xx 或超时：记录时间和请求标识，采用有限次数的退避重试；不要无限循环。

4. 让测试可复现

记录准确模型、输入、输出、耗时与账单。不要将凭据或敏感响应写进公开日志。测试成功只说明这一项请求可执行，不证明长期稳定。

1. 准备三项配置

2. 用标准库发起请求

3. 从错误定位问题

4. 让测试可复现

继续阅读