AI Agent Engineer

AI Agent Engineer
个人学习进度

标记这门课程

课程正文公开可读；登录后可保存个人进度。

LLM API 集成学习目录

10 min read

LLM API 集成

资料核验日期：2026-07-22。端点、SDK 方法、认证方式、默认重试、模型标识、事件类型、速率限制、存储默认值和价格均可能变化；本库教授稳定的集成边界，并为三家 Provider 固定一组可审计合同基线。实际接入仍必须以锁定的官方文档、SDK 版本、机器 schema 和 live 集成测试为准。

知识库简介

LLM API 集成把提示、上下文与工具调用接入可运行软件。入门示例往往只有一次请求，但生产系统还需处理身份认证、分层超时、单一重试预算、限流、结构化输出、流中失败、用量、日志、隐私与供应商差异。本库分两层实践：先用供应商无关的离线 client contract 学习可靠性责任，再分别解析 OpenAI Responses、Anthropic Messages 与 Gemini Interactions v1 的当前 Reference/SDK 事件投影和续接合同。canonical 事件只属于第一层；第二层不把三家的身份、终态、存储和重放语义强行统一，也不把离线 fixture 冒充真实 SSE 字节或 live conformance。

在总路线中的位置

本库是 LLM 应用基础的工程出口。现代 LLM 能力与模型选择提供候选与任务级验收合同，提示词工程提供任务与输出合同，上下文工程提供证据与状态；本库负责可靠传输、解析、观测和错误控制。后续 Tool Calling、RAG、Agent 框架和 LLMOps 都依赖这些基础。

学习目标

  • 在 Windows 11 / PowerShell 7 中用 venv + pip 建立最小 Python 环境，并安全读取密钥。
  • 理解 HTTP、官方 SDK 与应用 adapter 的职责边界。
  • 构造版本可追溯的消息、模型配置和请求元数据。
  • 正确处理结构化输出、SSE 流式事件、拒绝、截断与中途错误。
  • 为超时、429、连接与 5xx 等暂时故障设计有上限、带抖动的重试；不重试永久错误。
  • 记录请求 ID、提示版本、用量、延迟与结果状态，同时保护敏感内容。
  • 用稳定 operation_id 关联同一业务操作的 attempts，并把模型生成与外部副作用分离。
  • 通过 capability check 显式拒绝无法等价映射的供应商功能。
  • 分别处理 Responses Item/call、Messages block/tool-use 与 Interactions step/interaction 的身份和终态，不用数组位置猜关联关系。
  • 区分有状态句柄、无状态重放、Provider 存储/保留、自有日志与 durable 业务状态，不把 store=false 误当全链路无留存。
  • 区分 Platform API Key、工作负载短期 token 与 ChatGPT/Codex OAuth，不把同名模型、认证、实际后端和 Agent runtime 混为一谈。
  • 区分 fixture 合同测试、SDK 集成测试、live 模型评测与生产审计各自能证明的范围。

前置知识

  • Python 函数、类、异常与 JSON 基础。
  • HTTP 请求/响应、状态码和环境变量的基本概念。
  • 已完成提示词与上下文工程更佳，但可边学边补。

推荐学习顺序

  1. 环境、依赖与密钥管理：建立可复现且不泄密的本机环境。
  2. HTTP、SDK 与请求生命周期：理解一次调用真正经过哪些层。
  3. 消息、配置与版本意识：设计供应商无关的请求合同。
  4. 结构化输出与流式响应：正确解析完整与增量结果。
  5. 超时、错误、限流与重试：只对可恢复错误做受控重试。
  6. 用量、可观测性与供应商适配：让请求可追踪、可比较、可替换。
  7. 可靠客户端项目与自测：运行 mock transport 的单元测试。
  8. 三家 Provider 合同测试：解析当前三家流式工具调用合同并构造正确续接。
  9. OpenAI Responses API 常见用法：从最小请求到多轮、流式、结构化输出、工具、检索和图像输入。
  10. OpenAI Platform API Key 与 Codex OAuth：认证、路由与 Runtime：区分 Platform、WIF 与 Codex OAuth，并理解 OpenClaw 的认证、模型路由和 runtime 选择。

动手实践与项目入口

先完成 可靠客户端项目：reliable_client.py 定义严格请求/响应、错误分类、Retry-After、指数退避、抖动、attempt/deadline 双上限与有事件/文本资源界限的 canonical 流状态机，22 项离线测试验证成功与失败路径。

再完成 三家 Provider 合同测试：标准库实现分别消费 OpenAI/Gemini typed SSE projection 与 Anthropic wire SSE envelope projection，只有到达 Provider 终态才释放调用；五种构造器验证有状态/无状态续接、调用方已验证的 canonical history、caller controls、完整结果集合和前序/本轮存储边界。构造器会做 bounded JSON/身份/必需字段检查，但不会把任意 caller history 变成供应商已认证的会话。99 项测试覆盖事件漂移、交错、截断、错误、重放、官方来源 host/path 攻击、Anthropic fallback beta fail closed 和资源上限。两层合计 121 项测试，但仍不替代真实 SDK/API 集成测试。

掌握标准

  • 能解释为什么 SDK 的默认重试与自己再包一层重试可能导致次数成倍增加。
  • 能为连接、首字节、整体请求和业务截止时间设置边界，而不是无限等待。
  • 能区分可解析 JSON、schema 合规、语义正确和动作已授权。
  • 能在流式 HTTP 已返回成功状态后继续处理错误事件与不完整终止。
  • 能用稳定的应用接口隔离供应商差异，不假装所有参数语义完全相同。
  • 能在不记录原始敏感内容的前提下定位某次请求使用的配置和失败原因。
  • 能运行 22 项可靠客户端测试和 99 项 Provider 合同测试，并证明未知异常、永久错误、流中失败、错误关联、资源越界与缺少终止事件都不会被误判为成功。
  • 能说明 SDK 自动重试、Provider call ID、业务幂等键与 exactly-once 为什么不是同一机制。

与其他知识库的关系

主要参考资料

Backlinks