smolagents 模型层指南Model 接口契约、内置模型与自定义 LLM 接入【免费下载链接】smolagents smolagents: a barebones library for agents that think in code.项目地址: https://gitcode.com/gh_mirrors/smo/smolagents本篇基于 smolagents 仓库中的模型参考文档docs/source/zh/reference/models.md与模型层核心实现src/smolagents/models.py整理。文章围绕 smolagents 的模型抽象展开先讲清“什么对象可以充当 Agent 的模型”这一接口契约再逐一拆解 TransformersModel、InferenceClientModel、LiteLLMModel、OpenAIModel、AzureOpenAIModel、MLXModel 等内置模型类最后深入到 API 模型的限流与重试机制、参数优先级和序列化安全机制。读完后你可以直接选型内置模型驱动 CodeAgent也能按契约快速接入任意自研 LLM。需要说明的前提smolagents 是一个实验性 API官方文档明确提示其可能随时变化底层 API 或模型变动都可能导致 Agent 结果不同当前仓库版本为1.27.0.dev0见 pyproject.toml。模型接口契约任何可调用对象都能驱动 Agentsmolagents 对模型没有强绑定你可以自由创建和使用自己的模型为智能体提供支持。文档给出的准入条件只有两条它遵循消息格式List[Dict[str, str]]将其作为输入messages并返回一个包含.content属性的对象其中包含生成的文本它在生成的序列到达stop_sequences参数中指定的内容之前停止生成输出。要定义你的 LLM可以创建一个custom_model方法它接受一个 messages 列表并返回包含.content属性的对象。此可调用对象还需要接受一个stop_sequences参数用于指示何时停止生成。文档给出的示例基于 Hugging Face InferenceClientfrom huggingface_hub import login, InferenceClient login(YOUR_HUGGINGFACEHUB_API_TOKEN) model_id meta-llama/Llama-3.3-70B-Instruct client InferenceClient(modelmodel_id) def custom_model(messages, stop_sequences[Task]): response client.chat_completion(messages, stopstop_sequences, max_tokens1000) answer response.choices[0].message return answer此外custom_model还可以接受一个grammar参数。如果在智能体初始化时指定了grammar则此参数将在调用模型时传递以便进行约束生成从而强制生成格式正确的智能体输出。从源码结构看这套契约的正式承载者是 models.py 中的Model基类所有模型实现必须实现generate(messages, stop_sequencesNone, response_formatNone, tools_to_call_fromNone, **kwargs)返回值是统一的ChatMessage数据类见 ChatMessage 定义其中content即生成文本tool_calls、token_usage、raw分别承载工具调用、token 统计和原始响应Model.__call__直接委托给generate所以文档中“可调用对象”的写法与基类语义一致基类还暴露了tool_name_key默认name与tool_arguments_key默认arguments用于从纯文本响应中解析工具调用parse_tool_calls方法models.py这正是 CodeAgent 依赖“输出以Task等停止序列结束”这类文本协议的原因。_prepare_completion_kwargsmodels.py是参数装配的中枢值得注意两点参数优先级文档化的优先级为“模型初始化时的self.kwargs最高 调用时显式传入的 kwargs 具体参数stop_sequences、response_format 等”。测试 tests/test_models.py 专门验证了这一点初始化时写Model(max_tokens100)会覆盖调用时传入的max_tokens50。REMOVE_PARAMETER 哨兵把某个参数设为REMOVE_PARAMETER可以从最终请求中移除该参数同样有测试覆盖。另外当传入tools_to_call_from时默认tool_choicerequired测试 tests/test_models.py 覆盖了required/auto/工具名/字典/显式None等组合这保证了 API 模型在工具场景下倾向发出结构化 tool call。消息格式与内部数据流文档提到的消息格式List[Dict[str, str]]在仓库中由get_clean_message_listmodels.py统一清洗它接受ChatMessage或 dict 混合列表支持自定义role_conversions角色映射可把图片编码为 base64 或image_url并在flatten_messages_as_textTrue时把相邻同角色消息合并为纯文本。默认的角色映射是tool_role_conversions {TOOL_CALL: ASSISTANT, TOOL_RESPONSE: USER}。角色集合由MessageRole枚举定义user、assistant、system、tool-call、tool-responsemodels.py。一个容易被忽略的实现细节是stop_sequences 的“事后截断”。部分推理模型如 openai/o3、o4-mini、gpt-5 系列及部分 grok 模型的 API 不支持stop参数supports_stop_parametermodels.py会根据model_id判断不支持时不向 API 传stop而在拿到响应后调用remove_content_after_stop_sequences把停止序列之后的内容切掉。测试 test_supports_stop_parameter 用大量模型 ID 覆盖了该正则含带路径前缀、带日期后缀、o3-mini例外等边缘情况test_stop_sequence_cutting_for_o4_mini 则验证了事后截断行为。内置模型一TransformersModel本地推理TransformersModel为初始化时指定的model_id构建一个本地transformerspipeline 来实现上述功能from smolagents import TransformersModel model TransformersModel(model_idHuggingFaceTB/SmolLM-135M-Instruct) print(model([{role: user, content: [{type: text, text: Ok!}]}], stop_sequences[great])) What a必须在机器上安装transformers和torch。如果尚未安装请运行pip install smolagents[transformers]该 extra 实际还包含accelerate和 torch 依赖见 pyproject.toml 的[project.optional-dependencies]。结合 TransformersModel 源码 可以补充若干文档未展开的参数max_new_tokens默认4096max_tokens是其别名且优先级更高device_map不传时自动选择cuda若可用否则cputorch_dtype、trust_remote_codeHub 上需要远程代码的模型须置True、model_kwargs透传给from_pretrained、apply_chat_template_kwargs均可用它会先尝试AutoModelForImageTextToText加载视觉语言模型配合AutoProcessor失败且报错为 Unrecognized configuration class 时回退到AutoModelForCausalLMAutoTokenizer——因此非视觉模型的消息会被展平为纯文本flatten_messages_as_text由是否 VLM 自动决定停止序列通过自定义StoppingCriteria实现逐 token 解码后检查流是否以任一 stop 字符串结尾生成后仍会再做一次remove_content_after_stop_sequences截断兜底它不支持response_format结构化输出源码中直接抛出ValueError并提示“use VLLMModel for this”额外提供generate_stream用TextIteratorStreamer在独立线程中逐 token 输出测试 test_transformers_message_no_tool 验证了非流式与流式输出一致。内置模型二InferenceClientModelHugging Face 推理网络InferenceClientModel封装了 huggingface_hub 的 InferenceClient 用于执行 LLM支持 HF 的 Inference API 以及 Hub 上所有可用的 Inference ProvidersCerebras、Cohere、Fal、Fireworks、HF-Inference、Hyperbolic、Nebius、Novita、Replicate、SambaNova、Together 等from smolagents import InferenceClientModel messages [ {role: user, content: [{type: text, text: Hello, how are you?}]} ] model InferenceClientModel() print(model(messages)) Of course! If you change your mind, feel free to reach out. Take care!从 InferenceClientModel 源码 可见其关键参数与默认值model_id默认Qwen/Qwen3-Next-80B-A3B-Thinking注释标明未来可能变更provider默认auto即选取该模型可用的第一个 Provider传入base_url时provider不生效token与api_key二选一api_key是为了对齐 OpenAI 客户端命名而设的别名都不传时读取环境变量HF_TOKEN否则回退到 HF CLI 本地配置timeout默认 120 秒支持requests_per_minute限流经由ApiModel见下文“API 模型的公共机制”结构化输出response_format仅限STRUCTURED_GENERATION_PROVIDERS [cerebras, fireworks-ai]两个 provider否则会抛出ValueError有对应测试 test_structured_outputs_with_unsupported_provider同样提供generate_stream流式接口。内置模型三LiteLLMModel 与 LiteLLMRouterModel100 提供商LiteLLMModel利用 LiteLLM 支持来自不同提供商的 100 个 LLM。你可以在模型初始化时传递kwargs这些参数将在每次使用模型时被使用例如下面的示例中传递了temperaturefrom smolagents import LiteLLMModel messages [ {role: user, content: [{type: text, text: Hello, how are you?}]} ] model LiteLLMModel(model_idanthropic/claude-3-5-sonnet-latest, temperature0.2, max_tokens10) print(model(messages))安装方式为pip install smolagents[litellm]。从 LiteLLMModel 源码 补充model_id缺省时默认anthropic/claude-3-5-sonnet-20240620并给出将变为必传的未来警告flatten_messages_as_text对ollama、groq、cerebras前缀的模型默认置True其余默认False图片内容会以image_urldata URL形式传给 API。LiteLLMRouterModel则继承 LiteLLM 的 Router提供跨多部署的负载均衡、队列化、冷却/回退与指数退避重试等路由策略适合把同一模型名挂到多个后端from smolagents import LiteLLMRouterModel messages [ {role: user, content: [{type: text, text: Hello, how are you?}]} ] model LiteLLMRouterModel( model_idllama-3.3-70b, model_list[ { model_name: llama-3.3-70b, litellm_params: {model: groq/llama-3.3-70b, api_key: os.getenv(GROQ_API_KEY)}, }, { model_name: llama-3.3-70b, litellm_params: {model: cerebras/llama-3.3-70b, api_key: os.getenv(CEREBRAS_API_KEY)}, }, ], client_kwargs{ routing_strategy: simple-shuffle, }, ) print(model(messages))测试 TestLiteLLMRouterModel 验证了model_list与client_kwargs会原样传给litellm.router.Router构造函数。内置模型四OpenAIModel 与 AzureOpenAIModelOpenAIModel允许你调用任何 OpenAI 兼容OpenAI Server模型可通过api_base指向其他服务器import os from smolagents import OpenAIModel model OpenAIModel( model_idgpt-4o, api_basehttps://api.openai.com/v1, api_keyos.environ[OPENAI_API_KEY], )需要安装pip install smolagents[openai]。从 OpenAIModel 源码 看它还有organization、project、client_kwargs如max_retries等参数全部透传给openai.OpenAI客户端测试 test_client_kwargs_passed_correctly 验证了透传generate_stream支持流式 tool call 聚合测试 test_streaming_tool_calls 覆盖了并行final_answer工具调用场景。仓库中OpenAIServerModel是它的别名。AzureOpenAIModel允许你连接到任何 Azure OpenAI 部署。下面是设置示例请注意如果已经设置了相应的环境变量你可以省略azure_endpoint、api_key和api_version参数——环境变量包括AZURE_OPENAI_ENDPOINT、AZURE_OPENAI_API_KEY和OPENAI_API_VERSION。请注意OPENAI_API_VERSION没有AZURE_前缀这是由于底层 openai 包的设计所致。import os from smolagents import AzureOpenAIModel model AzureOpenAIModel( model_id os.environ.get(AZURE_OPENAI_MODEL), azure_endpointos.environ.get(AZURE_OPENAI_ENDPOINT), api_keyos.environ.get(AZURE_OPENAI_API_KEY), api_versionos.environ.get(OPENAI_API_VERSION) )实现上AzureOpenAIModel继承OpenAIModel仅在create_client中改用openai.AzureOpenAI并把api_version、azure_endpoint注入客户端参数models.py测试 TestAzureOpenAIModel 验证了参数组装。内置模型五MLXModelApple Silicon 本地推理from smolagents import MLXModel model MLXModel(model_idHuggingFaceTB/SmolLM-135M-Instruct) print(model([{role: user, content: Ok!}], stop_sequences[great])) What a必须在机器上安装mlx-lm。如果尚未安装请运行pip install smolagents[mlx-lm]。从 MLXModel 源码 可补充load_kwargs透传给mlx_lm.loadtrust_remote_code默认Falseapply_chat_template_kwargs默认带add_generation_promptTruemlx-lm 不支持视觉模型消息一律展平为纯文本流式生成中逐 token 检查 stop 序列并以text.rfind精确截断测试 test_get_mlx_message_tricky_stop_sequence 专门覆盖了 stop 序列后紧跟其他字符的场景MLX 不支持结构化输出传response_format会报错。该测试仅在 macOS 上运行skipif not darwin。模型注册表中的其他成员除文档主体覆盖的模型外模型注册表 MODEL_REGISTRY 还登记了VLLMModel本地 vLLM 服务pip install smolagents[vllm]支持 JSON schema 结构化输出与model_kwargs/apply_chat_template_kwargs和AmazonBedrockModelpip install smolagents[bedrock]基于 boto3bedrock-runtime的converse接口默认把所有角色映射为user且不支持response_format。这两个类与上述模型一样通过from_dict参与模型序列化。API 模型的公共机制限流、重试与停止序列兜底所有 API 系模型InferenceClientModel、LiteLLMModel、OpenAIModel、AzureOpenAIModel、AmazonBedrockModel都继承ApiModelmodels.py共享三套基础设施客户端注入client参数允许传入预配置的客户端实例否则调用子类的create_client()限流requests_per_minute参数经RateLimiterutils.py实现按60/requests_per_minute秒的最小间隔节流None时禁用限流错误重试retryTrue时请求经由Retryingutils.py执行最多RETRY_MAX_ATTEMPTS 3次基准等待RETRY_WAIT 60秒、指数底数 2、带抖动常量定义。重试谓词is_rate_limit_error通过错误信息中是否含429、rate limit、too many requests、rate_limit判定。测试 test_retry_on_rate_limit_error 用 mock 验证了“两次 429 后成功、共调用 3 次”以及指数退避的耗时区间。每次generate返回的ChatMessage都携带token_usageinput/output token 数与raw原始响应供记忆、监控monitoring.py与运行日志使用。安装、依赖与模型序列化结合 pyproject.toml与模型相关的可选依赖extras如下模型类安装命令依赖要点TransformersModelpip install smolagents[transformers]acceleratetransformers4.0.0排除 5.13.0 torch/torchvision/numpyInferenceClientModel核心依赖即可huggingface-hub已是基础依赖LiteLLMModel/LiteLLMRouterModelpip install smolagents[litellm]litellm1.60.2OpenAIModel/AzureOpenAIModelpip install smolagents[openai]openai1.58.1AmazonBedrockModelpip install smolagents[bedrock]boto31.36.18MLXModelpip install smolagents[mlx-lm]mlx-lmVLLMModelpip install smolagents[vllm]vllm0.10.2 torch每个模型类在缺失对应依赖时会抛出带安装提示的ModuleNotFoundError例如VLLMModel的检查见 models.py可据此快速定位环境问题。最后模型实例可以安全地序列化进 Agent 存档Model.to_dictmodels.py导出model_id与采样参数temperature、max_tokens、provider、api_base、device_map等但出于安全考虑不导出token/api_key并打印提示需手动导出反序列化时只允许MODEL_REGISTRY中登记的类名实例化防止任意代码执行。这一机制配合from_dict使保存/恢复智能体成为可能。小结自定义模型只需满足两个条件接受messagesList[Dict[str, str]]stop_sequences返回带.content的对象进阶可实现Model子类并支持grammar约束生成参数传递遵循“初始化 kwargs 最高优先级”可用REMOVE_PARAMETER移除参数停止序列在不支持的模型上会自动退化为事后截断行为可预期有完整测试矩阵API 模型统一具备requests_per_minute限流与 429 指数退避重试选型建议本地小模型用TransformersModel/MLXModel/VLLMModel托管推理用InferenceClientModel多厂商统一接入用LiteLLMModel多后端负载均衡用LiteLLMRouterModelAzure/Bedrock 云部署用对应专属类。更多 API 细节可直接查阅 模型参考文档 与 tests/test_models.py 中的用例。【免费下载链接】smolagents smolagents: a barebones library for agents that think in code.项目地址: https://gitcode.com/gh_mirrors/smo/smolagents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/19 8:43:24 · 阅读 1.2k smolagents 模型层指南：Model 接口契约、内置模型与自定义 LLM 接入
smolagents 模型层指南Model 接口契约、内置模型与自定义 LLM 接入【免费下载链接】smolagents smolagents: a barebones library for agents that think in code.项目地址: https://gitcode.com/gh_mirrors/smo/smolagents本篇基于 smolagents 仓库中的模型参考文档docs/source/zh/reference/models.md与模型层核心实现src/smolagents/models.py整理。文章围绕 smolagents 的模型抽象展开先讲清“什么对象可以充当 Agent 的模型”这一接口契约再逐一拆解 TransformersModel、InferenceClientModel、LiteLLMModel、OpenAIModel、AzureOpenAIModel、MLXModel 等内置模型类最后深入到 API 模型的限流与重试机制、参数优先级和序列化安全机制。读完后你可以直接选型内置模型驱动 CodeAgent也能按契约快速接入任意自研 LLM。需要说明的前提smolagents 是一个实验性 API官方文档明确提示其可能随时变化底层 API 或模型变动都可能导致 Agent 结果不同当前仓库版本为1.27.0.dev0见 pyproject.toml。模型接口契约任何可调用对象都能驱动 Agentsmolagents 对模型没有强绑定你可以自由创建和使用自己的模型为智能体提供支持。文档给出的准入条件只有两条它遵循消息格式List[Dict[str, str]]将其作为输入messages并返回一个包含.content属性的对象其中包含生成的文本它在生成的序列到达stop_sequences参数中指定的内容之前停止生成输出。要定义你的 LLM可以创建一个custom_model方法它接受一个 messages 列表并返回包含.content属性的对象。此可调用对象还需要接受一个stop_sequences参数用于指示何时停止生成。文档给出的示例基于 Hugging Face InferenceClientfrom huggingface_hub import login, InferenceClient login(YOUR_HUGGINGFACEHUB_API_TOKEN) model_id meta-llama/Llama-3.3-70B-Instruct client InferenceClient(modelmodel_id) def custom_model(messages, stop_sequences[Task]): response client.chat_completion(messages, stopstop_sequences, max_tokens1000) answer response.choices[0].message return answer此外custom_model还可以接受一个grammar参数。如果在智能体初始化时指定了grammar则此参数将在调用模型时传递以便进行约束生成从而强制生成格式正确的智能体输出。从源码结构看这套契约的正式承载者是 models.py 中的Model基类所有模型实现必须实现generate(messages, stop_sequencesNone, response_formatNone, tools_to_call_fromNone, **kwargs)返回值是统一的ChatMessage数据类见 ChatMessage 定义其中content即生成文本tool_calls、token_usage、raw分别承载工具调用、token 统计和原始响应Model.__call__直接委托给generate所以文档中“可调用对象”的写法与基类语义一致基类还暴露了tool_name_key默认name与tool_arguments_key默认arguments用于从纯文本响应中解析工具调用parse_tool_calls方法models.py这正是 CodeAgent 依赖“输出以Task等停止序列结束”这类文本协议的原因。_prepare_completion_kwargsmodels.py是参数装配的中枢值得注意两点参数优先级文档化的优先级为“模型初始化时的self.kwargs最高 调用时显式传入的 kwargs 具体参数stop_sequences、response_format 等”。测试 tests/test_models.py 专门验证了这一点初始化时写Model(max_tokens100)会覆盖调用时传入的max_tokens50。REMOVE_PARAMETER 哨兵把某个参数设为REMOVE_PARAMETER可以从最终请求中移除该参数同样有测试覆盖。另外当传入tools_to_call_from时默认tool_choicerequired测试 tests/test_models.py 覆盖了required/auto/工具名/字典/显式None等组合这保证了 API 模型在工具场景下倾向发出结构化 tool call。消息格式与内部数据流文档提到的消息格式List[Dict[str, str]]在仓库中由get_clean_message_listmodels.py统一清洗它接受ChatMessage或 dict 混合列表支持自定义role_conversions角色映射可把图片编码为 base64 或image_url并在flatten_messages_as_textTrue时把相邻同角色消息合并为纯文本。默认的角色映射是tool_role_conversions {TOOL_CALL: ASSISTANT, TOOL_RESPONSE: USER}。角色集合由MessageRole枚举定义user、assistant、system、tool-call、tool-responsemodels.py。一个容易被忽略的实现细节是stop_sequences 的“事后截断”。部分推理模型如 openai/o3、o4-mini、gpt-5 系列及部分 grok 模型的 API 不支持stop参数supports_stop_parametermodels.py会根据model_id判断不支持时不向 API 传stop而在拿到响应后调用remove_content_after_stop_sequences把停止序列之后的内容切掉。测试 test_supports_stop_parameter 用大量模型 ID 覆盖了该正则含带路径前缀、带日期后缀、o3-mini例外等边缘情况test_stop_sequence_cutting_for_o4_mini 则验证了事后截断行为。内置模型一TransformersModel本地推理TransformersModel为初始化时指定的model_id构建一个本地transformerspipeline 来实现上述功能from smolagents import TransformersModel model TransformersModel(model_idHuggingFaceTB/SmolLM-135M-Instruct) print(model([{role: user, content: [{type: text, text: Ok!}]}], stop_sequences[great])) What a必须在机器上安装transformers和torch。如果尚未安装请运行pip install smolagents[transformers]该 extra 实际还包含accelerate和 torch 依赖见 pyproject.toml 的[project.optional-dependencies]。结合 TransformersModel 源码 可以补充若干文档未展开的参数max_new_tokens默认4096max_tokens是其别名且优先级更高device_map不传时自动选择cuda若可用否则cputorch_dtype、trust_remote_codeHub 上需要远程代码的模型须置True、model_kwargs透传给from_pretrained、apply_chat_template_kwargs均可用它会先尝试AutoModelForImageTextToText加载视觉语言模型配合AutoProcessor失败且报错为 Unrecognized configuration class 时回退到AutoModelForCausalLMAutoTokenizer——因此非视觉模型的消息会被展平为纯文本flatten_messages_as_text由是否 VLM 自动决定停止序列通过自定义StoppingCriteria实现逐 token 解码后检查流是否以任一 stop 字符串结尾生成后仍会再做一次remove_content_after_stop_sequences截断兜底它不支持response_format结构化输出源码中直接抛出ValueError并提示“use VLLMModel for this”额外提供generate_stream用TextIteratorStreamer在独立线程中逐 token 输出测试 test_transformers_message_no_tool 验证了非流式与流式输出一致。内置模型二InferenceClientModelHugging Face 推理网络InferenceClientModel封装了 huggingface_hub 的 InferenceClient 用于执行 LLM支持 HF 的 Inference API 以及 Hub 上所有可用的 Inference ProvidersCerebras、Cohere、Fal、Fireworks、HF-Inference、Hyperbolic、Nebius、Novita、Replicate、SambaNova、Together 等from smolagents import InferenceClientModel messages [ {role: user, content: [{type: text, text: Hello, how are you?}]} ] model InferenceClientModel() print(model(messages)) Of course! If you change your mind, feel free to reach out. Take care!从 InferenceClientModel 源码 可见其关键参数与默认值model_id默认Qwen/Qwen3-Next-80B-A3B-Thinking注释标明未来可能变更provider默认auto即选取该模型可用的第一个 Provider传入base_url时provider不生效token与api_key二选一api_key是为了对齐 OpenAI 客户端命名而设的别名都不传时读取环境变量HF_TOKEN否则回退到 HF CLI 本地配置timeout默认 120 秒支持requests_per_minute限流经由ApiModel见下文“API 模型的公共机制”结构化输出response_format仅限STRUCTURED_GENERATION_PROVIDERS [cerebras, fireworks-ai]两个 provider否则会抛出ValueError有对应测试 test_structured_outputs_with_unsupported_provider同样提供generate_stream流式接口。内置模型三LiteLLMModel 与 LiteLLMRouterModel100 提供商LiteLLMModel利用 LiteLLM 支持来自不同提供商的 100 个 LLM。你可以在模型初始化时传递kwargs这些参数将在每次使用模型时被使用例如下面的示例中传递了temperaturefrom smolagents import LiteLLMModel messages [ {role: user, content: [{type: text, text: Hello, how are you?}]} ] model LiteLLMModel(model_idanthropic/claude-3-5-sonnet-latest, temperature0.2, max_tokens10) print(model(messages))安装方式为pip install smolagents[litellm]。从 LiteLLMModel 源码 补充model_id缺省时默认anthropic/claude-3-5-sonnet-20240620并给出将变为必传的未来警告flatten_messages_as_text对ollama、groq、cerebras前缀的模型默认置True其余默认False图片内容会以image_urldata URL形式传给 API。LiteLLMRouterModel则继承 LiteLLM 的 Router提供跨多部署的负载均衡、队列化、冷却/回退与指数退避重试等路由策略适合把同一模型名挂到多个后端from smolagents import LiteLLMRouterModel messages [ {role: user, content: [{type: text, text: Hello, how are you?}]} ] model LiteLLMRouterModel( model_idllama-3.3-70b, model_list[ { model_name: llama-3.3-70b, litellm_params: {model: groq/llama-3.3-70b, api_key: os.getenv(GROQ_API_KEY)}, }, { model_name: llama-3.3-70b, litellm_params: {model: cerebras/llama-3.3-70b, api_key: os.getenv(CEREBRAS_API_KEY)}, }, ], client_kwargs{ routing_strategy: simple-shuffle, }, ) print(model(messages))测试 TestLiteLLMRouterModel 验证了model_list与client_kwargs会原样传给litellm.router.Router构造函数。内置模型四OpenAIModel 与 AzureOpenAIModelOpenAIModel允许你调用任何 OpenAI 兼容OpenAI Server模型可通过api_base指向其他服务器import os from smolagents import OpenAIModel model OpenAIModel( model_idgpt-4o, api_basehttps://api.openai.com/v1, api_keyos.environ[OPENAI_API_KEY], )需要安装pip install smolagents[openai]。从 OpenAIModel 源码 看它还有organization、project、client_kwargs如max_retries等参数全部透传给openai.OpenAI客户端测试 test_client_kwargs_passed_correctly 验证了透传generate_stream支持流式 tool call 聚合测试 test_streaming_tool_calls 覆盖了并行final_answer工具调用场景。仓库中OpenAIServerModel是它的别名。AzureOpenAIModel允许你连接到任何 Azure OpenAI 部署。下面是设置示例请注意如果已经设置了相应的环境变量你可以省略azure_endpoint、api_key和api_version参数——环境变量包括AZURE_OPENAI_ENDPOINT、AZURE_OPENAI_API_KEY和OPENAI_API_VERSION。请注意OPENAI_API_VERSION没有AZURE_前缀这是由于底层 openai 包的设计所致。import os from smolagents import AzureOpenAIModel model AzureOpenAIModel( model_id os.environ.get(AZURE_OPENAI_MODEL), azure_endpointos.environ.get(AZURE_OPENAI_ENDPOINT), api_keyos.environ.get(AZURE_OPENAI_API_KEY), api_versionos.environ.get(OPENAI_API_VERSION) )实现上AzureOpenAIModel继承OpenAIModel仅在create_client中改用openai.AzureOpenAI并把api_version、azure_endpoint注入客户端参数models.py测试 TestAzureOpenAIModel 验证了参数组装。内置模型五MLXModelApple Silicon 本地推理from smolagents import MLXModel model MLXModel(model_idHuggingFaceTB/SmolLM-135M-Instruct) print(model([{role: user, content: Ok!}], stop_sequences[great])) What a必须在机器上安装mlx-lm。如果尚未安装请运行pip install smolagents[mlx-lm]。从 MLXModel 源码 可补充load_kwargs透传给mlx_lm.loadtrust_remote_code默认Falseapply_chat_template_kwargs默认带add_generation_promptTruemlx-lm 不支持视觉模型消息一律展平为纯文本流式生成中逐 token 检查 stop 序列并以text.rfind精确截断测试 test_get_mlx_message_tricky_stop_sequence 专门覆盖了 stop 序列后紧跟其他字符的场景MLX 不支持结构化输出传response_format会报错。该测试仅在 macOS 上运行skipif not darwin。模型注册表中的其他成员除文档主体覆盖的模型外模型注册表 MODEL_REGISTRY 还登记了VLLMModel本地 vLLM 服务pip install smolagents[vllm]支持 JSON schema 结构化输出与model_kwargs/apply_chat_template_kwargs和AmazonBedrockModelpip install smolagents[bedrock]基于 boto3bedrock-runtime的converse接口默认把所有角色映射为user且不支持response_format。这两个类与上述模型一样通过from_dict参与模型序列化。API 模型的公共机制限流、重试与停止序列兜底所有 API 系模型InferenceClientModel、LiteLLMModel、OpenAIModel、AzureOpenAIModel、AmazonBedrockModel都继承ApiModelmodels.py共享三套基础设施客户端注入client参数允许传入预配置的客户端实例否则调用子类的create_client()限流requests_per_minute参数经RateLimiterutils.py实现按60/requests_per_minute秒的最小间隔节流None时禁用限流错误重试retryTrue时请求经由Retryingutils.py执行最多RETRY_MAX_ATTEMPTS 3次基准等待RETRY_WAIT 60秒、指数底数 2、带抖动常量定义。重试谓词is_rate_limit_error通过错误信息中是否含429、rate limit、too many requests、rate_limit判定。测试 test_retry_on_rate_limit_error 用 mock 验证了“两次 429 后成功、共调用 3 次”以及指数退避的耗时区间。每次generate返回的ChatMessage都携带token_usageinput/output token 数与raw原始响应供记忆、监控monitoring.py与运行日志使用。安装、依赖与模型序列化结合 pyproject.toml与模型相关的可选依赖extras如下模型类安装命令依赖要点TransformersModelpip install smolagents[transformers]acceleratetransformers4.0.0排除 5.13.0 torch/torchvision/numpyInferenceClientModel核心依赖即可huggingface-hub已是基础依赖LiteLLMModel/LiteLLMRouterModelpip install smolagents[litellm]litellm1.60.2OpenAIModel/AzureOpenAIModelpip install smolagents[openai]openai1.58.1AmazonBedrockModelpip install smolagents[bedrock]boto31.36.18MLXModelpip install smolagents[mlx-lm]mlx-lmVLLMModelpip install smolagents[vllm]vllm0.10.2 torch每个模型类在缺失对应依赖时会抛出带安装提示的ModuleNotFoundError例如VLLMModel的检查见 models.py可据此快速定位环境问题。最后模型实例可以安全地序列化进 Agent 存档Model.to_dictmodels.py导出model_id与采样参数temperature、max_tokens、provider、api_base、device_map等但出于安全考虑不导出token/api_key并打印提示需手动导出反序列化时只允许MODEL_REGISTRY中登记的类名实例化防止任意代码执行。这一机制配合from_dict使保存/恢复智能体成为可能。小结自定义模型只需满足两个条件接受messagesList[Dict[str, str]]stop_sequences返回带.content的对象进阶可实现Model子类并支持grammar约束生成参数传递遵循“初始化 kwargs 最高优先级”可用REMOVE_PARAMETER移除参数停止序列在不支持的模型上会自动退化为事后截断行为可预期有完整测试矩阵API 模型统一具备requests_per_minute限流与 429 指数退避重试选型建议本地小模型用TransformersModel/MLXModel/VLLMModel托管推理用InferenceClientModel多厂商统一接入用LiteLLMModel多后端负载均衡用LiteLLMRouterModelAzure/Bedrock 云部署用对应专属类。更多 API 细节可直接查阅 模型参考文档 与 tests/test_models.py 中的用例。【免费下载链接】smolagents smolagents: a barebones library for agents that think in code.项目地址: https://gitcode.com/gh_mirrors/smo/smolagents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考