18-Models-Messages-Streaming官方深读

核对日期：2026-05-18
官方资料：Models https://docs.langchain.com/oss/javascript/langchain/models；Messages https://docs.langchain.com/oss/javascript/langchain/messages；Streaming https://docs.langchain.com/oss/javascript/langchain/streaming；Event streaming https://docs.langchain.com/oss/javascript/langchain/event-streaming。

官方概念

官方 Models 文档把模型定位为 Agent 的推理引擎。模型接口既能独立调用，也能放进 Agent loop。它统一了 provider 的调用方式，但 provider 能力仍然不同，包括 tool calling、structured output、multimodal、reasoning、prompt caching、server-side tool use 和 token usage。

Messages 是模型上下文的主要载体，包含 system、user/human、assistant/AI、tool 等角色信息。Streaming 则把一次生成拆成可消费的增量事件，官方现在还推荐关注 event streaming，因为它按投影维度拆出 messages、values、tool calls、subgraphs 等迭代器。

机制

模型层需要同时处理三件事：

主题	官方能力	工程含义
初始化	`initChatModel` 或 provider class	用简单模型标识起步，需要精细参数时用 provider class
调用	`invoke`、`stream`、`batch`	单次、流式、批量分别建测试
韧性	`timeout`、`maxRetries`、指数退避	网络、429、5xx 可重试；401/404 不应重试
高阶	model profiles、multimodal、reasoning、local models、prompt caching、base URL/proxy、logprobs、token usage	每个 provider 支持不同，必须按目标 provider 验证

TypeScript 官方写法

模型初始化有两种策略：

import { initChatModel } from "langchain";

const model = await initChatModel("provider:model-name", {
  temperature: 0.2,
  timeout: 30,
  maxTokens: 1000,
  maxRetries: 6,
});

当需要 provider 专属参数时，用 provider class：

import { ChatOpenAI } from "@langchain/openai";

const model = new ChatOpenAI({
  model: process.env.MODEL_NAME,
  temperature: 0.1,
  timeout: 30_000,
  maxRetries: 6,
});

Messages 可以用 object 格式，也可以用 message class。团队中更推荐在业务边界用 plain object，在底层 adapter 里转成官方 message class，避免 UI/API 层绑定到某个 SDK 类型。

Invocation 模式

模式	官方含义	适用场景	验收点
`invoke`	输入一个字符串或 messages，返回完整 AI message	分类、抽取、小任务	超时、错误、usage 记录
`stream`	返回增量 chunk	长回答、聊天 UI、工具执行反馈	中途取消、错误事件、最终聚合
`batch`	并行处理多个独立输入	离线分类、批量抽取、eval	`maxConcurrency`、速率限制、失败重试
`streamEvents` / event streaming	按事件或投影消费执行过程	需要区分 token、工具、子图、状态更新	前端协议、日志结构

Streaming 高阶用法

官方 streaming 文档区分：

stream mode	含义	适合
`updates`	Agent 每一步后的状态更新	显示“正在调用工具”“工具完成”
`messages`	LLM token 与 metadata	打字机式输出、reasoning token 过滤
`custom`	工具或图节点自定义进度	长任务进度，如“已抓取 10/100 条”
多模式数组	同时消费多类事件	Chat UI + 工具进度 + debug panel

工程上不要把 streaming 只理解成“逐字输出”。Agent streaming 还要暴露工具调用、HITL interrupt、错误和最终状态。

Python 差异

Python 也有 invoke/stream/batch 的 Runnable 思路，但包名、模型 class 和回调事件对象不同。TypeScript 的 zod 和对象消息形态更容易和前端共享；Python 的 Pydantic 和 notebook 示例更多。跨语言项目应统一 message wire shape 和 usage 统计字段。

工程边界

initChatModel("model-name") 很方便，但生产要明确 provider、版本、timeout、retry 和 token 限制。
streaming 的每个 chunk 都可能进入前端，必须定义错误、取消和 done 协议。
batch 不是无限并发，应设置 maxConcurrency 并按 provider rate limit 控制。
reasoning / multimodal / prompt caching 是 provider 能力，不是所有模型都有。

常见反模式

反模式	后果
只写 `model.invoke(prompt)`	无法迁移到多轮、工具和 streaming
不记录 model id 和参数	eval 结果不可复现
streaming 只处理文本 chunk	工具事件、错误、HITL 中断丢失
batch 不限并发	触发 rate limit 或成本尖峰
不区分 provider retry 规则	401/404 这类配置错误被错误重试

练习任务

给 src/examples/01-chat-model.ts 增加 model config 输出，模拟记录 model、temperature、timeout。
给 src/examples/07-streaming-runtime-guardrails.ts 增加 updates/messages/custom 三类 chunk 的本地模拟。
设计一个 batch eval runner，限制并发为 3，并记录每条 case 的 latency。

官方概念​

机制​

TypeScript 官方写法​

Invocation 模式​

Streaming 高阶用法​

Python 差异​

工程边界​

常见反模式​

练习任务​