1. 零基础用 LangChain 搭第一个 AI Agent为什么十个有九个卡在环境依赖上先说结论LangChain 本身不难难的是它背后那一长串依赖链。你搜「LangChain 入门教程」前 100 个字一定是pip install langchain但没人告诉你装完之后langchain-openai、langchain-community、langchain-core三个包的版本必须对齐否则你连from langchain.chains import LLMChain都会报ImportError。我见过太多人卡在这一步Python 3.9 装完 LangChain 0.3跑官方示例直接pydantic版本冲突换 3.11 又遇到numpy和faiss-cpu的 ABI 不匹配。这不是你菜是 LangChain 的依赖树确实长得离谱——它同时依赖pydantic v2、SQLAlchemy、aiohttp、tiktoken而tiktoken又对rust编译环境有要求。小白第一次装不报错才奇怪。所以这篇不讲虚的。我按「先跑通再优化」的思路把 LangChain 从零到第一个可用 Agent 的完整链路拆成六段环境准备、TaoToken 统一 Key 接入、可复制的配置片段、验证请求、报错排查、以及后续怎么继续练。每一段都有可直接粘贴的命令和代码你跟着做就行。核心检索词先摆出来LangChain 是什么——它是一个把大模型调用、Prompt 模板、工具调用、RAG 检索串起来的开发框架能做什么——让你用几十行代码搭出一个能查知识库、能调工具的 AI Agent适合谁——有 Python 基础、想从零入门大模型应用开发的程序员。如果你连pip都没用过建议先补 Python 环境再来。环境这块我给你一个实测能跑通的组合别自己乱试python -m venv langchain-demo source langchain-demo/bin/activate # Windows 用 langchain-demo\Scripts\activate pip install --upgrade pip pip install langchain0.3.7 langchain-core0.3.15 langchain-community0.3.7 pip install langchain-openai0.2.8 openai1.54.0 pip install faiss-cpu1.8.0.post1 tiktoken0.8.0这套版本是我在 Python 3.11 上反复验证过的pydantic会自动锁到 2.9.x不会和langchain-core打架。装完先跑一句python -c import langchain; print(langchain.__version__)输出0.3.7就说明环境干净了。这里有个坑要提前说不要用pip install langchain[all]。那个 extras 会把langchain-experimental、langchain-cli全拉进来依赖冲突概率翻三倍。你需要什么装什么这是 LangChain 项目的第一条生存法则。环境搞定后下一步是模型接入。很多人到这里又卡住——OpenAI 官方 Key 要绑卡、要处理网络问题对小白极不友好。我的做法是用 TaoToken 的统一 Key 通道一个 Key 打通多家模型Base URL 换一下就能跑省掉大量配置时间。下一段详细说怎么接。2. TaoToken 统一 Key 接入 LangChain 的前置准备Base URL、API Key 与模型 ID 三件套LangChain 调模型本质是调 OpenAI 兼容接口。只要你把base_url、api_key、model三个参数配对ChatOpenAI这个类就能指向任何兼容 OpenAI 协议的服务。TaoToken 的价值就在这里它提供统一的 API 入口你不用为每个模型单独申请 Key、单独记 Base URL。前置准备只有三步我按顺序说。第一步拿 Key。打开 TaoToken 的 API Keys 页面https://taotoken.net/api-keys登录后创建一个新 Key复制下来。注意这个 Key 只显示一次丢了只能重建。建议命名成langchain-demo方便后面区分项目。第二步确认 Base URL。TaoToken 的 API 地址是https://taotoken.net/api注意结尾不带/v1。这一点和 OpenAI 官方不同——官方是https://api.openai.com/v1而 TaoToken 的路径设计是https://taotoken.net/api/v1/chat/completions所以你在 LangChain 里填base_url时填https://taotoken.net/api就行langchain-openai会自动补/v1。填错会直接 404这是新手最高频的错误之一。第三步选模型 ID。TaoToken 支持多家模型模型 ID 的写法要和你调用的服务对齐。比如你想用 Claude 系列模型 ID 写claude-sonnet-4-20250514想用 GPT 系列写gpt-4o-mini。具体可用列表在模型对话页面https://taotoken.net/chat能看到或者直接调/v1/models接口拉一遍。三件套凑齐后先别急着写 LangChain 代码用curl验证一下通道是否通curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: 只回复两个字通了}] }如果返回 JSON 里choices[0].message.content是「通了」说明 Key、Base URL、模型 ID 三件套全部正确。这一步千万别跳过——很多人直接写 LangChain 代码报错了分不清是 Key 问题还是代码问题白白浪费半小时。这里插一句关于成本的提醒。LangChain 的 Agent 会在一轮对话里多次调用模型每次工具调用都是一次请求Token 消耗比普通对话高 3 到 5 倍。我建议你在 TaoToken 控制台https://taotoken.net/console先设一个预算上限避免调试时忘记关进程导致意外消耗。这个习惯我从第一个项目就养成了后面省了不少心。前置准备做完下一段进入正题把三件套写进 LangChain 的配置里跑通第一个 Prompt 模板 模型调用的最小链路。3. 可复制的 LangChain 配置Prompt 模板、ChatOpenAI 与 RAG 最小链路代码这一段是全文的核心我给你一份可以直接存成demo.py跑起来的完整代码。它包含四个部分环境变量配置、Prompt 模板、模型初始化、RAG 最小检索链路。每一部分我都标了容易出错的地方。先看配置片段。我推荐用.env文件管理 Key别硬编码在代码里# .env TAOTOKEN_API_KEYsk-你的Key TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_MODELgpt-4o-mini然后demo.py这样写import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser load_dotenv() llm ChatOpenAI( modelos.getenv(TAOTOKEN_MODEL), api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL), temperature0.3, ) prompt ChatPromptTemplate.from_messages([ (system, 你是一个严谨的技术助手回答控制在三句话内。), (user, 用一句话解释什么是 {concept}。), ]) chain prompt | llm | StrOutputParser() result chain.invoke({concept: RAG}) print(result)这段代码里有两个高频坑。第一个是ChatPromptTemplate的变量名必须和invoke传入的字典 key 完全一致——你写{concept}传{topic: RAG}就会报KeyError: concept。第二个是base_url结尾不要加/v1加了会变成/api/v1/v1/chat/completions直接 404。Prompt 模板跑通后加 RAG。RAG 最小链路只需要四步加载文档、切分、向量化、检索。代码如下from langchain_community.document_loaders import TextLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_community.vectorstores import FAISS from langchain_openai import OpenAIEmbeddings loader TextLoader(knowledge.txt, encodingutf-8) docs loader.load() splitter RecursiveCharacterTextSplitter( chunk_size512, chunk_overlap64, separators[\n\n, \n, 。, ], ) chunks splitter.split_documents(docs) embeddings OpenAIEmbeddings( modeltext-embedding-3-small, api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL), ) vectorstore FAISS.from_documents(chunks, embeddings) retriever vectorstore.as_retriever(search_kwargs{k: 3}) rag_prompt ChatPromptTemplate.from_messages([ (system, 只根据以下上下文回答找不到答案就说不知道。\n\n上下文\n{context}), (user, {question}), ]) def rag_answer(question: str): docs retriever.invoke(question) context \n\n.join(d.page_content for d in docs) return (rag_prompt | llm | StrOutputParser()).invoke( {context: context, question: question} ) print(rag_answer(你的问题))chunk_size512和chunk_overlap64不是随便写的。我实测过中文技术文档用 512 切分召回准确率比 1000 高出一截overlap 给 64 能保证跨段落的句子不被切断。这两个参数你后面要按自己的语料调但起点用这组不会错。RAG 链路里最容易断的地方是OpenAIEmbeddings的base_url——它和ChatOpenAI用的是同一个地址但很多人只配了 Chat 那边忘了 Embedding 也要配结果报AuthenticationError。记住凡是走 OpenAI 兼容协议的类都要单独传api_key和base_url。代码写到这里你已经有了一个能查知识库的最小 RAG 应用。下一段讲怎么验证它真的跑通了以及 Agent 工具调用怎么加。4. 验证请求与成功结果从 Prompt 到 Agent 工具调用的逐项检查代码写完不等于跑通。我给你一套逐项验证的动作按顺序做每一步都有明确的成功标志。第一步验证 Prompt 模板变量。单独跑prompt.format(conceptRAG)看输出里{concept}是否被替换成RAG。如果报KeyError说明变量名对不上如果{concept}原样输出说明你用了format而不是invoke或者模板字符串写成了普通字符串。第二步验证模型连通。跑llm.invoke(你好)成功标志是返回AIMessage对象content字段有内容。如果报401检查 Key 是否复制完整如果报Connection error检查base_url是否写成了https://taotoken.net/api不带/v1。第三步验证 RAG 检索。单独跑retriever.invoke(你的问题)成功标志是返回一个Document列表长度等于k值。如果返回空列表说明向量库没建成功回去检查FAISS.from_documents是否报错如果返回的文档内容和问题无关说明切分参数或 Embedding 模型需要调整。第四步验证 Agent 工具调用。这是从「RAG 应用」升级到「AI Agent」的关键一步。加一个最简单的工具from langchain_core.tools import tool from langchain.agents import AgentExecutor, create_tool_calling_agent tool def get_word_length(word: str) - int: 返回单词的字符数。 return len(word) tools [get_word_length] agent_prompt ChatPromptTemplate.from_messages([ (system, 你可以使用工具来回答问题。), (human, {input}), (placeholder, {agent_scratchpad}), ]) agent create_tool_calling_agent(llm, tools, agent_prompt) executor AgentExecutor(agentagent, toolstools, verboseTrue) print(executor.invoke({input: langchain 这个单词有多少个字符}))成功标志是verboseTrue的输出里出现Invoking: get_word_length并且最终output是9。如果 Agent 直接回答而没有调用工具说明模型不支持 tool calling换gpt-4o-mini或claude-sonnet-4-20250514再试。这里有个细节agent_scratchpad这个 placeholder 必须写它是 Agent 存放中间步骤的地方。漏了会报Missing placeholder。另外create_tool_calling_agent要求模型本身支持 function calling不是所有模型都行——这也是为什么我在 TaoToken 上优先选 GPT 和 Claude 系列。四步验证全过你的第一个 LangChain Agent 就算真正跑通了。下一段集中处理报错。5. 本篇常见报错排查401、local proxy failed、reading choices、OAuth 逐项对照这一段我按真实报错信息来你遇到哪个直接对号入座。报错一openai.AuthenticationError: Error code: 401原因只有三种Key 错了、Key 没传进去、Base URL 和 Key 不匹配。排查顺序先print(os.getenv(TAOTOKEN_API_KEY))看是不是None如果是说明.env没加载成功检查load_dotenv()是否在读取环境变量之前调用如果 Key 有值用第 2 段的curl命令单独测一次排除 Key 本身失效。报错二APIConnectionError: local proxy failed这个报错通常出现在你本地配了某些网络工具的情况下。LangChain 底层用httpx它会读取系统代理环境变量。解决办法是在代码开头显式清掉import os os.environ.pop(HTTP_PROXY, None) os.environ.pop(HTTPS_PROXY, None) os.environ.pop(ALL_PROXY, None)然后重启 Python 进程。注意这不是让你去配代理而是把可能干扰请求的本地代理变量清掉让请求直连 TaoToken 的 API 地址。报错三KeyError: choices或Error reading choices这个报错说明返回的 JSON 结构和你预期的不一样。最常见的原因是base_url写错请求打到了错误的路径返回了一个 HTML 错误页而不是 JSON。检查你的base_url是不是https://taotoken.net/api结尾有没有多余的/v1或/chat/completions。另一个原因是模型 ID 写错服务端返回了错误对象LangChain 解析时找不到choices字段。报错四OAuth相关报错比如OAuth token exchange failed如果你用的是 Claude Code 或某些 CLI 工具可能会遇到 OAuth 流程问题。这类工具通常要求你先在浏览器完成授权再把 token 写进本地配置。以 Claude Code 为例它的配置文件在~/.claude/settings.json你需要把三件套写进去{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }注意 Claude Code 用的是ANTHROPIC_前缀不是OPENAI_。写错前缀会直接走 OAuth 流程然后失败。同理如果你用 Cline 或 CC Switch 这类工具它们的 MCP 配置里也要写全 Base URL、Key、Model ID 三件套缺一个都会报错。报错五pydantic.ValidationError或ImportError: cannot import name LLMChain这是版本问题。LangChain 0.3 把LLMChain移到了langchain的旧接口里新写法用prompt | llm的 LCEL 语法。如果你照抄的是 0.1 版本的教程就会报这个错。解决办法要么按本文第 3 段的 LCEL 写法改要么降级到langchain0.1.x但我不推荐降级新项目直接用 0.3 的语法。排查完这些你的链路基本就稳了。最后一段说后续怎么继续练以及 CTA。6. 从跑通到能用LangChain Agent 后续练习路径与 TaoToken 接入文档跑通第一个 Agent 只是起点。接下来你要练的是「工程化」——也就是让这个 Agent 在真实场景里稳定工作。我给你三条练习路径按难度递增。第一条把 RAG 的切分参数做成可配置。写一个config.yaml把chunk_size、chunk_overlap、k值抽出来然后写个脚本批量跑不同参数组合记录召回准确率。这一步能让你真正理解 RAG 的调参逻辑而不是抄一个数字就完事。第二条给 Agent 加多轮对话记忆。LangChain 提供ChatMessageHistory和RunnableWithMessageHistory你可以把历史消息存到内存或 Redis 里。重点练「上下文超长时怎么截断」——这是 Agent 上线前必须解决的问题。我的做法是保留最近 10 轮对话加上一个系统级的摘要把更早的内容压缩成一段话塞进 System Prompt。第三条把 Agent 接进真实工具。比如接一个天气 API、一个数据库查询工具、一个文件读写工具。每加一个工具你都要重新测一遍 Agent 的工具选择逻辑——工具描述写得越清楚Agent 选错的概率越低。工具描述里要写清楚「什么时候用这个工具」和「输入格式是什么」这两点比工具本身的功能更重要。如果你练到这里想继续深入TaoToken 的接入文档https://taotoken.net/doc里有完整的 API 说明和模型列表Coding Planhttps://taotoken.net/coding-plan适合长期做编码类 Agent 的场景模型对话页面https://taotoken.net/chat可以快速对比不同模型的输出效果。API Keys 管理在 https://taotoken.net/api-keys控制台在 https://taotoken.net/console。最后给你一个我自己的习惯每跑通一个链路就把当时的依赖版本、配置参数、报错记录写进一个NOTES.md。LangChain 版本迭代快三个月后你回头看这份笔记能帮你省掉重新踩坑的时间。我第一个 Agent 项目就是靠这份笔记在换机器时 20 分钟恢复了环境。