LLM 适配器如何接入任意模型

约 20 分钟

说明 LLM 适配器在 dsh 中的角色,及其与模型提供方配置的关系。

上一课你刚为同一时钟能力写完两个 Provider,一条配置行就完成了 UTC 与本地时间实现之间的切换,而 Consumer 在注入接口后无需任何改动便拿到了新实现。 现在回到 Agent 循环:当它要调用模型时,请求是怎么发出去的?答案不是某个写死的模型客户端,而是 LLM 适配器。 把两件事连起来看,模式是一样的:提供方配置负责“选谁”,适配器负责“怎么接”——就像配置行决定挂载哪个 Provider,而接口决定调用方如何访问。 适配器是 dsh 架构里的一层接缝,站在 Agent 循环与具体模型端点之间。循环只通过这层接缝发出调用,不直接认识任何一家模型的协议。 同一个接缝,不同的适配器。谁的实现被挂上去,请求就按谁的协议发出去,正如哪个 Provider 被挂载,时钟就走哪套实现。

核心概念

LLM 适配器:模型端点的转换插头

生活类比:你的笔记本插头是三孔,某国的墙插是两孔。转换插头负责把插头形状翻译成墙插能接受的形状,笔记本本身不用改。换一个国家,只需换一个转换插头;插头标准变了,笔记本的用电方式没变。 技术定义:LLM 适配器就是 dsh 的转换插头。Agent 循环只认一套调用约定:把消息送进去,把响应取回来。每个模型端点却各有各的协议、返回格式,甚至各有各的凭据要求。适配器把两者翻译对齐,循环不必知道对面是哪个模型。 在 dsh 中,llm/llm 核心包掌管消息与流式词汇,并暴露适配器接缝;具体实现注册在共享上下文的 ctx.llm 上。适配器本身也是插件,与其他插件一样被挂载进 Cordis 树,由配置决定加载哪一个。 选择发生在启动与配置阶段,不在对话中途。运行中的 dsh 是一棵在启动时由有序配置层组合出来的插件树;要换模型,就改配置或换插件,再让 dsh 重新加载。 举个例子:DeepSeek 官方端点由默认适配器服务;公司网关如果暴露兼容端点,就作为自定义提供方接入,复用同一类适配器。适配器不关心模型内部结构,只关心端点说什么协议、要什么凭据。

模型提供方配置是选择器,适配器是执行者。你在配置里选定提供方与模型,dsh 就加载对应的适配器,并带着凭据去访问那个端点。插件树在启动时按有序配置层组合,提供方配置决定了树里挂上哪个适配器。 默认情况下,dsh 使用 DeepSeek 适配器,请求发往 DeepSeek 兼容 API,所以必须提供 API 凭据。你可以在首次引导时填入,也可以在 Settings → Models 里补配;选中某个已配置提供方的模型后,它就成为新会话的默认模型。 提供方决定适配器,模型名决定调用哪个模型。同一个提供方下的多个模型共用适配器,切换模型不切换接缝。同一个 dsh 实例里,不同会话也可以使用不同提供方的模型——配置不同,走的适配器就不同。 换个端点,就换配置。配置指向哪个适配器,请求就走哪条路;循环、工具与插件都感受不到差异。

适配器本身也是插件,所以它遵守你学过的插件规则:被挂载进 Cordis 树,注册成为 ctx.llm 接缝上的实现;插件卸载时,注册随之为效应而撤销。 官方架构文档明确写到:产品里每个部分都是插件,包括模型适配器、工具注册表、会话日志与 Agent 循环本身;没有特权核心需要打补丁。想换模型能力,挂一个新的适配器插件、通过配置替换旧的即可,不用改循环,也不用改工具。 这也意味着适配器受插件生命周期的约束:配置档案、补丁与重载规则对它同样生效,你在前面课程里掌握的注入与清理经验可以直接迁移。你还能通过配置替换存储、加一个工具、组装自定义模式,而不是重写运行时;模型接入是同一套规则的其中一环。

适配器接缝让 dsh 不被锁死在某一家的 API 上。只要端点兼容,自建网关或公司网关都可以作为自定义提供方接入。官方文档把模型提供方与 LLM 适配器分开讲解,并提供了 add an LLM adapter 的 cookbook;接新模型是常规扩展,而不是改内核。 请分清角色:模型负责推理,适配器不推理。响应由端点上的模型生成,适配器只负责翻译协议、携带凭据、把响应送回循环。费用也按你配置的 API 提供方计费,与本地插件无关。 dsh 本身不是模型,也不只是某个模型的专属客户端。模型换代、端点升级,只要协议兼容,适配器通常不用动。这延续了 dsh 的老规矩:一切皆插件,配置层即可自由组合,无需改动源码。 下一课你会亲手写一个适配器并接上云托管模型;那时你会看到,适配器和其他插件走同一条注册与挂载流程。

判断请求走哪个适配器,看模型提供方配置里的三样东西:端点、凭据、模型名。适配器根据它们把调用翻译给目标端点;你不需要记住每个端点的协议细节,只需要知道配置指向哪里。你也不需要理解每个端点的鉴权细节,凭据由提供方配置持有,适配器按配置携带。 给云托管模型接入时,这一课会反复用到:先确认网关端点兼容,再确认凭据能访问,最后确认模型名被端点接受。剩下的事交给适配器。

自检:选定模型提供方与模型之后,请求是怎么送到模型的?

配置选定后,dsh 在启动组合插件树时加载对应的 LLM 适配器——它是挂在 ctx.llm 接缝上的插件——由它把 Agent 循环的消息调用翻译成该端点的协议,并取回响应。换端点等于换配置或换适配器,循环本身不用改。

自检:本地 Web UI 出现,能说明模型在本机推理吗?

不能。本地 Web UI 只是控制面板。默认 DeepSeek 适配器把请求发往 DeepSeek 兼容 API,需要 API 凭据;推理在远端发生,并按 API 提供方计费。判断推理位置要看请求发往的端点,而不是界面。