1. 从零跑通第一个 LangChain 应用我踩过的坑与最小可运行骨架LangChain 是一个把大语言模型、提示词、外部数据、工具调用串成“链”的开发框架你可以把它理解成 LLM 应用层的 Spring 或 Django。它最擅长三件事用统一接口调用不同厂商的模型、把检索到的私有文档塞进上下文做 RAG、让模型自主决定调用哪些工具完成多步任务。适合谁适合会一点 Python、想做大模型应用但不想从 HTTP 请求开始手搓的程序员。我试过直接拿 OpenAI SDK 写 Agent光工具调用的 JSON 解析和重试逻辑就写了三百行换成 LangChain 后核心逻辑压到三十行以内。这篇不堆概念直接给你一套能复制粘贴跑通的配置骨架包含 settings.json 与 config.toml 示例再逐步验证请求最后把 RAG、Agents、MCP 三个模块的接入方式讲清楚。1.1 为什么小白容易在第一步卡住大多数人卡在三个地方一是模型通道不统一今天用这个平台的 Key明天换那个平台的 URL代码里到处改 base_url二是环境变量管理混乱Key 硬编码在脚本里传到 Git 就泄露三是不知道从哪个最小示例开始一上来就看 Agent 源码直接被 Runnable、LCEL、Graph 这些概念劝退。我的建议是先跑通“提示词 → 模型 → 字符串输出”这条最短链路再往上叠 RAG 和工具。2. TaoToken 前置统一 Key 与 API 通道的接入准备TaoToken 在这里扮演的角色是统一模型通道。你不需要为每个模型厂商单独维护一套 Key 和 base_url而是通过一个兼容 OpenAI 规范的入口来调用。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。注意 API 地址后面不加 UTM 参数直接用于代码里的 base_url。2.1 获取 API Key 的正确姿势进入控制台创建 Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。创建后立刻复制页面刷新后不再完整显示。Key 的格式通常以 sk- 开头后面跟一串字符。拿到 Key 后不要写进代码先放进环境变量或配置文件。2.2 验证通道是否可用在写 LangChain 代码之前先用最朴素的 curl 确认通道通。这一步能帮你排除 90% 的“代码没问题但请求失败”的情况。curl https://taotoken.net/api/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: gpt-4o-mini, messages: [{role: user, content: 回复两个字通了}] }如果返回的 JSON 里有 choices 字段且 content 是“通了”说明 Key 和通道都正常。如果返回 401检查 Key 是否复制完整如果返回 404检查 base_url 是否写成了 https://taotoken.net/api 而不是别的路径。3. 可复制配置settings.json 与 config.toml 骨架配置文件的作用是把“会变的东西”和“不变的代码”分开。模型名、base_url、超时时间这些会随环境变化写进配置文件后换环境只改配置不改代码。3.1 settings.json 示例适合 Python 项目读取用 json.load 加载后传给初始化函数。{ llm: { provider: openai, model: gpt-4o-mini, base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY, temperature: 0.7, timeout: 60, max_retries: 2 }, embedding: { model: text-embedding-3-small, base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY }, vector_store: { type: milvus_lite, uri: ./milvus_demo.db, collection: demo_collection, dim: 1536 } }3.2 config.toml 示例如果你更喜欢 TOML 的可读性用 tomllibPython 3.11或 tomli 读取。[llm] provider openai model gpt-4o-mini base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY temperature 0.7 timeout 60 max_retries 2 [embedding] model text-embedding-3-small base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY [vector_store] type milvus_lite uri ./milvus_demo.db collection demo_collection dim 15363.3 环境变量与 .env 文件无论用哪种配置文件Key 本身都不应该出现在里面。用 .env 文件存 Key并加入 .gitignore。# .env TAOTOKEN_API_KEYsk-你的实际Key# config_loader.py import json import os from dotenv import load_dotenv load_dotenv() def load_settings(pathsettings.json): with open(path, r, encodingutf-8) as f: cfg json.load(f) cfg[llm][api_key] os.getenv(cfg[llm][api_key_env]) cfg[embedding][api_key] os.getenv(cfg[embedding][api_key_env]) return cfg4. 逐步验证从单次调用到 RAG 与 Agent配置准备好后按“单次调用 → 流式输出 → 结构化输出 → RAG → Agent”的顺序验证每步都能独立跑通再往下走。4.1 单次调用验证# step1_invoke.py from langchain_openai import ChatOpenAI from config_loader import load_settings cfg load_settings() llm ChatOpenAI( modelcfg[llm][model], base_urlcfg[llm][base_url], api_keycfg[llm][api_key], temperaturecfg[llm][temperature], timeoutcfg[llm][timeout], max_retriescfg[llm][max_retries], ) resp llm.invoke(用一句话解释什么是 RAG) print(resp.content)运行后如果打印出一句关于检索增强生成的解释说明模型通道和 LangChain 集成都没问题。4.2 流式输出验证流式输出适合做聊天界面用户不用等完整答案。# step2_stream.py for chunk in llm.stream(写一首关于春天的五言绝句): print(chunk.content, end, flushTrue)4.3 结构化输出验证用 Pydantic 模型约束输出格式方便下游程序解析。# step3_structured.py from pydantic import BaseModel, Field class Animal(BaseModel): name: str Field(description动物名称) emoji: str Field(description对应的 emoji) class AnimalList(BaseModel): animals: list[Animal] Field(description动物列表) structured_llm llm.with_structured_output(AnimalList) result structured_llm.invoke(随机生成三种动物及其 emoji) print(result)4.4 RAG 最小闭环验证RAG 的核心是“文档切块 → 向量化 → 存入向量库 → 检索 → 拼进提示词”。这里用 Milvus Lite 做本地向量库不需要额外部署服务。# step4_rag.py from langchain_community.document_loaders import TextLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_openai import OpenAIEmbeddings from langchain_milvus import Milvus from langchain_core.prompts import ChatPromptTemplate from langchain_core.runnables import RunnablePassthrough from langchain_core.output_parsers import StrOutputParser cfg load_settings() # 1. 加载与切分 docs TextLoader(assets/sample.txt, encodingutf-8).load() chunks RecursiveCharacterTextSplitter( chunk_size400, chunk_overlap50, separators[\n\n, \n, 。, , , , ], ).split_documents(docs) # 2. 向量化与存储 embeddings OpenAIEmbeddings( modelcfg[embedding][model], base_urlcfg[embedding][base_url], api_keycfg[embedding][api_key], ) vector_store Milvus.from_documents( chunks, embeddings, collection_namecfg[vector_store][collection], connection_args{uri: cfg[vector_store][uri]}, ) # 3. 检索与生成 retriever vector_store.as_retriever(search_kwargs{k: 3}) prompt ChatPromptTemplate.from_messages([ (system, 根据以下上下文回答问题\n\n{context}), (human, {question}), ]) rag_chain ( {context: retriever, question: RunnablePassthrough()} | prompt | llm | StrOutputParser() ) print(rag_chain.invoke(文档里提到了哪些关键概念))4.5 Agent 与工具调用验证Agent 的核心是让模型自己决定调用哪个工具。先定义一个简单工具再绑定到模型。# step5_agent.py from langchain.tools import tool from langchain.agents import create_agent tool def query_user_info(user_id: int) - str: 根据用户 ID 查询用户名 return {1001: Jack, 1002: Tom, 1003: Alice}.get(user_id, 未知用户) agent create_agent( modelllm, tools[query_user_info], system_prompt你是助手需要调用工具来帮助用户。, ) result agent.invoke({messages: [{role: user, content: 帮我查下 1001 用户的名称}]}) print(result)4.6 MCP 接入验证MCP 是模型上下文协议让模型通过标准接口访问外部工具和数据源。LangChain 通过 langchain-mcp-adapters 包接入。# step6_mcp.py import asyncio from langchain_mcp_adapters.client import MultiServerMCPClient from langchain.agents import create_agent async def main(): client MultiServerMCPClient({ filesystem: { transport: stdio, command: npx, args: [-y, modelcontextprotocol/server-filesystem, ./assets], } }) tools await client.get_tools() agent create_agent(modelllm, toolstools) result await agent.ainvoke({ messages: [{role: user, content: 列出 assets 目录下的文件}] }) print(result) asyncio.run(main())5. 本篇常见错排查5.1 401 Unauthorized最常见的原因是 Key 没读到。检查 .env 文件是否在项目根目录、load_dotenv() 是否在读取配置前调用、环境变量名是否和配置文件里的 api_key_env 一致。另一个原因是 Key 前后有空格复制时容易带上换行符。5.2 404 Not Foundbase_url 写错。正确写法是 https://taotoken.net/api 不要在后面加 /v1 或 /chat/completionsLangChain 的 OpenAI 兼容层会自动拼接路径。如果你用的是原生 OpenAI SDK才需要写完整路径。5.3 模型名不存在不同通道支持的模型名不同。先用 curl 测试模型名是否可用再写进配置。如果返回 model not found换一个模型名重试。5.4 RAG 检索结果不相关检查切分粒度。chunk_size 太大检索到的块包含太多无关信息太小语义不完整。中文文档建议 chunk_size 在 300 到 500 之间chunk_overlap 设为 chunk_size 的 10% 到 15%。另外检查 embedding 模型是否和向量库维度匹配dim 参数写错会导致插入失败或检索异常。5.5 Agent 不调用工具模型能力不足时会忽略工具。换一个支持 function calling 的模型或者在 system_prompt 里明确要求“必须调用工具”。另外检查工具的描述是否清晰模型靠描述判断何时调用。5.6 MCP 连接超时stdio 传输方式需要本地有对应的可执行命令。npx 方式首次运行会下载包网络慢时会超时。可以提前手动运行一次 npx 命令确认包能正常下载。streamable_http 方式检查 URL 和 headers 是否正确。6. 继续深入模型对话、Coding Plan 与接入文档跑通上面的最小闭环后你已经有了一套可复用的骨架。接下来想验证不同模型的表现可以直接在模型对话页面测试地址是 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。如果你打算长期做编码类 Agent 或需要稳定的调用额度可以了解 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。接入过程中遇到参数问题查阅接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面按模块列出了请求格式和返回字段。Key 管理在 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 可以创建多个 Key 分别用于开发和生产。如果你用 Claude Code 做开发Anthropic 兼容接入方式参考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-code-anthropicutm_campaignrewrite 。最后给一个实用建议把 settings.json 里的 model 字段做成可覆盖的通过环境变量 TAOTOKEN_MODEL 优先读取。这样在 CI 里跑测试用便宜模型本地开发用强模型不用改代码。