尧图网站设计 尧图网站设计YAOTU DESIGN
ARTICLE DETAIL

资讯详情

深耕网站设计与一线实操的经验洞察。

Pydantic AI 安装完全指南:标准安装、Slim 裁剪安装与模型扩展配置

Pydantic AI 安装完全指南:标准安装、Slim 裁剪安装与模型扩展配置 Pydantic AI 安装完全指南标准安装、Slim 裁剪安装与模型扩展配置【免费下载链接】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 在 Python 环境中的安装方式从一行命令完成的标准安装到按需裁剪的pydantic-ai-slim精简安装再到针对各类模型提供商、工具链与观测平台的 optional extras 选择。读完本文你将掌握如何根据具体模型与使用场景组合出最合适的安装命令理解 TLS 证书校验规则、Logfire 可观测性集成的启用方式以及如何运行官方示例代码。环境要求与核心依赖Pydantic AI 要求Python 3.10 及以上版本。这一下限在项目打包配置中多处声明根目录 pyproject.toml 与 pydantic_ai_slim/pyproject.toml 均设置了requires-python 3.10同时声明的版本支持矩阵覆盖 Python 3.10 至 3.14。pydantic-ai-slim的核心运行时依赖见 pydantic_ai_slim/pyproject.toml包括anyio4.7.0异步 I/O 基础设施流式会话的取消交付依赖该版本下限griffelib2.0函数签名解析用于从 Python 函数签名与 docstring 生成工具 schemahttpx22.7下一代 HTTP 客户端详见下文 TLS 一节pydantic2.12数据验证层Agent 的输入输出类型系统的基础pydantic-graph{version}与当前版本严格对齐的图执行引擎opentelemetry-api1.28.0观测性接口typing-inspection0.4.0、genai-prices0.1.6分别用于类型内省与模型价格数据exceptiongroup1.2.2仅 Python 3.11 时需要。可见即便是精简包也自带了一整套 Agent 运行所需的类型系统、HTTP 传输与可观测性底座。标准安装一条命令即可上手Pydantic AI 以pydantic-ai为名发布在 PyPI 上安装非常简单pip/uv-add pydantic-ai说明文档中的pip/uv-add是快捷记法等价于pip install pydantic-ai或uv add pydantic-ai后者在基于 uv 管理的项目中推荐使用。两种工具任选其一即可。这一条命令装好的不只是pydantic_ai包本身还包含核心依赖见上文清单OpenAI、Anthropic、Google 三个模型的客户端 SDK开箱即用CLI终端内与 LLM 对话、启动 Web 服务的clai命令行工具MCP模型上下文协议客户端支持EvalsPydantic Evals 评测框架Web UI内置的 Web 聊天界面与事件流支持Logfire可观测性集成。这一默认组合在根 pyproject.toml 中有明确的打包证据pydantic-ai的依赖被声明为pydantic-ai-slim[openai,anthropic,google,cli,mcp,evals,web,logfire]{version}即标准安装本质上就是 slim 包加上默认选中的 8 个 extras。按需添加其他模型或集成若要使用其他模型提供商Bedrock、Mistral、Groq、xAI、Cohere、Cerebras 等或 Temporal/DBOS/Prefect 等持久执行后端可在安装命令中追加对应的 extraspip/uv-add pydantic-ai[bedrock,temporal]由于根包的 extras 全部通过pydantic-ai-slim[同名 extra]{version}转发见 pyproject.toml标准安装支持的所有 extras 名称与pydantic-ai-slim完全一致完整清单见下文 Slim 安装 一节。TLS 证书校验系统信任存储 vs certifiPydantic AI 自身的 HTTP 请求以及已迁移到httpx2的模型提供商 SDK 发出的请求默认使用操作系统的信任存储来校验 TLS 证书而不是随包附带certifi证书包。这一行为对以下场景有直接影响极简容器镜像alpine等精简镜像往往没有安装 CA 证书需要在镜像中显式安装例如ca-certificates包以及企业代理的根 CA 证书使用私有 CA 的企业代理代理签发的证书不在系统信任链内时需要把私有根 CA 安装进运行环境。另一种规避方式是绕过库内建客户端给相应模型提供商传入你自己配置好的httpx2.AsyncClient通过其http_client参数证书策略完全由你掌控。各提供商接受哪种客户端参见 模型提供商文档。需要注意的例外仍使用 legacyhttpx的 SDK如 Groq 与 Cohere会继续沿用certifi证书校验此时传入的自定义客户端类型是 legacy 的httpx.AsyncClient。在写代码前先确认目标模型走的是哪条 HTTP 栈能避免大量证书校验失败的排查时间。与 Pydantic Logfire 集成Pydantic AI 与 Pydantic Logfire 有优秀但完全可选的集成用于查看和理解 Agent 运行过程包括每一次模型请求、工具调用的 span 与整条 trace。Logfire 已包含在标准版pydantic-ai中slim 版本不含需通过logfireextra 单独安装。安装完成后按 Logfire 使用文档 初始化即可pip/uv-add pydantic-ai # 标准包已内置 logfire 依赖 logfire auth # 认证本地环境 logfire projects new # 创建或 use 一个已有的项目之后在代码中启用埋点import logfire from pydantic_ai import Agent logfire.configure() # 默认从 .logfire 目录读取配置 logfire.instrument_pydantic_ai() # 开启 Pydantic AI 插桩 agent Agent(openai:gpt-5.2, namehello_world_agent, instructionsBe concise, reply with one sentence.) result agent.run_sync(Where does hello world come from?) print(result.output)若使用 slim 包则通过logfireextra 安装pip/uv-add pydantic-ai-slim[logfire]对应的依赖声明为logfire[httpx]4.39.0与opentelemetry-instrumentation-httpx0.65b0见 pydantic_ai_slim/pyproject.toml。运行官方示例pydantic-ai-examples官方示例代码作为独立的 PyPI 包pydantic-ai-examples单独分发便于你直接定制与运行。示例包的内容在仓库 examples/pydantic_ai_examples/ 目录下其打包配置见 examples/pyproject.toml依赖了pydantic-ai-slim[openai,google,groq,anthropic,ag-ui,realtime]、pydantic-evals、fastapi、gradio、uvicorn、mcp[cli]等完整示例运行环境。通过examples可选组安装pip/uv-add pydantic-ai[examples]运行方式与更多细节见 示例文档核心用法包括# 运行指定示例模块 python/uv-run -m pydantic_ai_examples.example_module_name # 例如运行最简单的 pydantic_model 示例 python/uv-run -m pydantic_ai_examples.pydantic_model # 使用 uv 的零配置一行运行无需先安装 OPENAI_API_KEYyour-api-key \ uv run --with pydantic-ai[examples] \ -m pydantic_ai_examples.pydantic_model # 将示例复制到本地目录便于编辑 python/uv-run -m pydantic_ai_examples --copy-to examples/多数示例需要配置 LLM 鉴权环境变量最常见的是export OPENAI_API_KEYyour-api-key # OpenAI export GEMINI_API_KEYyour-api-key # Google Gemini完整的环境变量配置说明见 模型配置文档。Slim 安装按需裁剪避免装无用依赖如果你已经确定要使用哪个模型且希望避免安装多余的包可以直接使用pydantic-ai-slim包。例如只使用OpenAIChatModel时pip/uv-add pydantic-ai-slim[openai]slim包仅携带上文列出的核心运行时依赖pydantic-ai的标准安装其实就是它的超集。它的pydantic_ai模块源码与完整版共用见 pydantic_ai_slim/pydantic_ai/区别只在于默认附带的 extras。Slim 可选组完整清单下表整理了pydantic-ai-slim的全部 optional groups 及其对应的依赖依据 pydantic_ai_slim/pyproject.toml 与官方安装文档Extra用途安装的依赖logfirePydantic Logfire 可观测性logfire[httpx]4.39.0、opentelemetry-instrumentation-httpx0.65b0evalsPydantic Evals 评测框架pydantic-evals{version}openaiOpenAI 模型openai3.8.0、tiktoken0.12.0googleGoogle 模型google-genai2.18.0anthropicAnthropic 模型anthropic1.3.0groqGroq 模型groq0.25.0mistralMistral 模型mistralai2.9.2cohereCohere 模型cohere5.20.6bedrockBedrock 模型boto31.42.63bedrock-mantleBedrock Mantle 模型openai3.8.0、botocore1.42.63xaixAI 模型xai-sdk1.16.0openrouterOpenRouteropenai3.8.0zaiZ.AI 模型openai3.8.0snowflakeSnowflake Cortex 模型openai3.8.0crusoeCrusoe 模型openai3.8.0cerebrasCerebras 模型openai3.8.0huggingfaceHugging Face 模型huggingface-hub1.3.4,2.0.0等sentence-transformers本地 Sentence Transformers 嵌入sentence-transformers5.2.0Python 3.14voyageaiVoyageAI 嵌入模型voyageai0.3.7Python 3.14duckduckgoDuckDuckGo 搜索工具ddgs9.0.0tavilyTavily 搜索工具tavily-python0.5.0exaExa 搜索工具exa-py2.0.0web-fetchWeb Fetch 工具markdownify1.2cliCLI 交互命令行rich13、prompt-toolkit3、argcomplete3.5.0、pyperclip1.9.0、pyyaml6.0.2realtime实时语音会话传输层websockets14.0openai-realtimeOpenAI Realtime 语音pydantic-ai-slim[openai,realtime]google-realtimeGoogle Gemini Live 语音pydantic-ai-slim[google,realtime]xai-realtimexAI Grok Voice 语音pydantic-ai-slim[xai,openai,realtime]mcpMCP 客户端fastmcp-slim[client]3.3.0,5mcp-tasksMCP FastMCP 4 任务扩展use_taskTruefastmcp-tasks4.0.0b1,5、fastmcp-slim[client]4.0.0b1,5uiUI 事件流starlette0.46.2webWeb UI含内置服务器starlette1.3.1、uvicorn0.38.0ag-uiAG-UI 事件流协议ag-ui-protocol0.1.10、starlette0.46.2retries传输层重试tenacity8.2.3、httpx0.27temporalTemporal 持久执行temporalio1.24.0dbosDBOS 持久执行dbos2.10.0prefectPrefect 持久执行prefect3.7.5specAgentSpec YAML/JSON Agent 定义pyyaml6.0.2、pydantic-handlebars0.1.0几个值得注意的细节OpenAI 兼容系openrouter、zai、snowflake、crusoe、cerebras等 providers 复用的是openaiSDK因此依赖条目都是openai3.8.0realtime 系openai-realtime等三个 extra 是指向其他 extra 的聚合组xai-realtime之所以同时带上openai是因为 xAI 的实时 API 复用 OpenAI 的编解码器Python 版本约束sentence-transformers与voyageai在 Python 3.14 下暂不提供配置中有python_version 3.14条件标记。组合多个 extras可以同时安装多个模型与用途的依赖例如pip/uv-add pydantic-ai-slim[openai,google,logfire]这样一条命令即可得到一个只含 OpenAI Google 模型 Logfire 观测的轻量环境。从源码开发安装可选如果你想在本地开发或贡献代码仓库使用 uv 的[tool.uv.workspace]声明workspace 成员包括pydantic_ai_slim、pydantic_evals、pydantic_graph、clai与examplesMakefile 提供了开发环境安装入口make install # 等价于 uv sync --frozen --all-extras --no-extra mcp-tasks --all-packages --group lint仓库在 Makefile 中特意排除了mcp-tasksextra它与开发组锁定的 FastMCP 3 存在依赖分叉FastMCP 4 处于预发布阶段日常开发不引入该 extra 以避免解析冲突。快速验证安装安装完成后可以用官方内置的test模型快速验证环境无需任何 API Keyfrom pydantic_ai import Agent agent Agent(test) result agent.run_sync(Hello!) print(result.output)或者使用 CLI 直接开始终端对话clai --model openai:gpt-5.2 # 需要先设置 OPENAI_API_KEY常见问题速查装完pydantic-ai后能用哪些模型默认含 OpenAI、Anthropic、Google其他模型Bedrock、Groq、Mistral、xAI、Cohere 等需要追加对应 extras如pydantic-ai[bedrock]。容器内出现 TLS 证书校验失败这是httpx2走系统信任存储所致安装ca-certificates包或注入企业根 CA或通过http_client传入自定义httpx2.AsyncClient。只想用极简依赖使用pydantic-ai-slim[你需要的 extra]例如只做 OpenAI 嵌入/对话pydantic-ai-slim[openai]。pydantic-ai与pydantic-ai-slim关系前者是后者的完整超集默认附加 8 个 extras后者只含核心运行时两者pydantic_ai源码同一可随时切换。【免费下载链接】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),仅供参考
返回列表