LLM 接入基础

是什么

把大模型当作一个"给定 messages，返回文本"的函数。Agent 的所有智能都建立在这个调用之上：理解它、控制它、度量它。

为什么需要

Agent 本质是"循环调用 LLM + 外部动作"。如果连一次稳定、可控、可计费的调用都做不好，上层架构都是空中楼阁。

核心概念

• Messages 结构：system（设定角色与规则）、user、assistant（历史）、tool（工具返回）。
• 流式（stream）：token 逐个返回，用于降低首字延迟、支持打字机体验。
• 采样参数：temperature（创造性，0=稳定）、top_p（核采样）。
• 上下文窗口：输入 + 输出 token 上限，溢出会截断或报错。
• 成本维度：按 token 计费，区分输入/输出价格；长上下文与推理模型更贵。

最小代码范式

from openai import OpenAI

client = OpenAI()  # 读环境变量 OPENAI_API_KEY

resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "你是一个严谨的运维助手，只回答与 Kubernetes 相关的问题。"},
        {"role": "user", "content": "Pod 一直处于 Pending 怎么排查？"},
    ],
    temperature=0.2,
    stream=True,
)
for chunk in resp:
    if delta := chunk.choices[0].delta.content:
        print(delta, end="")

模型选型维度

维度	关注点
能力	推理、代码、多语言、长上下文理解
成本	输入/输出单价、是否有免费额度
延迟	首字延迟、吞吐（影响交互体验）
上下文窗口	能否放下检索结果 / 长对话
多模态	是否支持图片 / 文件输入

常见陷阱

• 上下文溢出：把整库文档塞进 prompt，既贵又易截断。交给 RAG（见 06-rag）。
• 成本失控：日志里打印完整 prompt、无缓存、用大模型做简单分类。
• 无重试/退避：遇到 429（限流）直接失败，应指数退避 + 抖动。
• 供应商锁定：把调用细节散落各处，建议封装一层 LLMClient 便于换模型。

参考

• OpenAI Platform Docs（Chat Completions / Streaming）
• Anthropic Claude Docs（Messages API）
• 各云厂商大模型服务文档（阿里云百炼、腾讯云混元等）