在 Pydantic AI 中接入 Cerebras从 API Key 配置到推理模型深度集成【免费下载链接】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-aiCerebras 以 Wafer-Scale EngineWSE驱动的超高速推理著称在 Pydantic AI 生态中通过 OpenAI 兼容接口无缝接入。本文以 docs/models/cerebras.md 为主线结合 pydantic_ai_slim/pydantic_ai/models/cerebras.py 与 pydantic_ai_slim/pydantic_ai/providers/cerebras.py 的源码实现完整讲解 Cerebras 模型的安装、认证、三种初始化方式、自定义 Provider 以及推理thinking行为与模型级设置让你能直接在本仓库的 Pydantic AI 代码库中跑通并调优 Cerebras 模型。一、安装最小可选依赖组在 Pydantic AI 中Cerebras 模型属于可选能力你无需安装完整版pydantic-ai只需安装pydantic-ai-slim并附带cerebras可选组pip/uv-add pydantic-ai-slim[cerebras]该可选组在 pydantic_ai_slim/pyproject.toml 中定义为cerebras [openai3.8.0]即依赖新版 OpenAI SDK3.x。从源码看pydantic_ai_slim/pydantic_ai/models/cerebras.py 在导入时会尝试from openai import AsyncOpenAI若未安装会抛出带有明确安装提示的ImportErrorPlease install the openai package to use the Cerebras model, you can use the cerebras optional group — pip install pydantic-ai-slim[cerebras]注意Cerebras 模型在 Pydantic AI 内部是基于 OpenAI 兼容 API 实现的。CerebrasModel直接继承自OpenAIChatModel见 cerebras.py这解释了为什么openai是硬性依赖。二、获取 API Key 与设置环境变量使用 Cerebras 云 API 前需要先到 Cerebras 云控制台生成 API Key并在 Cerebras 官方模型列表中确认可用的模型名。拿到 API Key 后将其导出为环境变量export CEREBRAS_API_KEYyour-api-key该环境变量名的读取逻辑位于 pydantic_ai_slim/pydantic_ai/providers/cerebras.pyCerebrasProvider.__init__中执行api_key api_key or os.getenv(CEREBRAS_API_KEY)若两者都缺失且未传入现成客户端则抛出UserErrorSet the CEREBRAS_API_KEY environment variable or pass it via CerebrasProvider(api_key...) to use the Cerebras provider.对应测试 tests/providers/test_cerebras.py 专门验证了移除环境变量后必须显式传 key这一行为。三、两种模型初始化方式3.1 按名称字符串解析推荐设置好环境变量后直接用cerebras:前缀 模型名创建 Agentfrom pydantic_ai import Agent agent Agent(cerebras:llama-3.3-70b) ...这里的字符串会被 Pydantic AI 的模型推断机制解析在 pydantic_ai_slim/pydantic_ai/models/init.py 中model_kind cerebras时导入并返回CerebrasModel。测试 tests/providers/test_cerebras.py 验证了infer_model(cerebras:llama-3.3-70b)能正确构造出CerebrasModel且模型名为llama-3.3-70b。3.2 直接实例化 CerebrasModel也可以跳过字符串解析直接以模型名构造from pydantic_ai import Agent from pydantic_ai.models.cerebras import CerebrasModel model CerebrasModel(llama-3.3-70b) agent Agent(model) ...CerebrasModel.__init__的签名见 cerebras.py支持四个参数参数类型默认值说明model_nameCerebrasModelName必填模型名见下文模型名类型providerLiteral[cerebras] \| Provider[AsyncOpenAI]cerebras使用的 Provider默认按名称解析profileModelProfileSpec \| NoneNone模型画像默认根据模型名推导settingsCerebrasModelSettings \| NoneNone模型级默认设置模型名类型与已知模型CerebrasModelName str | LatestCerebrasModelNames其中LatestCerebrasModelNames当前显式列出三个模型cerebras.pygemma-4-31bgpt-oss-120bzai-glm-4.7源码注释明确说明Cerebras 支持的模型种类多且更新频繁因此类型提示中显式列出已知模型但同时允许任意字符串如文档示例中的llama-3.3-70b。已知模型名同样登记在 pydantic_ai_slim/pydantic_ai/models/_known_model_names.py。四、provider参数定制认证与 HTTP 客户端4.1 自定义 API Key如果不想使用环境变量或需要为不同请求使用不同 Key可显式传入CerebrasProviderfrom pydantic_ai import Agent from pydantic_ai.models.cerebras import CerebrasModel from pydantic_ai.providers.cerebras import CerebrasProvider model CerebrasModel( llama-3.3-70b, providerCerebrasProvider(api_keyyour-api-key) ) agent Agent(model) ...CerebrasProvider继承自OpenAICompatibleProvider见 providers/cerebras.py其关键属性在测试 tests/providers/test_cerebras.py 中被锁定name cerebrasbase_url https://api.cerebras.ai/v1client是一个配置好 Key 的AsyncOpenAI实例此外Provider 在创建 OpenAI 客户端时会自动附带请求头X-Cerebras-3rd-Party-Integration: pydantic-ai见 providers/cerebras.py标识集成来源。4.2 自定义 HTTP 客户端CerebrasProvider还接受httpx2.AsyncClient兼容旧版httpx.AsyncClient用于精细控制超时、代理与连接池from httpx2 import AsyncClient from pydantic_ai import Agent from pydantic_ai.models.cerebras import CerebrasModel from pydantic_ai.providers.cerebras import CerebrasProvider custom_http_client AsyncClient(timeout30) model CerebrasModel( llama-3.3-70b, providerCerebrasProvider(api_keyyour-api-key, http_clientcustom_http_client), ) agent Agent(model) ...从构造函数签名providers/cerebras.py看CerebrasProvider还支持第三种更底层的传入方式直接给一个现成的AsyncOpenAI客户端openai_client...此时api_key与http_client必须保持为None。底层客户端生命周期由 pydantic_ai_slim/pydantic_ai/providers/_openai_compatible.py 统一管理未传入http_client时自动创建 httpx2 客户端传入旧版 httpx 客户端时发出兼容性警告。4.3 Provider 解析当provider使用字符串cerebras默认值时会在 pydantic_ai_slim/pydantic_ai/providers/init.py 中通过名称查表导入CerebrasProvider即按名称使用模型与直接构造模型两条路径最终汇聚到同一个 Provider 实现。五、模型画像Model Profile按模型名自动调优CerebrasProvider.model_profile()见 providers/cerebras.py会按模型名前缀自动套用不同的行为画像这是直接用cerebras:llama-3.3-70b就能跑背后的关键机制模型前缀画像说明llamameta 画像使用内联定义式 JSON Schema 转换器qwenqwen 画像同上gpt-ossharmony 画像使用 OpenAI 标准 JSON Schema 转换器zaizai 画像同上且推理按think标签重放画像还声明了三个对 Cerebras 行为影响深远的能力源码注释与测试 tests/providers/test_cerebras.py 均有验证openai_unsupported_model_settings(logit_bias,)Cerebras 虽接受并校验logit_bias但实际不生效偏置前后 logprobs 逐位相同若转发大偏置表反而会在 Cerebras 侧触发 400 错误因此 Pydantic AI 将其静默剥离thinking_always_enabledgpt-oss在 Cerebras 上无条件推理disable_reasoningTrue会被 400 拒绝因此thinkingFalse必须被静默忽略而非发出zai-glm-4.7仍可显式关闭openai_chat_send_back_thinking_partszai/GLM 要求把先前推理以think.../think标签形式重放进 assistant 消息的content而gpt-ossHarmony 规则在独立的reasoning字段中重放。六、模型级设置推理控制与多轮思考保留CerebrasModelSettings继承自ModelSettingscerebras.py源码强制要求所有 Cerebras 专属字段以cerebras_前缀命名以便与其他模型设置合并时不冲突设置字段类型说明cerebras_disable_reasoningbool禁用模型推理。已弃用请改用统一的thinkingFalse设置cerebras_clear_thinkingbool多轮zai/GLM 请求中是否剥离先前轮次的推理。TrueCerebras API 默认会丢弃False保留提升多轮连贯性与提示缓存命中率代价是更多 token底层转换逻辑在 cerebras.py 的_cerebras_settings_to_openai_settings中Cerebras 设置会被转换为 OpenAI 兼容设置推理禁用Cerebras 已于 2026-03-24 弃用extra_body[disable_reasoning]改用标准reasoning_effortnone。因此cerebras_disable_reasoningTrue或统一设置thinkingFalse时会注入openai_reasoning_effortnone若显式传入已弃用的字段会触发PydanticAIDeprecationWarning测试 tests/models/test_cerebras.py 断言了线上请求体中reasoning_effort none且不再出现disable_reasoning思考保留对于走think标签重放路径的zai/GLM 模型若未显式设置cerebras_clear_thinking会自动注入clear_thinkingFalse防止 Cerebras 默认的clear_thinkingtrue把重放的推理剥离掉非 GLM 模型如gpt-oss不会发送该参数显式设置永远优先见测试 tests/models/test_cerebras.py设置合并安全转换前先copy()避免原地pop污染模型自身的settings字典防止下一次请求丢失键值。七、多轮对话中的思考内容Thinking PartCerebras 把模型的推理内容作为装饰性的ThinkingPart返回从响应的reasoning字段解析。两个相关测试验证了它在多轮场景中的完整生命周期tests/models/test_cerebras.pygpt-oss-120b两轮对话中第一轮的ThinkingPart会被逐字保留在消息历史中并在第二轮请求的 assistant 消息reasoning字段原样重放tests/models/test_cerebras.pyzai-glm-4.7的推理则必须以think.../think标签包裹在 assistant 消息content中重放且不得出现在独立的reasoning字段。理解这一点有助于你在多轮 Agent 应用中正确预期 Cerebras 推理内容的往返行为尤其是zai/GLM 系列对标签重放与clear_thinking的强依赖。八、其他可转发的标准设置除了 Cerebras 专属字段标准 OpenAI 设置同样可用。测试 tests/models/test_cerebras.py 确认了以下参数会如实到达线上请求体frequency_penalty、presence_penalty、parallel_tool_callsparallel_tool_calls仅在请求携带工具时才会出现在线路上service_tierauto/default/flex/priority四种取值在普通 Cerebras Key 上都会被 API 以 HTTP 200 接受层级处于 Private Preview是否真正获得该层级由网关决定但接受性不受限见 tests/models/test_cerebras.pyopenai_service_tier优先于统一的service_tierlogit_bias被画像显式剥离不会到达线上原因见第五节小结在 Pydantic AI 中使用 Cerebras 的核心链路可以总结为安装pip install pydantic-ai-slim[cerebras]依赖openai3.8.0认证设置CEREBRAS_API_KEY环境变量或在CerebrasProvider(api_key...)中显式传入初始化Agent(cerebras:model)字符串解析或CerebrasModel(model_name, provider...)直接构造调优通过CerebrasModelSettings控制推理推荐统一thinkingFalse与cerebras_clear_thinking多轮行为其余标准 OpenAI 设置按需转发。仓库中 tests/models/test_cerebras.py 与 tests/providers/test_cerebras.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），仅供参考
