Langchain-Chatchat 百度千帆（QianFan）接入指南：QianFanWorker 的鉴权、流式对话与文本向量化实现解析-CSDN博客

Langchain-Chatchat 百度千帆（QianFan）接入指南：QianFanWorker 的鉴权、流式对话与文本向量化实现解析

【免费下载链接】Langchain-Chatchat Langchain-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 历史 model_workers 架构中与百度千帆（ERNIE-Bot / 千帆 API）对接的核心实现，逐段解析 QianFanWorker 工作器与 get_baidu_access_token 鉴权函数的设计细节、请求流程与注意事项。读完本文，你将理解该架构下"在线 API 工作器"是如何封装 AK/SK 鉴权、流式聊天与分批向量化的，也能据此写出自己的自定义模型工作器，或理解模型平台（MODEL_PLATFORMS）方式下百度系列模型的配置路径。

说明：本文所剖析的内容记录于仓库文档 qianfan.md，隶属于 Langchain-Chatchat 演进过程中的 model_workers（FastChat Worker）一套在线模型接入框架。在该框架中，同一目录下的 base.md、azure.md、qwen.md 等分别记录了参数基类与各家厂商的 Worker 实现，可作为横向对照。

一、背景：千帆接入在项目中的两种形态

百度千帆（Baidu Qianfan / ERNIE-Bot 系列）是国内常用的云端大模型之一。Langchain-Chatchat 仓库中可以找到两条接入线索：

历史 model_workers 形态（本文主体）：以 QianFanWorker 类为代表，遵循 ApiModelWorker 的统一接口（do_chat / do_embeddings / make_conv_template），由该架构对应的入口（如 api_allinone_stale.py、webui_allinone_stale.py，均以 _stale 后缀保留）加载并对外提供兼容 Chat 的接口。
当前 MODEL_PLATFORMS 形态（印证千帆模型仍受支持）：在 settings.py 的 MODEL_PLATFORMS 示例中，oneapi 平台下的 llm_models 包含 ERNIE-Bot、ERNIE-Bot-turbo、ERNIE-Bot-4，embed_models 包含 Embedding-V1，注释明确标注"千帆 API"。这说明无论走哪条架构，ERNIE 系列模型在项目内始终是被支持的云端模型选项。

本文按文档主线，重点把 QianFanWorker 这套 Worker 实现的鉴权与调用细节讲透。

二、核心鉴权函数：`get_baidu_access_token(api_key, secret_key)`

百度开放平台使用 OAuth 2.0 的客户端凭证模式发放访问令牌。QianFanWorker 及向量化流程都需要先拿到 Access Token 才能调用模型接口，而负责这件事的就是独立的工具函数 get_baidu_access_token。

签名与参数

参数	类型	含义
`api_key`	str	百度智能云千帆应用的 API Key（即 AK）
`secret_key`	str	千帆应用的 Secret Key（即 SK）

内部流程（据文档描述还原）

定义一个指向百度 OAuth 2.0 token 获取接口的 URL；
构造参数字典，包含 grant_type（固定为客户端凭证模式）、client_id（即 api_key）、client_secret（即 secret_key）；
调用 get_httpx_client 获得 httpx 客户端实例，携带上述参数向该接口发起 GET 请求；
解析响应 JSON，取出 access_token 字段并返回。

关键依赖 get_httpx_client

文档明确指出该函数依赖 get_httpx_client 来创建 HTTP 客户端。在仓库中，该工具位于 server/utils.py，实现要点包括：

支持 use_async=False/True 返回同步或异步 httpx 客户端；
可传入 proxies（字符串或字典）与 unused_proxies 列表，自动为代理绕过本地 127.0.0.1、localhost 等地址；
默认超时取自 Settings.basic_settings.HTTPX_DEFAULT_TIMEOUT，其默认值为 300 秒（见 settings.py），可通过配置文件中的 HTTPX_DEFAULT_TIMEOUT 调整。

示例性伪代码（逻辑对应文档描述）

