LLM API 入门

大语言模型（LLM）API 是 AI 工程的基础。本章带你从开通账号、配置环境，到稳健调用、成本/安全/可观测性要点，完成入门闭环。

1) 生态速览与选型

选型建议：通用先选 OpenAI；长文档/安全 → Claude；多模态 → Gemini 3 Pro/Flash；预算敏感先用“小”模型。

示意图：LLM API 调用链路

2) 环境与密钥管理

• 创建并保存 API Key：OpenAI [platform.openai.com]、Claude [console.anthropic.com]、Gemini [ai.google.dev]。
• 将 Key 写入 .env，不要硬编码或放前端：

OPENAI_API_KEY=sk-xxx
ANTHROPIC_API_KEY=sk-ant-xxx
GEMINI_API_KEY=xxx

• 安装 SDK（常用）：
  • Python: pip install openai anthropic google-generativeai
  • Node: npm i openai @anthropic-ai/sdk @google/generative-ai
• 网络与超时：国内需代理；客户端超时 30s 以上，必要时设置重连。

3) 第一次调用（Python & Node）

Python (OpenAI):

from openai import OpenAI
import os

client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
messages = [
    {"role": "system", "content": "你是一个简洁的技术助手"},
    {"role": "user", "content": "用一句话解释什么是 API"}
]
resp = client.chat.completions.create(model="gpt-5", messages=messages)
print(resp.choices[0].message.content)
print("tokens:", resp.usage.total_tokens)

Node (Claude):

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
const resp = await client.messages.create({
	model: 'claude-3-haiku-20240307',
	system: '你是一个简洁的技术助手',
	messages: [{ role: 'user', content: '用一句话解释什么是 API' }],
	max_tokens: 200
});
console.log(resp.content[0].text);
console.log('tokens:', resp.usage.input_tokens + resp.usage.output_tokens);

多轮对话：在客户端维护 messages/history，每轮附带上下文发送。

4) 核心参数与调优

• model：先用最新的“小”模型（成本低），需要质量再换高配。
• temperature / top_p：随机性，0-0.7 常用；更创意可升高。
• max_tokens：限制输出长度，避免爆量扣费。
• presence_penalty / frequency_penalty：减少/增加重复。
• stop：定义停止符，控制输出格式。
• 系统提示：用 system 设定角色与风格，保持稳定输出。

5) 响应格式与结构化

• 要求 JSON 输出：在 prompt 明确格式，或使用厂商 JSON Mode（如 OpenAI response_format={"type":"json_object"}）。
• 验证输出：用 JSON schema 校验；失败时重试或降级。
• 表格/列表：指定字段名、顺序和示例，减少跑题。

6) 流式输出与体验

• 开启 stream 获取增量：
  • OpenAI Python：stream=True，迭代 for chunk in resp
  • Node：遍历 AsyncIterable，实时拼接
• 前端/终端要点：逐字追加、保留光标、支持取消。

7) 错误处理与可靠性

• 常见错误：401（Key/权限）、429（限流/配额）、5xx（服务端）。
• 重试策略：指数退避（如 0.5s, 1s, 2s...），限制最大重试次数；对 4xx 先检查配置。
• 超时与取消：为 HTTP 客户端设置超时；长流式可提供中断。
• 记录：日志包含请求 ID、模型、延迟、tokens 用量；必要时打点到 APM。

8) 成本与配额管理

• Token 概念：输入/输出分别计费；控制对话长度、裁剪历史。
• 节省策略：优先小模型；压缩上下文（摘要/检索 top-k）；设置 max_tokens。
• 监控：关注各平台配额/用量面板，异常用量要报警。

9) 安全与合规

• 不在前端暴露 Key；推荐后端代理网关统一鉴权、限流、审计。
• 数据最小化：少传 PII，必要时脱敏；避免把敏感文件直接送模型。
• 内容安全：利用厂商自带的安全过滤（如 Gemini 安全级别）或在网关二次校验。
• 访问控制：按环境分 Key（dev/uat/prod），最小权限，定期轮换。

10) 工程化封装与多提供商

• 抽象调用层：统一请求体、日志、错误码，方便切换模型或厂商。
• 多提供商回退：主模型失败时自动切换次优模型；对关键路径可并行竞速取最快。
• 观测性：埋点模型名称、延迟、成功率、tokens，用仪表盘追踪。

11) 性能与延迟优化

• 并发与队列：对高并发入口做排队/令牌桶，避免 429；控制单用户速率。
• 请求模板化：常用系统提示/格式模板化，减少重复字符串拼接。
• 压缩上下文：摘要历史、只带必要字段；长文本先做分段检索再拼上下文。
• 缓存：对确定性回答（FAQ/静态知识）可在上游缓存，命中直接返回。
• 传输优化：开启 HTTP/2；减少无关请求头；避免巨型 JSON。

12) 本地调试与模拟

• 使用真实 Key 前，先在本地用最小 prompt 验证。
• Mock：对前端/集成测试可用固定回复的 mock 服务，避免消耗额度。
• 速查：打印完整请求（去敏处理）与响应头，定位限流/区域问题。

13) 生产就绪清单

• Key 管理：分环境、可回收、可轮换；禁止前端暴露。
• 异常处理：401/403/429/5xx 有清晰提示；重试/超时策略已配置。
• 监控：成功率、P95 延迟、token 成本、限流次数、回退次数。
• 安全：输入脱敏、输出审查；日志避免泄露用户敏感内容。
• 灰度：新模型/参数走灰度或小流量 A/B，对比质量与成本。

14) 小练习

1. 写一个脚本：接受用户输入，调用 LLM，支持切换 temperature 与模型。
2. 在代码中加入 429/5xx 重试 + 30s 超时，打印 tokens/成本估算。
3. 开启流式输出，在终端实时显示增量文字；失败时自动降级为非流式。