1. 为什么要在 LangChain 里接智普大模型LangChain 调用智普大模型这件事本质上就是让一个擅长编排流程的框架去驱动一个中文理解能力不错的国产模型。LangChain 负责把 Prompt、Memory、Retriever、Agent 这些零件串起来智普大模型负责在链条末端生成内容。适合谁适合已经用 LangChain 写过 Demo、想换成国产模型降低中文场景翻车率、又不想重写整条链路的开发者。我这次的目标很明确在本地开发环境里用一份可复制的config.toml和settings.json骨架把智普大模型通过统一 Key/API 通道接进 LangChain然后跑一次对话请求验证链路。整个过程不碰复杂部署纯本地 Python 环境。先说清楚一个容易混淆的点。LangChain 本身不生产模型它只是调用方。智普大模型提供的是推理能力LangChain 提供的是调用方式和上下文管理。两者之间需要一个稳定的 API 通道来传 Key、传参数、收结果。我选择用 TaoToken 作为统一通道原因是它把 Key 管理和 API 地址收敛到一处本地配置不用散落在多个环境变量里换模型时只改配置不改代码。这篇笔记的节奏是先讲清楚接入前的准备再给配置骨架然后是可复制的代码接着是验证请求和预期返回最后把常见的报错逐个拆掉。你可以跟着一步步操作也可以直接跳到配置章节复制骨架。2. TaoToken 前置准备Key 与通道在写任何 LangChain 代码之前先把通道和 Key 准备好。这一步不做后面代码跑起来只会报 401。TaoToken 的作用是提供一个统一的 API 入口你在这里拿到 Key然后在 LangChain 里把 base_url 指向它就可以调用智普大模型。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意 API 地址不带 UTM 参数。操作路径是这样的进入控制台创建一个 API Key复制出来保存好。这个 Key 只显示一次丢了就得重建。拿到 Key 之后你还需要确认要调用的模型名称。智普大模型在 LangChain 里常用的模型标识有glm-4、glm-3-turbo这类具体以你账号下可用的为准。注意Key 不要硬编码进 Git 仓库。本地开发用.env或者配置文件提交前检查.gitignore。如果你还没有 Key可以直接去 API Keys 页面创建https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。创建完之后接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有完整的参数说明遇到不确定的字段可以对照查。这一步的产出就两个东西一个 API Key一个确认可用的模型名。记住它们下面配置要用。3. 可复制配置config.toml 与 settings.json 骨架本地开发最怕配置散落。我用两个文件把配置收口config.toml放模型和通道参数settings.json放运行时开关。这样 LangChain 代码只读配置不关心具体值。先看config.toml[llm] provider zhipu model glm-4 base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY temperature 0.3 top_p 0.8 max_tokens 2048 timeout 30 [llm.retry] max_attempts 3 backoff_seconds 2这里几个字段解释一下。base_url指向 TaoToken 的 API 地址LangChain 会往这个地址发请求。api_key_env不直接写 Key而是写环境变量名代码运行时从环境变量读取避免 Key 进版本库。temperature和top_p是生成参数智普模型推荐 temperature 在 0.1 到 0.5 之间太高会飘。max_tokens限制单次生成长度GLM-4 支持到 8192本地调试先给 2048 够用。再看settings.json{ runtime: { stream: true, verbose: false, log_level: INFO }, chain: { memory_enabled: true, memory_window: 10 }, paths: { config: ./config.toml, log_dir: ./logs } }stream控制是否流式输出本地调试建议开能看到逐字返回。memory_window是多轮对话保留的轮数10 轮对大多数场景够用。log_dir是日志目录排障时看这里。两个文件放同一目录代码启动时先读settings.json找到config.toml路径再读模型配置。这样换模型只改config.toml的model字段代码一行不动。环境变量这样设置Linux/macOS 用export TAOTOKEN_API_KEY你的KeyWindows PowerShell 用$env:TAOTOKEN_API_KEY你的Key提示如果你用.env文件管理记得装python-dotenv在代码入口load_dotenv()一下。配置骨架到这里就齐了。接下来写 LangChain 调用代码。4. LangChain 接入代码从配置到对话代码分三层读配置、建模型实例、跑对话。我尽量写得直白你复制就能用。先装依赖pip install langchain langchain-community langchain-openai python-dotenv tomli这里说明一下LangChain 调用兼容 OpenAI 接口的模型时用langchain-openai的ChatOpenAI类最省事因为 TaoToken 的 API 是 OpenAI 兼容格式。智普大模型通过这个通道暴露出来LangChain 侧不需要自定义 LLM 类。读配置的代码import os import json import tomli from dotenv import load_dotenv load_dotenv() def load_settings(settings_path./settings.json): with open(settings_path, r, encodingutf-8) as f: return json.load(f) def load_llm_config(config_path): with open(config_path, rb) as f: return tomli.load(f) settings load_settings() llm_cfg load_llm_config(settings[paths][config])[llm] api_key os.environ.get(llm_cfg[api_key_env])建模型实例from langchain_openai import ChatOpenAI llm ChatOpenAI( modelllm_cfg[model], api_keyapi_key, base_urlllm_cfg[base_url], temperaturellm_cfg[temperature], top_pllm_cfg[top_p], max_tokensllm_cfg[max_tokens], timeoutllm_cfg[timeout], streamingsettings[runtime][stream], )跑一次对话from langchain_core.messages import HumanMessage, SystemMessage messages [ SystemMessage(content你是一个简洁的中文技术助手。), HumanMessage(content用三句话说明 LangChain 接入智普大模型的核心步骤。), ] resp llm.invoke(messages) print(resp.content)如果你要接 Prompt 模板可以这样from langchain_core.prompts import ChatPromptTemplate prompt ChatPromptTemplate.from_messages([ (system, 你是一个中文技术助手回答不超过三句话。), (human, 解释{concept}), ]) chain prompt | llm result chain.invoke({concept: LangChain 的 Memory 组件}) print(result.content)多轮对话加 Memoryfrom langchain_core.messages import HumanMessage from langchain_community.chat_message_histories import ChatMessageHistory from langchain_core.runnables.history import RunnableWithMessageHistory history ChatMessageHistory() def get_session_history(session_id): return history conversation RunnableWithMessageHistory(llm, get_session_history) r1 conversation.invoke( [HumanMessage(content智普大模型在中文处理上有什么特点)], config{configurable: {session_id: demo}}, ) print(r1.content) r2 conversation.invoke( [HumanMessage(content它适合做 RAG 吗)], config{configurable: {session_id: demo}}, ) print(r2.content)这段代码里RunnableWithMessageHistory会自动把历史消息拼进上下文第二轮提问时模型能看到第一轮的内容。session_id用来区分不同会话本地调试固定一个就行。代码写完了下一步是验证。5. 验证请求与预期返回验证分两步先确认通道通再确认 LangChain 链路通。第一步用 curl 直接打 API排除 LangChain 层的干扰curl -X POST https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: glm-4, messages: [{role: user, content: 回复链路正常}], temperature: 0.1 }预期返回是一个 JSON结构里choices[0].message.content字段包含模型输出。如果这一步返回 401说明 Key 有问题返回 404说明模型名或路径不对返回 200 但内容为空检查messages格式。第二步跑上面的 Python 代码。预期输出类似LangChain 接入智普大模型的核心步骤第一准备 API Key 和通道地址 第二用 ChatOpenAI 类配置模型参数第三通过 invoke 或 chain 调用并验证返回。如果你开了streamTrue会看到逐字打印。如果verboseTrue会看到 LangChain 内部的调用日志包括实际请求的 URL 和参数。验证通过的标志有三个curl 返回 200 且有内容、Python 脚本正常打印、多轮对话第二轮能引用第一轮信息。三个都过链路就算跑通了。注意验证时把max_tokens设小一点比如 256省额度也快。确认通了再调大。6. 本篇常见报错排查接入过程中最容易撞的几类错误我按出现频率排一下。第一类401 Unauthorized。原因通常是 Key 没读到或者 Key 失效。排查顺序先echo $TAOTOKEN_API_KEY确认环境变量有值再确认代码里api_key不是 None最后去控制台看 Key 是否被禁用。如果用了.env确认load_dotenv()在读取环境变量之前执行。第二类404 Not Found。多半是base_url写错。正确写法是https://taotoken.net/api不要多加/v1或者结尾斜杠。LangChain 的ChatOpenAI会自动拼接/chat/completions你只需要给到/api。第三类模型名不识别。报错信息里会有model not found或类似提示。去接入文档核对当前可用的模型标识别用已经下线的旧名字。glm-4和glm-3-turbo是常见可用的但以你账号实际权限为准。第四类超时。本地网络波动或者max_tokens设太大都会导致。先把timeout调到 60max_tokens降到 512 试。如果还超时用 curl 单独测一次区分是网络问题还是代码问题。第五类流式输出报错。如果你开了streamTrue但用的是invoke而不是stream某些版本会报类型错误。流式场景改用for chunk in llm.stream(messages)逐块取。第六类Memory 不生效。多轮对话第二轮没有引用第一轮通常是session_id没传或者每次新建了 history 对象。确认get_session_history返回的是同一个实例或者用官方的持久化方案。排障时把log_level调到DEBUG日志里能看到完整的请求体和响应体定位快很多。7. 下一步把链路用起来链路跑通之后你可以做几件事。一是把config.toml里的model换成glm-3-turbo对比响应速度和生成质量选一个适合你场景的。二是把 Prompt 模板抽出来单独管理不同任务用不同模板代码里只传变量。三是接 RAG用 LangChain 的 Retriever 把本地知识库挂上去智普大模型负责生成检索部分用中文 Embedding 模型。如果你要长期跑编码类任务或者 Agent可以考虑 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有配额和并发相关的说明。想先在网页上试模型效果用模型对话页面https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。控制台在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content Key 管理和用量查看都在那里。我自己的习惯是每接一个新模型先跑一遍这篇里的验证请求确认通道和参数都对再往业务代码里搬。这样出问题时能快速定位是配置层还是业务层。配置骨架和代码你直接复制改一下 Key 和模型名就能用。
1. 为什么要在 LangChain 里接智普大模型LangChain 调用智普大模型这件事本质上就是让一个擅长编排流程的框架去驱动一个中文理解能力不错的国产模型。LangChain 负责把 Prompt、Memory、Retriever、Agent 这些零件串起来智普大模型负责在链条末端生成内容。适合谁适合已经用 LangChain 写过 Demo、想换成国产模型降低中文场景翻车率、又不想重写整条链路的开发者。我这次的目标很明确在本地开发环境里用一份可复制的config.toml和settings.json骨架把智普大模型通过统一 Key/API 通道接进 LangChain然后跑一次对话请求验证链路。整个过程不碰复杂部署纯本地 Python 环境。先说清楚一个容易混淆的点。LangChain 本身不生产模型它只是调用方。智普大模型提供的是推理能力LangChain 提供的是调用方式和上下文管理。两者之间需要一个稳定的 API 通道来传 Key、传参数、收结果。我选择用 TaoToken 作为统一通道原因是它把 Key 管理和 API 地址收敛到一处本地配置不用散落在多个环境变量里换模型时只改配置不改代码。这篇笔记的节奏是先讲清楚接入前的准备再给配置骨架然后是可复制的代码接着是验证请求和预期返回最后把常见的报错逐个拆掉。你可以跟着一步步操作也可以直接跳到配置章节复制骨架。2. TaoToken 前置准备Key 与通道在写任何 LangChain 代码之前先把通道和 Key 准备好。这一步不做后面代码跑起来只会报 401。TaoToken 的作用是提供一个统一的 API 入口你在这里拿到 Key然后在 LangChain 里把 base_url 指向它就可以调用智普大模型。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意 API 地址不带 UTM 参数。操作路径是这样的进入控制台创建一个 API Key复制出来保存好。这个 Key 只显示一次丢了就得重建。拿到 Key 之后你还需要确认要调用的模型名称。智普大模型在 LangChain 里常用的模型标识有glm-4、glm-3-turbo这类具体以你账号下可用的为准。注意Key 不要硬编码进 Git 仓库。本地开发用.env或者配置文件提交前检查.gitignore。如果你还没有 Key可以直接去 API Keys 页面创建https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。创建完之后接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有完整的参数说明遇到不确定的字段可以对照查。这一步的产出就两个东西一个 API Key一个确认可用的模型名。记住它们下面配置要用。3. 可复制配置config.toml 与 settings.json 骨架本地开发最怕配置散落。我用两个文件把配置收口config.toml放模型和通道参数settings.json放运行时开关。这样 LangChain 代码只读配置不关心具体值。先看config.toml[llm] provider zhipu model glm-4 base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY temperature 0.3 top_p 0.8 max_tokens 2048 timeout 30 [llm.retry] max_attempts 3 backoff_seconds 2这里几个字段解释一下。base_url指向 TaoToken 的 API 地址LangChain 会往这个地址发请求。api_key_env不直接写 Key而是写环境变量名代码运行时从环境变量读取避免 Key 进版本库。temperature和top_p是生成参数智普模型推荐 temperature 在 0.1 到 0.5 之间太高会飘。max_tokens限制单次生成长度GLM-4 支持到 8192本地调试先给 2048 够用。再看settings.json{ runtime: { stream: true, verbose: false, log_level: INFO }, chain: { memory_enabled: true, memory_window: 10 }, paths: { config: ./config.toml, log_dir: ./logs } }stream控制是否流式输出本地调试建议开能看到逐字返回。memory_window是多轮对话保留的轮数10 轮对大多数场景够用。log_dir是日志目录排障时看这里。两个文件放同一目录代码启动时先读settings.json找到config.toml路径再读模型配置。这样换模型只改config.toml的model字段代码一行不动。环境变量这样设置Linux/macOS 用export TAOTOKEN_API_KEY你的KeyWindows PowerShell 用$env:TAOTOKEN_API_KEY你的Key提示如果你用.env文件管理记得装python-dotenv在代码入口load_dotenv()一下。配置骨架到这里就齐了。接下来写 LangChain 调用代码。4. LangChain 接入代码从配置到对话代码分三层读配置、建模型实例、跑对话。我尽量写得直白你复制就能用。先装依赖pip install langchain langchain-community langchain-openai python-dotenv tomli这里说明一下LangChain 调用兼容 OpenAI 接口的模型时用langchain-openai的ChatOpenAI类最省事因为 TaoToken 的 API 是 OpenAI 兼容格式。智普大模型通过这个通道暴露出来LangChain 侧不需要自定义 LLM 类。读配置的代码import os import json import tomli from dotenv import load_dotenv load_dotenv() def load_settings(settings_path./settings.json): with open(settings_path, r, encodingutf-8) as f: return json.load(f) def load_llm_config(config_path): with open(config_path, rb) as f: return tomli.load(f) settings load_settings() llm_cfg load_llm_config(settings[paths][config])[llm] api_key os.environ.get(llm_cfg[api_key_env])建模型实例from langchain_openai import ChatOpenAI llm ChatOpenAI( modelllm_cfg[model], api_keyapi_key, base_urlllm_cfg[base_url], temperaturellm_cfg[temperature], top_pllm_cfg[top_p], max_tokensllm_cfg[max_tokens], timeoutllm_cfg[timeout], streamingsettings[runtime][stream], )跑一次对话from langchain_core.messages import HumanMessage, SystemMessage messages [ SystemMessage(content你是一个简洁的中文技术助手。), HumanMessage(content用三句话说明 LangChain 接入智普大模型的核心步骤。), ] resp llm.invoke(messages) print(resp.content)如果你要接 Prompt 模板可以这样from langchain_core.prompts import ChatPromptTemplate prompt ChatPromptTemplate.from_messages([ (system, 你是一个中文技术助手回答不超过三句话。), (human, 解释{concept}), ]) chain prompt | llm result chain.invoke({concept: LangChain 的 Memory 组件}) print(result.content)多轮对话加 Memoryfrom langchain_core.messages import HumanMessage from langchain_community.chat_message_histories import ChatMessageHistory from langchain_core.runnables.history import RunnableWithMessageHistory history ChatMessageHistory() def get_session_history(session_id): return history conversation RunnableWithMessageHistory(llm, get_session_history) r1 conversation.invoke( [HumanMessage(content智普大模型在中文处理上有什么特点)], config{configurable: {session_id: demo}}, ) print(r1.content) r2 conversation.invoke( [HumanMessage(content它适合做 RAG 吗)], config{configurable: {session_id: demo}}, ) print(r2.content)这段代码里RunnableWithMessageHistory会自动把历史消息拼进上下文第二轮提问时模型能看到第一轮的内容。session_id用来区分不同会话本地调试固定一个就行。代码写完了下一步是验证。5. 验证请求与预期返回验证分两步先确认通道通再确认 LangChain 链路通。第一步用 curl 直接打 API排除 LangChain 层的干扰curl -X POST https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: glm-4, messages: [{role: user, content: 回复链路正常}], temperature: 0.1 }预期返回是一个 JSON结构里choices[0].message.content字段包含模型输出。如果这一步返回 401说明 Key 有问题返回 404说明模型名或路径不对返回 200 但内容为空检查messages格式。第二步跑上面的 Python 代码。预期输出类似LangChain 接入智普大模型的核心步骤第一准备 API Key 和通道地址 第二用 ChatOpenAI 类配置模型参数第三通过 invoke 或 chain 调用并验证返回。如果你开了streamTrue会看到逐字打印。如果verboseTrue会看到 LangChain 内部的调用日志包括实际请求的 URL 和参数。验证通过的标志有三个curl 返回 200 且有内容、Python 脚本正常打印、多轮对话第二轮能引用第一轮信息。三个都过链路就算跑通了。注意验证时把max_tokens设小一点比如 256省额度也快。确认通了再调大。6. 本篇常见报错排查接入过程中最容易撞的几类错误我按出现频率排一下。第一类401 Unauthorized。原因通常是 Key 没读到或者 Key 失效。排查顺序先echo $TAOTOKEN_API_KEY确认环境变量有值再确认代码里api_key不是 None最后去控制台看 Key 是否被禁用。如果用了.env确认load_dotenv()在读取环境变量之前执行。第二类404 Not Found。多半是base_url写错。正确写法是https://taotoken.net/api不要多加/v1或者结尾斜杠。LangChain 的ChatOpenAI会自动拼接/chat/completions你只需要给到/api。第三类模型名不识别。报错信息里会有model not found或类似提示。去接入文档核对当前可用的模型标识别用已经下线的旧名字。glm-4和glm-3-turbo是常见可用的但以你账号实际权限为准。第四类超时。本地网络波动或者max_tokens设太大都会导致。先把timeout调到 60max_tokens降到 512 试。如果还超时用 curl 单独测一次区分是网络问题还是代码问题。第五类流式输出报错。如果你开了streamTrue但用的是invoke而不是stream某些版本会报类型错误。流式场景改用for chunk in llm.stream(messages)逐块取。第六类Memory 不生效。多轮对话第二轮没有引用第一轮通常是session_id没传或者每次新建了 history 对象。确认get_session_history返回的是同一个实例或者用官方的持久化方案。排障时把log_level调到DEBUG日志里能看到完整的请求体和响应体定位快很多。7. 下一步把链路用起来链路跑通之后你可以做几件事。一是把config.toml里的model换成glm-3-turbo对比响应速度和生成质量选一个适合你场景的。二是把 Prompt 模板抽出来单独管理不同任务用不同模板代码里只传变量。三是接 RAG用 LangChain 的 Retriever 把本地知识库挂上去智普大模型负责生成检索部分用中文 Embedding 模型。如果你要长期跑编码类任务或者 Agent可以考虑 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有配额和并发相关的说明。想先在网页上试模型效果用模型对话页面https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。控制台在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content Key 管理和用量查看都在那里。我自己的习惯是每接一个新模型先跑一遍这篇里的验证请求确认通道和参数都对再往业务代码里搬。这样出问题时能快速定位是配置层还是业务层。配置骨架和代码你直接复制改一下 Key 和模型名就能用。
