Langchain 1.0.2 全栈开发教程：用 TaoToken 统一 Key 打通 RAG+Agents 全链路

1. 从两个 Key 到一条链路LangChain 1.0.2 全栈开发里最烦的那件事LangChain 1.0.2 全栈开发教程里RAG 检索链和 Agents 工具调用是两条主线但真正卡住大多数人的不是链怎么写而是 Key 怎么管。RAG 要调 Embedding 模型Agents 要调对话模型工具调用还要再调一次模型一个项目里散落着三四个不同厂商的 API Key改一个环境变量就得翻半天配置文件。LangChain 1.0.2 本身把init_chat_model和bind_tools的接口统一了但模型供应商的 base_url 和 api_key 还是各写各的。这篇教程面向需要统一管理多模型 Key 的开发者给出config.toml与settings.json骨架把 TaoToken 作为统一 Key 和 API 通道接进 LangChain 1.0.2 的 RAG 链与 Agent 工具调用里最后附一条 RAG 问答和一条 Agent 工具调用的可复制验证动作。适合已经跑通过 LangChain 基础 demo、准备把 RAG 和 Agents 拼成一个完整应用的人。如果你还在纠结用哪个 Embedding 模型、工具调用返回的tool_calls怎么解析这篇会把这些环节串起来。我试过在一个项目里同时接三个厂商的 Key结果.env文件里六行变量换台机器就报AuthenticationError。后来把模型通道收敛到一个入口配置从六行降到两行RAG 和 Agent 共用同一套凭证排障时只需要看一个地方。2. TaoToken 前置统一 Key 与 API 通道的接入位置TaoToken 在这里扮演的角色是模型调用的统一入口。LangChain 1.0.2 的init_chat_model支持传入base_url和api_key只要这个入口兼容 OpenAI 的 Chat Completions 协议RAG 里的对话模型和 Agent 里的推理模型都能走同一条通道。Embedding 部分如果也用兼容接口同样可以收敛进来。接入位置有三个一是config.toml里放模型名和 base_url二是settings.json里放运行时参数三是环境变量里放 Key。这样做的目的是让 RAG 链和 Agent 共享同一份模型配置而不是各写各的。先拿到 Key。访问 https://taotoken.net/api-keys 创建注意这个页面带 UTM 参数创建后复制保存。API 通道地址是 https://taotoken.net/api 这个地址不带 UTM直接作为base_url使用。模型对话入口在 https://taotoken.net/models 可以在这里确认你要用的模型名。接入文档在 https://taotoken.net/doc 配置项对不上时回来查。注意Key 只放环境变量或本地配置文件不要提交到 Git。.env和config.toml都要进.gitignore。3. 可复制配置config.toml 与 settings.json 骨架3.1 config.toml 骨架config.toml放模型定义RAG 和 Agent 都从这里读。LangChain 1.0.2 本身不解析 toml我们用 Python 标准库tomllib3.11或tomli读进来再传给init_chat_model。# config.toml [provider] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY [models.chat] name gpt-4o-mini temperature 0.2 max_tokens 2048 [models.agent] name gpt-4o-mini temperature 0.0 max_tokens 4096 [models.embedding] name text-embedding-3-small dim 1536 [rag] chunk_size 400 chunk_overlap 50 top_k 3 [agent] max_iterations 8这里base_url统一指向 TaoToken 的 API 通道api_key_env指向环境变量名不直接写 Key。models.chat给 RAG 用models.agent给 Agent 用models.embedding给向量化用。三个模型走同一个 base_urlKey 也同一份。3.2 settings.json 骨架settings.json放运行时开关方便不改代码切换行为。{ env: dev, tracing: false, rag: { vector_store: milvus_lite, collection: demo_collection, db_path: ./milvus_demo.db }, agent: { enable_tools: true, tool_timeout: 15, stream: true }, logging: { level: INFO, log_tool_calls: true } }tracing关掉时不上报链路本地调试够用。log_tool_calls打开后Agent 每次工具调用的入参和返回都会打到日志排障时不用猜模型到底调了什么。3.3 加载配置的代码# settings_loader.py import os import json import tomllib from pathlib import Path def load_config(config_path: str config.toml) - dict: with open(config_path, rb) as f: cfg tomllib.load(f) api_key os.getenv(cfg[provider][api_key_env]) if not api_key: raise RuntimeError(f环境变量 {cfg[provider][api_key_env]} 未设置) cfg[provider][api_key] api_key return cfg def load_settings(settings_path: str settings.json) - dict: with open(settings_path, r, encodingutf-8) as f: return json.load(f) if __name__ __main__: cfg load_config() st load_settings() print(base_url:, cfg[provider][base_url]) print(chat model:, cfg[models][chat][name]) print(env:, st[env])运行前设置环境变量export TAOTOKEN_API_KEY你的KeyWindows CMD 用set TAOTOKEN_API_KEY你的Key。跑python settings_loader.py能打印出 base_url 和模型名就说明配置读通了。3.4 把配置接进 LangChain 1.0.2# model_factory.py from langchain.chat_models import init_chat_model from settings_loader import load_config def build_chat_model(role: str chat): cfg load_config() m cfg[models][role] return init_chat_model( modelm[name], model_provideropenai, base_urlcfg[provider][base_url], api_keycfg[provider][api_key], temperaturem[temperature], max_tokensm[max_tokens], )role传chat或agent分别拿到 RAG 用和 Agent 用的模型实例。两者 base_url 和 Key 相同只有温度和 max_tokens 不同。这样 RAG 链和 Agent 共享同一套凭证换模型只改config.toml。4. 验证请求一条 RAG 问答与一条 Agent 工具调用4.1 RAG 问答验证RAG 链的核心是检索加生成。这里用 Milvus Lite 做本地向量库Embedding 走 TaoToken 通道。先建库、灌数据再跑问答。# rag_demo.py import os from pymilvus import MilvusClient, DataType from langchain.chat_models import init_chat_model from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser from langchain_core.runnables import RunnablePassthrough from settings_loader import load_config, load_settings cfg load_config() st load_settings() client MilvusClient(urist[rag][db_path]) collection st[rag][collection] def build_schema(): return ( MilvusClient.create_schema(auto_idTrue, enable_dynamic_fieldTrue) .add_field(field_nameid, datatypeDataType.INT64, is_primaryTrue) .add_field(field_namevector, datatypeDataType.FLOAT_VECTOR, dimcfg[models][embedding][dim]) .add_field(field_nametext, datatypeDataType.VARCHAR, max_length2048) ) def build_index(): p MilvusClient.prepare_index_params() p.add_index(field_namevector, index_typeAUTOINDEX, metric_typeL2) return p if client.has_collection(collection): client.drop_collection(collection) client.create_collection(collection_namecollection, schemabuild_schema(), index_paramsbuild_index()) # 用 TaoToken 通道做 embedding from openai import OpenAI oai OpenAI(base_urlcfg[provider][base_url], api_keycfg[provider][api_key]) def embed(texts): resp oai.embeddings.create(modelcfg[models][embedding][name], inputtexts) return [d.embedding for d in resp.data] docs [ LangChain 1.0.2 的 create_agent 使用 LangGraph 构建基于图的运行时。, RAG 的检索阶段先算查询向量再在向量库中找相似向量。, TaoToken 提供统一的 API 通道base_url 是 https://taotoken.net/api 。, ] vecs embed(docs) client.insert(collection_namecollection, data[ {vector: v, text: t} for v, t in zip(vecs, docs) ]) def retrieval(query: str): qv embed([query])[0] res client.search( collection_namecollection, data[qv], anns_fieldvector, search_params{metric_type: L2}, output_fields[text], limitcfg[rag][top_k], ) return \n.join(hit[entity][text] for hit in res[0]) llm init_chat_model( modelcfg[models][chat][name], model_provideropenai, base_urlcfg[provider][base_url], api_keycfg[provider][api_key], temperaturecfg[models][chat][temperature], ) prompt ChatPromptTemplate.from_messages([ (system, 根据上下文回答问题不要编造。\n\n上下文\n{context}), (human, {query}), ]) chain ( {query: RunnablePassthrough(), context: lambda x: retrieval(x)} | prompt | llm | StrOutputParser() ) print(chain.invoke(TaoToken 的 base_url 是什么))跑起来后应该输出类似「TaoToken 的 base_url 是 https://taotoken.net/api」。如果检索不到检查top_k和 embedding 维度是否和 schema 里的dim一致。这条链验证了 RAG 的检索加生成两段都走通了 TaoToken 通道。4.2 Agent 工具调用验证Agent 部分用create_agent加一个自定义工具验证工具调用链路。# agent_demo.py from langchain.tools import tool from langchain.agents import create_agent from langchain.chat_models import init_chat_model from settings_loader import load_config, load_settings cfg load_config() st load_settings() tool def query_order(order_id: str) - str: 根据订单号查询订单状态。 fake_db { A1001: 已发货预计明天到达, A1002: 待付款, A1003: 已签收, } return fake_db.get(order_id, 订单不存在) llm init_chat_model( modelcfg[models][agent][name], model_provideropenai, base_urlcfg[provider][base_url], api_keycfg[provider][api_key], temperaturecfg[models][agent][temperature], ) agent create_agent( modelllm, tools[query_order], system_prompt你是订单助手需要调用工具查询订单状态。, ) if st[agent][stream]: for chunk in agent.stream({messages: [{role: user, content: 帮我查一下订单 A1001 的状态}]}): print(chunk, end\n\n) else: res agent.invoke({messages: [{role: user, content: 帮我查一下订单 A1001 的状态}]}) print(res)跑起来后日志里会先出现模型返回的tool_calls里面name是query_orderargs是{order_id: A1001}然后工具执行返回「已发货预计明天到达」最后模型把结果组织成自然语言。这条验证了 Agent 的工具调用链路走通了 TaoToken 通道。提示如果tool_calls为空说明模型没触发工具调用。检查system_prompt是否明确要求调用工具以及工具描述是否清晰。工具描述写「根据订单号查询订单状态」比写「查询」更容易被模型选中。5. 本篇常见错排查5.1 AuthenticationError 或 401最常见的原因是环境变量没设或设错。先确认echo $TAOTOKEN_API_KEY有输出再确认config.toml里api_key_env的名字和实际环境变量名一致。如果 Key 是从 https://taotoken.net/api-keys 复制的注意不要带多余空格。另一个原因是base_url写成了带 UTM 的地址base_url应该用 https://taotoken.net/api 不带查询参数。5.2 模型名报 not foundconfig.toml里的模型名要和 TaoToken 支持的模型名一致。去 https://taotoken.net/models 确认可用模型列表。如果用的是gpt-4o-mini这类名字注意大小写和连字符。模型名写错时报错通常是model_not_found或 404。5.3 RAG 检索返回空先检查 embedding 维度。config.toml里models.embedding.dim要和 Milvus schema 里的dim一致也要和实际 embedding 返回的向量长度一致。text-embedding-3-small是 1536 维如果 schema 写了 768 就会插入失败或检索异常。再检查top_k是否大于 0以及 collection 里是否真的有数据。用client.query(collection_namecollection, filterid 0, output_fields[text], limit5)确认数据在。5.4 Agent 不调用工具模型没触发工具调用时先看system_prompt有没有明确要求。create_agent的system_prompt写「你是订单助手需要调用工具查询订单状态」比写「你是助手」更容易触发。再看工具描述tool装饰的函数 docstring 就是工具描述写清楚输入输出。如果模型支持tool_choice参数可以在init_chat_model后通过bind_tools时指定但create_agent内部已经处理了绑定一般不需要手动干预。5.5 工具调用超时Agent 调用外部工具时可能卡住。settings.json里agent.tool_timeout设了 15 秒但create_agent本身不直接读这个值需要在工具函数内部自己做超时控制或者用asyncio.wait_for包一层。如果工具是网络请求先确认目标服务可达。日志里log_tool_calls打开后能看到工具调用开始和结束的时间戳方便定位卡在哪一步。5.6 配置读不到tomllib是 Python 3.11 才有的标准库。如果用的是 3.10 或更低版本装tomli并改成import tomli as tomllib。settings.json的编码要显式写utf-8否则 Windows 上可能因为默认编码报UnicodeDecodeError。路径问题也要注意config.toml和settings.json默认从当前工作目录读如果从其他目录运行脚本用绝对路径或Path(__file__).parent拼。6. 把 RAG 和 Agent 拼成一个应用RAG 链和 Agent 各自跑通后拼起来的方式是把 RAG 检索封装成一个工具挂到 Agent 上。这样 Agent 在需要查知识库时会调用 RAG 工具不需要时直接回答。# hybrid_demo.py from langchain.tools import tool from langchain.agents import create_agent from langchain.chat_models import init_chat_model from settings_loader import load_config cfg load_config() tool def search_knowledge(query: str) - str: 在知识库中检索与问题相关的文档片段。 # 这里复用 4.1 的 retrieval 函数 from rag_demo import retrieval return retrieval(query) llm init_chat_model( modelcfg[models][agent][name], model_provideropenai, base_urlcfg[provider][base_url], api_keycfg[provider][api_key], temperature0.0, ) agent create_agent( modelllm, tools[search_knowledge], system_prompt你是知识助手需要查资料时调用 search_knowledge 工具。, ) for chunk in agent.stream({messages: [{role: user, content: LangChain 1.0.2 的 create_agent 用什么构建运行时}]}): print(chunk, end\n\n)这条链路里Agent 判断需要查知识库调用search_knowledge工具内部走 RAG 检索返回文档片段Agent 再组织成回答。RAG 和 Agent 共用同一份config.toml和同一个 TaoToken Key配置只有一处。长期跑编码类 Agent 或需要多轮工具调用的场景可以看 https://taotoken.net/coding-plan 按用量规划比单次调用更省心。模型对话调试在 https://taotoken.net/models 直接试接入文档在 https://taotoken.net/doc 查配置项。Key 管理在 https://taotoken.net/api-keys 控制台在 https://taotoken.net/console 。Claude Code 相关接入参考 https://taotoken.net/claudecode 。最后留一个实用技巧把config.toml里的models段做成多套比如models.chat.dev和models.chat.prod用settings.json里的env字段决定加载哪套。这样本地调试用便宜模型上线切正式模型只改一个字段RAG 和 Agent 同时生效。