大模型应用开发 / 系统课时
接入生成模型
接入生成模型
本节把“能访问模型”落实为一条可运行的调用链:用环境变量保存访问参数,通过兼容 Chat Completions 的 HTTP 接口发送消息,解析回复正文,并把超时、HTTP 错误和响应结构异常变成可定位的失败信息。
学习目标
- 配置模型地址、密钥、模型名和超时参数
- 发送一次对话请求并安全读取模型回复
- 区分网络超时、HTTP 调用失败和响应结构异常
准备访问参数
不要把密钥直接写进源码。应用只读取环境变量,部署环境再通过本机配置、容器 Secret 或密钥管理服务注入真实值。下面的变量名与具体模型供应商无关,只要求目标服务提供兼容的 /chat/completions 接口。
export LLM_BASE_URL="<BASE_URL>"
export LLM_API_KEY="<API_KEY>"
export LLM_MODEL="<MODEL>"
export LLM_TIMEOUT_SECONDS="15"这些命令属于配置片段,需把尖括号占位符替换为供应商实际参数。
预期结果
当前 Shell 会话中四个变量可被后续 Python 进程读取;配置动作本身不会产生固定控制台输出。随后可确认模型名和超时值,但不要打印完整密钥。
python -c "import os; print(os.environ['LLM_MODEL']); print(os.environ['LLM_TIMEOUT_SECONDS'])"预期输出
<MODEL>
15发送并解析对话请求
下面示例只使用 Python 标准库,因此无需额外安装 HTTP 客户端。请求体包含模型名和消息列表;成功后只向业务层返回 choices[0].message.content,不让上层代码依赖整份供应商响应。
import json
import os
import socket
from urllib import error, request
BASE_URL = os.environ["LLM_BASE_URL"].rstrip("/")
API_KEY = os.environ["LLM_API_KEY"]
MODEL = os.environ["LLM_MODEL"]
TIMEOUT_SECONDS = float(os.getenv("LLM_TIMEOUT_SECONDS", "15"))
def chat(user_text: str) -> str:
payload = json.dumps({
"model": MODEL,
"messages": [{"role": "user", "content": user_text}],
"temperature": 0.2
}).encode("utf-8")
req = request.Request(
f"{BASE_URL}/chat/completions",
data=payload,
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
},
method="POST"
)
try:
with request.urlopen(req, timeout=TIMEOUT_SECONDS) as resp:
body = json.load(resp)
except error.HTTPError as exc:
detail = exc.read().decode("utf-8", errors="replace")
raise RuntimeError(f"HTTP {exc.code}: {detail[:200]}") from exc
except (error.URLError, TimeoutError, socket.timeout) as exc:
raise RuntimeError(f"network error: {exc}") from exc
try:
content = body["choices"][0]["message"]["content"]
except (KeyError, IndexError, TypeError) as exc:
raise RuntimeError("unexpected response schema") from exc
if not isinstance(content, str) or not content.strip():
raise RuntimeError("empty model response")
return content.strip()
if __name__ == "__main__":
try:
print(f"content={chat('用一句简短的话说明 RAG 的作用')}")
except RuntimeError as exc:
print(f"call_failed={exc}")
raise SystemExit(1)预期输出
content=<VALUE><VALUE> 是模型实际生成的文本,因此每次可能不同。应用应只依赖“成功时得到非空字符串”这一契约,而不是依赖固定措辞。
看懂成功与失败路径
一次调用至少涉及应用、HTTP 服务和生成模型三个环节。把正常返回与三类失败分开处理,后续才能决定是重试、降级还是直接报错。

网络超时通常表示连接、DNS、代理或服务响应时间有问题;HTTP 401/403 多半是鉴权或权限问题;429 表示限流;5xx 更可能是服务端临时故障。unexpected response schema 则提示接口虽然返回了 JSON,但字段结构与当前解析逻辑不一致。
接入业务前的验证
先用一个短提示词验证“配置、鉴权、路由、解析”全部打通,再接入检索结果和长上下文。若调用失败,按“环境变量是否正确 → HTTP 状态码 → 响应体摘要 → 网络与超时”顺序定位,比直接修改 Prompt 更有效。
当这条最小调用链稳定后,RAG 的生成阶段就可以把检索出的上下文拼进消息内容;模型接入层仍只负责请求、响应解析和错误归一化,避免把检索逻辑与供应商协议耦合在一起。