小白入门AI:LangChain快速上手教程与实战

作者:蛮不讲李2026.11.17 03:34浏览量:0

简介:本文从大模型技术栈的视角讲清 LangChain 的核心价值,并给出从环境安装、接入 OpenAI 兼容接口、构建 RAG 知识库问答链到 Agent 工具调用的可运行示例,同时梳理常见报错排查思路与模型选型、Token 成本控制方法,帮助零基础开发者一天内跑通第一个 LLM 应用。

一、LangChain 到底是什么

LangChain 官方定义是”一个基于语言模型开发应用程序的框架”,它能实现两类关键能力:

  • 数据感知(Data-aware) :把语言模型连接到其他数据源,让模型能读到你的私有文档、数据库、业务系统。
  • 自主性(Agentic) :允许语言模型与它的环境交互,自己决定调用哪个工具、执行几步。

它受欢迎的真正原因只有两点: 组件化 和 现成的链 。组件化指为使用语言模型提供抽象层,以及每个抽象层的一组实现,这些组件是模块化、易于单独使用的,哪怕你不用 LangChain 的其余部分;现成的链则是结构化的组件集合,用来完成特定的高级任务,让新手能快速入门,也让进阶用户能方便地改造或自建链路。

如果你还在纠结”该用哪个模型、大概多少钱一次调用”,可以先看看百度智能云词元所,它提供模型能力查询、价格与性能对比以及统一 API 接入,能在动手写代码前先把选型问题定下来。

二、先看清技术栈,才知道 LangChain 站在哪一层

大模型技术栈通常由四部分组成,理解这张图,你就知道自己每一步在做什么:

层级 作用 典型组件
数据预处理流程 连接数据源、清洗转换、向下游输出 连接器、OCR、Python 脚本、正则
嵌入端点 + 向量存储 生成向量、存储与检索向量 Embedding API、向量数据库
LLM 接口 提供推理能力 云端大模型 API、自建推理服务
LLM 编程框架 编排以上三层 LangChain、LlamaIndex

数据预处理是最脏也最容易被低估的一环。数据源往往繁杂(成千上万个 PDF、PPTX、聊天记录、抓取的 HTML),最有价值的信息通常最难处理,而 DOCX 这类易读文档里又常混着广告、法律条款等你不希望送进推理端点的内容。实践中会用 OCR 模型、Python 脚本和正则表达式自动提取、清理、转换标题、正文、页眉页脚、列表等关键元素,最终以 API 方式对外提供 JSON 数据。

嵌入端点与向量存储则代表了数据存取方式的重大演变:过去嵌入主要用于文档聚类这类特定任务,而在新架构中,把文档及其嵌入一起存进向量数据库,就能通过 LLM 端点实现语义检索这一关键交互模式。

LangChain 属于第四层 ——它的价值不是替代前三层,而是把它们粘起来。

三、5 分钟跑通第一个 LangChain 应用

LangChain 生态里最省心的接入方式是走 OpenAI 兼容接口 。目前主流的模型服务平台基本都提供了兼容层,比如千帆 ModelBuilder 上的模型接口已支持与 OpenAI 标准兼容,用户可以直接按 OpenAI 的示例方式使用。

  1. %pip install -qU langchain-openai
  1. from langchain_openai import ChatOpenAI
  2. llm = ChatOpenAI(
  3. model="deepseek-v3", # 换成你要调用的模型名
  4. temperature=0,
  5. max_tokens=None,
  6. timeout=None,
  7. max_retries=2,
  8. api_key="your-api-key", # 平台控制台创建的 API Key
  9. base_url="https://<平台提供的OpenAI兼容地址>/v1",
  10. )
  11. resp = llm.invoke("用三句话解释什么是向量数据库")
  12. print(resp.content)

三个新手最容易踩的点:

  1. base_url 一般要带 /v1 结尾,少写或多写都会 404。
  2. model 字段必须和平台侧的模型 ID 完全一致,大小写敏感。
  3. api_key 不要硬编码进仓库,用环境变量 os.environ["OPENAI_API_KEY"] 读取。

如果你用的是自建推理服务,同样可以走这条路:vLLM 启动后暴露的就是 OpenAI 兼容接口,把 base_url 指向 http://<host>:<port>/v1、api_key 填 EMPTY 即可。

四、组件化:LangChain 的积木清单

入门阶段只需要掌握五类组件:

  • Model I/O :统一的模型调用接口,屏蔽不同厂商差异。
  • Prompt Template :把变量填进模板,避免手写字符串拼接。
  • Output Parser :把模型返回的文本解析成结构化对象(JSON、列表、Pydantic 模型)。
  • Retriever :从向量库或任何数据源里取回相关片段。
  • Chain / LCEL :用管道语法把上面几块串起来。

