该内容为自助投放广告,真伪自辨
立即入驻

Koog Java 智能体如何配置多模型提供商:从统一执行器到模型选择

广告也精彩

一个 Java 项目最初只接一家模型服务时,代码通常很干净:一个客户端、一个密钥、一处调用。等到产品想拆分工序——摘要走便宜的模型、复杂推理走能力更强的模型,或者某个区域需要换成本地可用的服务商——麻烦就来了。密钥散在配置文件里,客户端在多个类里各自创建,调用点写死了模型名,每加一家都要把业务代码再翻一遍。Koog 把这个问题的解法拆成了两层:执行器决定“能连哪些提供商”,智能体构建阶段决定“这一次走哪个模型”。理解这两层,配置多模型就是一件有固定套路的事。

先分清两条路径:单提供商与多提供商

Koog 的官方文档给了一个很明确的分岔判断:如果只对接一家 LLM 提供商,直接用 LLM client 跑提示就够了;只有在需要对接多个提供商时,才应该用 prompt executor。这个区分值得在动手前想清楚,因为它决定了代码的初始形态。

单一提供商的路径胜在直接。少一层封装,参数传递、异常堆栈、调试断点都更贴近原始 SDK,排查问题时不用在中间层来回跳。代价是耦合发生在看不到的地方:业务代码里逐渐出现那家 SDK 的类型、那家特有的响应结构、那家的模型命名规则。

多提供商路径的代价是前期多写一段初始化,收益是变更被收进一个地方。新增一家提供商时,改动集中在执行器的注册逻辑,而不是散落到每个调用点。

两条路径共享的部分是提示本身。temperature、toolChoice、numberOfChoices、schema、maxTokens 这些参数作用于提示构建阶段,与“由谁来执行”是正交的两件事。也就是说,一条写好的提示换模型时通常不需要重写,这是后文谈切换成本的前提。其中 speculation 这类参数只被特定模型支持,跨提供商使用前需要先确认。

把多家模型接进同一个执行器

准备条件并不复杂。GitHub 上的 Koog 示例工程要求 Java 17+,并为每一个计划使用的提供商准备对应的 API Key——OpenAI 的键、Anthropic 的键,以及按需补充的其他提供商密钥。

密钥的存放方式值得照搬示例工程的做法:通过环境变量注入,例如 OPENAI_API_KEY、ANTHROPIC_API_KEY;或者在项目根目录放一个 env.properties 集中管理。这样切换环境时只换变量,代码和仓库里不留密钥。多提供商场景下这件事尤其重要,因为需要管理的密钥从一份变成了好几份,一旦有人图省事写进常量,后面很难清理干净。

接线的基本结构是:每个提供商各创建一个客户端,把这些客户端注册进同一个执行器,业务代码只面向执行器。

// 结构示意:具体类名与方法签名请以所用 Koog 版本的文档为准

// 1. 密钥从环境变量或 env.properties 读取,不写死在代码里
//    OPENAI_API_KEY / ANTHROPIC_API_KEY

// 2. 每个提供商各创建一个 LLM 客户端
var openAiClient    = createOpenAiClient();
var anthropicClient = createAnthropicClient();

// 3. 注册到同一个执行器:业务代码只依赖这一层
PromptExecutor executor = createExecutor(openAiClient, anthropicClient);

// 4. 构建提示,这一步与模型无关
Prompt prompt = Prompt.builder()
        .system("你是一个回答简洁的中文助手")
        .user("用三句话说明提示执行器的作用")
        .build();

// 5. 执行时再指定本次使用哪个模型标识
var response = executor.execute(prompt, "对应提供商的模型标识");

这段骨架里有三个点决定了后续是否好维护。客户端创建集中在初始化阶段,而不是散落各处;执行器是唯一暴露给业务层的入口,业务代码不应该出现具体提供商的类型;模型标识作为执行参数传入,而不是硬编码在提示内部。做到这三点,增删提供商就变成改一处初始化的事。

多个模型服务接入同一个提示执行器的结构示意