def get_baidu_access_token(api_key: str, secret_key: str):
    # 指向百度 OAuth 2.0 Token 接口
    token_url = ".../oauth/2.0/token"
    params = {
        "grant_type": "client_credentials",
        "client_id": api_key,
        "client_secret": secret_key,
    }
    try:
        with get_httpx_client() as client:
            resp = client.get(token_url, params=params)
            return resp.json().get("access_token")
    except Exception as e:
        print(e)
        return None

输出示例与失败行为

成功时返回形如 "24.abcdefghijk1234567890" 的 Access Token 字符串；失败时（密钥无效、网络异常、接口报错等）不返回值，仅在控制台打印错误信息。因此上游调用方必须对返回 None 的情况做兜底处理。

使用注意

AK/SK 必须有效且拥有千帆服务权限，否则无法换取 Token；
Access Token 是计费与限流的关键凭证，应妥善管理并尽量缓存复用，避免高频重复请求造成不必要的配额消耗；
若项目要求经代理访问，请通过 get_httpx_client 的代理参数统一配置，以复用其本地地址自动绕过逻辑。

三、`QianFanWorker` 类总览

QianFanWorker 是文档记载的"与百度千帆 API 交互的工作器"，继承自 ApiModelWorker（该基类与参数体系在 base.md 中有系统描述），通过重写父类方法实现了千帆聊天与文本向量化两大能力。

类级属性与默认值

属性	默认值	含义
`DEFAULT_EMBED_MODEL`	`"embedding-v1"`	千帆默认文本嵌入模型
`version`	`"ernie-bot"`	模型版本，支持 `ernie-bot`、`ernie-bot-turbo`
`model_names`	`["qianfan-api"]`	注册的模型名称列表
`controller_addr`	—	控制器地址，用于与模型控制器通信
`worker_addr`	—	工作器地址，用于收发模型处理请求

核心方法清单

方法	类型	作用
`__init__`	构造器	完成版本、模型名、地址等参数装配
`do_chat`	核心	以流式方式调用千帆聊天模型并产出回复
`do_embeddings`	核心	分批调用千帆嵌入模型将文本转成向量
`get_embeddings`	桩	打印调试信息，供后续扩展
`make_conv_template`	桩/模板	生成对话模板 `conv.Conversation`

从整体看，这套设计把"厂商差异"收敛在 Worker 内部：对外统一暴露 do_chat / do_embeddings 语义，内部则各自拼 URL、构造 payload、解析厂商专有响应字段（例如千帆的 result 与 error_code）。

3.1 构造函数 `init`

参数

参数	类型	默认值	说明
`version`	str	`"ernie-bot"`	模型版本，可选 `ernie-bot` / `ernie-bot-turbo`
`model_names`	list[str]	`["qianfan-api"]`	该 Worker 负责的模型名集合
`controller_addr`	str	可选	FastChat 控制器地址
`worker_addr`	str	可选	本工作器对外地址
`**kwargs`	dict	—	透传给父类 `ApiModelWorker.__init__` 的附加参数

初始化逻辑要点

将 model_names、controller_addr、worker_addr 通过 kwargs.update() 并入关键字参数，统一交给父类构造；
通过 kwargs.setdefault("context_len", 16384) 设置默认上下文长度为 16384（若调用方已显式传入则保持不变）；
调用父类 __init__ 完成框架侧初始化，再把 version 存入 self.version 供后续请求拼装使用。

使用注意

version 必须取支持值，因为它直接决定聊天接口按哪个模型版本调用；
model_names 支持同时注册多个名字，使同一 Worker 能对应多个别名模型；
**kwargs 提供了扩展弹性，但传入项必须是父类支持的参数。

3.2 聊天实现 `do_chat(params)`

do_chat 是整条对话链路的核心，职责是"把一次用户请求转发给百度千帆聊天接口，并把流式返回的文本逐段产出"。

入参类型：ApiChatParams。该参数类继承自 ApiModelParams（基类字段含 api_base_url、api_key、secret_key、temperature、max_tokens、top_p 等），并补充 messages（消息列表）、system_message、role_meta 等字段，详见 base.md。

执行流程（据文档描述还原）

