Dagger TypeScript SDK 中 ClientLlmOpts 类型别解详解client.llm() 的选项对象及其底层实现【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/dagger本文围绕 Dagger 0.20 版 TypeScript SDK 自动生成 API 参考中的ClientLlmOpts类型别解展开逐一说明client.llm(opts)这一实验性 API 的全部选项model与maxAPICalls的语义、默认行为与版本门禁并结合引擎侧源码core/schema/llm.go与core/llm.go还原这两个参数在运行时的实际作用路径帮助读者在编写基于 LLM 的 Dagger 模块时正确、可控地使用该类型。一、ClientLlmOpts 是什么ClientLlmOpts是dagger.io/dagger包中api/client.gen模块下的一个类型别解Type Alias定义形式为ClientLlmOptsobject它本身不是一个独立的运行时对象而是Client类上llm()方法的可选参数opts形状。在 v0.20 的生成参考中见 Client 类文档llm()的签名为// 标记为 Experimental llm(opts?: ClientLlmOpts): LLM即调用client.llm(...)初始化一次大型语言模型LLM会话返回一个 LLM 对象用于排入提示词、暴露工具并逐步推进模型直到其结束当前轮次。ClientLlmOpts中所有属性均为optional因此llm()也可以不传任何参数直接调用。该类型在仓库中的参考文档为 ClientLlmOpts.md它与同目录下的ClientContainerOpts、ClientGitOpts等“ClientXxxOpts”类型属于同一族——每一个都对应Client上一个工厂方法的选项对象。二、属性逐一解析ClientLlmOpts只有两个可选属性两者共同决定了新 LLM 会话“用哪个模型”以及“最多允许多少轮 API 调用”。2.1model?: string— 指定要使用的模型model?: string Model to use该字段用于指定会话所针对的模型。从引擎侧实现core/schema/llm.go 中llm字段的参数定义看它有以下行为为空时的默认路由若不传model引擎会调用DefaultLLMRoute解析客户端环境中配置的默认模型与 provider并以解析出的模型“重新调用自身”与Container.from用消化后的引用自调用的方式一致。这样记录的 ID 会命名会话实际运行的模型使保存的会话恢复时仍然停留在自己的模型上而不是恢复到恢复环境恰好配置的默认模型参见 core/schema/llm.go 第 707–733 行附近的llm字段 resolver。模型别名在 core/llm.go 中resolveModelAlias支持把anthropic/claude、google/gemini、openai/gpt、meta/llama、mistral等别名解析为具体模型 ID对应各 provider 的默认模型常量如 Anthropic 的 Claude Sonnet 4.5、Google 的gemini-2.5-flash、OpenAI 的gpt-4.1定义于 core/llm.go 第 41–48 行。Codex 前缀路由以openai-codex/为前缀的模型名会被固定路由到 CodexChatGPT 订阅后端normalizeCodexModel会在需要时自动为该前缀补齐保证按名称匹配不到时也能正确路由。provider 推断与model配套地schema 层还接受一个provider参数如openai用于在模型名不符合已知命名模式例如微调模型时显式指定 provider该参数在 v1.0.0-0 之后视图才暴露见 core/schema/llm.go 第 27–29 行。因此对ClientLlmOpts.model而言传“具体模型 ID”“provider 别名”或留空三条路径都有明确的后端语义。2.2maxAPICalls?: number— 限制该 LLM 的 API 调用次数maxAPICalls?: number Cap the number of API calls for this LLM文档描述为“为该 LLM 封顶 API 调用数量”。结合引擎源码其真实作用机制值得展开schema 层maxAPICalls是一个仅对 v1 之前视图暴露的遗留参数。在 core/schema/llm.go 中dagql.Arg(maxAPICalls).Doc(Cap the number of API calls for this LLM). View(BeforeVersion(v1.0.0-0)),参数结构体中的注释进一步说明这是“对 API 调用的遗留封顶只暴露给 pre-v1 的模块视图v1 的调用方改为向loop()传maxSteps”。状态层参数解析后经由 core/llm.go 中的WithMaxAPICalls写入LLM状态// WithMaxAPICalls sets a default cap on the number of steps per loop, used // when loop() doesnt specify its own cap. Kept for the legacy // llm(maxAPICalls:) argument exposed to pre-v1 module views. func (llm *LLM) WithMaxAPICalls(calls int) *LLM { llm llm.Clone() llm.maxSteps calls return llm }注意内部字段名叫maxSteps这个“API 调用封顶”实际上约束的是评估循环中每轮的步数每一步对应一次向 provider 的 API 调用及随后的工具执行。循环层Loopcore/llm.go 第 2462 行起在每次迭代前检查steps maxSteps达到上限即返回reached step limit错误若调用方未显式给loop()的maxSteps传值则回退使用本字段设置的封顶if maxSteps 0 { // fall back to the legacy llm(maxAPICalls:) cap, if one was set maxSteps llm.maxSteps }所以对 v0.20 使用者而言maxAPICalls的实际价值是为 LLM 会话设定一个全局默认的安全阀防止工具调用循环失控地消耗 token 配额而在 v1 及以后的视图中应当改用loop({ maxSteps })做每次调用的显式封顶。三、版本门禁与适用前提阅读ClientLlmOpts时需要注意它的生命周期约束这直接决定代码能否在新版本视图中通过编译/内省llm()方法在 v0.20 参考文档中整体标记为Experimental说明该 API 尚处于实验阶段后续签名可能变化。maxAPICalls参数受View(BeforeVersion(v1.0.0-0))门禁保护即只在 v1 之前的模块视图中可见v1 视图中该选项会从内省 schema 中消失。从源码结构看这是 Dagger 版本门禁机制参见 version-gating 设计文档在 GraphQL 参数粒度上的典型应用同一个llm字段在不同引擎版本下暴露不同参数集合。与之对照provider、contextWindow、messages等字段则使用View(AfterVersion(v1.0.0-0))属于 v1 起暴露的新能力。因此编写面向 0.20 的 TypeScript 模块时可以放心使用这两个选项但若模块目标视图升级到 v1应迁移到loop()的maxSteps参数并改用 provider 相关的新 API 面。四、使用示例与关联 API 面基于生成参考中确认的签名llm(opts?: ClientLlmOpts): LLM返回的LLM继承BaseClient一个最小用法示意如下import { Context, dagger } from dagger.io/dagger; type MyOpts { prompt: string }; export async function summarize(ctx: Context, opts: MyOpts) { const client await dagger.query((c) c, {}); // ClientLlmOpts: 仅使用 model 字段不传 maxAPICalls 表示不设默认封顶 const llm client.llm({ model: anthropic }); return llm; // 继续调用 LLM 上的 prompt/step/loop 等方法推进会话 }要点model传别名如anthropic时由引擎解析为该 provider 的默认模型传具体模型 ID 则直接使用。传maxAPICalls后该值成为整个会话在loop()未显式封顶时的默认步数上限超限即报reached step limit。返回的LLM对象上可继续读取model()、provider()等字段在 v0.20 视图中可用确认会话最终落在哪个模型上。五、延伸阅读类型本体文档ClientLlmOpts.md方法宿主Client 类含 llm() 方法说明返回类型LLM 类构造函数与内部状态字段服务端实现core/schema/llm.gollm字段参数、版本门禁与默认路由、core/llm.go模型别名解析、WithMaxAPICalls、Loop步数封顶TypeScript SDK 源码目录sdk/typescript【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/dagger创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考