Langchain-Chatchat 接入智谱 AI（ZhipuAI / 智谱清言）在线模型：ChatGLMWorker 的 JWT 鉴权与 SSE 流式对话实现解析-开发者社区

Langchain-Chatchat 接入智谱 AI（ZhipuAI / 智谱清言）在线模型：ChatGLMWorker 的 JWT 鉴权与 SSE 流式对话实现解析

【免费下载链接】Langchain-ChatchatLangchain-Chatchat（原Langchain-ChatGLM）基于 Langchain 与 ChatGLM, Qwen 与 Llama 等语言模型的 RAG 与 Agent 应用 | Langchain-Chatchat (formerly langchain-ChatGLM), local knowledge based LLM (like ChatGLM, Qwen and Llama) RAG and Agent app with langchain项目地址: https://gitcode.com/GitHub_Trending/la/Langchain-Chatchat

Langchain-Chatchat 是一套基于 Langchain 的本地知识库与 Agent 应用框架，其重要能力之一是把大厂在线大模型 API 接入统一的对话服务。本文以仓库文档 markdown_docs/server/model_workers/zhipu.md 为骨架，完整解析智谱 AI（智谱清言，bigmodel.cn）接入层ChatGLMWorker工作器的实现原理——包括基于 API 密钥签名生成 JWT 访问令牌的generate_token、基于 HTTPX 的 SSE 流式连接connect_sse、核心对话方法do_chat以及会话模板构造逻辑。读完本文，你将掌握：Langchain-Chatchat 中"模型工作器（Model Worker）"如何向智谱在线 API 发起带鉴权的流式请求、请求参数如何组织、返回结构如何解析，以及在新版架构中智谱平台（platform_type=zhipuai）的接入位置与配置要点。

阅读指引：本文主题文档本身是围绕具体函数/类的技术说明，适合与仓库中同目录的基类说明 markdown_docs/server/model_workers/base.md 对照阅读。文中提到的参数结构与当前仓库内get_model_info/get_model_worker_config使用的模型配置字段（platform_type、api_base_url、api_key、api_proxy等）相互印证。

一、角色定位：模型工作器（Model Worker）与在线 API 接入

在 Langchain-Chatchat 的服务架构中，"模型工作器"是负责把某一具体模型/供应商的 API 封装成统一对话接口的组件。ChatGLMWorker正是面向智谱 AI 的 GLM-4 在线模型设计的工作器：它负责接收控制器（Controller）下发的聊天请求，向智谱开放平台发起 HTTP 调用，并把响应转换成统一格式流式返回给上层。

该工作器的几个核心预设属性（来源于文档定义）是理解它行为的关键：

属性	默认值	含义
`model_names`	`["zhipu-api"]`	注册到系统中的模型名列表，上层用该名称定位工作器
`controller_addr`	`None`	控制器地址，用于与控制面通信
`worker_addr`	`None`	工作器自身地址，用于接收控制器转发的请求
`version`	`"glm-4"`	模型版本，文档明确"目前只支持`glm-4`"
`context_len`	`4096`	默认上下文长度，代表一次请求可容纳的最大 token 规模

值得说明的是，仓库当前文档目录 markdown_docs/server/model_workers/zhipu.md 以函数/类为单位完整保留了这套历史实现说明；而在新版代码中，智谱在线模型的等价接入点是langchain_chatchat/chat_models/base.py中统一的消息/平台模型封装，其内部对glm-4等模型的支持依然保留（下文第五节会结合源码展开）。两类形态的"配置字段体系"是一脉相承的：api_base_url、api_proxy、api_key、secret_key等均出自 base.md 中ApiConfigParams的字段定义。

二、鉴权前置：`generate_token`与 API 密钥签名令牌

在线 API 接入的第一个核心问题是鉴权。文档给出的generate_token(apikey, exp_seconds)描述了智谱 AI 旧式签名认证的完整流程。

参数与签名规则：

