pydantic-ai 接入 Groq 模型完整指南安装配置、GroqModel 用法与源码级原理【免费下载链接】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 仓库中 docs/models/groq.md 与 docs/api/models/groq.md 为核心系统讲解如何在 pydantic-ai 中使用 Groq 的高性能推理 APILlama、GPT-OSS 等模型从安装依赖、获取 API Key、环境变量配置到通过字符串别名与GroqModel类两种方式初始化 Agent、自定义GroqProvider与 HTTP 客户端、控制 SDK 重试策略并深入源码剖析其模型映射、原生工具Web 搜索、推理reasoning参数与错误处理机制。读完本文你将能在自己的项目中快速、可靠地接入 Groq 模型。1. 安装引入 Groq 支持pydantic-ai 将模型支持做成了可选依赖组。使用GroqModel需要安装pydantic-ai完整包或者安装pydantic-ai-slim并带上groq可选组pip/uv-add pydantic-ai-slim[groq]pip/uv-add是 pydantic-ai 文档中统一表示用 pip 或 uv 安装的速记写法实际执行时等价于pip install pydantic-ai-slim[groq]或uv add pydantic-ai-slim[groq]。从源码看该可选组实际引入的是 Groq 官方的 Python SDKgroq。在 models/groq.py 中模块导入被包在try/except ImportError里如果未安装groq包会抛出带有明确指引的错误信息Please install groq to use the Groq model, you can use the groq optional group — pip install pydantic-ai-slim[groq]providers/groq.py 中的GroqProvider同样依赖groq包未安装时会提示同样的安装命令。2. 配置API Key 与模型名称2.1 获取 API Key要使用 Groq 的 API需要先到 Groq 控制台的密钥管理页面console.groq.com/keys生成一个 API Key。这是所有后续调用的凭证基础。2.2 模型名称类型GroqModelNameGroqModelName是 pydantic-ai 为 Groq 定义的模型名称类型见 models/groq.py。其定义为GroqModelName str | ProductionGroqModelNames | PreviewGroqModelNames其中ProductionGroqModelNames是生产可用模型的字面量联合PreviewGroqModelNames是预览模型的字面量联合源码中截至 2025-03-31 的清单包括生产模型llama-3.1-8b-instant、llama-3.3-70b-versatile、meta-llama/llama-guard-4-12b、openai/gpt-oss-120b、openai/gpt-oss-20b、whisper-large-v3、whisper-large-v3-turbo预览模型meta-llama/llama-4-maverick-17b-128e-instruct、meta-llama/llama-prompt-guard-2-22m、meta-llama/llama-prompt-guard-2-86m、openai/gpt-oss-safeguard-20b、playai-tts、playai-tts-arabic类型注解中同时保留了str因为 Groq 支持的模型清单变动频繁pydantic-ai 允许传入任意模型名方便你使用清单之外的新模型类型检查会给出建议但不强制限制。最新的完整模型列表以 Groq 官方控制台的模型文档页为准。3. 环境变量GROQ_API_KEY拿到 API Key 后将其设置为环境变量export GROQ_API_KEYyour-api-keypydantic-ai 在创建GroqProvider时会自动读取该环境变量。源码 providers/groq.py 的逻辑是api_key api_key or os.getenv(GROQ_API_KEY) base_url base_url or os.getenv(GROQ_BASE_URL, https://api.groq.com) if not api_key: raise UserError( Set the GROQ_API_KEY environment variable or pass it via GroqProvider(api_key...) to use the Groq provider. )需要注意的细节除了GROQ_API_KEY还支持GROQ_BASE_URL环境变量来自定义 API 地址默认值为https://api.groq.com如果环境变量和显式参数都没有提供 API Key会直接抛出UserError不会静默失败。这一点有测试用例佐证tests/providers/test_groq.py 中test_groq_provider_need_api_key移除了GROQ_API_KEY环境变量后断言抛出该错误。4. 初始化 Groq 模型两种方式4.1 方式一通过字符串别名推荐入门pydantic-ai 支持用groq:model-name格式的字符串直接指定模型框架会自动完成 provider 推断from pydantic_ai import Agent agent Agent(groq:llama-3.3-70b-versatile) ...这种方式最简洁框架在内部通过infer_provider根据前缀groq解析出对应的模型与 provider参见 models/groq.py 中provider参数为字符串时的推断逻辑。4.2 方式二直接初始化GroqModel需要更精细控制时可以显式导入并实例化GroqModelfrom pydantic_ai import Agent from pydantic_ai.models.groq import GroqModel model GroqModel(llama-3.3-70b-versatile) agent Agent(model) ...GroqModel的构造签名models/groq.py为def __init__( self, model_name: GroqModelName, *, provider: Literal[groq, gateway] | Provider[AsyncGroq] groq, profile: ModelProfileSpec | None None, settings: ModelSettings | None None, ):model_name要使用的 Groq 模型名provider认证与访问方式可以是字符串groq或gateway走 gateway 代理或一个Provider[AsyncGroq]实例默认groqprofile模型 profile默认由 provider 根据模型名挑选settings模型级默认设置。内部实现上GroqModel是一个dataclass其client属性直接暴露底层的AsyncGroq客户端self._provider.clientbase_url、model_name、system属性分别给出 API 地址、模型名与 provider 名称。5. 自定义provider参数5.1 通过GroqProvider传入 API Key如果你不想依赖环境变量可以通过provider参数显式传入GroqProviderfrom pydantic_ai import Agent from pydantic_ai.models.groq import GroqModel from pydantic_ai.providers.groq import GroqProvider model GroqModel( llama-3.3-70b-versatile, providerGroqProvider(api_keyyour-api-key) ) agent Agent(model) ...GroqProvider的构造参数providers/groq.py包括参数说明默认值api_keyAPI Key未提供时读取GROQ_API_KEY环境变量Nonebase_url请求的 API 地址未提供时读取GROQ_BASE_URL环境变量再回退到 Groq 官方地址https://api.groq.comgroq_client直接传入一个现成的AsyncGroq客户端互斥约束见下Nonehttp_client传入一个现成的httpx.AsyncClient用于 HTTP 请求None约束关系一旦提供了groq_clienthttp_client、api_key、base_url必须全部为None源码用assert强制校验而api_key与http_client可以同时提供此时会基于该 HTTP 客户端构造AsyncGroq。5.2 自定义httpx.AsyncClient你还可以为GroqProvider定制一个httpx.AsyncClient用于统一超时、代理、连接池等传输层行为from httpx import AsyncClient from pydantic_ai import Agent from pydantic_ai.models.groq import GroqModel from pydantic_ai.providers.groq import GroqProvider custom_http_client AsyncClient(timeout30) model GroqModel( llama-3.3-70b-versatile, providerGroqProvider(api_keyyour-api-key, http_clientcustom_http_client), ) agent Agent(model) ...这里timeout30表示每个 HTTP 请求 30 秒超时你可以根据实际网络环境调整。测试 tests/providers/test_groq.py 验证了传入的http_client会被透传到AsyncGroq客户端内部断言provider.client._client http_client。若你的调用链中还配置了重试传输层SDK 级重试会叠加在传输层重试之上二者的预算相互独立。6. SDK 重试max_retries与groq_clientGroqProvider内部构建的AsyncGroq客户端自带重试逻辑与它所模仿的 OpenAI 客户端一致默认max_retries2即每个请求最多重试 2 次共 3 次尝试。如果不希望 SDK 层做重试而是把重试策略完全交给传输层例如你在自定义httpx.AsyncClient上挂了基于 tenacity 的重试传输可以显式传入一个max_retries0的AsyncGroq客户端from groq import AsyncGroq from pydantic_ai import Agent from pydantic_ai.models.groq import GroqModel from pydantic_ai.providers.groq import GroqProvider model GroqModel( llama-3.3-70b-versatile, providerGroqProvider(groq_clientAsyncGroq(max_retries0)), ) agent Agent(model)注意传入groq_client后就不能再同时传api_key、base_url或http_client见第 5.1 节的互斥约束API Key 需在构造AsyncGroq时一并给出如AsyncGroq(api_key..., max_retries0)。关于重试层的定位pydantic-ai 的 docs/retries.md 中Provider SDK retries一节明确指出SDK 客户端位于传输层与模型之间是 Agent 看不到的一层它自己会重发失败的请求默认值、可重试错误与配置方式因 provider 而异。配置传输层重试不会关闭 SDK 层重试两者是叠加关系而非替代关系——因此如果你只想保留传输层策略就必须显式用groq_clientAsyncGroq(max_retries0)关掉 SDK 层。7. 源码级原理GroqModel如何工作7.1 请求流程GroqModel继承自Model[AsyncGroq]核心请求方法_completions_createmodels/groq.py把 pydantic-ai 的抽象消息结构翻译成 Groq SDK 的chat.completions.create调用主要映射关系model_settings中的max_tokens、temperature、top_p、timeout、seed、presence_penalty、frequency_penalty、logit_bias、stop_sequences等直接透传parallel_tool_calls、tools、tool_choice由工具解析逻辑_get_tool_choice计算得出结构化输出输出模式为native时使用response_format{type: json_schema, ...}_map_json_schema为prompted且模型 profile 支持json_object时使用{type: json_object}消息映射_map_messages支持文本、图像ImageUrl与BinaryContent、工具调用/返回、重试提示RetryPromptPart等部件图像输入支持detail元数据默认auto音频、视频、文档、上传文件在 Groq 用户消息中当前不支持会抛出NotImplementedError。7.2 原生工具Web 搜索GroqModel.supported_native_tools()models/groq.py返回frozenset({WebSearchTool})即 Groq 模型支持 pydantic-ai 的原生 Web 搜索工具。其实现细节_get_native_tools是对复合模型compound 系列内置隐式 Web 搜索pydantic-ai 不会下发工具定义而是把域名过滤条件转成search_settings的include_domains/exclude_domains透传给 Groq API对不支持的模型使用WebSearchTool会抛出UserError。是否内置该工具由模型 profile 中的groq_always_has_web_search_builtin_tool决定profiles/groq.py仅 compound 系列模型为True。7.3 推理reasoning参数GroqModelSettingsGroqModelSettingsmodels/groq.py为 Groq 请求提供两个专属设置字段约定以groq_前缀命名以便与其他模型设置合并字段取值说明groq_reasoning_formathidden|raw|parsed推理输出的格式hidden抑制推理输出、raw在内容里带think标签、parsed将推理单独放入reasoning字段pydantic-ai 会解析为ThinkingPartgroq_reasoning_effortnone|default|low|medium|high推理强度级别此外GroqModel还支持 pydantic-ai 统一的thinking机制ModelRequestParameters.thinking并针对不同模型家族做了差异化处理_translate_thinking与reasoning_effort合并逻辑见 models/groq.pyqwen3 家族thinkingFalse时通过reasoning_effortnone真正关闭推理profile 的groq_supports_reasoning_disableTrue其他推理模型只能通过hidden抑制推理输出模型内部仍会推理gpt-oss 家族接受分级的reasoning_effortlow/medium/high统一的 thinking 强度通过GROQ_GPT_OSS_REASONING_EFFORT_MAPprofiles/groq.py映射minimal/low→lowmedium→mediumhigh/xhigh→high裸thinkingTrue映射为medium由于reasoning_effort不是 Groq SDK 的命名参数它通过extra_body传递见 models/groq.py。推理模型的识别在 profiles/groq.py 的groq_model_profile中完成前缀匹配openai/gpt-oss、qwen/qwen3、qwen-qwq、deepseek-r1、llama-4-maverick的模型被视为推理模型supports_thinkingTrue。同时GroqProvider.model_profileproviders/groq.py会按模型名前缀选择对应的家族 profileMeta、Google、Qwen、DeepSeek、Mistral、MoonshotAI、OpenAI 等再与 Groq 专属 profile 合并并叠加supports_inline_system_promptsTrue。7.4 错误处理与容错GroqModel对 API 错误做了统一封装_map_api_errorsmodels/groq.pyAPIStatusError状态码 ≥ 400转为ModelHTTPError并携带响应头、状态码当错误码为model_not_found时会尝试根据 provider 错误信息推荐相近的已知模型名suggested_model_id方便你纠错APIConnectionError转为ModelAPIError。一个值得一提的容错细节Groq SDK 在模型生成的工具参数不符合 schema 时会主动抛错tool_use_failed错误pydantic-ai 选择自己处理这类错误——解析出失败的生成结果后将其包装为ToolCallPart或TextPart返回让 Agent 有机会让模型重试工具调用而不是直接让 run 失败。对应的解析逻辑_parse_tool_use_failed_error及其测试用例如tests/models/cassettes/test_groq/test_tool_use_failed_error.yaml都存在于仓库中。流式响应GroqStreamedResponse同样实现了这一处理。7.5 用量统计_map_usagemodels/groq.py把 Groq 返回的 token 用量映射为 pydantic-ai 的usage.RequestUsage提取prompt_tokens、completion_tokens、total_tokens并将completion_tokens_details如reasoning_tokens等细节放入details供成本核算与用量限制UsageLimits使用。8. 完整实战示例把以上内容串起来一个带工具、自定义超时与 Web 搜索的完整示例import os from httpx import AsyncClient from pydantic_ai import Agent from pydantic_ai.models.groq import GroqModel from pydantic_ai.providers.groq import GroqProvider # 方式 A环境变量 默认 provider最简单 agent_a Agent(groq:llama-3.3-70b-versatile) # 方式 B显式 provider 自定义 HTTP 客户端30 秒超时 custom_http_client AsyncClient(timeout30) model GroqModel( llama-3.3-70b-versatile, providerGroqProvider( api_keyos.getenv(GROQ_API_KEY, your-api-key), http_clientcustom_http_client, ), ) agent_b Agent(model) result agent_b.run_sync(介绍一下 pydantic-ai 接入 Groq 的要点) print(result.output)9. 常见问题与注意事项API Key 缺失报错未设置GROQ_API_KEY且未传api_key时GroqProvider会抛出UserError提示信息见 providers/groq.py。groq_client与http_client/api_key互斥二者不可同时传入否则触发assert失败providers/groq.py。SDK 重试叠加AsyncGroq默认max_retries2与传输层重试相互独立、可叠加只想保留传输层策略时传入AsyncGroq(max_retries0)。重试层级说明参见 docs/retries.md。多模态限制Groq 用户消息目前只支持文本与图像音频AudioUrl、视频VideoUrl、文档DocumentUrl、上传文件UploadedFile会抛出NotImplementedError。模型名时效性GroqModelName字面量清单以 2025-03-31 为准新模型可直接用字符串传入推理相关的thinking行为与模型家族强相关qwen3、gpt-oss 行为不同跨模型切换时注意推理配置。如需了解 pydantic-ai 中 Groq 模块的完整 API 签名可查阅 docs/api/models/groq.md对应测试用例位于 tests/models/test_groq.py 与 tests/providers/test_groq.py可用于验证上述行为。【免费下载链接】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 接入 Groq 模型完整指南：安装配置、GroqModel 用法与源码级原理
pydantic-ai 接入 Groq 模型完整指南安装配置、GroqModel 用法与源码级原理【免费下载链接】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 仓库中 docs/models/groq.md 与 docs/api/models/groq.md 为核心系统讲解如何在 pydantic-ai 中使用 Groq 的高性能推理 APILlama、GPT-OSS 等模型从安装依赖、获取 API Key、环境变量配置到通过字符串别名与GroqModel类两种方式初始化 Agent、自定义GroqProvider与 HTTP 客户端、控制 SDK 重试策略并深入源码剖析其模型映射、原生工具Web 搜索、推理reasoning参数与错误处理机制。读完本文你将能在自己的项目中快速、可靠地接入 Groq 模型。1. 安装引入 Groq 支持pydantic-ai 将模型支持做成了可选依赖组。使用GroqModel需要安装pydantic-ai完整包或者安装pydantic-ai-slim并带上groq可选组pip/uv-add pydantic-ai-slim[groq]pip/uv-add是 pydantic-ai 文档中统一表示用 pip 或 uv 安装的速记写法实际执行时等价于pip install pydantic-ai-slim[groq]或uv add pydantic-ai-slim[groq]。从源码看该可选组实际引入的是 Groq 官方的 Python SDKgroq。在 models/groq.py 中模块导入被包在try/except ImportError里如果未安装groq包会抛出带有明确指引的错误信息Please install groq to use the Groq model, you can use the groq optional group — pip install pydantic-ai-slim[groq]providers/groq.py 中的GroqProvider同样依赖groq包未安装时会提示同样的安装命令。2. 配置API Key 与模型名称2.1 获取 API Key要使用 Groq 的 API需要先到 Groq 控制台的密钥管理页面console.groq.com/keys生成一个 API Key。这是所有后续调用的凭证基础。2.2 模型名称类型GroqModelNameGroqModelName是 pydantic-ai 为 Groq 定义的模型名称类型见 models/groq.py。其定义为GroqModelName str | ProductionGroqModelNames | PreviewGroqModelNames其中ProductionGroqModelNames是生产可用模型的字面量联合PreviewGroqModelNames是预览模型的字面量联合源码中截至 2025-03-31 的清单包括生产模型llama-3.1-8b-instant、llama-3.3-70b-versatile、meta-llama/llama-guard-4-12b、openai/gpt-oss-120b、openai/gpt-oss-20b、whisper-large-v3、whisper-large-v3-turbo预览模型meta-llama/llama-4-maverick-17b-128e-instruct、meta-llama/llama-prompt-guard-2-22m、meta-llama/llama-prompt-guard-2-86m、openai/gpt-oss-safeguard-20b、playai-tts、playai-tts-arabic类型注解中同时保留了str因为 Groq 支持的模型清单变动频繁pydantic-ai 允许传入任意模型名方便你使用清单之外的新模型类型检查会给出建议但不强制限制。最新的完整模型列表以 Groq 官方控制台的模型文档页为准。3. 环境变量GROQ_API_KEY拿到 API Key 后将其设置为环境变量export GROQ_API_KEYyour-api-keypydantic-ai 在创建GroqProvider时会自动读取该环境变量。源码 providers/groq.py 的逻辑是api_key api_key or os.getenv(GROQ_API_KEY) base_url base_url or os.getenv(GROQ_BASE_URL, https://api.groq.com) if not api_key: raise UserError( Set the GROQ_API_KEY environment variable or pass it via GroqProvider(api_key...) to use the Groq provider. )需要注意的细节除了GROQ_API_KEY还支持GROQ_BASE_URL环境变量来自定义 API 地址默认值为https://api.groq.com如果环境变量和显式参数都没有提供 API Key会直接抛出UserError不会静默失败。这一点有测试用例佐证tests/providers/test_groq.py 中test_groq_provider_need_api_key移除了GROQ_API_KEY环境变量后断言抛出该错误。4. 初始化 Groq 模型两种方式4.1 方式一通过字符串别名推荐入门pydantic-ai 支持用groq:model-name格式的字符串直接指定模型框架会自动完成 provider 推断from pydantic_ai import Agent agent Agent(groq:llama-3.3-70b-versatile) ...这种方式最简洁框架在内部通过infer_provider根据前缀groq解析出对应的模型与 provider参见 models/groq.py 中provider参数为字符串时的推断逻辑。4.2 方式二直接初始化GroqModel需要更精细控制时可以显式导入并实例化GroqModelfrom pydantic_ai import Agent from pydantic_ai.models.groq import GroqModel model GroqModel(llama-3.3-70b-versatile) agent Agent(model) ...GroqModel的构造签名models/groq.py为def __init__( self, model_name: GroqModelName, *, provider: Literal[groq, gateway] | Provider[AsyncGroq] groq, profile: ModelProfileSpec | None None, settings: ModelSettings | None None, ):model_name要使用的 Groq 模型名provider认证与访问方式可以是字符串groq或gateway走 gateway 代理或一个Provider[AsyncGroq]实例默认groqprofile模型 profile默认由 provider 根据模型名挑选settings模型级默认设置。内部实现上GroqModel是一个dataclass其client属性直接暴露底层的AsyncGroq客户端self._provider.clientbase_url、model_name、system属性分别给出 API 地址、模型名与 provider 名称。5. 自定义provider参数5.1 通过GroqProvider传入 API Key如果你不想依赖环境变量可以通过provider参数显式传入GroqProviderfrom pydantic_ai import Agent from pydantic_ai.models.groq import GroqModel from pydantic_ai.providers.groq import GroqProvider model GroqModel( llama-3.3-70b-versatile, providerGroqProvider(api_keyyour-api-key) ) agent Agent(model) ...GroqProvider的构造参数providers/groq.py包括参数说明默认值api_keyAPI Key未提供时读取GROQ_API_KEY环境变量Nonebase_url请求的 API 地址未提供时读取GROQ_BASE_URL环境变量再回退到 Groq 官方地址https://api.groq.comgroq_client直接传入一个现成的AsyncGroq客户端互斥约束见下Nonehttp_client传入一个现成的httpx.AsyncClient用于 HTTP 请求None约束关系一旦提供了groq_clienthttp_client、api_key、base_url必须全部为None源码用assert强制校验而api_key与http_client可以同时提供此时会基于该 HTTP 客户端构造AsyncGroq。5.2 自定义httpx.AsyncClient你还可以为GroqProvider定制一个httpx.AsyncClient用于统一超时、代理、连接池等传输层行为from httpx import AsyncClient from pydantic_ai import Agent from pydantic_ai.models.groq import GroqModel from pydantic_ai.providers.groq import GroqProvider custom_http_client AsyncClient(timeout30) model GroqModel( llama-3.3-70b-versatile, providerGroqProvider(api_keyyour-api-key, http_clientcustom_http_client), ) agent Agent(model) ...这里timeout30表示每个 HTTP 请求 30 秒超时你可以根据实际网络环境调整。测试 tests/providers/test_groq.py 验证了传入的http_client会被透传到AsyncGroq客户端内部断言provider.client._client http_client。若你的调用链中还配置了重试传输层SDK 级重试会叠加在传输层重试之上二者的预算相互独立。6. SDK 重试max_retries与groq_clientGroqProvider内部构建的AsyncGroq客户端自带重试逻辑与它所模仿的 OpenAI 客户端一致默认max_retries2即每个请求最多重试 2 次共 3 次尝试。如果不希望 SDK 层做重试而是把重试策略完全交给传输层例如你在自定义httpx.AsyncClient上挂了基于 tenacity 的重试传输可以显式传入一个max_retries0的AsyncGroq客户端from groq import AsyncGroq from pydantic_ai import Agent from pydantic_ai.models.groq import GroqModel from pydantic_ai.providers.groq import GroqProvider model GroqModel( llama-3.3-70b-versatile, providerGroqProvider(groq_clientAsyncGroq(max_retries0)), ) agent Agent(model)注意传入groq_client后就不能再同时传api_key、base_url或http_client见第 5.1 节的互斥约束API Key 需在构造AsyncGroq时一并给出如AsyncGroq(api_key..., max_retries0)。关于重试层的定位pydantic-ai 的 docs/retries.md 中Provider SDK retries一节明确指出SDK 客户端位于传输层与模型之间是 Agent 看不到的一层它自己会重发失败的请求默认值、可重试错误与配置方式因 provider 而异。配置传输层重试不会关闭 SDK 层重试两者是叠加关系而非替代关系——因此如果你只想保留传输层策略就必须显式用groq_clientAsyncGroq(max_retries0)关掉 SDK 层。7. 源码级原理GroqModel如何工作7.1 请求流程GroqModel继承自Model[AsyncGroq]核心请求方法_completions_createmodels/groq.py把 pydantic-ai 的抽象消息结构翻译成 Groq SDK 的chat.completions.create调用主要映射关系model_settings中的max_tokens、temperature、top_p、timeout、seed、presence_penalty、frequency_penalty、logit_bias、stop_sequences等直接透传parallel_tool_calls、tools、tool_choice由工具解析逻辑_get_tool_choice计算得出结构化输出输出模式为native时使用response_format{type: json_schema, ...}_map_json_schema为prompted且模型 profile 支持json_object时使用{type: json_object}消息映射_map_messages支持文本、图像ImageUrl与BinaryContent、工具调用/返回、重试提示RetryPromptPart等部件图像输入支持detail元数据默认auto音频、视频、文档、上传文件在 Groq 用户消息中当前不支持会抛出NotImplementedError。7.2 原生工具Web 搜索GroqModel.supported_native_tools()models/groq.py返回frozenset({WebSearchTool})即 Groq 模型支持 pydantic-ai 的原生 Web 搜索工具。其实现细节_get_native_tools是对复合模型compound 系列内置隐式 Web 搜索pydantic-ai 不会下发工具定义而是把域名过滤条件转成search_settings的include_domains/exclude_domains透传给 Groq API对不支持的模型使用WebSearchTool会抛出UserError。是否内置该工具由模型 profile 中的groq_always_has_web_search_builtin_tool决定profiles/groq.py仅 compound 系列模型为True。7.3 推理reasoning参数GroqModelSettingsGroqModelSettingsmodels/groq.py为 Groq 请求提供两个专属设置字段约定以groq_前缀命名以便与其他模型设置合并字段取值说明groq_reasoning_formathidden|raw|parsed推理输出的格式hidden抑制推理输出、raw在内容里带think标签、parsed将推理单独放入reasoning字段pydantic-ai 会解析为ThinkingPartgroq_reasoning_effortnone|default|low|medium|high推理强度级别此外GroqModel还支持 pydantic-ai 统一的thinking机制ModelRequestParameters.thinking并针对不同模型家族做了差异化处理_translate_thinking与reasoning_effort合并逻辑见 models/groq.pyqwen3 家族thinkingFalse时通过reasoning_effortnone真正关闭推理profile 的groq_supports_reasoning_disableTrue其他推理模型只能通过hidden抑制推理输出模型内部仍会推理gpt-oss 家族接受分级的reasoning_effortlow/medium/high统一的 thinking 强度通过GROQ_GPT_OSS_REASONING_EFFORT_MAPprofiles/groq.py映射minimal/low→lowmedium→mediumhigh/xhigh→high裸thinkingTrue映射为medium由于reasoning_effort不是 Groq SDK 的命名参数它通过extra_body传递见 models/groq.py。推理模型的识别在 profiles/groq.py 的groq_model_profile中完成前缀匹配openai/gpt-oss、qwen/qwen3、qwen-qwq、deepseek-r1、llama-4-maverick的模型被视为推理模型supports_thinkingTrue。同时GroqProvider.model_profileproviders/groq.py会按模型名前缀选择对应的家族 profileMeta、Google、Qwen、DeepSeek、Mistral、MoonshotAI、OpenAI 等再与 Groq 专属 profile 合并并叠加supports_inline_system_promptsTrue。7.4 错误处理与容错GroqModel对 API 错误做了统一封装_map_api_errorsmodels/groq.pyAPIStatusError状态码 ≥ 400转为ModelHTTPError并携带响应头、状态码当错误码为model_not_found时会尝试根据 provider 错误信息推荐相近的已知模型名suggested_model_id方便你纠错APIConnectionError转为ModelAPIError。一个值得一提的容错细节Groq SDK 在模型生成的工具参数不符合 schema 时会主动抛错tool_use_failed错误pydantic-ai 选择自己处理这类错误——解析出失败的生成结果后将其包装为ToolCallPart或TextPart返回让 Agent 有机会让模型重试工具调用而不是直接让 run 失败。对应的解析逻辑_parse_tool_use_failed_error及其测试用例如tests/models/cassettes/test_groq/test_tool_use_failed_error.yaml都存在于仓库中。流式响应GroqStreamedResponse同样实现了这一处理。7.5 用量统计_map_usagemodels/groq.py把 Groq 返回的 token 用量映射为 pydantic-ai 的usage.RequestUsage提取prompt_tokens、completion_tokens、total_tokens并将completion_tokens_details如reasoning_tokens等细节放入details供成本核算与用量限制UsageLimits使用。8. 完整实战示例把以上内容串起来一个带工具、自定义超时与 Web 搜索的完整示例import os from httpx import AsyncClient from pydantic_ai import Agent from pydantic_ai.models.groq import GroqModel from pydantic_ai.providers.groq import GroqProvider # 方式 A环境变量 默认 provider最简单 agent_a Agent(groq:llama-3.3-70b-versatile) # 方式 B显式 provider 自定义 HTTP 客户端30 秒超时 custom_http_client AsyncClient(timeout30) model GroqModel( llama-3.3-70b-versatile, providerGroqProvider( api_keyos.getenv(GROQ_API_KEY, your-api-key), http_clientcustom_http_client, ), ) agent_b Agent(model) result agent_b.run_sync(介绍一下 pydantic-ai 接入 Groq 的要点) print(result.output)9. 常见问题与注意事项API Key 缺失报错未设置GROQ_API_KEY且未传api_key时GroqProvider会抛出UserError提示信息见 providers/groq.py。groq_client与http_client/api_key互斥二者不可同时传入否则触发assert失败providers/groq.py。SDK 重试叠加AsyncGroq默认max_retries2与传输层重试相互独立、可叠加只想保留传输层策略时传入AsyncGroq(max_retries0)。重试层级说明参见 docs/retries.md。多模态限制Groq 用户消息目前只支持文本与图像音频AudioUrl、视频VideoUrl、文档DocumentUrl、上传文件UploadedFile会抛出NotImplementedError。模型名时效性GroqModelName字面量清单以 2025-03-31 为准新模型可直接用字符串传入推理相关的thinking行为与模型家族强相关qwen3、gpt-oss 行为不同跨模型切换时注意推理配置。如需了解 pydantic-ai 中 Groq 模块的完整 API 签名可查阅 docs/api/models/groq.md对应测试用例位于 tests/models/test_groq.py 与 tests/providers/test_groq.py可用于验证上述行为。【免费下载链接】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），仅供参考