在 pydantic-ai 中使用 Hugging Face Inference Providers 构建 Agent安装、配置与源码级解析【免费下载链接】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-aiHugging Face 聚合了几乎所有主流开源模型其 Inference Providers 服务让 DeepSeek-R1、Qwen3、Llama 4 等开源模型可以通过无服务器基础设施按需调用。本文以 docs/models/huggingface.md 为骨架完整讲解如何在 pydantic-ai 中通过HuggingFaceModel接入 Hugging Face Inference Providers覆盖安装、令牌配置、Provider 选择、自定义客户端并深入到 HuggingFaceModel 实现 与 HuggingFaceProvider 实现 的源码层面帮助读者理解工具调用、思考内容、多模态输入等能力的底层机制。安装要使用HuggingFaceModel有两种安装方式直接安装完整的pydantic-ai包安装pydantic-ai-slim并带上huggingface可选组extra该可选组会额外拉取huggingface_hub依赖pip/uv-add pydantic-ai-slim[huggingface]从 模型实现 的导入逻辑可以看到huggingface_hub是硬依赖若未安装导入时会直接抛出ImportError提示使用huggingface可选组安装。而 Provider 实现 中特意在huggingface_hub导入成功后才导入httpx以保证缺少 extra 时用户看到的是可操作的安装提示而不是ModuleNotFoundError: httpx。配置 Hugging Face 访问凭证使用 Hugging Face 推理服务前需要完成三步配置前往 Hugging Face 官网注册账号有免费额度可用于 Inference Providers在账号设置中创建一个新的访问令牌Access Token将令牌设置为环境变量HF_TOKENexport HF_TOKENhf_token从 Provider 源码 可见HuggingFaceProvider初始化时会先读取环境变量HF_TOKEN若未设置环境变量也未显式传入api_key会抛出UserError提示设置HF_TOKEN环境变量或通过HuggingFaceProvider(api_key...)传入。基本用法两种初始化方式方式一通过模型名直接声明pydantic-ai 支持用huggingface:前缀的模型名直接创建 Agentfrom pydantic_ai import Agent agent Agent(huggingface:Qwen/Qwen3-235B-A22B)在 已知模型名注册表 中可以看到当前内置支持的 Hugging Face 模型清单包括huggingface:deepseek-ai/DeepSeek-R1huggingface:Qwen/Qwen3-235B-A22Bhuggingface:Qwen/Qwen3-32Bhuggingface:Qwen/Qwen2.5-72B-Instructhuggingface:Qwen/QwQ-32Bhuggingface:meta-llama/Llama-3.3-70B-Instructhuggingface:meta-llama/Llama-4-Maverick-17B-128E-Instructhuggingface:meta-llama/Llama-4-Scout-17B-16E-Instruct当然模型名并不局限于上述列表任意huggingface:组织/模型名形式均可使用源码类型定义为str | LatestHuggingFaceModelNames。底层Agent(huggingface:...)会通过 infer_provider 解析出huggingface对应的 HuggingFaceProvider。方式二直接实例化模型也可以显式创建HuggingFaceModel实例并传入 Agentfrom pydantic_ai import Agent from pydantic_ai.models.huggingface import HuggingFaceModel model HuggingFaceModel(Qwen/Qwen3-235B-A22B) agent Agent(model)HuggingFaceModel的构造签名见 models/huggingface.py支持四个参数model_name模型名必填、provider可传字符串huggingface或Provider[AsyncInferenceClient]实例默认huggingface、profile模型画像默认由 Provider 根据模型名挑选、settings模型级默认设置。Provider 的自动选择逻辑默认情况下HuggingFaceModel使用HuggingFaceProvider它会自动为模型选择第一个可用的推理供应商如 Cerebras、Together AI、Cohere 等排序依据是你在https://hf.co/settings/inference-providers中配置的首选顺序不指定provider_name时默认值为auto。从 Provider 的base_url属性providers/huggingface.py可以看到请求地址最终形如https://router.huggingface.co/provider这一推断也被测试中的provider_urlhttps://router.huggingface.co/together所印证。配置 Inference Provider如果你希望在代码中显式指定推理供应商而不是依赖自动选择可以实例化HuggingFaceProvider并通过provider_name参数指定from pydantic_ai import Agent from pydantic_ai.models.huggingface import HuggingFaceModel from pydantic_ai.providers.huggingface import HuggingFaceProvider model HuggingFaceModel(Qwen/Qwen3-235B-A22B, providerHuggingFaceProvider(api_keyhf_token, provider_namenebius)) agent Agent(model)HuggingFaceProvider构造参数见 providers/huggingface.py说明参数含义与约束api_key访问令牌不传时回退读取环境变量HF_TOKEN两者皆无则抛UserErrorprovider_name推理供应商名称默认auto自动选择传入base_url时该参数不再生效base_url自定义请求基础地址与provider_name不能同时提供否则抛ValueErrorhf_client已配置好的AsyncInferenceClient实例传入后其余参数不再用于创建客户端http_client目前被忽略若传入会抛ValueError请改用hf_client值得注意的是Provider 的model_profile静态方法providers/huggingface.py会为deepseek-ai、google、qwen、meta-llama、mistralai、moonshotai等已识别组织下的模型自动挑选对应的模型画像含思维标签、内联系统提示支持等未识别组织则返回None。自定义 AsyncInferenceClient 客户端HuggingFaceProvider还接受一个自定义的AsyncInferenceClient实例通过hf_client参数从而可以精细控制headers、bill_to将账单记到你所属的 HF 组织、base_url等选项from huggingface_hub import AsyncInferenceClient from pydantic_ai import Agent from pydantic_ai.models.huggingface import HuggingFaceModel from pydantic_ai.providers.huggingface import HuggingFaceProvider client AsyncInferenceClient( bill_toopenai, api_keyhf_token, providerfireworks-ai, ) model HuggingFaceModel( Qwen/Qwen3-235B-A22B, providerHuggingFaceProvider(hf_clientclient), ) agent Agent(model)传入hf_client后Provider 不再自行创建客户端而是直接复用该实例self._client hf_client。由于AsyncInferenceClient是huggingface_hub库提供的类型headers、base_url、超时、代理等更多定制项可参考 Hugging Face Hub Python 库的官方文档按需配置。流式响应与取消HuggingFaceModel支持流式输出request_stream走streamTrue分支见 models/huggingface.py在流式响应结束时还会对响应对象调用aclose()释放资源。关于流取消需要特别注意StreamedRunResult.cancel()能安全地中断本地的流拉取包括在其他任务中运行的拉取但huggingface_hub.AsyncInferenceClient把 HTTP 响应保留在客户端持有的退出栈exit stack中且没有暴露文档化的按流传输句柄因此关闭返回的迭代器并不能保证立即中断 HTTP 传输也无法保证远端生成与计费立即停止。如果你的应用对成本控制敏感请在取消后自行在服务端或账户侧核对用量。源码级剖析HuggingFaceModel 的内部机制模型设置到请求参数的映射HuggingFaceModel在发起请求时models/huggingface.py会调用self.client.chat.completions.create(...)并将 pydantic-ai 的ModelSettings字段逐一映射为 Hugging Face API 参数pydantic-ai 设置项HF API 参数max_tokensmax_tokensstop_sequencesstoptemperaturetemperaturetop_ptop_pseedseedpresence_penaltypresence_penaltyfrequency_penaltyfrequency_penaltylogit_biaslogit_biaslogprobslogprobstop_logprobstop_logprobsextra_bodyextra_body透传附加请求体测试用例test_max_completion_tokenstests/models/test_huggingface.py验证了通过ModelSettings(max_tokens100)可以约束单次输出的 token 上限。工具调用与 tool_choice_get_tool_choice方法models/huggingface.py负责把 pydantic-ai 的 tool_choice 语义翻译给 Hugging Faceauto/required直接透传none使用原生none模式禁用工具调用同时保留工具定义的缓存指定单个必选工具构造ChatCompletionInputToolChoiceClass指定多个必选工具Hugging Face 不支持通过 API 参数裁剪工具因此实现上会先在本地过滤tool_defs再整体透传注释明确说明这会破坏缓存。工具的 JSON Schema 描述与参数会映射为ChatCompletionInputTool见_map_tool_definition工具调用结果与重试提示则映射为roletool的消息。测试test_request_tool_call完整验证了工具调用 → 工具执行 → 失败重试 → 再次调用 → 最终回答的多轮交互链路。思考内容Thinking的处理对于 DeepSeek-R1 这类会输出思考过程的模型_process_response使用split_content_into_text_and_thinking配合模型画像中的thinking_tags默认标签为think把响应拆分为ThinkingPart与TextPart回传历史消息时ThinkingPart会被重新包裹上开始/结束标签models/huggingface.py。测试test_hf_model_thinking_part与test_thinking_part_in_historytests/models/test_huggingface.py分别验证了非流式响应中的思考拆分以及带思考内容的历史消息会被正确编码为think.../think文本。多模态输入支持与限制_map_user_promptmodels/huggingface.py对用户内容做了如下分类处理支持纯文本、TextContent、ImageUrl、图片类BinaryContent以 data URI 形式转发为image_url明确不支持AudioUrl、DocumentUrl、VideoUrl、UploadedFile均抛出NotImplementedError测试test_unsupported_media_types逐一断言了这些错误信息静默忽略CachePointHugging Face 不支持通过 CachePoint 做提示词缓存见测试test_cache_point_filtering。图片输入在真实调用中已被验证test_image_url_input与test_image_as_binary_content_input使用Qwen/Qwen2.5-VL-72B-Instruct分别通过 URL 与二进制内容喂入图片并成功得到多模态回答。错误处理与用量统计API 层错误统一通过_map_api_errors上下文管理器捕获HfHubHTTPError并转换为 pydantic-ai 的ModelHTTPError携带 status_code、模型名、响应体与响应头见 models/huggingface.py。测试test_model_status_error验证了 500 错误会被正确包装并保留x-request-id等响应头。用量统计方面_map_usage把 HF 返回的prompt_tokens/completion_tokens映射为 pydantic-ai 的input_tokens/output_tokensmodels/huggingface.py流式响应会在每个 chunk 到达时增量累加结合项目内置的价格表RunUsage中还会附带估算成本如测试快照中的costDecimal(0.001391)。一个可运行的完整示例综合以上内容一个完整的、指定供应商并启用结构化输出的 Agent 可以这样写from pydantic_ai import Agent from pydantic_ai.models.huggingface import HuggingFaceModel from pydantic_ai.providers.huggingface import HuggingFaceProvider model HuggingFaceModel( deepseek-ai/DeepSeek-R1, providerHuggingFaceProvider(provider_nametogether, api_keyhf_token), ) agent Agent(model, output_typelist[int]) result agent.run_sync(What are the first three prime numbers? Return them as a list of integers.) print(result.output) # [2, 3, 5]已知边界与注意事项本地 Embedding 不走本页方案本页只覆盖 Hugging Face Inference Providers 的对话补全。若要在本地运行 Hugging Face 的embedding模型无需 API Key、无网络调用请使用 Sentence Transformers 本地嵌入模型它兼容 sentence-transformers 库中的任意预训练模型。流取消的传输语义如前文所述取消本地拉取不保证远端 HTTP 立即断开需在计费敏感场景自行评估。http_client参数已废弃HuggingFaceProvider不接受httpx.AsyncClient必须通过hf_client传入完整客户端。受限的媒体类型音频、文档、视频与已上传文件当前不被支持多模态仅限图像URL 或二进制。base_url与provider_name互斥同时传入会抛出ValueError传入base_url后自动选择逻辑不再生效。如果需要在测试环境中快速验证集成是否打通可以参考仓库中基于 VCR 录制的真实调用测试tests/models/test_huggingface.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 中使用 Hugging Face Inference Providers 构建 Agent：安装、配置与源码级解析
在 pydantic-ai 中使用 Hugging Face Inference Providers 构建 Agent安装、配置与源码级解析【免费下载链接】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-aiHugging Face 聚合了几乎所有主流开源模型其 Inference Providers 服务让 DeepSeek-R1、Qwen3、Llama 4 等开源模型可以通过无服务器基础设施按需调用。本文以 docs/models/huggingface.md 为骨架完整讲解如何在 pydantic-ai 中通过HuggingFaceModel接入 Hugging Face Inference Providers覆盖安装、令牌配置、Provider 选择、自定义客户端并深入到 HuggingFaceModel 实现 与 HuggingFaceProvider 实现 的源码层面帮助读者理解工具调用、思考内容、多模态输入等能力的底层机制。安装要使用HuggingFaceModel有两种安装方式直接安装完整的pydantic-ai包安装pydantic-ai-slim并带上huggingface可选组extra该可选组会额外拉取huggingface_hub依赖pip/uv-add pydantic-ai-slim[huggingface]从 模型实现 的导入逻辑可以看到huggingface_hub是硬依赖若未安装导入时会直接抛出ImportError提示使用huggingface可选组安装。而 Provider 实现 中特意在huggingface_hub导入成功后才导入httpx以保证缺少 extra 时用户看到的是可操作的安装提示而不是ModuleNotFoundError: httpx。配置 Hugging Face 访问凭证使用 Hugging Face 推理服务前需要完成三步配置前往 Hugging Face 官网注册账号有免费额度可用于 Inference Providers在账号设置中创建一个新的访问令牌Access Token将令牌设置为环境变量HF_TOKENexport HF_TOKENhf_token从 Provider 源码 可见HuggingFaceProvider初始化时会先读取环境变量HF_TOKEN若未设置环境变量也未显式传入api_key会抛出UserError提示设置HF_TOKEN环境变量或通过HuggingFaceProvider(api_key...)传入。基本用法两种初始化方式方式一通过模型名直接声明pydantic-ai 支持用huggingface:前缀的模型名直接创建 Agentfrom pydantic_ai import Agent agent Agent(huggingface:Qwen/Qwen3-235B-A22B)在 已知模型名注册表 中可以看到当前内置支持的 Hugging Face 模型清单包括huggingface:deepseek-ai/DeepSeek-R1huggingface:Qwen/Qwen3-235B-A22Bhuggingface:Qwen/Qwen3-32Bhuggingface:Qwen/Qwen2.5-72B-Instructhuggingface:Qwen/QwQ-32Bhuggingface:meta-llama/Llama-3.3-70B-Instructhuggingface:meta-llama/Llama-4-Maverick-17B-128E-Instructhuggingface:meta-llama/Llama-4-Scout-17B-16E-Instruct当然模型名并不局限于上述列表任意huggingface:组织/模型名形式均可使用源码类型定义为str | LatestHuggingFaceModelNames。底层Agent(huggingface:...)会通过 infer_provider 解析出huggingface对应的 HuggingFaceProvider。方式二直接实例化模型也可以显式创建HuggingFaceModel实例并传入 Agentfrom pydantic_ai import Agent from pydantic_ai.models.huggingface import HuggingFaceModel model HuggingFaceModel(Qwen/Qwen3-235B-A22B) agent Agent(model)HuggingFaceModel的构造签名见 models/huggingface.py支持四个参数model_name模型名必填、provider可传字符串huggingface或Provider[AsyncInferenceClient]实例默认huggingface、profile模型画像默认由 Provider 根据模型名挑选、settings模型级默认设置。Provider 的自动选择逻辑默认情况下HuggingFaceModel使用HuggingFaceProvider它会自动为模型选择第一个可用的推理供应商如 Cerebras、Together AI、Cohere 等排序依据是你在https://hf.co/settings/inference-providers中配置的首选顺序不指定provider_name时默认值为auto。从 Provider 的base_url属性providers/huggingface.py可以看到请求地址最终形如https://router.huggingface.co/provider这一推断也被测试中的provider_urlhttps://router.huggingface.co/together所印证。配置 Inference Provider如果你希望在代码中显式指定推理供应商而不是依赖自动选择可以实例化HuggingFaceProvider并通过provider_name参数指定from pydantic_ai import Agent from pydantic_ai.models.huggingface import HuggingFaceModel from pydantic_ai.providers.huggingface import HuggingFaceProvider model HuggingFaceModel(Qwen/Qwen3-235B-A22B, providerHuggingFaceProvider(api_keyhf_token, provider_namenebius)) agent Agent(model)HuggingFaceProvider构造参数见 providers/huggingface.py说明参数含义与约束api_key访问令牌不传时回退读取环境变量HF_TOKEN两者皆无则抛UserErrorprovider_name推理供应商名称默认auto自动选择传入base_url时该参数不再生效base_url自定义请求基础地址与provider_name不能同时提供否则抛ValueErrorhf_client已配置好的AsyncInferenceClient实例传入后其余参数不再用于创建客户端http_client目前被忽略若传入会抛ValueError请改用hf_client值得注意的是Provider 的model_profile静态方法providers/huggingface.py会为deepseek-ai、google、qwen、meta-llama、mistralai、moonshotai等已识别组织下的模型自动挑选对应的模型画像含思维标签、内联系统提示支持等未识别组织则返回None。自定义 AsyncInferenceClient 客户端HuggingFaceProvider还接受一个自定义的AsyncInferenceClient实例通过hf_client参数从而可以精细控制headers、bill_to将账单记到你所属的 HF 组织、base_url等选项from huggingface_hub import AsyncInferenceClient from pydantic_ai import Agent from pydantic_ai.models.huggingface import HuggingFaceModel from pydantic_ai.providers.huggingface import HuggingFaceProvider client AsyncInferenceClient( bill_toopenai, api_keyhf_token, providerfireworks-ai, ) model HuggingFaceModel( Qwen/Qwen3-235B-A22B, providerHuggingFaceProvider(hf_clientclient), ) agent Agent(model)传入hf_client后Provider 不再自行创建客户端而是直接复用该实例self._client hf_client。由于AsyncInferenceClient是huggingface_hub库提供的类型headers、base_url、超时、代理等更多定制项可参考 Hugging Face Hub Python 库的官方文档按需配置。流式响应与取消HuggingFaceModel支持流式输出request_stream走streamTrue分支见 models/huggingface.py在流式响应结束时还会对响应对象调用aclose()释放资源。关于流取消需要特别注意StreamedRunResult.cancel()能安全地中断本地的流拉取包括在其他任务中运行的拉取但huggingface_hub.AsyncInferenceClient把 HTTP 响应保留在客户端持有的退出栈exit stack中且没有暴露文档化的按流传输句柄因此关闭返回的迭代器并不能保证立即中断 HTTP 传输也无法保证远端生成与计费立即停止。如果你的应用对成本控制敏感请在取消后自行在服务端或账户侧核对用量。源码级剖析HuggingFaceModel 的内部机制模型设置到请求参数的映射HuggingFaceModel在发起请求时models/huggingface.py会调用self.client.chat.completions.create(...)并将 pydantic-ai 的ModelSettings字段逐一映射为 Hugging Face API 参数pydantic-ai 设置项HF API 参数max_tokensmax_tokensstop_sequencesstoptemperaturetemperaturetop_ptop_pseedseedpresence_penaltypresence_penaltyfrequency_penaltyfrequency_penaltylogit_biaslogit_biaslogprobslogprobstop_logprobstop_logprobsextra_bodyextra_body透传附加请求体测试用例test_max_completion_tokenstests/models/test_huggingface.py验证了通过ModelSettings(max_tokens100)可以约束单次输出的 token 上限。工具调用与 tool_choice_get_tool_choice方法models/huggingface.py负责把 pydantic-ai 的 tool_choice 语义翻译给 Hugging Faceauto/required直接透传none使用原生none模式禁用工具调用同时保留工具定义的缓存指定单个必选工具构造ChatCompletionInputToolChoiceClass指定多个必选工具Hugging Face 不支持通过 API 参数裁剪工具因此实现上会先在本地过滤tool_defs再整体透传注释明确说明这会破坏缓存。工具的 JSON Schema 描述与参数会映射为ChatCompletionInputTool见_map_tool_definition工具调用结果与重试提示则映射为roletool的消息。测试test_request_tool_call完整验证了工具调用 → 工具执行 → 失败重试 → 再次调用 → 最终回答的多轮交互链路。思考内容Thinking的处理对于 DeepSeek-R1 这类会输出思考过程的模型_process_response使用split_content_into_text_and_thinking配合模型画像中的thinking_tags默认标签为think把响应拆分为ThinkingPart与TextPart回传历史消息时ThinkingPart会被重新包裹上开始/结束标签models/huggingface.py。测试test_hf_model_thinking_part与test_thinking_part_in_historytests/models/test_huggingface.py分别验证了非流式响应中的思考拆分以及带思考内容的历史消息会被正确编码为think.../think文本。多模态输入支持与限制_map_user_promptmodels/huggingface.py对用户内容做了如下分类处理支持纯文本、TextContent、ImageUrl、图片类BinaryContent以 data URI 形式转发为image_url明确不支持AudioUrl、DocumentUrl、VideoUrl、UploadedFile均抛出NotImplementedError测试test_unsupported_media_types逐一断言了这些错误信息静默忽略CachePointHugging Face 不支持通过 CachePoint 做提示词缓存见测试test_cache_point_filtering。图片输入在真实调用中已被验证test_image_url_input与test_image_as_binary_content_input使用Qwen/Qwen2.5-VL-72B-Instruct分别通过 URL 与二进制内容喂入图片并成功得到多模态回答。错误处理与用量统计API 层错误统一通过_map_api_errors上下文管理器捕获HfHubHTTPError并转换为 pydantic-ai 的ModelHTTPError携带 status_code、模型名、响应体与响应头见 models/huggingface.py。测试test_model_status_error验证了 500 错误会被正确包装并保留x-request-id等响应头。用量统计方面_map_usage把 HF 返回的prompt_tokens/completion_tokens映射为 pydantic-ai 的input_tokens/output_tokensmodels/huggingface.py流式响应会在每个 chunk 到达时增量累加结合项目内置的价格表RunUsage中还会附带估算成本如测试快照中的costDecimal(0.001391)。一个可运行的完整示例综合以上内容一个完整的、指定供应商并启用结构化输出的 Agent 可以这样写from pydantic_ai import Agent from pydantic_ai.models.huggingface import HuggingFaceModel from pydantic_ai.providers.huggingface import HuggingFaceProvider model HuggingFaceModel( deepseek-ai/DeepSeek-R1, providerHuggingFaceProvider(provider_nametogether, api_keyhf_token), ) agent Agent(model, output_typelist[int]) result agent.run_sync(What are the first three prime numbers? Return them as a list of integers.) print(result.output) # [2, 3, 5]已知边界与注意事项本地 Embedding 不走本页方案本页只覆盖 Hugging Face Inference Providers 的对话补全。若要在本地运行 Hugging Face 的embedding模型无需 API Key、无网络调用请使用 Sentence Transformers 本地嵌入模型它兼容 sentence-transformers 库中的任意预训练模型。流取消的传输语义如前文所述取消本地拉取不保证远端 HTTP 立即断开需在计费敏感场景自行评估。http_client参数已废弃HuggingFaceProvider不接受httpx.AsyncClient必须通过hf_client传入完整客户端。受限的媒体类型音频、文档、视频与已上传文件当前不被支持多模态仅限图像URL 或二进制。base_url与provider_name互斥同时传入会抛出ValueError传入base_url后自动选择逻辑不再生效。如果需要在测试环境中快速验证集成是否打通可以参考仓库中基于 VCR 录制的真实调用测试tests/models/test_huggingface.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），仅供参考
