Pydantic AI 集成 Groq 模型安装配置、Provider 定制与源码级原理全解析【免费下载链接】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 编写。作为 Pydantic AIPython 生态中主打类型安全端到端的 AI Agent 框架的核心模型接入之一Groq 以其高速推理能力为 Agent 应用提供了低延迟的 LLM 后端。读完本文你将掌握如何安装 groq 可选依赖、如何用环境变量或 Provider 对象配置GroqModel、如何注入自定义httpx.AsyncClient与AsyncGroq客户端以及 SDK 层重试与传输层重试的正确组合方式同时我们将深入源码剖析GroqModel的底层调用链、模型名清单、推理设置与内置 Web 搜索工具等实现细节。一、安装两种方式按需选择要使用GroqModel你只需要两条安装路径之一安装完整的pydantic-ai包默认自带全部模型支持安装精简版pydantic-ai-slim并附加上groq可选依赖组。官方文档给出的安装命令docs/models/groq.md如下pip/uv-add pydantic-ai-slim[groq]这里pip/uv-add是 Pydantic AI 文档的统一写法实际使用时按你的包管理器替换为pip install pydantic-ai-slim[groq]或uv add pydantic-ai-slim[groq]。项目根目录的 pyproject.toml 与 uv.lock 中可以看到groq可选组会引入官方的groqPython SDKAsyncGroq客户端即来自该 SDK。一个值得注意的细节pydantic_ai.models.groq模块在导入时会先try: from groq import ...如果 groq 包未安装会抛出带明确提示的ImportError见 pydantic_ai_slim/pydantic_ai/models/groq.pyPlease installgroqto use the Groq model, you can use thegroqoptional group —pip install pydantic-ai-slim[groq]也就是说缺少依赖时的报错信息本身就是一条安装指引不用担心装完报一堆找不到模块的困惑。二、配置获取 API Key 与模型名要使用 Groq 的 API需要先到 console.groq.com/keys 生成一个 API Key官方文档指引见 docs/models/groq.md。Pydantic AI 在源码中维护了GroqModelName类型它由生产模型和预览模型两部分联合构成见 pydantic_ai_slim/pydantic_ai/models/groq.py生产模型ProductionGroqModelNamesllama-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预览模型PreviewGroqModelNamesmeta-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-arabicGroqModelName str | ProductionGroqModelNames | PreviewGroqModelNames由于 Groq 支持的模型清单变化频繁源码明确列出截至 2025-03-31 的具名模型但在类型上允许传入任意字符串以便使用尚未收录的新模型。需要特别说明的是以上模型清单来源于仓库源码的注释与类型定义仅用于说明GroqModelName的类型设计实际可用模型请以 Groq 官方控制台的模型列表为准Pydantic AI 的类型系统并不会阻止你传入清单之外的模型名。环境变量GROQ_API_KEY拿到 API Key 后最简洁的方式是把它导出为环境变量docs/models/groq.mdexport GROQ_API_KEYyour-api-key从 pydantic_ai_slim/pydantic_ai/providers/groq.py 可以看到GroqProvider的解析顺序显式传入的api_key优先否则回退到GROQ_API_KEY环境变量base_url同理优先取显式参数其次读GROQ_BASE_URL环境变量默认值是https://api.groq.com。如果两者都没有会抛出带指引的UserErrorSet theGROQ_API_KEYenvironment variable or pass it viaGroqProvider(api_key...)to use the Groq provider.三、三种初始化方式3.1 按模型名直接使用推荐入门最省事的写法是不实例化任何模型对象直接把groq:模型名的字符串交给Agentdocs/models/groq.mdfrom pydantic_ai import Agent agent Agent(groq:llama-3.3-70b-versatile)Pydantic AI 会自动解析groq:前缀并走 Groq Provider 的默认初始化逻辑读取环境变量GROQ_API_KEY。Agent构造后即可正常await agent.run(...)或agent.run_sync(...)。3.2 显式初始化GroqModel当你需要更精细地控制模型对象时可以直接构造GroqModel只传模型名即可docs/models/groq.mdfrom pydantic_ai import Agent from pydantic_ai.models.groq import GroqModel model GroqModel(llama-3.3-70b-versatile) agent Agent(model)从源码看GroqModel.__init__的完整签名是pydantic_ai_slim/pydantic_ai/models/groq.pydef __init__( self, model_name: GroqModelName, *, provider: Literal[groq, gateway] | Provider[AsyncGroq] groq, profile: ModelProfileSpec | None None, settings: ModelSettings | None None, ):provider可以是字符串groq默认走 Groq 官方 API或gateway走 Pydantic AI Gateway也可以是任意Provider[AsyncGroq]实例传入字符串时内部调用infer_provider完成解析profile模型 Profile默认由 Provider 根据模型名挑选下文会展开settings模型级默认设置用于为所有请求统一覆盖ModelSettings。GroqModel暴露了三个常用只读属性client底层AsyncGroq客户端、base_url如https://api.groq.com、system返回groq。测试 tests/models/test_groq.py 中的test_init验证了这些属性与 Provider 的关联关系。3.3 通过provider参数注入自定义 Provider官方文档强调可以通过provider参数传入自定义的GroqProviderdocs/models/groq.mdfrom 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的构造参数pydantic_ai_slim/pydantic_ai/providers/groq.py如下参数类型说明api_keystr \| NoneAPI Key不传则读GROQ_API_KEY环境变量base_urlstr \| None请求基地址不传则读GROQ_BASE_URL默认https://api.groq.comhttp_clienthttpx.AsyncClient \| None自定义 HTTP 客户端与groq_client互斥groq_clientAsyncGroq \| None直接复用已构造的AsyncGroq实例此时api_key/base_url/http_client必须为None否则触发断言3.4 自定义httpx.AsyncClient更进阶的用法是定制底层 HTTP 传输层。你可以构造一个带超时、代理、连接池配置的httpx.AsyncClient注入到GroqProvider中docs/models/groq.mdfrom 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)从源码实现看当提供了http_client时GroqProvider直接以AsyncGroq(base_urlbase_url, api_keyapi_key, http_clienthttp_client)构建客户端未提供时则调用create_async_http_client()创建默认客户端并自持生命周期pydantic_ai_slim/pydantic_ai/providers/groq.py。这意味着自定义AsyncClient的超时、限流、代理等策略会完整作用于 Groq 请求。四、SDK 层重试与传输层重试正确叠加文档单独用一节说明 SDK 重试行为docs/models/groq.mdGroqProvider内部构建的AsyncGroq客户端和 OpenAI 客户端一样会自己对失败的请求进行重试默认max_retries2。如果你想只让传输层transport负责重试策略可以传入groq_clientAsyncGroq(max_retries0)关闭 SDK 层重试from groq import AsyncGroq 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)), )为什么值得关注这一层Pydantic AI 的重试文档 docs/retries.md 给出了清晰的层级说明在传输层重试之上、模型agent之下还夹着一层Provider SDK 自己的客户端重试。这两层是叠加而非互相替代的关系——配置其中一层并不会关闭另一层。对于一个失败的 HTTP 请求可能先被 SDK 客户端重试若干次再被传输层重试若干次最终才冒泡到 Agent而 agent 侧对前几层重试毫不知情。各 Provider 的 SDK 重试设置见 docs/retries.md 中列出的文档链接OpenAI、Anthropic、Google、Groq、Cohere、Bedrock 各自不同。此外 docs/retries.md 还提醒FallbackModel是换模型而不是重试——瞬态失败应该重试同一 ProviderProvider 真正不可用才考虑切换到别的 Provider。五、源码级原理GroqModel的底层调用链5.1 请求主流程GroqModel继承自Model[AsyncGroq]核心请求都汇聚到_completions_createpydantic_ai_slim/pydantic_ai/models/groq.py最终调用self.client.chat.completions.create(...)。从源码可以看到请求参数与ModelSettings的映射关系Groq API 参数来源ModelSettings字段model构造时传入的model_namemessages经_map_messages转换后的 Groq 消息格式tools/tool_choice_get_tool_choice解析后的工具定义与选择策略max_tokens/temperature/top_p/seed对应ModelSettings字段presence_penalty/frequency_penalty/logit_bias对应ModelSettings字段stopstop_sequencesresponse_format结构化输出native 模式走json_schemaprompted 模式且模型支持时走json_objectparallel_tool_calls仅在有工具时透传extra_headers默认注入User-Agentget_user_agent()非流式响应在_process_response中处理流式响应则由GroqStreamedResponse逐 chunk 消费thinking 增量、文本增量、工具调用增量分别交给_parts_manager的对应处理器。5.2 错误处理与模型名建议_map_api_errors上下文管理器pydantic_ai_slim/pydantic_ai/models/groq.py把 Groq SDK 的APIStatusError/APIConnectionError统一转换为 Pydantic AI 的ModelHTTPError/ModelAPIError当错误体中出现error.code model_not_found时还会调用_suggest_known_model_id_from_provider_error给出相近模型名建议对应 docs/models/overview.md 的模型名提示机制。测试test_model_status_error/test_model_connection_errortests/models/test_groq.py分别验证了 500 状态码和连接超时两条路径的异常转换。另外Groq SDK 在模型生成的工具参数不符合 schema时会自作主张抛异常而GroqModel.request会解析这种tool_use_failed错误体_parse_tool_use_failed_error把失败的生成物还原成ToolCallPart或TextPart返回从而让 Agent 自己决定如何重试工具调用——而不是直接失败。5.3GroqModelSettingsGroq 专属推理设置除了通用的ModelSettings模块还定义了带groq_前缀的专属设置pydantic_ai_slim/pydantic_ai/models/groq.pygroq_reasoning_format: Literal[hidden, raw, parsed]—— 控制推理输出格式hidden抑制推理输出模型内部仍会推理、raw把think标签原样留在内容里、parsed将推理内容解析为独立的ThinkingPartgroq_reasoning_effort: Literal[none, default, low, medium, high]—— 推理努力程度取值因模型家族而异。这两个字段必须带groq_前缀目的是保证不同模型的设置可以安全合并。在请求组装时_translate_thinking会把统一的thinking语义映射到reasoning_format显式设置了groq_reasoning_format则优先thinkingFalse时对可关闭推理的模型qwen3 家族通过reasoning_effortnone真正关闭其余模型退化为hiddenthinkingTrue则用parsed。这些映射逻辑集中在 pydantic_ai_slim/pydantic_ai/profiles/groq.py 的groq_model_profile与GROQ_GPT_OSS_REASONING_EFFORT_MAP中更完整的统一推理语义见 docs/capabilities/thinking.md。5.4 原生工具Web 搜索GroqModel.supported_native_tools()返回frozenset({WebSearchTool})即 Groq 模型唯一内置支持的原生工具是网络搜索pydantic_ai_slim/pydantic_ai/models/groq.py。_get_native_tools的实现细节仅groq/compound系列模型groq_always_has_web_search_builtin_toolTrue支持WebSearchTool其他模型调用会抛UserErrorcompound 模型隐式执行搜索因此 Pydantic AI 不发送工具定义而是把WebSearchTool的域名过滤规则allowed_domains→include_domainsblocked_domains→exclude_domains作为search_settings透传给 API响应中的executed_tools类型search会被映射为NativeToolCallPartNativeToolReturnPart流式模式下分别按增量处理。对应测试 tests/models/test_groq.pytest_groq_model_web_search_tool演示了带搜索能力的天气 Agent 端到端调用录制的 VCR 磁带位于 tests/models/cassettes/test_groq/。5.5 多模态输入的能力边界_map_user_prompt揭示了 Groq 模型当前的多模态边界pydantic_ai_slim/pydantic_ai/models/groq.py支持文本内容、ImageUrl含force_download时自动下载转 base64、图片BinaryContent图片还支持vendor_metadata[detail]low/high/auto透传测试test_image_detail_vendor_metadata验证了这一点不支持BinaryContent中的非图片媒体抛NotImplementedError: Only images are supported for BinaryContent in Groq user prompts、DocumentUrl、AudioUrl、VideoUrl、UploadedFile。这也解释了为什么项目测试目录里同时存在 tests/models/cassettes/test_multimodal_tool_returns/ 下大量 Groq 相关的多模态返回矩阵用例——Groq 在 Pydantic AI 的多模态测试矩阵中是重要成员但能力边界由 Groq API 本身决定。六、验证与测试资源仓库为 Groq 模型提供了完整的测试覆盖可作为你本地集成的参照单元/集成测试tests/models/test_groq.py请求、流式、工具调用、结构化输出、图像输入、错误映射、原生工具等录制请求磁带tests/models/cassettes/test_groq/VCR 重放无需真实 API Key 即可跑通Provider 层测试tests/providers/test_groq.py 与 tests/providers/cassettes/test_gateway/test_gateway_provider_with_groq.yamlAPI 参考文档docs/api/models/groq.md。此外GroqProvider.model_profile会根据模型名前缀为不同模型家族挑选 Profilepydantic_ai_slim/pydantic_ai/providers/groq.pyllama/meta-llama/走 Meta、gemma走 Google、qwen走 Qwen、deepseek走 DeepSeek、mistral走 Mistral、openai/走 OpenAI、compound-/groq/compound走 Groq 自身的 Profile最后再与 Groq 的推理相关 Profile 合并——保证每个模型家族拿到正确的推理、JSON 输出等能力标记。七、小结围绕 Groq 接入你可以按三层递进组织你的代码开箱即用Agent(groq:llama-3.3-70b-versatile)GROQ_API_KEY环境变量显式控制GroqModel(llama-3.3-70b-versatile, providerGroqProvider(api_key...))深度定制注入自定义httpx.AsyncClient超时/代理/连接池或复用既有AsyncGroq实例含max_retries调整并正确理解 SDK 层重试与传输层重试的叠加关系。在功能层面Groq 模型在 Pydantic AI 中支持工具调用、结构化输出native JSON Schema、流式输出、图像输入以及 compound 系列的内置 Web 搜索推理模型的reasoning_format/reasoning_effort则通过GroqModelSettings统一管理。把握住模型对象 Provider 对象 传输层这一分层结构你就能像替换其他任何模型一样无缝地把应用切换到 Groq 高速推理后端。【免费下载链接】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），仅供参考