上面第 4 步和第 5 步分开写并不是形式主义。提示构建时用 schema 约束结构化返回、用 maxTokens 限制长度、用 temperature 调整随机性,这些都属于“任务要什么”;执行时传模型标识,属于“谁来干”。两者分开之后,同一套提示可以在不同提供商之间流转,切换时只需要改后面那个参数。

构建智能体时,模型在哪里指定

到了智能体构建阶段,需要明确的是两件事的组合:用哪个执行器,以及本次用哪个模型标识。前者在构建时就固定下来,决定这个智能体“能碰到的提供商范围”;后者决定了某一次调用实际落在哪家。

这种职责划分带来的一个实际好处是,你可以让同一个智能体在不同任务环节指向不同模型,而不需要维护两套智能体代码。文档和示例里提到的多模型设置,本质上就是这个用法:一个任务交给这家,另一个任务交给那家。

真正容易被忽略的是切换时的上下文处理。Koog 在切换 LLM 时会做历史适配,把之前的多轮对话消息转换为新模型可接受的形式。对需要中途换模型降本、或者在主模型失败时切到备用模型的场景,这一步不做的话,对话会突然“失忆”。所以如果你的智能体涉及多轮交互,切换模型后要专门验证一下上下文是否还在,而不是只看单次问答是否正常。

统一接入与单一提供商,维护差异到底在哪

把两种做法的差异摊开对照,比抽象地说“解耦更好”更有用:

维度 只接一家提供商 统一执行器接入多家
新增提供商的改动点 业务代码里多处适配 初始化注册处集中修改
密钥管理 一份,简单 多份,必须依赖环境变量或配置文件
故障切换 需要自己写降级逻辑 切换变成换一个执行参数
调试难度 堆栈贴近原始 SDK 多一层中间层,需熟悉执行器
初始成本 低 需要先搭好接线结构

表格右侧未必全优。中间层会让人在排查异常时多走一步,如果你的团队对那家 SDK 已经很熟,这层抽象反而可能挡住细节。左侧也未必就差,单模型、短期没有切换计划的项目直接上 LLM client 完全合理,硬套执行器只是给自己加负担。

判断标准其实很朴素:未来半年内是否真的可能加第二家。如果答案是“很可能”,前期多写一段初始化就是划算的,因为真正的成本不在第一次接入,而在第一次变更——变更时你要改的代码越集中,出错的概率越低。如果答案是“基本不会”,那就别为一个假想需求提前抽象。

调用链验证:不要只看代码写了什么

配置完成后,代码里写了什么并不重要,重要的是请求实际发给了谁。多提供商配置最常见的故障不是报错,而是静默走错路径——你以为切到了新模型,实际还在用旧的。

验证可以按这几步走:

  • 为每个提供商各挑一个该家能识别的模型标识,跑同一条最小提示,确认返回结果对应得上,而不是所有请求都返回同一种风格。

  • 临时移除某一家的密钥,重新跑一次该路径,确认它明确报错,而不是悄悄回退到另一家。这一条能暴露掉很多“默认值掩盖配置错误”的情况。

  • 如果是多轮对话,中途切换模型,检查之前几轮的内容是否还被记得,验证历史适配确实生效。

  • 用了结构化输出的场景,换模型后重跑一次,确认 schema 约束在新模型下依然被遵守。

从统一执行器到具体模型的调用链验证示意

这几步做完,你手里就有了一个可切换模型的 Java 智能体原型。往后要调整的地方只有两处:初始化阶段增加或移除客户端,调用阶段改那个模型标识参数。提示不用动,业务逻辑不用动,密钥不进代码库——这三条守住了,多模型配置就不会随着提供商数量增长而失控。

需要更细的接口细节时,可以去查 Koog 的提示文档(docs.koog.ai/prompts/prompt-creation)和示例工程(GitHub 上的 simple-examples),前者讲清了单提供商与多提供商的分工,后者给出了环境变量和工程结构的参考写法。

© 版权声明

相关文章

暂无评论

none
暂无评论...