apikey：用户的 API 密钥，通常由 ID 与密钥两部分组成，中间以英文点号.分隔；
exp_seconds：令牌过期时间，单位秒。

算法步骤（依据文档描述）：

将apikey按.分割成 ID 与密钥两部分，若分割失败则抛出异常提示"API 密钥无效"；
构造负载（payload），包含三个字段：API 密钥 ID、过期时间戳（当前时间 +exp_seconds）、当前时间戳；
使用 HS256 算法对负载做 JWT 编码；
附加头部信息，声明算法（HS256）、令牌类型（JWT）与签名类型（sign_type: "SIGN"）；
返回编码后的令牌字符串。

输出示例（文档原样）：

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsInNpZ25fdHlwZSI6IlNJR04ifQ.eyJhcGlfa2V5IjoiMTIzNDU2IiwiZXhwIjoxNjMwMjM0MDAwLCJ0aW1lc3RhbXAiOjE2MzAyMzM5NDAwfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"

解码后可以看到三段式 JWT 结构：头部携带HS256 / JWT / SIGN，负载内含api_key（即 API 密钥 ID）、exp（过期时间戳）、timestamp（当前时间戳）——这正是文档所述负载构成。注意：实际令牌值会随apikey、exp_seconds与当前时间动态变化，示例仅用于演示令牌三段式格式。

关键注意点（文档原文要点）：

必须保证传入的apikey格式正确（含 ID 与密钥、以点分隔），否则无法完成签名；
过期时间应按业务实际设定，令牌只在exp_seconds内有效；
HS256 属于对称签名，密钥必须妥善保管，严禁泄露，否则任何持有密钥者都能伪造令牌。

从代码结构看，generate_token被ChatGLMWorker.do_chat调用：在每次发起对话请求前，用用户提供的 API 密钥和固定 60 秒过期时间生成令牌，并作为 HTTP 请求的Authorization头部使用。这决定了它属于"短时效访问凭证"——一次对话若因网络等原因持续超过 60 秒，令牌可能过期，需要重新生成。

三、流式底座：`connect_sse`与 Server-Sent Events

ChatGLMWorker的流式响应能力建立在 Server-Sent Events（SSE）之上，由文档定义的connect_sse(client, method, url, **kwargs)承担。

参数说明：

client：一个httpx.Client实例，负责实际执行 HTTP 请求；
method：HTTP 请求方法字符串，例如"GET"/"POST"；
url：目标 URL 字符串；
**kwargs：任意关键字参数，会原样透传给client.stream方法，可用于携带请求头、查询参数、JSON 请求体等。

实现要点（依据文档）：

借助with语句与client.stream(...)建立上下文管理器——这是保证连接正确打开与关闭的关键；
client.stream被调用时依次接收 method、url 以及**kwargs；
建立连接并收到响应后，通过yield返回一个EventSource实例——它是对 SSE 事件流的封装，让调用方能够以简洁方式逐个消费服务端推送的事件。

工程注意点（文档原文要点）：

使用前需确保httpx已正确安装并导入；
URL 必须指向支持 SSE 的服务端端点；
处理事件时应关注异常处理与连接稳定性，网络波动或服务端异常时需要正确处理或实现重连逻辑。

SSE 机制天然适合大模型"边生成边返回"的流式输出：客户端不必等待完整响应，即可逐块拿到增量文本，从而获得更低的"首字延迟"体验。这是整个智谱工作器实现流式聊天的底层基石。

四、核心对话逻辑：`ChatGLMWorker.do_chat`全链路剖析

do_chat(params)是ChatGLMWorker的核心方法，它接收一个ApiChatParams对象（携带聊天请求所需的全部信息），并完整走通"加载配置 → 生成令牌 → 构造请求 → 发起调用 → 流式解析"这条链路。

逐步流程（依据文档）：