调用 load_config() 按当前模型名加载配置（该机制会把外部配置中缺失的字段自动补全，属于 ApiConfigParams 家族的标准能力）；
依据模型 version 与上一步获取的 Access Token 拼接聊天接口 URL；
调用 get_baidu_access_token(api_key, secret_key)；若获取失败（返回空），直接返回错误信息，不再发起后续请求；
构造 payload：包含聊天消息、温度参数（temperature）、流式响应标志（stream）等；设置请求头；
通过 get_httpx_client 得到客户端，向聊天接口发起流式 POST 请求；
遍历响应体每一行，逐行解析 JSON：
- 若含 result 字段 → 将其文本累加到 text，产出 {"error_code": 0, "text": 累加文本} 字典；
- 若响应含错误信息 → 构造含错误详情的字典并记录错误日志，同时作为生成器输出。

返回值语义：本方法是生成器，调用方需遍历以取回所有流式消息块；每个产出项都带 error_code，调用方应逐项检查以判断成功与否。

输出示例（成功）

{
  "error_code": 0,
  "text": "这是由百度千帆模型生成的回复文本。"
}

使用注意

使用前务必在 ApiChatParams 中正确填写 AK/SK；
由于是流式长连接，耗时会受网络与模型推理速度影响，应配合 HTTPX_DEFAULT_TIMEOUT 的合理取值；
result 采用逐段累加，长回复会持续累积文本，调用方要处理好大文本场景；
错误项需要被调用方识别并转为用户可读的失败提示，而不是静默吞掉。

3.3 向量化实现 `do_embeddings(params)`

do_embeddings 负责把一批文本通过千帆嵌入模型转成向量，是知识库向量化场景（例如把文档切片灌入向量库前）会用到的能力。

入参类型：ApiEmbeddingsParams。该参数类在 base.md 中有描述，承载文本列表 texts、嵌入模型标识等字段。

执行流程（据文档描述还原）

调用 params.load_config(...) 加载模型配置，保证按正确模型名执行；
确定嵌入模型：取 params.embed_model，若未指定则回落为类属性 DEFAULT_EMBED_MODEL（embedding-v1）；
用 AK/SK 换取 Access Token；
拼接携带"嵌入模型标识 + Access Token"的请求 URL；
用 get_httpx_client 取得客户端，将文本按每批 10 条切分，对每批发起 POST；
解析响应：
- 含 error_code → 判定出错，构造错误信息返回；
- 成功 → 从响应中提取嵌入向量并累积到结果列表。

成功输出示例

{
  "code": 200,
  "data": [
    [0.1, 0.2, 0.3, ...],
    [0.4, 0.5, 0.6, ...]
  ]
}

失败输出示例

