langchain1.0 入门

入门与上手

面向开发者的 LangChain 1.0 入门速查:搞清它由哪几块拼起来、最小可跑的搭建顺序,以及卡住时该按什么顺序排查。

你可能已经听过 LangChain,也照着别人的例子粘过一段代码,但一到自己项目里就懵:到底该用哪几个包、谁负责拼提示词、谁负责调模型、跑不起来是环境问题还是写法问题。这篇不讲原理史,只给一条从零到能跑通的最小路径:先认包、再装环境、写出第一个能跑的链路,最后按一份排查清单收尾。看数字类信息请到站内对应页面核对。

你可能已经听过 LangChain,也照着别人的例子粘过一段代码,但一到自己项目里就懵:到底该装哪几个包、谁负责拼提示词、谁负责调模型、跑不起来是环境问题还是写法问题。这篇不讲原理史,也不讲它怎么演变来的,只给一条从零到能跑通的最小路径:先认包,再装环境,写出第一个能跑的链路,最后按一份排查清单收尾。涉及价格、模型清单这类会变动的数字,请到站内对应页面核对当时的情况。

读的时候建议一边读一边动手。每小节末尾的判断标准,可以直接当成你项目里的取舍依据;如果某一步在你的场景里不适用,我会写清什么情况下可以跳过。

先认清 LangChain 1.0 到底是什么,别把它当框架全家桶

一句话:它是把「模型调用 + 提示词 + 工具 + 记忆」串成链的编排层。它不是模型本身,也不是你必须整套都用上的东西。很多入门项目真正用到的只有前三块,工具和记忆是后面按需加的。

编排层
负责把提示词、模型调用、输出处理这几步按顺序串起来,本身不产生智能
模型
真正干活的推理服务,可以是官方 API,也可以是通过中转站转发的接口
提示词模板
把变量填进固定话术里,避免每次手写字符串拼接
工具
让模型去查东西、算数、调外部接口的能力,不是入门必备
记忆
把前几轮对话带进下一轮,单轮任务用不上

和直接写 HTTP 请求比,它省掉的是拼装与切换模型的胶水代码,代价是多一层抽象,以及抽象层本身会随版本变动。所以判断标准很直接:如果你的项目只有一两个固定提示词、只调一个模型、完全不做工具调用,那裸调 API 反而更好维护,别为了用而用。

  • 需要频繁换模型或换提供商时,编排层的价值才明显
  • 提示词里有大量变量、需要复用同一套话术时,模板能省不少事
  • 需要模型自己去查数据、算数、调接口时,才值得引入工具这一层
  • 只是做一次性的小脚本,直接写请求更快,别绕远路

最小可用搭建路径:按顺序做完这五步

入门最容易翻车的地方不是代码写错,而是一上来把扩展包全装了,结果依赖互相打架。下面这五步按顺序做,每一步都能单独验证,出问题时也容易定位到是哪一步。

  1. 第一步:定环境用独立虚拟环境或容器把依赖隔离出来,版本写在项目依赖文件里。验证方式:在这个环境里执行一次依赖安装,确认没有报冲突,再开始写代码。
  2. 第二步:装包先只装核心包,跑通之后按需再加装工具、向量库、文档加载器这些扩展包。验证方式:装完先在环境里导入一次,确认能 import 成功再继续。
  3. 第三步:配密钥密钥走环境变量,不写进代码、不提交到仓库。验证方式:在脚本里打印一个布尔值确认变量读到了,但不要把密钥本身打出来。配法可参考站内环境变量相关页面。
  4. 第四步:写第一个链路提示词模板 + 模型 + 输出解析,三段串成一条最小链,只打印结果不做别的。验证方式:换一个输入再跑一遍,两次都能出结果才算过。
  5. 第五步:拆成函数把这段代码封装成能被别的脚本调用的函数,参数收输入、返回字符串。验证方式:在另一个文件里导入这个函数并调用一次,确认脱离原脚本也能跑。

跑不起来时的排查顺序

报错信息往往指向最后一行,但根因不一定在那里。按下面的顺序分层排查,比盲目改代码快得多。每一步都先验证再往下走,不要跳步。

现象先查什么再查什么
装包阶段报冲突是不是一次装了太多扩展包项目依赖清单里有没有重复或互斥的包
导入阶段报找不到模块包名和模块名是否一致核心包和扩展包是不是都装了
调用阶段报鉴权失败环境变量里的密钥是否生效base_url 是否指到了正确的服务地址
调用阶段报网络错本机能不能连通目标服务有没有代理或防火墙拦了请求
输出格式不对先固定模型和提示词单独跑一次看原始返回长什么样,再改解析逻辑

最后一步常被忽略:跑通之后记下当时的包版本和调用参数,当成基线。以后再出问题,先和这条基线对比,能快速判断是新装了什么包导致的,还是服务端那边变了。数字和可用模型这类信息会变,具体到站内模型资料库核对更稳。

跑通之后往哪走,以及什么时候该停

链路能跑之后,很多人会顺手把工具、知识库、智能体全加上,结果复杂度上来了,问题也更难查。加东西要有触发条件,不是有就加。

  • 加工具的判断标准:模型需要自己去查东西、算数或调外部接口时才引入,否则先用纯提示词解决
  • 接外部知识库时先想清楚数据格式和检索口径,再选向量库,不要先选库再倒推数据
  • 只有多步决策、需要动态选工具时才值得上智能体编排,单轮问答套上只会更难调
  • 给项目留退路:把模型调用抽成一个薄封装,将来换模型或换提供商只改这一处

反过来,什么时候该停:如果链路已经稳定、输入输出都固定、没人要求换模型,那就没必要继续往上堆抽象。抽象层越多,升级时要动的地方越多。

下一步想知道各家中转站当前的可信度和可用性,再决定接哪家,可以到站内中转站列表按检测结果挑;价格和模型清单会变,动手前到价格追踪页核对当时的数字。

常见问题

LangChain 1.0 和以前的版本差别大吗,老教程还能照着抄吗?

能看思路,别照抄代码。主要变化在包拆分方式和部分模块的导入路径上,老例子里的一句导入现在可能报错。建议先按官方当前文档把核心链路跑通一遍,再回头对照老教程理解概念。涉及具体版本号和变更条目,到站内文档或术语页对照当时的说明。

只用 LangChain 不接外部工具,是不是没必要?

如果你的场景是固定提示词、单一模型、单轮输出,直接调 API 更短更可控,LangChain 带来的收益有限。它的价值在于把提示词、模型、工具、外部数据按统一接口串起来,一旦你要换模型、加检索、加工具调用,这种统一接口才开始省事。先按最小链路跑通,再决定留不留。

跑通了但输出不稳定,是框架的问题吗?

多数时候不是框架的问题,而是模型本身的随机性、提示词写法、或者输出解析太严。排查顺序是先把解析层去掉看原始返回,再固定参数重跑,最后才动提示词。同一提示词多次结果不同属于正常现象,具体缓解思路可以到站内相关页面看。

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