加载配置：调用params.load_config(...)，依据当前模型的工作器名称加载相应配置。这一机制定义在 base.md 所描述的ApiConfigParams.load_config中：它会调用get_model_worker_config拉取配置，并把命中的字段用setattr逐个写回实例。ApiChatParams通过继承ApiModelParams/ApiConfigParams，一次性获得以下字段：
- 连接类：api_base_url、api_proxy、api_key、secret_key；
- 生成控制类：temperature、max_tokens（默认与模型相关）、top_p（默认1.0）；
- 聊天专属类：messages（消息列表，每项为含角色与内容的字典）；
生成令牌：调用generate_token(api_key, 60)，用 60 秒有效期换取本次请求的访问令牌；

构造请求头：

{ "Content-Type": "application/json", "Authorization": "<上一步生成的令牌>" }

构造请求体，关键字段如下：

字段	说明
`model`（文档称为"聊天模型的版本"）	即`glm-4`
`messages`	来自`ApiChatParams.messages`的对话消息列表
`max_tokens`	本次生成允许的最大令牌数
`temperature`	采样温度，控制随机性
`stream`	布尔值，指示是否流式传输

发起请求：使用httpx.Client以 POST 方法向硬编码端点https://open.bigmodel.cn/api/paas/v4/chat/completions发送上述请求体——该 URL 对应智谱 AI 开放平台 v4 版 Chat Completions 接口；
解析并返回：请求成功后解析响应内容，通过生成器yield返回统一的字典结构：
```
{ "error_code": 0, "text": "这是由模型生成的回复文本。" }
```
error_code为0表示成功，text为模型生成的回复文本。注意返回值是生成器，调用方需要通过迭代才能真正消费到结果。

文档明确的注意项（实践红线）：

确保传入的params已正确实例化并携带全部必要的聊天信息；
认证令牌有时效（60 秒），长会话中可能需要重新生成；
网络请求具有不确定性，建议在调用侧补充异常处理逻辑以保障健壮性；
返回值是生成器，需迭代使用；
请求 URL 目前是硬编码的，若 API 地址变更需同步更新。

辅助方法速览

get_embeddings(params)：文档明确指出它当前仅作示例——先打印"embedding"字符串，再打印传入的params，并未实现真正的向量生成逻辑。在实际把智谱文本向量模型接入知识库流程时，应对其进行扩展（详见下一节中新版platform_type="zhipuai"的嵌入接入分支）。
make_conv_template(conv_template, model_path)：负责构建Conversation会话对象，返回结构如下（依据文档输出示例）：
```
Conversation( name="模型名称", # 取 self.model_names[0] system_message="你是智谱AI小助手，请根据用户的提示来完成任务", messages=[], # 初始为空 roles=["user", "assistant", "system"], sep="\n###", stop_str="###", )
```
其中conv_template与model_path两个入参在当前实现中未被直接使用，但文档指出它们可为未来"自定义会话模板"预留扩展位。sep="\n###"与stop_str="###"共同定义了该模型消息拼接的格式与停止符约定。

构造函数`init`细节

构造时把model_names、controller_addr、worker_addr三个参数并入kwargs转交给父类ApiModelWorker初始化；随后用setdefault为context_len设置默认值4096（若调用方已传入则保留原值）；最后把version写入self.version。三个可选参数在需要连接特定控制器/工作器时应当显式提供，而version参数在当前版本仅支持"glm-4"。

五、源码佐证：新版架构中的`zhipuai`平台接入点

尽管zhipu.md记录的是面向工作器形态的经典实现，当前仓库代码中依然能清晰找到智谱平台的对接证据，可作为把文档知识"映射到现代用法"的坐标。

