智能体如何只改配置就切换模型供应商
教程用 openJiuwen Agent Core 将连接配置和推理参数拆分,让同一个摘要智能体分别使用 OpenAI 和 DeepSeek,也演示了如何在运行时通过别名选择供应商。三种方式共用工作流、提示词模板和输出结构。
AI 深度解读
在 openJiuwen Agent Core 的摘要示例里,从 OpenAI 的 gpt-4o 切到 DeepSeek 的 deepseek-chat,真正影响调用的改动只有四处。两次调用沿用同一套工作流、提示词和输出结构,作者报告两个模型都返回了有效 JSON,摘要措辞各有不同。
这套做法适合已经依赖模型输出的程序员参考。它把「怎么接入」和「怎么生成」拆开,让换供应商的代码改动集中在一处。至于换过去以后能否稳定交付同一种结果,还要靠每家供应商的实调来验证。
为什么换供应商只动两份配置?
ModelClientConfig 管连接,包括 client_provider、api_key、api_base、timeout、max_retries 和 verify_ssl。ModelRequestConfig 管单次请求,包括 model、temperature、top_p、max_tokens 和 stream。两份配置分别填进 LLMCompConfig 的 model_client_config 和 model_config,再交给 LLMComponent。
这个拆分给迁移划出了具体的改动范围。作者把共享代码放在 src/workflow_builder.py。build_llm_comp_config 把两份配置和提示词组装起来,build_workflow 串起 Start、LLMComponent 和 End,build_agent 再把整个流程包成 WorkflowAgent。工作流版本为 1.0,inputs_schema 用 ${query} 读取入口参数,用 ${start.query} 把文本传给模型节点,再用 ${llm.output} 把模型节点的输出交给 End,最终返回带 response 键的字典。add_connection 则负责指定执行顺序。
下面的差异展示了从 src/baseline_agent.py 切到 src/provider_swap.py 时,连接和推理配置各改了什么。
ModelClientConfig(
- client_provider="OpenAI",
- api_key=os.environ["OPENAI_API_KEY"],
- api_base=os.getenv("OPENAI_API_BASE", "https://api.openai.com/v1"),
+ client_provider="DeepSeek",
+ api_key=os.environ["DEEPSEEK_API_KEY"],
+ api_base=os.getenv("DEEPSEEK_API_BASE", "https://api.deepseek.com"),
timeout=60,
max_retries=3,
verify_ssl=True,
)
ModelRequestConfig(
- model="gpt-4o",
+ model="deepseek-chat",
temperature=0.7,
top_p=1.0,
max_tokens=1024,
stream=False,
)
先看 client_provider="DeepSeek" 那一行。原文示例能这么切,是因为 DeepSeek 提供 OpenAI 兼容 API,Agent Core 可以复用 OpenAI 客户端。换成第三家前,要先确认已安装版本支持什么 client_provider。名字不受支持时,构造 ModelClientConfig 就会报错,并列出可用选项。
配置能通过,为什么请求还是会报错?
这个版本的 ModelRequestConfig 会接受未声明的字段。到了请求阶段,OpenAI 客户端又会把这些字段当成关键字参数交给 OpenAI SDK。参数拼错,或者把供应商特有的请求字段放在顶层,构造配置时可能一切正常,真正调用才报 unexpected keyword argument。原文的写法是 extra_body={"frequency_penalty": 0},由 SDK 合并到 JSON 请求体里。把字段放进 extra_fields 也会遇到同类报错。
参数传过去了,下一关是输出。LLMComponent 设置 response_format={"type": "json"} 后,会解析模型回复,再按节点的 output_config 校验。JSON 无法解析、必填字段缺失或类型不符,都会中止这次工作流。原文说明,这类失败不会触发自动重试,也不会把原始字符串当成结果返回。连接配置里的 max_retries=3 和这里的输出校验是两回事。
作者在示例中观察到,两家用相同输入都返回了带 response 的有效 JSON,措辞不同。如果下游还要从 response 里提取固定内容,单看这个键是否存在就不够了。文章也没有给出多样本的格式通过率,无法据此判断哪家更稳定。
运行时切换,其实就是按别名选工厂
src/multi_model.py 用一个普通字典 _PROVIDER_FACTORIES 管理 openai 和 deepseek。下面这段代码把别名查找、配置构造和工作流装配接到了一起。
_PROVIDER_FACTORIES = {
"openai": _make_openai_configs,
"deepseek": _make_deepseek_configs,
}
_DEFAULT_PROVIDER: ProviderAlias = "openai"
def get_agent(alias: ProviderAlias = _DEFAULT_PROVIDER) -> WorkflowAgent:
if alias not in _PROVIDER_FACTORIES:
raise ValueError(f"Unknown provider alias '{alias}'. "
f"Available: {list(_PROVIDER_FACTORIES)}")
client_config, request_config = _PROVIDER_FACTORIES[alias]()
flow = build_workflow(
client_config,
request_config,
workflow_id=f"summarise_{alias}_multi",
)
return build_agent(
agent_id=f"summarise_agent_{alias}_multi",
description=f"Summarisation agent — {alias} provider (multi-model config)",
flow=flow,
)
要看的是 flow = build_workflow( 这一行。每次 get_agent(alias) 都会新建工作流和 Agent,所以作者建议每个别名构造一次再复用。调用侧可以用 get_agent("deepseek") 取实例,然后把 {"query": query} 交给 Runner.run_agent。新增第三家时,要补配置工厂、字典条目和 ProviderAlias 类型。工厂构造时就会读取对应密钥,缺失会直接抛 KeyError。
示例还有一条容易误判的日志。build_workflow 先向 Runner 注册工作流,WorkflowAgent.add_workflows 又注册一次,于是出现 ERROR ... add resource failed ... resource already exist。作者的运行随后打印了 Successfully added workflow instance,并正常返回了结果。排查时可以用后续日志和实际返回值确认是不是这条已知的重复注册路径。
本地绿灯和真实调用各证明什么?
原文要求 Python 3.11、3.12 或 3.13,配套仓库用 3.12 开发。用 python -m venv .venv 建环境,执行 source .venv/bin/activate 激活,Windows 则用 .venv\Scripts\activate,再运行 pip install -r requirements.txt。依赖文件固定 workswarm==0.2.7 并列出 pytest,由 workswarm 带入 openjiuwen 0.1.19,示例脚本直接从 openjiuwen 导入。
在仓库根目录,python -m src.baseline_agent 需要 OPENAI_API_KEY,python -m src.provider_swap 需要 DEEPSEEK_API_KEY。python -m src.multi_model 和依次跑三个场景的 python -m src.main 都需要两把密钥。src.main 会逐场检查,缺 DeepSeek 密钥时会在第一个场景跑完后停下。OPENAI_API_BASE 和 DEEPSEEK_API_BASE 可选,默认地址见上面的代码。脚本不会主动加载 .env,已有该文件时可依次运行 set -a、source .env、set +a,把变量导入当前 shell 环境。
作者给出的 pytest -v 结果是 11 passed。这些冒烟测试无需密钥,覆盖导入路径、配置参数名、extra_body 和 generate_workflow_key 等。仓库的 .github/workflows/verify.yml 在每次推送时执行同一命令。升级后可以先用它发现接口变动,连接、鉴权和真实输出则需要用密钥实调。
我的判断
这个示例最有说服力的是改动边界。对只需要在 Python 服务里切换兼容端点的团队,两份配置加一个工厂表,就能把供应商差异集中到模型入口。如果前端、Node 服务和其他调用方还需要共用一个对外端点,HTTP 网关则能让这些调用方共享同一个入口。文章没有比较两者的延迟、维护成本或故障率,省掉额外服务是示例的部署取舍,成本收益仍是经验判断。
作者实际展示的是两个模型成功完成同一个单句摘要任务。按成本路由、按租户指定供应商、失败后切换别名,都是基于工厂表提出的扩展思路。文章没有展示价格对照、租户隔离验证或回退测试。尤其当租户只能走指定供应商时,允许尝试的别名范围得由应用明确决定。
能拿来做什么
- 如果前端通过后端接口消费
response,切换供应商前拿同一批代表性输入跑两家,同时检查 JSON 字段、摘要是否符合要求,以及页面能否直接展示。 - 给已有的 Python Agent 加第二家供应商时,可以先把连接配置和生成参数集中到工厂,再让入口通过别名取已构建的实例。定位缺密钥、别名无效和供应商调用失败时,分别记录对应错误。
- 升级
openjiuwen时,先用pytest -v检查导入和构造参数,再用真实密钥跑python -m src.main,把每家供应商的返回结果和结构校验一起纳入验收。