Pydantic AI ModelSettings 全解跨提供商 LLM 请求参数、Tool Choice 与设置合并机制【免费下载链接】pydantic-aiHow Python does AI. Agents, realtime voice, image generation, embeddings. Every model, every interface, typed end to end.项目地址: https://gitcode.com/GitHub_Trending/py/pydantic-ai本文以 Pydantic AI 的pydantic_ai.settings模块为核心系统讲解ModelSettings提供的全部跨提供商请求参数采样、超时、思考、服务层级、工具选择等、ToolChoice/ToolOrOutput的取值语义、ThinkingLevel与ServiceTier统一类型别名以及merge_model_settings在 Agent、Run 与 Capability 之间的合并规则帮助你在任何模型提供商下用一套类型安全的方式控制 LLM 行为。一、pydantic_ai.settings模块总览pydantic_ai.settings的 API 参考页见 docs/api/settings.md它通过 mkdocs-autorefs 渲染源码中pydantic_ai.settings模块的四个公开成员成员类型职责ModelSettingsTypedDict(totalFalse)跨提供商通用的 LLM 请求参数集合ToolChoiceTypeAliastool_choice字段的全部合法取值ToolOrOutputdataclass限定函数工具但保留结构化输出/文本/图片输出的复合取值ServiceTierTypeAlias跨提供商的统一服务层级取值集模块实现位于 pydantic_ai_slim/pydantic_ai/settings.py仅 500 余行是 Pydantic AI 中一次声明、全提供商生效这一设计的关键枢纽。它的设计约束在ModelSettings的类文档中写得很明确只收录跨多个模型/提供商通用的设置——并非每个字段都被所有模型支持每个字段的Supported by:列表标注了哪些模型类会真正把这个字段放上线即序列化进请求体。裸名字如OpenAI覆盖该模型提供的全部接口OpenAIChatModel与OpenAIResponsesModel带接口的名字如OpenAI Chat Completions只覆盖单一接口列表在发送意义上有效不代表服务商一定采纳OpenAI 兼容类模型会把 OpenAI schema 接受的东西原样转发背后的具体提供商可能忽略或拒绝自己 API 未定义的字段所有类型必须可用 Pydantic 序列化。二、ModelSettings跨提供商通用参数详解ModelSettings是一个totalFalse的TypedDict意味着所有字段可选、按需传入未设置的字段不会进入请求。以下逐字段说明其语义与支持范围。2.1 采样与生成控制字段类型说明max_tokensint停止生成前的最大 token 数。OpenAI、Anthropic、Google、Groq、Cohere、Mistral、Bedrock、MCP Sampling、xAI、HuggingFace、Cerebras、Crusoe、GitHub Copilot、Ollama、OpenRouter、Snowflake、Z.AI、Bedrock Mantle 支持temperaturefloat注入的随机程度。接近0.0适合分析/选择题接近模型上限适合生成式任务注意即使为0.0结果也不完全确定。多数提供商支持GitHub Copilot 对拒绝采样参数的 Anthropic 模型如claude-opus-4.8不发送top_pfloat核采样只考虑概率质量前top_p的 token0.1表示只考虑前 10% 概率质量。官方建议temperature与top_p二选一调整不要同时改top_kint每个后续 token 只从 top K 选项中采样用于剔除长尾低概率响应。仅 Anthropic、Google、Cohere、Bedrock仅 Anthropic 与 Amazon Nova 模型支持seedint随机种子理论上可得到确定性结果。支持列表限定在 Chat Completions 系接口OpenAI Chat Completions、Google、Groq、Cohere、Mistral、xAI 等注意 Responses 接口不在其列presence_penaltyfloat按 token 是否已出现惩罚新 tokenfrequency_penaltyfloat按 token 已有出现频率惩罚新 tokenlogit_biasdict[str, int]修改指定 token 出现在补全中的概率。注意 Anthropic、Cohere、Bedrock、OpenRouter 之外并不普遍支持Ollama 会发送但文档标注logit_bias不受支持stop_sequenceslist[str]触发停止生成的序列。支持范围最广的字段之一含 MCP Samplingstop_sequences的端到端行为有真实集成测试佐证tests/test_settings.py 中test_stop_settings在 openai、anthropic、bedrock、mistral、groq、cohere、google 七个模型上用 VCR cassette 回放验证回答包含 Paris 但不以 Paris 开头并特别标注 Bedrock 的行为差异——它会把停止序列包含在响应里result.output.endswith(Paris)其余提供商则是停止序列不包含在输出中。这是使用该字段时值得记住的边界行为。2.2 超时、并行工具调用与请求扩展字段类型说明timeoutint \| float \| Timeout以秒为单位覆盖客户端级默认超时。数字秒数全平台可用同时接受遗留的httpx.Timeout在 SDK 期望httpx2.Timeout的路径上自动转换Google 与 Mistral 只接受数字秒数parallel_tool_callsbool是否允许并行工具调用。OpenAI部分模型o1 不行、OpenAI Codex、Anthropic、Groq、Mistral、xAI、Cerebras、Crusoe、GitHub Copilot、Ollama、OpenRouter、Snowflake、Z.AI、Bedrock Mantle 支持extra_headersdict[str, str]发送到模型请求的额外 HTTP 头extra_bodyobject追加到请求体中的额外字段用于传递 Pydantic AI 尚未封装的提供商能力。注意在 Cerebras、OpenRouter、Snowflake、Z.AI 这些自行构造extra_body的 OpenAI 衍生模型上模型自有的派生键在键冲突时覆盖你的键timeout的类型定义本身就体现了对依赖可选性的处理从源码结构看settings.py 中当 legacyhttpx未安装时Timeout别名坍缩为float使联合类型退化为纯数字——这保证了未安装 httpx 的环境中ModelSettings依然可用。2.3 thinking统一的思考/推理开关thinking字段的类型是ThinkingLevelThinkingEffort: TypeAlias Literal[minimal, low, medium, high, xhigh] ThinkingLevel: TypeAlias bool | ThinkingEffort取值语义见 settings.py 的文档字符串True以提供商默认强度启用思考False关闭思考对始终开启思考的模型会被静默忽略minimal/low/medium/high/xhigh以指定强度启用思考。不是所有提供商都支持所有档位。当某个档位不被原生支持时会映射到最接近的可用值例如不支持xhigh的提供商会落到high没有 minimal 档的提供商会把minimal映射为low。各模型类的具体落线方式差异很大源码文档逐条列出Cerebras 只转发False映射为reasoning_effortnone因其模型默认推理且gpt-oss连关闭也会忽略OpenRouter 与 SnowflakeClaude 模型以extra_body[reasoning]承载Z.AI 以extra_body[thinking]承载GitHub Copilot 以reasoning_effort发送且不支持的值会收到400 invalid_reasoning_effortBedrock Mantle 仅 Responses 接口发送。另外提供商专属思考字段如anthropic_thinking、openai_reasoning_effort优先于这个统一字段。2.4 service_tier统一服务层级与提供商映射ServiceTier是一个四值类型别名auto | default | flex | priority语义见 settings.pyauto交给提供商决定——通常意味着可用时走高优先级/扩容额度层否则走标准层。对服务端没有 auto 概念的提供商会省略该字段让其默认值生效default显式请求标准层退出服务端可能有的自动升级到高级层的行为flex更低成本、延迟容忍型层级提供商提供时不支持的提供商如 Anthropic静默忽略也有个别提供商会直接拒绝该字段priority更高优先级/更低延迟层级提供商提供时不支持的提供商静默忽略。跨提供商映射表源码文档原表取值OpenAIAnthropicBedrockGoogle (Gemini API)Google Cloudautoautoauto(省略)(省略)无请求头PT 优先其后 on-demanddefaultdefaultstandard_only{type: default}standard无请求头PT 优先其后 on-demandflexflex(省略){type: flex}flex请求头Shared-Request-Type: flexPT 优先其后 Flex PayGoprioritypriority(省略){type: priority}priority请求头Shared-Request-Type: priorityPT 优先其后 Priority PayGo两个值得注意的实现细节一是在 Google Cloud 上统一字段只映射到安全的 PT预留吞吐溢出变体以让有 Provisioned Throughput 的账号优先消耗预留容量若要完全绕过 PT需用提供商专属字段google_cloud_service_tier传flex_only或priority_only。二是 Bedrock 的reserved、Anthropic 的standard_only、Google Cloud 的 PT 路由档位等不在统一取值集内的值只能通过提供商专属字段到达而所有提供商专属字段openai_service_tier、anthropic_service_tier、bedrock_service_tier、google_cloud_service_tier一旦设置一律优先于统一字段service_tier。2.5 tool_choice工具选择控制tool_choice的类型是ToolChoice这是本模块中最复杂的一个联合类型ToolChoiceScalar Literal[none, required, auto] dataclass class ToolOrOutput: function_tools: list[str] # 模型可用的函数工具名列表 ToolChoice ToolChoiceScalar | list[str] | ToolOrOutput | None各取值的语义见 settings.py 文档None默认等价auto行为auto所有工具可用由模型自行决定是否调用none禁用函数工具模型只以文本响应输出工具保留结构化输出不受影响required强制使用工具排除输出工具因此静态设置时 Agent 无法产生最终响应list[str]只允许指定工具同样排除输出工具ToolOrOutput指定函数工具子集同时保留输出工具/文本/图片输出——这是限制函数工具但不阻断 Agent 收尾的正确方式。关键约束静态required或list[str]会抛UserError。源码文档明确说明通过Agent.run的model_settings参数或 Agent 自身的model_settings静态设置这两种取值时由于会在每一步强制工具调用、阻止 Agent 产生最终响应Pydantic AI 会直接抛出UserError。如需按步变化tool_choice例如只在第一步强制某工具正确路径是让 Capability 的get_model_settings返回可调用对象——这些值被视为跨步骤自适应而受信任见 capabilities/combined.py 中对get_model_settings返回值的解析。若只是单次 API 调用而不需要 Agent 循环用pydantic_ai.direct.model_request。各提供商对tool_choice的处理方式差异也在文档中注明Cohere 与 Mistral 对命名子集是通过过滤工具列表实现的而非作为参数发送Anthropic 在启用 thinking 时不支持required与指定工具Ollama 会发送但文档标注不受支持。三、merge_model_settingsAgent、Run 与 Capability 的设置合并模块末尾的merge_model_settings是所有设置最终生效的汇聚点settings.pydef merge_model_settings(base: ModelSettings | None, overrides: ModelSettings | None) - ModelSettings | None: Merge two sets of model settings, preferring the overrides. A common use case is: merge_model_settings(agent settings, run settings) if base and overrides: return base | overrides else: return base or overrides实现极简单两个字典的浅合并|运算符键冲突时overrides胜出任一为None时返回另一个。源码注释还留了一个演进注记——如果将来加入非原始值可能需要递归合并从源码结构看当前所有字段均为扁平原始值浅合并语义恰好够用。它在代码库中的调用点勾勒出完整的优先级链Agent 层agent/init.py 中 Agent 级model_settings作为 baseagent/init.py 中先并入 Agent 设置、再并入本次run()传入的model_settings——即Run 参数 Agent 参数Capability 层capabilities/combined.py 在每步执行时把各 Capabilityget_model_settings解析出的设置再次并入ctx.model_settings能力返回的可调用对象在此被调用并解析模型层各模型实现如 models/openai.py、models/anthropic.py、models/bedrock.py在构造请求前把实例级self.settings与本次请求的model_settings再合并一次请求参数 模型实例参数。合并语义有专门的单元测试覆盖tests/test_settings.py 的TestMergeModelSettingsThinking与TestMergeModelSettingsServiceTier验证了thinking布尔/强度档的覆盖、无关字段max_tokens、temperature在合并中保留、以及None边界的三种组合base 为 None、overrides 为 None、双 None 返回 None。四、提供商专属设置前缀命名的扩展体系ModelSettings只覆盖通用参数。各提供商自己的参数如anthropic_thinking、openai_reasoning_effort定义在各自模型模块中以提供商名作前缀的ModelSettings子类中。tests/test_settings.py 通过动态发现机制强制执行这一命名纪律_discover_model_settings()遍历pydantic_ai.models包下所有子模块用__orig_bases__找出每个ModelSettings子类因为TypedDict子类的__bases__只报告dict真实继承链要取__orig_bases__然后断言所有不属于全局ModelSettings的字段名必须以{模块名}_开头mcp_sampling是例外用mcp_前缀因为它是 MCP sampling 伪模型而非真正的提供商集成。test_model_settings_discovery还设置了模块遍历数量的腐烂守卫防止包结构变动导致前缀检查静默失效。五、实战组合使用这些设置把上述能力组合起来典型的 Agent 配置如下from pydantic_ai import Agent from pydantic_ai.settings import ModelSettings, ToolOrOutput agent Agent( openai:gpt-4o, model_settingsModelSettings( temperature0.3, max_tokens2000, tool_choiceToolOrOutput(function_tools[get_weather, get_time]), thinkinghigh, service_tierauto, stop_sequences[[END]], ), ) # Run 级覆盖只需给出要改的键其余沿用 Agent 设置 result await agent.run( 明天天气如何, model_settingsModelSettings(temperature0.1, timeout30), )这段示例的每个行为点都对应前文的实现证据ToolOrOutput让模型在两个函数工具与直接给出结构化输出之间选择而不强制工具调用Run 级model_settings经merge_model_settings与 Agent 设置浅合并仅temperature与新增的timeout生效其余键原样保留thinkinghigh会按各提供商的映射规则落到其支持的档位service_tierauto按第二节映射表翻译为各提供商的具体线格式。需要按步动态调整tool_choice时参考 docs/tools-advanced.md 中 Tool Choice 一节的完整示例核心手段是 Capability 的get_model_settings钩子而非静态model_settings。六、验证与深入阅读的路径源码定义pydantic_ai_slim/pydantic_ai/settings.py约 534 行含全部字段文档与Supported by列表合并行为测试tests/test_settings.pystop_sequences跨 7 提供商集成回放 合并语义单测 前缀命名契约测试设置是否真正上线的逐线核对ModelSettings文档字符串声明其Supported by列表由 tests/models/test_model_settings_support.py 解析并对照真实 wire 请求校验因此文档中的支持列表是有测试背书的实现事实而非口头承诺。适用前提提示本文所有字段语义与提供商映射均取自当前仓库源码文档Supported by列表描述的是 Pydantic AI发送该设置的范围个别提供商背后的实际接受行为以其自身 API 参考为准文档中已知会被拒绝或忽略的字段如 Snowflake Cortex 拒绝service_tier、Cerebras 的层级处于私有预览均已按源码原文注明。【免费下载链接】pydantic-aiHow Python does AI. Agents, realtime voice, image generation, embeddings. Every model, every interface, typed end to end.项目地址: https://gitcode.com/GitHub_Trending/py/pydantic-ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Pydantic AI ModelSettings 全解：跨提供商 LLM 请求参数、Tool Choice 与设置合并机制
Pydantic AI ModelSettings 全解跨提供商 LLM 请求参数、Tool Choice 与设置合并机制【免费下载链接】pydantic-aiHow Python does AI. Agents, realtime voice, image generation, embeddings. Every model, every interface, typed end to end.项目地址: https://gitcode.com/GitHub_Trending/py/pydantic-ai本文以 Pydantic AI 的pydantic_ai.settings模块为核心系统讲解ModelSettings提供的全部跨提供商请求参数采样、超时、思考、服务层级、工具选择等、ToolChoice/ToolOrOutput的取值语义、ThinkingLevel与ServiceTier统一类型别名以及merge_model_settings在 Agent、Run 与 Capability 之间的合并规则帮助你在任何模型提供商下用一套类型安全的方式控制 LLM 行为。一、pydantic_ai.settings模块总览pydantic_ai.settings的 API 参考页见 docs/api/settings.md它通过 mkdocs-autorefs 渲染源码中pydantic_ai.settings模块的四个公开成员成员类型职责ModelSettingsTypedDict(totalFalse)跨提供商通用的 LLM 请求参数集合ToolChoiceTypeAliastool_choice字段的全部合法取值ToolOrOutputdataclass限定函数工具但保留结构化输出/文本/图片输出的复合取值ServiceTierTypeAlias跨提供商的统一服务层级取值集模块实现位于 pydantic_ai_slim/pydantic_ai/settings.py仅 500 余行是 Pydantic AI 中一次声明、全提供商生效这一设计的关键枢纽。它的设计约束在ModelSettings的类文档中写得很明确只收录跨多个模型/提供商通用的设置——并非每个字段都被所有模型支持每个字段的Supported by:列表标注了哪些模型类会真正把这个字段放上线即序列化进请求体。裸名字如OpenAI覆盖该模型提供的全部接口OpenAIChatModel与OpenAIResponsesModel带接口的名字如OpenAI Chat Completions只覆盖单一接口列表在发送意义上有效不代表服务商一定采纳OpenAI 兼容类模型会把 OpenAI schema 接受的东西原样转发背后的具体提供商可能忽略或拒绝自己 API 未定义的字段所有类型必须可用 Pydantic 序列化。二、ModelSettings跨提供商通用参数详解ModelSettings是一个totalFalse的TypedDict意味着所有字段可选、按需传入未设置的字段不会进入请求。以下逐字段说明其语义与支持范围。2.1 采样与生成控制字段类型说明max_tokensint停止生成前的最大 token 数。OpenAI、Anthropic、Google、Groq、Cohere、Mistral、Bedrock、MCP Sampling、xAI、HuggingFace、Cerebras、Crusoe、GitHub Copilot、Ollama、OpenRouter、Snowflake、Z.AI、Bedrock Mantle 支持temperaturefloat注入的随机程度。接近0.0适合分析/选择题接近模型上限适合生成式任务注意即使为0.0结果也不完全确定。多数提供商支持GitHub Copilot 对拒绝采样参数的 Anthropic 模型如claude-opus-4.8不发送top_pfloat核采样只考虑概率质量前top_p的 token0.1表示只考虑前 10% 概率质量。官方建议temperature与top_p二选一调整不要同时改top_kint每个后续 token 只从 top K 选项中采样用于剔除长尾低概率响应。仅 Anthropic、Google、Cohere、Bedrock仅 Anthropic 与 Amazon Nova 模型支持seedint随机种子理论上可得到确定性结果。支持列表限定在 Chat Completions 系接口OpenAI Chat Completions、Google、Groq、Cohere、Mistral、xAI 等注意 Responses 接口不在其列presence_penaltyfloat按 token 是否已出现惩罚新 tokenfrequency_penaltyfloat按 token 已有出现频率惩罚新 tokenlogit_biasdict[str, int]修改指定 token 出现在补全中的概率。注意 Anthropic、Cohere、Bedrock、OpenRouter 之外并不普遍支持Ollama 会发送但文档标注logit_bias不受支持stop_sequenceslist[str]触发停止生成的序列。支持范围最广的字段之一含 MCP Samplingstop_sequences的端到端行为有真实集成测试佐证tests/test_settings.py 中test_stop_settings在 openai、anthropic、bedrock、mistral、groq、cohere、google 七个模型上用 VCR cassette 回放验证回答包含 Paris 但不以 Paris 开头并特别标注 Bedrock 的行为差异——它会把停止序列包含在响应里result.output.endswith(Paris)其余提供商则是停止序列不包含在输出中。这是使用该字段时值得记住的边界行为。2.2 超时、并行工具调用与请求扩展字段类型说明timeoutint \| float \| Timeout以秒为单位覆盖客户端级默认超时。数字秒数全平台可用同时接受遗留的httpx.Timeout在 SDK 期望httpx2.Timeout的路径上自动转换Google 与 Mistral 只接受数字秒数parallel_tool_callsbool是否允许并行工具调用。OpenAI部分模型o1 不行、OpenAI Codex、Anthropic、Groq、Mistral、xAI、Cerebras、Crusoe、GitHub Copilot、Ollama、OpenRouter、Snowflake、Z.AI、Bedrock Mantle 支持extra_headersdict[str, str]发送到模型请求的额外 HTTP 头extra_bodyobject追加到请求体中的额外字段用于传递 Pydantic AI 尚未封装的提供商能力。注意在 Cerebras、OpenRouter、Snowflake、Z.AI 这些自行构造extra_body的 OpenAI 衍生模型上模型自有的派生键在键冲突时覆盖你的键timeout的类型定义本身就体现了对依赖可选性的处理从源码结构看settings.py 中当 legacyhttpx未安装时Timeout别名坍缩为float使联合类型退化为纯数字——这保证了未安装 httpx 的环境中ModelSettings依然可用。2.3 thinking统一的思考/推理开关thinking字段的类型是ThinkingLevelThinkingEffort: TypeAlias Literal[minimal, low, medium, high, xhigh] ThinkingLevel: TypeAlias bool | ThinkingEffort取值语义见 settings.py 的文档字符串True以提供商默认强度启用思考False关闭思考对始终开启思考的模型会被静默忽略minimal/low/medium/high/xhigh以指定强度启用思考。不是所有提供商都支持所有档位。当某个档位不被原生支持时会映射到最接近的可用值例如不支持xhigh的提供商会落到high没有 minimal 档的提供商会把minimal映射为low。各模型类的具体落线方式差异很大源码文档逐条列出Cerebras 只转发False映射为reasoning_effortnone因其模型默认推理且gpt-oss连关闭也会忽略OpenRouter 与 SnowflakeClaude 模型以extra_body[reasoning]承载Z.AI 以extra_body[thinking]承载GitHub Copilot 以reasoning_effort发送且不支持的值会收到400 invalid_reasoning_effortBedrock Mantle 仅 Responses 接口发送。另外提供商专属思考字段如anthropic_thinking、openai_reasoning_effort优先于这个统一字段。2.4 service_tier统一服务层级与提供商映射ServiceTier是一个四值类型别名auto | default | flex | priority语义见 settings.pyauto交给提供商决定——通常意味着可用时走高优先级/扩容额度层否则走标准层。对服务端没有 auto 概念的提供商会省略该字段让其默认值生效default显式请求标准层退出服务端可能有的自动升级到高级层的行为flex更低成本、延迟容忍型层级提供商提供时不支持的提供商如 Anthropic静默忽略也有个别提供商会直接拒绝该字段priority更高优先级/更低延迟层级提供商提供时不支持的提供商静默忽略。跨提供商映射表源码文档原表取值OpenAIAnthropicBedrockGoogle (Gemini API)Google Cloudautoautoauto(省略)(省略)无请求头PT 优先其后 on-demanddefaultdefaultstandard_only{type: default}standard无请求头PT 优先其后 on-demandflexflex(省略){type: flex}flex请求头Shared-Request-Type: flexPT 优先其后 Flex PayGoprioritypriority(省略){type: priority}priority请求头Shared-Request-Type: priorityPT 优先其后 Priority PayGo两个值得注意的实现细节一是在 Google Cloud 上统一字段只映射到安全的 PT预留吞吐溢出变体以让有 Provisioned Throughput 的账号优先消耗预留容量若要完全绕过 PT需用提供商专属字段google_cloud_service_tier传flex_only或priority_only。二是 Bedrock 的reserved、Anthropic 的standard_only、Google Cloud 的 PT 路由档位等不在统一取值集内的值只能通过提供商专属字段到达而所有提供商专属字段openai_service_tier、anthropic_service_tier、bedrock_service_tier、google_cloud_service_tier一旦设置一律优先于统一字段service_tier。2.5 tool_choice工具选择控制tool_choice的类型是ToolChoice这是本模块中最复杂的一个联合类型ToolChoiceScalar Literal[none, required, auto] dataclass class ToolOrOutput: function_tools: list[str] # 模型可用的函数工具名列表 ToolChoice ToolChoiceScalar | list[str] | ToolOrOutput | None各取值的语义见 settings.py 文档None默认等价auto行为auto所有工具可用由模型自行决定是否调用none禁用函数工具模型只以文本响应输出工具保留结构化输出不受影响required强制使用工具排除输出工具因此静态设置时 Agent 无法产生最终响应list[str]只允许指定工具同样排除输出工具ToolOrOutput指定函数工具子集同时保留输出工具/文本/图片输出——这是限制函数工具但不阻断 Agent 收尾的正确方式。关键约束静态required或list[str]会抛UserError。源码文档明确说明通过Agent.run的model_settings参数或 Agent 自身的model_settings静态设置这两种取值时由于会在每一步强制工具调用、阻止 Agent 产生最终响应Pydantic AI 会直接抛出UserError。如需按步变化tool_choice例如只在第一步强制某工具正确路径是让 Capability 的get_model_settings返回可调用对象——这些值被视为跨步骤自适应而受信任见 capabilities/combined.py 中对get_model_settings返回值的解析。若只是单次 API 调用而不需要 Agent 循环用pydantic_ai.direct.model_request。各提供商对tool_choice的处理方式差异也在文档中注明Cohere 与 Mistral 对命名子集是通过过滤工具列表实现的而非作为参数发送Anthropic 在启用 thinking 时不支持required与指定工具Ollama 会发送但文档标注不受支持。三、merge_model_settingsAgent、Run 与 Capability 的设置合并模块末尾的merge_model_settings是所有设置最终生效的汇聚点settings.pydef merge_model_settings(base: ModelSettings | None, overrides: ModelSettings | None) - ModelSettings | None: Merge two sets of model settings, preferring the overrides. A common use case is: merge_model_settings(agent settings, run settings) if base and overrides: return base | overrides else: return base or overrides实现极简单两个字典的浅合并|运算符键冲突时overrides胜出任一为None时返回另一个。源码注释还留了一个演进注记——如果将来加入非原始值可能需要递归合并从源码结构看当前所有字段均为扁平原始值浅合并语义恰好够用。它在代码库中的调用点勾勒出完整的优先级链Agent 层agent/init.py 中 Agent 级model_settings作为 baseagent/init.py 中先并入 Agent 设置、再并入本次run()传入的model_settings——即Run 参数 Agent 参数Capability 层capabilities/combined.py 在每步执行时把各 Capabilityget_model_settings解析出的设置再次并入ctx.model_settings能力返回的可调用对象在此被调用并解析模型层各模型实现如 models/openai.py、models/anthropic.py、models/bedrock.py在构造请求前把实例级self.settings与本次请求的model_settings再合并一次请求参数 模型实例参数。合并语义有专门的单元测试覆盖tests/test_settings.py 的TestMergeModelSettingsThinking与TestMergeModelSettingsServiceTier验证了thinking布尔/强度档的覆盖、无关字段max_tokens、temperature在合并中保留、以及None边界的三种组合base 为 None、overrides 为 None、双 None 返回 None。四、提供商专属设置前缀命名的扩展体系ModelSettings只覆盖通用参数。各提供商自己的参数如anthropic_thinking、openai_reasoning_effort定义在各自模型模块中以提供商名作前缀的ModelSettings子类中。tests/test_settings.py 通过动态发现机制强制执行这一命名纪律_discover_model_settings()遍历pydantic_ai.models包下所有子模块用__orig_bases__找出每个ModelSettings子类因为TypedDict子类的__bases__只报告dict真实继承链要取__orig_bases__然后断言所有不属于全局ModelSettings的字段名必须以{模块名}_开头mcp_sampling是例外用mcp_前缀因为它是 MCP sampling 伪模型而非真正的提供商集成。test_model_settings_discovery还设置了模块遍历数量的腐烂守卫防止包结构变动导致前缀检查静默失效。五、实战组合使用这些设置把上述能力组合起来典型的 Agent 配置如下from pydantic_ai import Agent from pydantic_ai.settings import ModelSettings, ToolOrOutput agent Agent( openai:gpt-4o, model_settingsModelSettings( temperature0.3, max_tokens2000, tool_choiceToolOrOutput(function_tools[get_weather, get_time]), thinkinghigh, service_tierauto, stop_sequences[[END]], ), ) # Run 级覆盖只需给出要改的键其余沿用 Agent 设置 result await agent.run( 明天天气如何, model_settingsModelSettings(temperature0.1, timeout30), )这段示例的每个行为点都对应前文的实现证据ToolOrOutput让模型在两个函数工具与直接给出结构化输出之间选择而不强制工具调用Run 级model_settings经merge_model_settings与 Agent 设置浅合并仅temperature与新增的timeout生效其余键原样保留thinkinghigh会按各提供商的映射规则落到其支持的档位service_tierauto按第二节映射表翻译为各提供商的具体线格式。需要按步动态调整tool_choice时参考 docs/tools-advanced.md 中 Tool Choice 一节的完整示例核心手段是 Capability 的get_model_settings钩子而非静态model_settings。六、验证与深入阅读的路径源码定义pydantic_ai_slim/pydantic_ai/settings.py约 534 行含全部字段文档与Supported by列表合并行为测试tests/test_settings.pystop_sequences跨 7 提供商集成回放 合并语义单测 前缀命名契约测试设置是否真正上线的逐线核对ModelSettings文档字符串声明其Supported by列表由 tests/models/test_model_settings_support.py 解析并对照真实 wire 请求校验因此文档中的支持列表是有测试背书的实现事实而非口头承诺。适用前提提示本文所有字段语义与提供商映射均取自当前仓库源码文档Supported by列表描述的是 Pydantic AI发送该设置的范围个别提供商背后的实际接受行为以其自身 API 参考为准文档中已知会被拒绝或忽略的字段如 Snowflake Cortex 拒绝service_tier、Cerebras 的层级处于私有预览均已按源码原文注明。【免费下载链接】pydantic-aiHow Python does AI. Agents, realtime voice, image generation, embeddings. Every model, every interface, typed end to end.项目地址: https://gitcode.com/GitHub_Trending/py/pydantic-ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考