嵌入模型（Embeddings）分支：在 libs/chatchat-server/chatchat/server/utils.py 的get_Embeddings中，存在platform_type == "zhipuai"的分支，会构造ZhipuAIEmbeddings，并把模型信息中的api_base_url、api_key、api_proxy传入：
```
elif model_info.get("platform_type") == "zhipuai": return ZhipuAIEmbeddings( base_url=model_info.get("api_base_url"), api_key=model_info.get("api_key"), zhipuai_proxy=model_info.get("api_proxy"), model=embed_model, )
```
这说明，在模型注册/模型信息配置中，智谱平台用platform_type="zhipuai"标识，配置键名与文档中ApiConfigParams的字段一一对应（api_base_url/api_key/api_proxy）。
嵌入实现类：libs/chatchat-server/langchain_chatchat/embeddings/zhipuai.py 中定义的ZhipuAIEmbeddings支持通过base_url/api_key/zhipuai_proxy三个别名注入，并会从环境变量ZHIPUAI_API_KEY等位置兜底读取密钥——这意味着即使不在配置中显式写 key，也可以借助环境变量完成鉴权，与文档中"API 密钥需妥善保护"的告诫互为印证。
聊天模型层：在 libs/chatchat-server/langchain_chatchat/chat_models/base.py 中，glm-4仍是模型名默认值之一（例如ChatModel/平台模型构造时的model="glm-4"默认），并且该文件内部返回的平台标识为"zhipuai-chat"。可见无论接入形态如何演进，智谱 GLM-4 对话能力始终是框架在线模型能力集中受支持的一环。
框架支持声明：仓库根 README 亦将"智谱清言（bigmodel.cn）"列入框架所支持的开源/在线大模型列表。文档zhipu.md所记载的 v4 版端点https://open.bigmodel.cn/api/paas/v4/chat/completions与其平台命名保持一致。

从源码结构可以推断：文档中经典的model_names=["zhipu-api"]形式，在新版中对应的是把platform_type设为zhipuai的在线模型注册条目；鉴权方式则由工作器内的 HS256 签名令牌，演变为以api_key/环境变量统一管理的平台密钥体系。若你需要在知识库检索链路中使用智谱向量模型，只需按上文platform_type="zhipuai"分支的字段约定登记模型信息即可。

六、实践要点与排障清单

综合文档各函数"注意"部分，给出可落地的接入清单：

依赖：确保httpx已安装（SSE 连接依赖httpx.Client；新版嵌入链路还需pip install zhipuai才能驱动官方 SDK，见 zhipuai.py 中相应提示）。
密钥管理：API 密钥由 ID 与密钥点分拼接；优先通过配置的api_key字段或ZHIPUAI_API_KEY环境变量注入，切勿把密钥硬编码或提交到版本库。
令牌时效：旧式签名令牌默认 60 秒过期，长耗时会话或异步场景需考虑重新签发。
流式消费：do_chat与connect_sse均为生成器/迭代式消费模型，调用方必须迭代取值；网络抖动时要具备异常捕获与重连策略。
端点一致性：v4 对话端点为https://open.bigmodel.cn/api/paas/v4/chat/completions；若未来平台调整地址，硬编码处需同步更新。
版本限制：ChatGLMWorker.version当前仅支持"glm-4"，选用其他版本前应先确认实现是否需要调整。
会话模板：构造出的Conversation使用roles=["user","assistant","system"]、分隔符"\n###"、停止符"###"，接入上层对话渲染时应与其保持一致，避免消息格式错乱。

七、总结

从zhipu.md可以完整还原智谱 AI 接入一条链路的技术全貌：generate_token解决"我是谁、何时过期"的鉴权问题，connect_sse解决"如何流式接收增量"的传输问题，ChatGLMWorker.do_chat把二者与ApiChatParams的配置体系串成一次完整的在线对话请求，而make_conv_template则负责把模型协议翻译成框架统一的会话形态。对照当前仓库源码，这条链路已在platform_type="zhipuai"的嵌入接入与glm-4默认模型支持中延续下来。

如果你正在 Langchain-Chatchat 中配置智谱清言 GLM-4 的在线对话与向量检索能力，建议将本文与 zhipu.md、base.md 两份文档配合使用：前者回答"工作器内部如何工作"，后者回答"配置字段从何而来、如何被加载"，二者共同构成可检索、可复用的接入知识基座。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Langchain-Chatchat 接入智谱 AI（ZhipuAI / 智谱清言）在线模型：ChatGLMWorker 的 JWT 鉴权与 SSE 流式对话实现解析