{
  "code": 错误码,
  "msg": "错误信息",
  "error": {
    "message": "具体错误信息",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}

使用注意

AK/SK 必须有效，且需开通千帆向量化相关权限；
params.texts 不应为空，单个文本长度需符合百度接口要求；
分批大小为 10，大批量文本会发起多次请求，整体耗时受网络与接口响应影响，建议在调用方侧做好超时与重试策略；
内置错误处理可在 API 出错时返回结构化错误而非直接抛异常，调用方应优先检查 error_code / code 字段。

3.4 桩方法：`get_embeddings` 与 `make_conv_template`

文档明确提示这两个方法目前属于占位 / 待完善性质，阅读源码文档时需要把预期放低：

get_embeddings(params)：当前实现仅打印 "embedding" 字样与传入的 params，用于测试或演示，并未真正产出向量。实际嵌入能力由 do_embeddings 承载；若项目需要"按参数直接取向量"的入口，需要在此方法基础上按需扩展。
make_conv_template(conv_template, model_path)：用于创建对话模板，返回一个 conv.Conversation 对象。conv_template 与 model_path 两个入参在当前实现中未被直接使用（更像是为后续扩展预留的接口）。模板的关键内容固定为：

字段	值
`name`	`self.model_names[0]`（模型名列表首项）
`system_message`	`"你是一个聪明的助手，请根据用户的提示来完成任务"`
`messages`	`[]`（初始为空）
`roles`	`["user", "assistant"]`
`sep`	`"\n### "`
`stop_str`	`"###"`

返回对象示意

Conversation(
    name="qianfan-api",
    system_message="你是一个聪明的助手，请根据用户的提示来完成任务",
    messages=[],
    roles=["user", "assistant"],
    sep="\n### ",
    stop_str="###",
)

该模板的作用是定义模型对话时的系统提示、角色划分、消息分隔符与停止符，让上层对话链路能够按统一格式组织多轮上下文。

四、结合仓库框架加深理解：参数基类与统一超时

把 QianFanWorker 放回框架中看，会更容易理解它为什么长这样：

统一参数模型：ApiConfigParams →（派生）ApiModelParams →（派生）ApiChatParams / ApiEmbeddingsParams。它们支持从模型配置文件"自动补全未显式提供的字段"（通过 root validator 与 load_config），因此 Worker 方法内部只认字段名、不关心值从哪来。这也是 do_chat / do_embeddings 开头都要先 load_config 的原因——确保运行时配置（含 AK/SK、temperature 等）是最新且完整的。
统一 HTTP 客户端：get_httpx_client（server/utils.py）承担代理、超时与异步/同步的选择；QianFanWorker 的所有外部请求都经由它发出，避免各厂商代码各自重复实现网络层。
统一超时配置：默认请求超时来自 HTTPX_DEFAULT_TIMEOUT（默认 300 秒），该配置项支持运行时即时生效，适合在访问耗时较长的千帆模型时调大。

五、从这套 Worker 迁移到当前模型平台形态的提示

如果读者是在较新版本的 Langchain-Chatchat 上接入千帆模型，需要注意架构差异：

QianFanWorker 及其文档记录的鉴权/分批/流式逻辑属于 model_workers 架构，其相关入口文件以 _stale 后缀（如 api_allinone_stale.py、webui_allinone_stale.py）保留，说明该套接法在项目演进中已逐步让位于以 MODEL_PLATFORMS / OpenAI 兼容网关为核心的新形态。
新形态下，可通过在模型平台配置中声明 oneapi（或其他兼容网关）并填入千帆模型名来使用 ERNIE 系列模型（settings.py 中 ERNIE-Bot、ERNIE-Bot-turbo、ERNIE-Bot-4、Embedding-V1 即为现成示例），由网关统一处理 AK/SK 与 OpenAI 兼容协议的转换。
即便如此，理解 QianFanWorker 依然有价值：它清晰展示了"AK/SK 换 Token → 按版本拼 URL → 统一 httpx 客户端 → 流式/分批解析厂商字段"这套对接任何云端大模型的通用心智模型。若要为某个不支持 OpenAI 协议、又无网关的厂商写自定义接入，完全可以以本文剖析的这套结构为蓝本。

六、小结与踩坑清单

关注点	建议
Token 获取	务必检查 `get_baidu_access_token` 是否返回空，失败即中止后续调用；Token 建议缓存复用
版本参数	`version` 仅支持文档所列值，拼装 URL 依赖它，别传任意模型名
流式响应	`do_chat` 是生成器，需遍历消费并逐项检查 `error_code`
向量分批	`do_embeddings` 每批 10 条，文本量大时留意整体耗时与超时配置
占位方法	`get_embeddings` / `make_conv_template` 仅打印/生成模板，勿假设前者已产出向量
配置加载	所有请求前先 `load_config`，保证 AK/SK、temperature 等运行时配置是最新的
新老架构	新版本优先走 `MODEL_PLATFORMS` + 网关；`model_workers` 侧重理解原理

结合 qianfan.md 原文档、base.md 参数基类说明以及 server/utils.py 的 httpx 客户端实现，开发者可以完整复现"百度千帆 Worker"的鉴权—聊天—向量化闭环，并将其推广到任何云端大模型的接入工作中。

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

Langchain-Chatchat 百度千帆（QianFan）接入指南：QianFanWorker 的鉴权、流式对话与文本向量化实现解析