LangChain学习记录：用TaoToken统一Key跑通Chain与Agent的最小配置

1. 从一堆 Key 到一把钥匙LangChain 入门最烦的事如果你刚开始学 LangChain大概率会遇到这样一个场景跟着教程写了个 Chain跑通了想换个模型对比效果得去翻.env改OPENAI_API_KEY再想试试 Agent 调工具又发现工具调用和模型绑定得死死的换一个模型就得重写一遍bind_tools。更别提同时开着 OpenAI、Claude、国产模型好几个 Key环境变量文件越写越长切来切去自己都记不清哪个是哪个。LangChain 本身是个很灵活的框架Chain 负责把「提示词 → 模型 → 解析」串成流水线Agent 负责让模型自己决定调哪个工具、走哪条路。但灵活的另一面就是配置分散模型供应商、API Key、Base URL、模型名这些东西散落在代码、.env、config.toml里入门阶段光是理清这些就够劝退的。这篇记录就是解决这个问题的。核心思路很简单用 TaoToken 作为统一的模型接入层把多供应商的 Key 收敛成一把然后在 LangChain 里通过config.toml.env两个文件管理配置Chain 和 Agent 共用同一套模型初始化逻辑。适合正在学 LangChain、想快速跑通最小可运行示例、又不想被 Key 管理拖住的人。下面从环境准备到运行验证一步步来。2. TaoToken 前置统一 Key 与接入地址TaoToken 在这里扮演的角色是「模型网关」——你只需要在它那边拿到一个 API Key配置好要用的模型LangChain 侧就统一指向它的 API 地址。这样切换模型时改的是 TaoToken 后台的配置而不是你项目里散落各处的环境变量。需要提前准备的东西一个 TaoToken 账号在控制台创建一个 API Key确认你要用的模型已经在 TaoToken 侧可用本地 Python 环境建议 3.10装好langchain、langchain-openai、python-dotenv、pydanticTaoToken 的 API 地址是https://taotoken.net/api兼容 OpenAI 的接口格式所以 LangChain 里直接用ChatOpenAI这个类把base_url指过去就行。这也是它方便的地方不用为每个供应商装不同的 SDK一套 OpenAI 兼容接口全搞定。拿 Key 的入口在控制台的 API Keys 页面创建后复制出来注意它只显示一次。模型对话的调试入口可以用来先确认模型通不通再进代码。如果你后面要长期跑编码类 Agent可以了解下 Coding Plan不过入门阶段先用按量调用就够了。注意API Key 不要硬编码进代码也不要提交到 Git。下面统一用.env管理。3. 可复制配置config.toml 与 .env 骨架先建项目目录结构大概这样langchain-demo/ ├── .env ├── config.toml ├── requirements.txt ├── chain_demo.py └── agent_demo.pyrequirements.txt内容langchain0.3.0 langchain-openai0.2.0 langchain-core0.3.0 python-dotenv1.0.0 pydantic2.0.0.env只放敏感信息一个 Key 搞定TAOTOKEN_API_KEYsk-你的TaoToken密钥config.toml放非敏感的模型配置这样切换模型不用动代码[llm] base_url https://taotoken.net/api model gpt-4o-mini temperature 0.3 max_tokens 1024 [agent] model gpt-4o-mini max_iterations 5这里max_tokens控制的是模型单次输出的上限不是输入长度。入门阶段设小一点比如 1024既能省钱也能防止 Agent 陷入死循环一直输出。temperature调低让输出更稳定方便调试。读取配置的公共模块我习惯单独写一个llm_factory.pyChain 和 Agent 都从这里拿模型实例import os import tomllib from dotenv import load_dotenv from langchain_openai import ChatOpenAI load_dotenv() def load_config(path: str config.toml) - dict: with open(path, rb) as f: return tomllib.load(f) def get_llm(section: str llm) - ChatOpenAI: cfg load_config()[section] return ChatOpenAI( api_keyos.getenv(TAOTOKEN_API_KEY), base_urlcfg[base_url], modelcfg[model], temperaturecfg.get(temperature, 0.3), max_tokenscfg.get(max_tokens, 1024), )tomllib是 Python 3.11 内置的3.10 的话装个tomli并改成import tomli as tomllib即可。这样模型初始化只有一处改配置就全局生效。4. 跑通 Chain最小可运行示例Chain 的本质是「输入 → 提示词模板 → 模型 → 输出解析」的流水线。先写一个最简单的验证链路通不通from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser from llm_factory import get_llm llm get_llm(llm) prompt ChatPromptTemplate.from_messages([ (system, 你是一个简洁的技术助手回答控制在三句话内。), (human, {question}), ]) chain prompt | llm | StrOutputParser() if __name__ __main__: result chain.invoke({question: LangChain 里 Chain 和 Agent 有什么区别}) print(result)运行python chain_demo.py如果配置正确你会看到模型返回的一段文字。这条链路里prompt | llm | StrOutputParser()用管道符把三个组件串起来invoke传入字典填充模板变量。这就是 Chain 最小形态——一问一答没有状态没有工具。接下来加结构化输出。入门阶段经常需要模型返回 JSON 而不是自由文本用 Pydantic 定义结构让模型按 Schema 输出from pydantic import BaseModel, Field from langchain_core.prompts import ChatPromptTemplate from llm_factory import get_llm class BookInfo(BaseModel): title: str Field(description书名) author: str Field(description作者) year: int Field(description出版年份) llm get_llm(llm) structured_llm llm.with_structured_output(BookInfo) prompt ChatPromptTemplate.from_messages([ (system, 从用户描述中提取书籍信息。), (human, {text}), ]) chain prompt | structured_llm if __name__ __main__: out chain.invoke({text: 我最近在读《人类简史》尤瓦尔·赫拉利写的2014年出版。}) print(out) print(type(out))with_structured_output会把 Pydantic 模型转成模型能理解的 Schema返回的直接是BookInfo实例不用自己json.loads。实测下来结构化输出和 Tool Calling 是两套机制前者负责让模型返回业务数据后者负责让模型决定调哪个工具别混用。流式输出也顺手加一下Chain 支持streamfor chunk in chain.stream({text: 《三体》刘慈欣2008年。}): print(chunk, end, flushTrue)不过结构化输出配流式会有点别扭因为要等整个 JSON 拼完才能解析。入门阶段建议自由文本用stream结构化数据用invoke。5. 跑通 Agent工具调用与状态管理Agent 和 Chain 的核心区别在于Chain 是你定死的流水线Agent 是模型自己决定下一步。在 LangChain 里用tool装饰器把普通函数变成模型可调用的工具from langchain_core.tools import tool tool def get_weather(city: str) - str: 查询指定城市的天气。输入城市名返回天气描述。 fake_db {北京: 晴25度, 上海: 多云28度, 深圳: 阵雨30度} return fake_db.get(city, 暂无该城市数据) tool def calculate(expression: str) - str: 计算数学表达式例如 2 3 * 4。 try: return str(eval(expression, {__builtins__: {}}, {})) except Exception as e: return f计算失败: {e}tool会自动提取函数名、docstring 和参数类型生成模型能理解的工具描述。docstring 很重要模型就是靠它判断该不该调这个工具。然后构建 Agent。LangChain 现在推荐用 LangGraph 的create_react_agent它内部维护一个 State能管理多轮工具调用from langgraph.prebuilt import create_react_agent from llm_factory import get_llm from tools import get_weather, calculate llm get_llm(agent) tools [get_weather, calculate] agent create_react_agent(llm, tools) if __name__ __main__: result agent.invoke({ messages: [(human, 北京天气怎么样顺便算一下 12 * 8 等于多少。)] }) for msg in result[messages]: print(f[{msg.type}] {msg.content})运行后你会看到消息序列先是 human 提问然后 AI 发起 tool_call接着 tool 返回结果最后 AI 汇总回答。这就是 Agent 的完整生命周期——模型决策、工具执行、结果回填、再决策直到给出最终答案。Agent 的 State 里messages字段用的是追加策略历史对话会保留而像中间结果这类字段通常是覆盖。如果你要加短期记忆可以配 Checkpointer同一个thread_id再次请求时会恢复之前的 State。入门阶段先用内存版就够from langgraph.checkpoint.memory import MemorySaver memory MemorySaver() agent create_react_agent(llm, tools, checkpointermemory) config {configurable: {thread_id: user-001}} agent.invoke({messages: [(human, 北京天气如何)]}, config) # 第二次调用会带上之前的上下文 agent.invoke({messages: [(human, 那上海呢)]}, config)注意MemorySaver存在内存里进程重启就没了。生产环境要换持久化存储但学习阶段够用。6. 本篇常见错排查报错一AuthenticationError或 401最常见的原因是.env没被加载或者 Key 复制时带了空格。先确认load_dotenv()在读取环境变量之前调用再打印os.getenv(TAOTOKEN_API_KEY)[:8]看前几位对不对。另外确认base_url写的是https://taotoken.net/api末尾不要多加/v1之类的路径。报错二model not found或 404config.toml里的model字段要和 TaoToken 侧实际可用的模型名一致。不同供应商模型命名规则不同别想当然填。先去模型对话页面确认模型名再回填配置。报错三Agent 不调工具直接瞎编答案通常是工具 docstring 写得太模糊模型判断不出该不该调。把 docstring 写清楚这个工具做什么、输入什么、返回什么。另外temperature太高也会让模型不稳定调到 0.2 以下试试。报错四max_tokens设太小导致回答被截断max_tokens限制的是输出长度不是输入。如果模型回答到一半停了检查这个值。入门调试可以设 2048稳定后再按业务调小。报错五结构化输出报 Schema 校验失败模型偶尔会返回不符合 Pydantic 定义的字段。可以在with_structured_output里加strictTrue如果模型支持或者给字段加默认值兜底。另外字段描述Field(description...)要写清楚模型靠它理解每个字段含义。报错六流式输出中文乱码或断字stream返回的是 chunk中文可能被拆到两个 chunk 里。用print(chunk, end, flushTrue)逐块输出即可不要自己拼接后再打印。如果要做前端渲染按 chunk 追加到缓冲区。7. 下一步把统一 Key 用顺跑通 Chain 和 Agent 之后你会发现统一 Key 的价值在切换模型时才真正体现。比如想把config.toml里的model从gpt-4o-mini换成另一个模型只改一行配置Chain 和 Agent 都不用动。这就是把模型接入层收敛到一处的好处。如果你要长期跑编码类任务或复杂 Agent可以看看 Coding Plan它在调用额度和并发上更适合持续使用。日常调试模型通不通用模型对话页面最快。需要管理多个 Key 或查看用量去控制台。接入文档里有更完整的参数说明和兼容性细节遇到本文没覆盖的报错可以去翻。入门阶段不用追求一步到位先把这条最小链路跑顺.env放 Keyconfig.toml放模型配置llm_factory.py统一初始化Chain 和 Agent 共用。后面加工具、加记忆、换模型都是在这个骨架上长出来的。