langchain1.0开发入门

入门与上手

给开发者一份 LangChain 1.0 上手指南:先弄清核心概念的分工,再跑通一个最小可运行的例子,最后知道该往哪查。

你可能已经写脚本调通过大模型接口,但一想到「搭个应用」就不知道从哪儿下手:链、工具、检索、记忆这些词混在一起,文档又改过好几轮。这篇不铺开讲全家桶,只做三件事:把 1.0 里真正要用的几个概念按职责拆开,给一段能照着跑的最小例子,再告诉你接下来按什么顺序往上加东西。

你大概已经会用脚本调通一次大模型接口了,但想到「搭个应用」,链、工具、检索、记忆这些词就糊成一团,官方文档还改过好几轮,照着旧例子抄经常第一步就报错。这篇不铺开讲全家桶,只做三件事:把真正要用的几个概念按职责拆开,给一段能照着跑的最小例子,再告诉你接下来按什么顺序往上加东西。

先说一句省事的判断:如果你的需求只是「问一句、答一句」,那压根不用上框架,直接调官方接口最快也最好排查。只有出现多步骤、要中途调外部数据、要把几段输出串起来的时候,框架才开始划算。先把这条线划清楚,能帮你省掉一堆没必要的学习成本。

先分清 1.0 里几个概念的职责

新手最容易犯的错,是把整套东西当成一个大框架来背。其实拆开看就四件事:怎么把话发给模型、怎么把提示词固定下来、怎么让模型去调一个外部动作、怎么把外部资料喂进去。四件事各自解决各自的问题,混在一起学才会觉得乱。1.0 的写法比早期版本收敛了不少,能少写的样板代码就别硬抄旧教程。

模型调用
把一段文本发给模型、拿回一段文本,其余都是在这上面加东西
提示模板
把反复出现的提示词抽成一个带占位符的模板,换任务只改一处
工具调用
让模型决定「我该去查一下」,由你的代码执行真实动作再把结果交回去
检索
先从你自己的资料里捞出相关片段,再拼进提示词,而不是让模型凭空答

什么情况下不适用?如果你还没独立跑通过一次最普通的接口调用,报错时你分不清是框架抛的、接口返回的、还是自己的代码炸的,先回去补那一课。另外别默认这套东西只此一家,同类框架的分工差异可以到 /stacks/frameworks 对照着看,选谁更多是团队习惯问题,不是对错问题。

最小可跑例子:从一次调用到一条链

别一上来就搭完整流水线。按三段走,每段都能单独跑通再往下,出问题时你就知道该停在哪一段。第一段只做「输入一句、输出一句」,把密钥、模型名、超时这些参数统一放进配置文件,不要写死在函数体里,不然换环境要改的地方太多。

  1. 第一段:跑通单次调用目标只有一个——打印出模型的回复。验证方式:写死一句问题,运行能看到正常输出,就算过。
  2. 第二段:抽出提示模板把提示词单独放一个文件,用占位符留出变量。验证方式:改一处模板,换不同输入都走同一段代码。
  3. 第三段:挂一个外部工具查天气、读本地文件、查数据库都行,重点是让模型输出「要调工具」的信号,你的代码真的去执行。验证方式:打印中间步骤,确认工具确实被触发过,而不是模型自己编了答案。

还有个小提醒:工具函数本身要能独立测试。先不经过模型、直接拿写死的参数调一次你的工具函数,确认它自己能返回正确结果,再把它交给模型去决定什么时候调。这样能排掉一大半「看起来是框架的问题」。

工程化前置:密钥、依赖与目录

例子能跑之后,先把这三件小事做掉,不然等代码量涨起来会很难受。它们不花什么时间,但能避免团队协作里最烦人的「只在我机器上能跑」。具体每种框架读哪个环境变量名,以它的官方说明为准,别凭记忆写。

  • 密钥一律走环境变量,不进代码库;本地用不提交的配置文件,线上用部署平台的密钥管理
  • 依赖版本锁死,框架迭代快,两个人装出不同版本就会出现莫名其妙的报错
  • 目录至少分三块:配置、提示词、业务代码,提示词多起来你会庆幸当初这么分
  • 给每次模型调用留一条日志,记下输入长度和耗时,出问题时有据可查

版本这件事值得多说一句:别急着追最新,先看团队里其他人用的什么,统一了再动。升级前先跑一遍你现有的例子,确认行为没变再往生产推。

往上加东西的顺序,以及该去哪查

推荐的加层顺序是:单次调用 → 提示模板 → 工具调用 → 检索增强 → 多步流程。每加一层,都要先保证上一层还能跑,不然一旦出问题,你面对的是一堆互相纠缠的变量。这个顺序不是铁律,但按它走,出错时你基本能定位到是哪一层新引入的。

你现在想要的功能优先加哪一层什么时候先别加
换个问法问同一件事提示模板还没跑通单次调用
让模型查实时信息工具调用工具函数自己单独测都过不了
基于自己的资料回答检索增强资料量很小,直接塞进提示词就够
拆成多步自动跑多步流程前面几层还没稳定,或单步就能满足需求

查资料的时候,需要外部知识先看 /stacks/vector-dbs 和 /embeddings,向量库不是越贵越好,先按你的数据量和查询频次选,量小的时候用简单的方案反而更省心。报错则先分类:框架抛的、接口返回的、还是你的工具函数自己炸的,三类处理方式完全不同;接口类报错按返回的错误文本来查,别把状态码和错误信息混着看。

最后是钱的问题。心里没底就去 /tools/model-cost-calculator 按你的调用量和上下文长度估一遍,再决定要不要用更省 token 的写法。同一件事换种提示词写法,成本差别可能不小,但具体差多少,到站内页面按你当时的参数核对,别信任何一口价的说法。

下一步例子跑通之后,去模型资料库把你在用的那个模型的上下文长度和调用限制看清楚,再回来决定要不要上检索,这一步能省掉不少返工。

常见问题

LangChain 1.0 和早期版本差别大吗,老教程还能照着抄吗?

写法收敛了不少,老教程里的很多样板代码现在可以直接删掉。建议以官方文档的当前写法为准,老教程只用来理解概念,不要把代码结构整套搬过来,否则你会花大量时间在已经不需要的抽象上。

必须用框架吗?直接调接口不行吗?

单轮问答、简单分类这类,直接调接口更省事也更好排查。出现多步骤、要调外部工具、要接知识库、要在团队里长期维护提示词时,框架的收益才明显。判断标准是复杂度和维护人数,不是新不新。

跑通了例子之后,下一步该学什么?

按「提示词模板 → 工具调用 → 检索增强 → 多步流程」这个顺序往上加,每加一层先确保上一层还能跑。同时把密钥管理和依赖版本这两件事固定下来,不然越往后越容易出只在某台机器上复现的问题。

本文依据各平台公开文档与官方公告整理,只做中文归纳;具体做法、参数与限制以官方文档为准。