尧图网站建设 
Langchain-Chatchat 讯飞星火Spark接入指南SparkApi 鉴权签名与 WebSocket 请求链路解析【免费下载链接】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本篇指南以 SparkApi.md 为主体系统讲解 Langchain-Chatchat 为接入讯飞星火大模型Spark API而封装的 SparkApi 工具模块Ws_Param类如何生成携带鉴权信息的 WebSocket 连接 URLgen_params如何构造符合 API 规范的请求体以及它们与模型工作器XingHuoWorker的组合调用链路。读完本文你将掌握 Langchain-Chatchat 集成星火在线模型的完整底层原理并能依据鉴权算法与请求结构完成二次开发或排障。一、SparkApi 在 Langchain-Chatchat 中的定位Langchain-Chatchat 支持通过各类在线模型工作器model worker接入云端大模型服务。讯飞星火Spark / iFLYTEK Spark属于典型的在线 API 服务它与本地模型不同不需要下载权重而是通过WebSocket长连接与讯飞云端交互且连接建立前必须完成一套基于HMAC-SHA256的签名鉴权。SparkApi模块正是这套通信机制中最底层、与业务无关的工具层。从其被引用的关系看模块核心由两部分构成组成部分职责文档出处Ws_Param类保存 APPID / APIKey / APISecret 等凭证并生成带鉴权参数的连接 URLSparkApi.mdgen_params()函数将提问文本与采样参数组装为符合星火 API 规范的 JSON 请求体SparkApi.md两者的消费者是上层的工作器实现。根据仓库中的配套文档 xinghuo.mdSparkApi.Ws_Param与SparkApi.gen_params均由xinghuo.py中的request函数调用先通过Ws_Param.create_url()拿到鉴权 URL再以gen_params()生成请求数据随后用websockets.connect建立连接并异步接收流式文本。也就是说SparkApi 是星火接入的地基而XingHuoWorker是搭建在其上的业务层。说明本仓库当前快照中model_workers目录下的原始 Python 实现文件未包含在内但 xinghuo.md、base.md 等 API 文档完整记录了上述类的接口契约与调用关系本文据此展开。二、Ws_Param类凭证模型与 URL 解析Ws_Param是一个凭证 URL 构造器双重职责的类。它的全部实例属性如下属性类型含义说明APPID应用 ID在讯飞开放平台创建应用后获得APIKeyAPI 密钥用于访问 Spark 服务APISecret密钥的 Secret参与签名计算的核心机密host网络地址由Spark_url解析出的netloc主机名 端口pathURL 路径由Spark_url解析出的pathSpark_url服务完整 URL形如wss://.../v1.1/chat的连接地址2.1__init__构造与 URL 拆解构造函数接收APPID、APIKey、APISecret、Spark_url四个参数完成两件事将四个入参原样保存在实例上供后续方法使用使用 Python 标准库urllib.parse.urlparse解析Spark_url把解析结果的netloc与path分别赋给self.host与self.path。这种先拆解、后签名、再拼接的设计是为了在create_url中把host、path作为独立片段参与签名原文构造详见下文。它同时意味着Spark_url的格式是否规范会直接影响签名能否通过因此文档特别提示使用前须确保Spark_url可被正确解析出网络位置与路径本构造函数不做参数合法性校验APPID/APIKey/APISecret的准确性与安全性需要调用方负责三个凭证应统一从讯飞开放平台的应用管理后台获取。三、create_url基于 HMAC-SHA256 的鉴权 URL 生成create_url是Ws_Param中技术含量最高的方法其核心任务是把明文凭证加工成可被服务端验证的签名并拼接到原始 URL 上。官方 WebSocket 鉴权流程通常包含五个环节本方法一一对应① 生成 RFC1123 时间戳 date ② 拼接签名原文host \n date \n GET path HTTP/1.1 ③ 以 APISecret 为密钥对签名原文做 HMAC-SHA256 加密 ④ 将密文做 Base64 编码得到 signature_sha ⑤ 构造 Authorization APIKey 变量 : signature_sha连同 date、host 一起 URL 编码后附加到 Spark_url 末尾这里补充几个值得注意的工程细节RFC1123 时间戳即GMT格式的 HTTP 标准日期如Mon, 20 Sep 2023 12:00:00 GMT。该时间同时用于签名原文与最终 URL 的date参数服务端据此校验请求新鲜度因此文档强调生成的 URL 应立即使用避免因时间差导致鉴权失败。签名原文采用三行结构host、date、请求行这是讯飞 WebSocket 鉴权协议约定的拼接方式请求行使用大写GET与HTTP/1.1版本号与常规 HTTP 签名规范一致。密钥分工APIKey以明文身份标识出现在Authorization前缀中APISecret则只作为 HMAC 密钥参与运算绝不直接传输。最终生成的 URL 结构可概括为Spark_url ? authorization Base64(Authorization头) date URL编码(RFC1123时间) host host文档给出的示意如下https://spark.example.com/api?authorizationBase64EncodedStringdateRFC1123Datehostspark.example.com其中authorization的值是对APIKey:Base64(HMAC-SHA256签名)再一次编码后的字符串。务必注意此 URL 已内含APIKey与APISecret的派生物属敏感信息文档明确警告打印日志或调试输出时应谨慎防止凭证泄露。四、gen_params星火对话请求体的组装拿到鉴权 URL 后下一步是构造真正要发送的对话请求。gen_params(appid, domain, question, temperature, max_token)负责完成这一任务其返回结构为星火 API 标准的三段式 JSON{ header: { app_id: your_appid, uid: 1234 }, parameter: { chat: { domain: your_domain, random_threshold: 0.5, max_tokens: 100, auditing: default, temperature: 0.7 } }, payload: { message: { text: 你的问题 } } }各字段职责如下字段所属层级作用与建议app_idheader应用标识须与Ws_Param.APPID一致uidheader会话内用户标识便于服务端区分请求来源domainparameter.chat请求所属领域/模型版本标识如general、generalv2等具体以接入版本为准random_thresholdparameter.chat随机采样阈值控制回答多样性max_tokensparameter.chat生成最大 token 数须依据实际版本上限调整auditingparameter.chat内容审核级别temperatureparameter.chat创造性控制参数值越高回答越多样值越低越确定textpayload.message用户的提问文本question该函数把appid、domain、question以及生成控制参数统一收敛进一个自洽的数据结构中使上层代码无需关心星火 API 的层级嵌套细节是业务与协议解耦的关键一环。五、完整调用链路从request到XingHuoWorker5.1requestWebSocket 连接与流式接收根据 xinghuo.mdxinghuo.py中的request(appid, api_key, api_secret, Spark_url, domain, question, temperature, max_token)把上文两个工具串成一条完整链路创建 Ws_Param 对象 → 调用 create_url() 得到鉴权 URL → 调用 gen_params() 生成请求 JSON → websockets.connect(url) 建立连接 → json.dumps 后发送请求体 → 异步循环逐帧接收服务端响应 ├─ 响应 header.status 2 → 处理完成结束循环 └─ 响应 payload 含文本 → 逐块 yield 给调用方其中request是异步生成器既通过await等待网络事件又用yield把分片文本逐段吐出。文档提示调用方需在异步环境下使用并通过异步迭代消费结果。响应头status 2是星火协议中本轮生成完毕的信号是该循环的终止条件。5.2XingHuoWorker工作器封装与版本管理XingHuoWorker继承自ApiModelWorker见 base.md是模型工作器层级对星火 API 的落地实现。它的核心设计点包括默认属性model_names默认为[xinghuo-api]context_len默认 8000通过kwargs.setdefault(context_len, 8000)设置可被外部配置覆盖版本映射do_chat内部维护version_mapping含各版本的 domain、URL 与 max_tokens 上限由内嵌函数get_version_details(version_key)按params.version取用未命中时返回{domain: None, url: None}完成优雅降级避免异常中断token 上限收敛params.max_tokens min(details[max_tokens], params.max_tokens)确保请求不超过服务端允许的上限异步同步化通过iter_over_async同步迭代异步生成器的工具详见 utils.md把request产生的异步流逐步拉取并累加到text后以{error_code: 0, text: ...}的形式逐块 yield 给上层未实现的方法get_embeddings目前仅打印参数暗示星火 worker 暂未落地 embedding 能力需要 embedding 场景时应改用其他嵌入模型对话模板make_conv_template生成namemodel_names[0]、系统提示为你是一个聪明的助手请根据用户的提示来完成任务、roles[user, assistant]、sep\n### 、stop_str###的会话结构。5.3 配置字段的注入方式在 base.md 中可以看到在线 API 配置基类ApiConfigParams显式声明了星火相关字段APPID、APISecret以及worker_name等并允许extra allow兼容额外字段。其load_config(worker_name)与validate_config机制会调用get_model_worker_config配置合并逻辑见 utils.md把默认配置 在线模型配置 特定模型配置逐层合并后回填到参数对象。因此在 Langchain-Chatchat 中接入星火时只需在模型配置中声明 provider 与上述凭证字段XingHuoWorker.do_chat内的params.load_config(...)便会自动完成配置装载而无需手工逐项传参。六、接入注意事项与排障要点结合原文档的注意条目与整体调用链实际接入时建议重点检查以下几点凭证三件套齐全APPID、APIKey、APISecret缺一不可任一错误都会导致鉴权失败或连接被拒务必从讯飞开放平台后台获取勿硬编码进版本库。Spark_url与version匹配Spark_url决定host/path拆分结果version决定domain与url的选取两者不匹配会直接表现为握手失败或返回未知 domain。URL 即时使用签名内的时间戳基于当前时间URL 生成到发起连接之间不应有显著延迟否则会因时间窗过期鉴权失败。不要在日志中打印鉴权 URLURL 携带可推导凭证的信息调试时建议打码或仅打印 host 部分。异步环境约束request、do_chat均为异步生成器须在异步环境中await/ 异步迭代事件循环获取失败时需自行创建避免循环冲突do_chat与iter_over_async都体现了这一处理。参数边界temperature与max_tokens直接决定输出质量与长度须结合所选模型版本的实际取值范围设定服务端 max_tokens 上限由get_version_details统一收敛。七、小结从模块职责看Langchain-Chatchat 将鉴权与协议细节下沉到SparkApi将版本策略与业务封装上移到XingHuoWorker中间以request的 WebSocket 异步流作为桥梁形成了一条清晰的三层调用链SparkApi.Ws_Param.create_url()签名 URL→SparkApi.gen_params()协议请求体→request()连接与流式收发。理解这条链路的读者既能独立排查星火接入中的签名、参数与异步问题也能以此为模板为 Langchain-Chatchat 扩展其他 WebSocket 型在线模型工作器提供参考。进一步阅读SparkApi.md本篇主题文档含Ws_Param与gen_params的完整契约说明xinghuo.mdrequest与XingHuoWorker的实现细节、版本映射与输出示例base.mdApiConfigParams/ApiModelWorker基类设计说明 APPID、APISecret 等字段如何随配置注入utils.mdget_model_worker_config、iter_over_async等支撑工具【免费下载链接】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），仅供参考 Langchain-Chatchat 讯飞星火（Spark）接入指南：SparkApi 鉴权签名与 WebSocket 请求链路解析
Langchain-Chatchat 讯飞星火Spark接入指南SparkApi 鉴权签名与 WebSocket 请求链路解析【免费下载链接】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本篇指南以 SparkApi.md 为主体系统讲解 Langchain-Chatchat 为接入讯飞星火大模型Spark API而封装的 SparkApi 工具模块Ws_Param类如何生成携带鉴权信息的 WebSocket 连接 URLgen_params如何构造符合 API 规范的请求体以及它们与模型工作器XingHuoWorker的组合调用链路。读完本文你将掌握 Langchain-Chatchat 集成星火在线模型的完整底层原理并能依据鉴权算法与请求结构完成二次开发或排障。一、SparkApi 在 Langchain-Chatchat 中的定位Langchain-Chatchat 支持通过各类在线模型工作器model worker接入云端大模型服务。讯飞星火Spark / iFLYTEK Spark属于典型的在线 API 服务它与本地模型不同不需要下载权重而是通过WebSocket长连接与讯飞云端交互且连接建立前必须完成一套基于HMAC-SHA256的签名鉴权。SparkApi模块正是这套通信机制中最底层、与业务无关的工具层。从其被引用的关系看模块核心由两部分构成组成部分职责文档出处Ws_Param类保存 APPID / APIKey / APISecret 等凭证并生成带鉴权参数的连接 URLSparkApi.mdgen_params()函数将提问文本与采样参数组装为符合星火 API 规范的 JSON 请求体SparkApi.md两者的消费者是上层的工作器实现。根据仓库中的配套文档 xinghuo.mdSparkApi.Ws_Param与SparkApi.gen_params均由xinghuo.py中的request函数调用先通过Ws_Param.create_url()拿到鉴权 URL再以gen_params()生成请求数据随后用websockets.connect建立连接并异步接收流式文本。也就是说SparkApi 是星火接入的地基而XingHuoWorker是搭建在其上的业务层。说明本仓库当前快照中model_workers目录下的原始 Python 实现文件未包含在内但 xinghuo.md、base.md 等 API 文档完整记录了上述类的接口契约与调用关系本文据此展开。二、Ws_Param类凭证模型与 URL 解析Ws_Param是一个凭证 URL 构造器双重职责的类。它的全部实例属性如下属性类型含义说明APPID应用 ID在讯飞开放平台创建应用后获得APIKeyAPI 密钥用于访问 Spark 服务APISecret密钥的 Secret参与签名计算的核心机密host网络地址由Spark_url解析出的netloc主机名 端口pathURL 路径由Spark_url解析出的pathSpark_url服务完整 URL形如wss://.../v1.1/chat的连接地址2.1__init__构造与 URL 拆解构造函数接收APPID、APIKey、APISecret、Spark_url四个参数完成两件事将四个入参原样保存在实例上供后续方法使用使用 Python 标准库urllib.parse.urlparse解析Spark_url把解析结果的netloc与path分别赋给self.host与self.path。这种先拆解、后签名、再拼接的设计是为了在create_url中把host、path作为独立片段参与签名原文构造详见下文。它同时意味着Spark_url的格式是否规范会直接影响签名能否通过因此文档特别提示使用前须确保Spark_url可被正确解析出网络位置与路径本构造函数不做参数合法性校验APPID/APIKey/APISecret的准确性与安全性需要调用方负责三个凭证应统一从讯飞开放平台的应用管理后台获取。三、create_url基于 HMAC-SHA256 的鉴权 URL 生成create_url是Ws_Param中技术含量最高的方法其核心任务是把明文凭证加工成可被服务端验证的签名并拼接到原始 URL 上。官方 WebSocket 鉴权流程通常包含五个环节本方法一一对应① 生成 RFC1123 时间戳 date ② 拼接签名原文host \n date \n GET path HTTP/1.1 ③ 以 APISecret 为密钥对签名原文做 HMAC-SHA256 加密 ④ 将密文做 Base64 编码得到 signature_sha ⑤ 构造 Authorization APIKey 变量 : signature_sha连同 date、host 一起 URL 编码后附加到 Spark_url 末尾这里补充几个值得注意的工程细节RFC1123 时间戳即GMT格式的 HTTP 标准日期如Mon, 20 Sep 2023 12:00:00 GMT。该时间同时用于签名原文与最终 URL 的date参数服务端据此校验请求新鲜度因此文档强调生成的 URL 应立即使用避免因时间差导致鉴权失败。签名原文采用三行结构host、date、请求行这是讯飞 WebSocket 鉴权协议约定的拼接方式请求行使用大写GET与HTTP/1.1版本号与常规 HTTP 签名规范一致。密钥分工APIKey以明文身份标识出现在Authorization前缀中APISecret则只作为 HMAC 密钥参与运算绝不直接传输。最终生成的 URL 结构可概括为Spark_url ? authorization Base64(Authorization头) date URL编码(RFC1123时间) host host文档给出的示意如下https://spark.example.com/api?authorizationBase64EncodedStringdateRFC1123Datehostspark.example.com其中authorization的值是对APIKey:Base64(HMAC-SHA256签名)再一次编码后的字符串。务必注意此 URL 已内含APIKey与APISecret的派生物属敏感信息文档明确警告打印日志或调试输出时应谨慎防止凭证泄露。四、gen_params星火对话请求体的组装拿到鉴权 URL 后下一步是构造真正要发送的对话请求。gen_params(appid, domain, question, temperature, max_token)负责完成这一任务其返回结构为星火 API 标准的三段式 JSON{ header: { app_id: your_appid, uid: 1234 }, parameter: { chat: { domain: your_domain, random_threshold: 0.5, max_tokens: 100, auditing: default, temperature: 0.7 } }, payload: { message: { text: 你的问题 } } }各字段职责如下字段所属层级作用与建议app_idheader应用标识须与Ws_Param.APPID一致uidheader会话内用户标识便于服务端区分请求来源domainparameter.chat请求所属领域/模型版本标识如general、generalv2等具体以接入版本为准random_thresholdparameter.chat随机采样阈值控制回答多样性max_tokensparameter.chat生成最大 token 数须依据实际版本上限调整auditingparameter.chat内容审核级别temperatureparameter.chat创造性控制参数值越高回答越多样值越低越确定textpayload.message用户的提问文本question该函数把appid、domain、question以及生成控制参数统一收敛进一个自洽的数据结构中使上层代码无需关心星火 API 的层级嵌套细节是业务与协议解耦的关键一环。五、完整调用链路从request到XingHuoWorker5.1requestWebSocket 连接与流式接收根据 xinghuo.mdxinghuo.py中的request(appid, api_key, api_secret, Spark_url, domain, question, temperature, max_token)把上文两个工具串成一条完整链路创建 Ws_Param 对象 → 调用 create_url() 得到鉴权 URL → 调用 gen_params() 生成请求 JSON → websockets.connect(url) 建立连接 → json.dumps 后发送请求体 → 异步循环逐帧接收服务端响应 ├─ 响应 header.status 2 → 处理完成结束循环 └─ 响应 payload 含文本 → 逐块 yield 给调用方其中request是异步生成器既通过await等待网络事件又用yield把分片文本逐段吐出。文档提示调用方需在异步环境下使用并通过异步迭代消费结果。响应头status 2是星火协议中本轮生成完毕的信号是该循环的终止条件。5.2XingHuoWorker工作器封装与版本管理XingHuoWorker继承自ApiModelWorker见 base.md是模型工作器层级对星火 API 的落地实现。它的核心设计点包括默认属性model_names默认为[xinghuo-api]context_len默认 8000通过kwargs.setdefault(context_len, 8000)设置可被外部配置覆盖版本映射do_chat内部维护version_mapping含各版本的 domain、URL 与 max_tokens 上限由内嵌函数get_version_details(version_key)按params.version取用未命中时返回{domain: None, url: None}完成优雅降级避免异常中断token 上限收敛params.max_tokens min(details[max_tokens], params.max_tokens)确保请求不超过服务端允许的上限异步同步化通过iter_over_async同步迭代异步生成器的工具详见 utils.md把request产生的异步流逐步拉取并累加到text后以{error_code: 0, text: ...}的形式逐块 yield 给上层未实现的方法get_embeddings目前仅打印参数暗示星火 worker 暂未落地 embedding 能力需要 embedding 场景时应改用其他嵌入模型对话模板make_conv_template生成namemodel_names[0]、系统提示为你是一个聪明的助手请根据用户的提示来完成任务、roles[user, assistant]、sep\n### 、stop_str###的会话结构。5.3 配置字段的注入方式在 base.md 中可以看到在线 API 配置基类ApiConfigParams显式声明了星火相关字段APPID、APISecret以及worker_name等并允许extra allow兼容额外字段。其load_config(worker_name)与validate_config机制会调用get_model_worker_config配置合并逻辑见 utils.md把默认配置 在线模型配置 特定模型配置逐层合并后回填到参数对象。因此在 Langchain-Chatchat 中接入星火时只需在模型配置中声明 provider 与上述凭证字段XingHuoWorker.do_chat内的params.load_config(...)便会自动完成配置装载而无需手工逐项传参。六、接入注意事项与排障要点结合原文档的注意条目与整体调用链实际接入时建议重点检查以下几点凭证三件套齐全APPID、APIKey、APISecret缺一不可任一错误都会导致鉴权失败或连接被拒务必从讯飞开放平台后台获取勿硬编码进版本库。Spark_url与version匹配Spark_url决定host/path拆分结果version决定domain与url的选取两者不匹配会直接表现为握手失败或返回未知 domain。URL 即时使用签名内的时间戳基于当前时间URL 生成到发起连接之间不应有显著延迟否则会因时间窗过期鉴权失败。不要在日志中打印鉴权 URLURL 携带可推导凭证的信息调试时建议打码或仅打印 host 部分。异步环境约束request、do_chat均为异步生成器须在异步环境中await/ 异步迭代事件循环获取失败时需自行创建避免循环冲突do_chat与iter_over_async都体现了这一处理。参数边界temperature与max_tokens直接决定输出质量与长度须结合所选模型版本的实际取值范围设定服务端 max_tokens 上限由get_version_details统一收敛。七、小结从模块职责看Langchain-Chatchat 将鉴权与协议细节下沉到SparkApi将版本策略与业务封装上移到XingHuoWorker中间以request的 WebSocket 异步流作为桥梁形成了一条清晰的三层调用链SparkApi.Ws_Param.create_url()签名 URL→SparkApi.gen_params()协议请求体→request()连接与流式收发。理解这条链路的读者既能独立排查星火接入中的签名、参数与异步问题也能以此为模板为 Langchain-Chatchat 扩展其他 WebSocket 型在线模型工作器提供参考。进一步阅读SparkApi.md本篇主题文档含Ws_Param与gen_params的完整契约说明xinghuo.mdrequest与XingHuoWorker的实现细节、版本映射与输出示例base.mdApiConfigParams/ApiModelWorker基类设计说明 APPID、APISecret 等字段如何随配置注入utils.mdget_model_worker_config、iter_over_async等支撑工具【免费下载链接】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），仅供参考