Langchain-Chatchat 接入智谱 AIZhipuAI / 智谱清言在线模型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-ChatchatLangchain-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_typezhipuai的接入位置与配置要点。阅读指引本文主题文档本身是围绕具体函数/类的技术说明适合与仓库中同目录的基类说明 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_addrNone控制器地址用于与控制面通信worker_addrNone工作器自身地址用于接收控制器转发的请求versionglm-4模型版本文档明确目前只支持glm-4context_len4096默认上下文长度代表一次请求可容纳的最大 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 EventsChatGLMWorker的流式响应能力建立在 Server-Sent EventsSSE之上由文档定义的connect_sse(client, method, url, **kwargs)承担。参数说明client一个httpx.Client实例负责实际执行 HTTP 请求methodHTTP 请求方法字符串例如GET/POSTurl目标 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-4messages来自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_typezhipuai的嵌入接入分支。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_urlmodel_info.get(api_base_url), api_keymodel_info.get(api_key), zhipuai_proxymodel_info.get(api_proxy), modelembed_model, )这说明在模型注册/模型信息配置中智谱平台用platform_typezhipuai标识配置键名与文档中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/平台模型构造时的modelglm-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_typezhipuai分支的字段约定登记模型信息即可。六、实践要点与排障清单综合文档各函数注意部分给出可落地的接入清单依赖确保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_typezhipuai的嵌入接入与glm-4默认模型支持中延续下来。如果你正在 Langchain-Chatchat 中配置智谱清言 GLM-4 的在线对话与向量检索能力建议将本文与 zhipu.md、base.md 两份文档配合使用前者回答工作器内部如何工作后者回答配置字段从何而来、如何被加载二者共同构成可检索、可复用的接入知识基座。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考