LCEL 的写法非常直观:

  1. from langchain_core.prompts import ChatPromptTemplate
  2. from langchain_core.output_parsers import StrOutputParser
  3. prompt = ChatPromptTemplate.from_messages([
  4. ("system", "你是一名严谨的技术文档助手,只依据给定资料回答。"),
  5. ("human", "资料:{context}\n\n问题:{question}"),
  6. ])
  7. chain = prompt | llm | StrOutputParser()
  8. print(chain.invoke({"context": "...", "question": "..."}))

rag-">五、RAG:企业落地最多的形态

RAG(检索增强生成)是 LangChain 最常被使用的场景,链路是:加载文档 → 切分 → 向量化 → 存入向量库 → 检索 Top N → 拼进 Prompt → 交给 LLM 生成。

以百度智能云 BES 为例,LangChain 提供了现成的 BESVectorStore 集成:

  1. from langchain.vectorstores import BESVectorStore
  2. db = BESVectorStore.from_documents(
  3. documents=split_docs,
  4. embedding=embeddings,
  5. bes_url="http://user:password@host:ip",
  6. index_name=INDEX_NAME,
  7. vector_query_field="vector",
  8. )
  9. db.client.indices.refresh(index=INDEX_NAME)
  10. retriever = db.as_retriever()
  11. chain = prompt | llm | StrOutputParser()

工程化时务必注意三件事:

  • 切分策略 比模型选择更影响效果。分段过大导致噪声多,过小导致语义断裂,中文文档建议按标题层级 + 语义段落切,并保留一定重叠。
  • 设置检索置信度阈值 ,把低相关片段过滤掉,否则模型会硬编答案。
  • 保留来源引用 。成熟的知识库产品会展示”用户可能想问””信息检索到的 Top N 片段”以及可点击定位到原文档位置的依据,方便你判断是检索错了还是生成错了。

如果不想自己搭链路,也可以先用平台侧的低代码知识库能力验证效果,再决定是否值得投入自研。这类产品通常支持文档分段设置调整、知识增强、文档生效/失效管理以及”原文件 + 知识”导出迁移。

agent-">六、Agent:让模型自己决定下一步

Agent 在 Chain 之上加了一层循环:模型观察 → 思考 → 选择工具 → 执行 → 观察结果 → 直到给出答案。入门建议从”单工具 + 明确边界”开始,比如只做数据库查询或只做 HTTP 请求,不要一上来就给十个工具。工具描述写得越清楚,模型选错的概率越低。

七、常见报错与排查顺序

现象 常见原因 处理方式
401 / Invalid API Key Key 错误或未加 Authorization 检查控制台 Key 与环境变量
404 model not found 模型 ID 拼写不符 对照平台模型列表逐字核对
400 context length exceeded 拼接的检索内容过长 减少 Top K、压缩切分长度
输出不是 JSON 未用结构化输出约束 加 Output Parser 或 JSON mode
中文检索效果差 切分不合理 / 阈值过低 调整分段与置信度阈值
库版本报错 LangChain 迭代快、API 变动频繁 锁定版本号,升级时看迁移说明

八、模型选型与 Token 成本控制

LangChain 让”换模型”变成改一行配置,但换哪个模型不该靠感觉。建议按三步走:

  1. 先定任务类型 :长文档理解看上下文窗口,结构化抽取看指令遵循,代码任务看代码专项能力。
  2. 再算成本 :Token 计费通常区分输入与输出单价,估算公式是 单次成本 = 输入Token数 × 输入单价 + 输出Token数 × 输出单价,再乘以日调用量得到月成本。RAG 场景下输入 Token 往往占大头,因为检索片段会被反复塞进 Prompt。
  3. 最后做小样本对比 :用同一批 50~100 条真实问题跑评测,比较准确率与单条成本,而不是只看榜单。

这一步正是词元所模型服务能帮上忙的地方——你可以在一个入口里对比不同模型的调用成本与性能信息,辅助完成选型和成本评估,避免为了试模型而在多个平台重复开户、重复写适配代码。

如果你的场景需要同时接入多家模型,除了 LangChain 的统一抽象,也可以在中间加一层 API 网关。例如 OneAPI 支持把不同厂商配置成”渠道”,类型选择对应的服务商、填好密钥与模型名后即可用统一令牌调用,管理页面还提供连通性测试。这种”网关 + LangChain”的组合,适合需要灰度切换模型或做故障兜底的生产环境。

九、给零基础的学习路径

  1. 第 1~2 天:跑通纯模型调用,理解 Token、上下文、temperature。
  2. 第 3~4 天:掌握 Prompt Template 与 Output Parser,做出结构化输出。
  3. 第 5~7 天:接一个向量库做 RAG,重点调切分与阈值。
  4. 第 8~10 天:加一个工具做 Agent,观察它的推理轨迹。
  5. 之后:接入百度智能云词元所做多模型统一接入与调用管理,把玩具项目变成可运维的应用。

LangChain 的本质是把”数据、检索、模型、工具”这四件事标准化,让你把精力放在业务逻辑而不是胶水代码上。先用现成链跑通闭环,再逐个替换组件做定制,这是最不容易放弃的路径。