LangChain 入门:用 JavaScript 组织模型调用与提示模板
给页面加一个“AI 生成”按钮,第一步通常不难:把用户输入发给模型,再把回答展示出来。真正麻烦的是后面的需求——换一种写作风格、延续上一轮对话、让结果填进表单、在失败时指出具体原因。
例如,我们希望用户输入“JavaScript Promise 的错误传播”,应用就生成一份面向前端开发者的文章提纲。接下来,用户还可以说“减少概念介绍,多加几个排错案例”。这时需要组织的已经不只是一段提示词,而是输入、上下文、模型响应和业务数据之间的关系。
本文用这个例子讲清楚 LangChain 的几个基础概念,以及它们在 JavaScript 应用中怎样配合。配套的可视化编辑项目放在 GitHub:LangChainWeb。读完本篇,可以继续看实战篇,把一次调用扩展成可以编辑和运行的工作流。
一、从一次请求到一条调用链
先看最普通的实现:读取主题,拼接提示词,发送请求,取出返回文本。对于单一、稳定的功能,这样完全可以满足需求,没有必要为了调用一次模型就引入一整套框架。
当多个功能开始共享同一套逻辑时,维护成本才会出现。例如,提纲生成和正文改写都要处理模型配置;三个接口各自拼接历史消息;模型切换后,返回内容的读取方式又需要一起调整。
LangChain 的基础组件把这条路径拆成几个具有明确输入和输出的步骤:
| 步骤 | 接收什么 | 产出什么 | 主要职责 |
|---|---|---|---|
| 提示模板 | 主题、读者、要求等业务字段 | 按角色组织的提示消息 | 稳定地组装输入 |
| 聊天模型 | 消息列表或提示值 | 模型响应消息 | 生成内容 |
| 输出解析器 | 模型响应或文本 | 字符串、对象等数据 | 转换表示形式 |
| 业务校验 | 解析后的数据 | 可接受的结果或明确错误 | 判断结果能否交给应用 |
这样做的收益是可以分别检查、替换和复用每个步骤。更换模型时,尽量保持上下游的数据约定;修改提纲格式时,重点调整提示要求和结果校验。
但统一接口不会抹平模型差异。不同模型支持的输入类型、工具调用、上下文长度和结构化输出能力仍然需要核实。模型适配器的作用,是把这些差异放在一个相对集中的位置处理。相关能力可对照官方模型文档。
二、消息:给上下文保留角色与顺序
聊天模型看到的通常是一组消息,而不是浏览器中的聊天气泡。LangChain 用消息对象承载角色、内容及相关元数据。
| 消息类型 | 在提纲生成例子中的含义 |
|---|---|
SystemMessage |
说明写作任务、输出要求和固定规则 |
HumanMessage |
用户输入主题,或者提出本轮修改要求 |
AIMessage |
模型上一次给出的提纲;在工具场景下也可能包含工具调用请求 |
ToolMessage |
工具执行后返回的结果,需要对应具体的工具调用 |
这些类型及其内容结构见官方消息文档。在简单文本任务里,内容可以是一段文字;扩展到图片、音频或工具时,就不能假定每条消息的内容都是普通字符串。
多轮对话为什么要重新带上历史
用户第二次只说“第三节展开一点”,这句话本身没有交代主题,也没有说明第三节是什么。为了理解它,模型至少需要看到上一版提纲和本轮要求。
一次合理的上下文顺序是:固定规则 → 上一轮用户需求 → 上一轮提纲 → 本轮修改要求。模型服务是否支持会话状态是另外一层能力;仅仅创建消息对象,不会让应用自动保存历史。
LangChain 的 MessagesPlaceholder 可以把已有的消息列表插入模板的指定位置。它解决的是历史放在哪里,历史从哪里读取、如何按用户隔离、保留哪些内容,仍然属于应用设计。MessagesPlaceholder API中可以查看对应接口。
实际实现时还要分清“聊天历史”和“当前成果”。如果用户已经在表单里把第三节改过,当前提纲才是本轮修改的准确起点,聊天记录中的旧提纲只能作为补充。否则,模型可能认真地修改了一个已经过时的版本。
历史也不适合无限追加。可以保留近期完整对话,再加一份当前提纲和关键要求;更长的记录按任务需要检索或摘要。涉及工具时,应保留工具请求与结果的配对关系,不能简单截断到任意一条消息。
三、提示模板:把任务约定与用户数据分开
提示模板最容易被理解成字符串替换,但它更有用的地方是让输入约定变得明确。文章提纲任务可以分成三部分:
| 部分 | 示例 | 谁来决定 |
|---|---|---|
| 固定任务 | 生成技术文章提纲,每一节说明要回答的问题 | 应用配置 |
| 可变输入 | 主题、目标读者、章节数量、表达风格 | 表单或当前请求 |
| 当前上下文 | 上一版提纲、用户已经确认的修改要求 | 应用状态 |
ChatPromptTemplate 用于组合这些消息。常见的 {topic}、{audience} 是模板变量,调用时需要提供对应字段;它们不是模型会自动去读取的 JavaScript 变量。ChatPromptTemplate API描述了模板的输入与格式化接口。
一份针对提纲任务的提示要求可以写成:
为了解 JavaScript 基础的开发者规划一篇文章。主题由本轮输入提供。输出四节提纲,每节包括标题、要解释的问题和一个可验证的示例方向。没有依据的性能数字不要补写;主题不明确时,指出缺少的信息。
这段要求有三个可检查的目标:读者是谁、结果包含哪些内容、哪些信息不能凭空补齐。相比“请写得专业一点”,它更便于评价结果是否符合用途。
这里还有一个实现细节:先准备好业务数据,再让模板引用它。 例如,把当前提纲整理成一个独立输入字段,比在多个字符串片段中混合拼接更容易排错。模板文本里的固定 JSON 大括号还可能与变量语法冲突,需要按模板格式转义;把 JSON 作为一个变量值传入,通常更容易管理。
模板可以统一表达要求,但不会强制模型遵守,也不会核实事实。用户提供的资料仍然是待处理内容,不能因为它被放进模板,就获得修改应用权限或执行工具的能力。
四、Runnable:统一步骤的调用方式
在 JavaScript 中,可以把 Runnable 理解成遵守同一套调用接口的处理单元。模板、模型和解析器能够组合起来,关键在于:前一步的输出,必须符合后一步的输入要求。
以提纲任务为例,数据依次经历以下转换:
- 业务对象包含主题、读者和章节数。
- 提示模板把对象转换成可以表示为消息列表的提示值。
- 模型接收提示,返回一条响应消息。
- 解析器从响应中提取文本或对象。
- 应用检查章节是否齐全,再更新页面。
pipe 用来描述这些步骤的连接关系,组成的 RunnableSequence 会把每一步的结果交给下一步。它并不意味着每一步都会调用模型,也不意味着各步骤会并行执行。RunnableSequence API给出了这一组合接口。
三个常见入口分别适合什么任务
| 入口 | 使用场景 | 实现时要注意 |
|---|---|---|
invoke |
为一个主题生成一份提纲 | 等待本次调用完成,处理成功或失败 |
batch |
为多个独立主题分别生成提纲 | 控制并发量、速率和费用;它不等于把所有主题塞进同一条提示 |
stream |
在生成过程中持续接收内容 | 检查模型及中间步骤是否支持增量传递 |
流式输出尤其容易产生误解:模型能逐步返回文字,不代表整条链都会立即向页面转发。一个中间步骤如果要等完整结果才能解析,后续输出仍然可能被缓冲。实现时要分别观察模型输出、服务端转发和浏览器消费三个位置。
调试也可以沿着数据边界进行。输入变量缺失,应先检查模板;已经得到响应但页面没有内容,应查看响应类型和解析器;解析成对象后被拒绝,则查看业务约束。把这些阶段都显示成“AI 出错了”,会让排查变得很慢。
五、结构化输出:让回答进入表单和后续流程
如果提纲只用于阅读,一段 Markdown 就够了。如果页面要让用户逐节编辑、调整顺序、继续生成正文,就需要一份稳定的数据结构。
例如,可以约定每份提纲包含以下内容。这里展示的是教学用的数据约定,不对应某个项目的接口:
| 字段 | 类型 | 约束与用途 |
|---|---|---|
title |
字符串 | 非空,作为文章标题 |
audience |
字符串 | 说明目标读者 |
sections |
数组 | 本次要求恰好四节 |
每节的 id |
字符串 | 在这份提纲中唯一,便于编辑时定位 |
每节的 heading |
字符串 | 小节标题 |
每节的 goal |
字符串 | 说明该节要解决的问题 |
要让这份结果可靠地进入应用,需要经过三道检查:
| 检查层次 | 能发现什么 | 还不能说明什么 |
|---|---|---|
| 格式解析 | 返回文本是否能够解析为 JSON | 对象是否具有正确字段 |
| Schema 校验 | 字段类型、必填项、数量与范围是否符合约定 | 内容是否正确、有用 |
| 业务校验 | 小节 ID 是否重复、引用是否存在、是否符合本次任务 | 文中的事实是否都有依据 |
JsonOutputParser 主要解决解析问题。能解析出一个对象,不等于它已经满足这些规则。支持相应能力的模型适配器可以通过 withStructuredOutput 等方式施加输出结构约束,但具体策略取决于适配器和模型;使用前应查阅模型结构化输出说明。
即使结构正确,也要检查内容质量。“四节提纲”可能四节都在重复概念,没有任何实践问题。对文章生成任务,可以用覆盖范围、重复程度、示例可验证性这些标准做评估,不能只用 JSON 校验通过率衡量效果。
失败后如何修正
假设模型返回了五节提纲,而本次需要四节。可以把具体的校验反馈连同原始要求交给模型,让它重新生成符合约定的结果,并设置有限的尝试次数。
这种“根据反馈修正输出”与网络重试是两种处理。网络超时需要判断请求是否已经被服务端接受;字段缺失需要修改结果;权限或配置错误则需要修正配置。把所有错误都直接重试三遍,可能只会增加等待时间和重复请求。
对于可以展示但尚未通过校验的结果,也可以先保留为草稿,标明问题,让用户继续编辑。不要让一个内容不完整的对象悄悄进入后续自动执行步骤。
六、怎样把这条链放进前端应用
一个常见的实现方式,是由浏览器负责输入和结果交互,应用服务负责组装上下文、调用模型和校验结果。模型服务凭据保留在服务端,浏览器只提交本轮任务需要的业务数据。
开发顺序可以从最小闭环开始:
- 固定输入与输出约定。 先确定主题、读者、章节数,以及页面需要哪些结果字段。
- 用模拟结果跑通页面。 检查加载状态、编辑操作和错误展示,不依赖模型随机输出。
- 接入一次真实调用。 单独查看模板组装后的消息、模型响应和校验结果。
- 补齐续改。 下一轮同时携带当前提纲和必要历史,避免修改旧版本。
- 处理请求竞争。 用户改了内容、切换页面或取消请求后,旧响应不能覆盖新状态。
模拟结果只能说明交互与数据通路可以工作。真实模型是否能稳定生成合适的提纲,还需要用一组固定输入反复检查,例如宽泛主题、信息不足的主题、带有明确限制的主题,以及多轮修改。
在开源项目 LangChainWeb 中,可以从对话助手组件观察“当前内容 + 历史消息 + 本轮要求”的组织方式,以及请求取消和候选结果的处理。它的前端交互适合借鉴;模型服务与执行能力仍需由对应服务提供。
七、什么时候需要 Agent 或 LangGraph
理解一次调用链之后,再看 Agent 和 LangGraph,就容易分清它们分别解决什么问题。
| 需求 | 可以从哪里开始 | 下一步由谁决定 |
|---|---|---|
| 固定地生成一份提纲 | 普通异步函数,或模板、模型、解析器组成的链 | 开发者预先确定 |
| 先提纲、再正文,保留各步骤结果 | 显式工作流;复杂后使用 LangGraph 管理状态与跳转 | 图结构及条件规则 |
| 根据任务选择搜索、查询等工具,并决定是否继续 | 使用模型决策的 Agent | 模型在应用允许的范围内决定 |
| 暂停等待用户确认,再继续后续步骤 | 具备检查点与恢复机制的图执行流程 | 流程规则与外部输入共同决定 |
LangChain 的 createAgent 用于构建代理;LangGraph 提供更底层的状态和执行控制。两者可以结合,图中的某个节点也可以包含一条模型调用链或一个代理。官方的工作流与代理说明讨论了这类区别。
选型时可以先写下一个问题:下一步是固定的,还是需要模型根据结果决定? 如果步骤已经确定,明确的数据转换往往就足够了。需要分支、循环、多个中间结果或暂停恢复时,再把执行过程表达成图。
下一篇会沿着“输入主题 → 生成提纲 → 撰写正文”的例子,继续讨论工作流定义、节点状态和可视化编辑:LangChain 与 LangGraph 项目实战:从对话生成到可编辑工作流。
LangChain 入门:用 JavaScript 组织模型调用与提示模板
https://hjb.leheavengame.com/2026/05/01/LangChain-入门:用-JavaScript-组织模型调用与提示模板/

