直接调用模型 SDK 与使用框架

核心答案：SDK 主要封装厂商协议，框架主要组织应用结构。 SDK 调用可以写进 LangGraph 节点；这不是必须二选一的架构。框架也不能让模型变得确定，或让不同厂商的全部能力天然兼容。

分清抽象层

选择	主要收益	需要自己承担
HTTP / 厂商 SDK	请求与响应直接可见，接入新能力较快	消息适配、工具循环、错误分类
模型统一抽象	减少厂商间重复适配	处理抽象未覆盖的特殊字段
Agent 框架	复用工具循环与中间件	明确停止条件、权限与业务约束
状态编排框架	表达分支、暂停、恢复	业务事务、外部副作用与版本控制

LangChain 官方概览描述高层 Agent 组合；LangGraph 官方概览强调状态与流程控制。选择时先列需要的能力，而不是比较谁“更高级”。

最小例子：稳定应用契约

from dataclasses import dataclass

@dataclass
class ModelResult:
    text: str
    input_tokens: int | None
    output_tokens: int | None

def decode_response(raw):
    usage = raw.get("usage", {})
    return ModelResult(raw["text"], usage.get("input_tokens"),
                       usage.get("output_tokens"))
result = decode_response({"text": "你好"})
assert result.input_tokens is None

独立示例说明缺失 usage 应记录为未知，不能填 0 冒充零成本。真实适配器负责将厂商响应转换成应用契约，并保留必要的请求 ID、模型名与失败类型。

教材系统中的选择

本项目需要重点学习原始模型调用、结构化输出与函数请求，因此保留可读的服务适配层，让 LangGraph 只管理流程。这样可以分别定位“供应商接口变了”和“流程路由错误”。对常规 LLM 接口可采用兼容协议；图片与语音服务仍应按各自真实契约接入，不能假定改个 base_url 就全部兼容。

如果后来增加多厂商路由、复杂消息转换和观测中间件，统一框架的收益会增加。迁移前应先做契约测试：相同输入下，字段、错误与工具结果回传是否满足业务要求。源码导航见系统架构。

自测与排障

给示例加入 usage，再删除 output_tokens，解释三种结果如何影响成本统计。接着写出服务适配契约的最小字段，并说明超时不等于供应商未执行。

常见误区是只统计自己写了多少行代码。框架节约的行数如果变成隐式重试、难以定位的状态转换，也可能增加维护成本。反过来，为了“完全可控”重写成熟的持久化编排，也需要承担正确性验证。

官方资料与版本边界

• OpenAI Function Calling：理解不依赖框架的工具交互契约。
• LangChain overview：高层应用组合。
• LangGraph overview：编排层职责。

核验日期：2026-11-03。页面不承诺 SDK 与任意兼容服务完全互通；支持的字段、重试默认值和错误类型必须以锁定 SDK 及服务端能力为准。